# TariffTrust > Sourced US import duty estimates for a known HTS code, origin, value and product facts. Every amount cites its official, dated source. Informational estimates, not customs determinations. TariffTrust never classifies products. Base URL: https://api.tarifftrust.com/v1 · Authentication: `Authorization: Bearer ` · OpenAPI: https://api.tarifftrust.com/v1/openapi.json · Reference: https://tarifftrust.com/api/reference/ · Official clients: Python `pip install tarifftrust`, Node.js `npm install tarifftrust`, https://github.com/tarifftrust/tarifftrust · MCP (Streamable HTTP): https://api.tarifftrust.com/mcp/ ## Rules for agents - Unknown is never zero: a `null` amount is unknown. Never present `known_duty_subtotal` as the duty when `estimated_duty` is `null`. - Keep the `status` (`calculated`, `needs_information`, `partial`, `unsupported`, `not_covered`, `not_found`), the `warnings` and the `sources` when you relay a result. - `assumptions`: a question nobody answered takes its ordinary case (the goods are what the measures of their code are aimed at; no exemption, advantage or certification is claimed). Tell the user each assumption and its `alternatives` (what another answer would give); send the user's own answer in `facts` to replace one. - `needs_information`: the question has no ordinary case. Ask the user only the `input_guidance` questions, then calculate again with `facts`. `scenarios` show every combination of the unanswered yes/no and choice facts (up to twelve), with bounds. A reply that gives a duty amount (the duty of each answer, their bounds, the subtotal already known) or a rate is counted against the quota, as an estimate; one that only asks, without any duty amount or rate, is not. Once the quota is used up, every request is refused, these included. - `review_pending` lists what withholds part of the estimate: positions under review (kind `position`), wrong-rate incidents (`incident`), official notices not yet read (`notice`) and measures in force whose rate is not announced yet (`pending_rate`). - A component whose `source.ahead_of_tariff` is `true` rests on an official notice (a proclamation, a USTR notice, a customs message) the USITC tariff does not hold yet: say so when you relay it. - Status, freshness (`freshness`) and verification health (`verification`) are three separate signals. - Estimate a whole import declaration with `POST /estimates/entry`: MPF and HMF are computed once per declaration. Adding single-product results of the lines of one declaration gives a wrong MPF. - An unsaved estimate cannot be replayed, reported or notified in an incident. Save it with `POST /saved-estimates` (or `save: true` with MCP). - `as_of` is the day of entry in New York time (`2026-04-05`); on a day when a measure takes effect at a stated hour, the instant with its UTC offset (`2026-04-05T00:01:00-04:00`). `preference` claims a trade agreement and declares its rules of origin met. ## REST endpoints Every field of each operation is described on its reference page and in the OpenAPI description. - `GET /agreements` — List the trade agreements. https://tarifftrust.com/api/reference/#list-agreements - `POST /estimates` — Estimate one product: `hts`, `origin`, `as_of`, `customs_value`, `entry_type`, `facts`, `freight`, `include_fees`, `insurance`, `preference`, `publication_id`, `quantities`, `transport_mode`. https://tarifftrust.com/api/reference/#estimate - `POST /estimates/batch` — Estimate up to 200 products: `items`, `publication_id`. https://tarifftrust.com/api/reference/#estimate-batch - `POST /estimates/entry` — Estimate a whole import declaration: `lines`, `as_of`, `entry_type`, `facts`, `freight`, `include_fees`, `insurance`, `publication_id`, `reference`, `transport_mode`. https://tarifftrust.com/api/reference/#estimate-entry - `POST /estimates/history` — Estimate one product at every change of the tariff: `hts`, `origin`, `customs_value`, `entry_type`, `facts`, `freight`, `from`, `include_fees`, `insurance`, `preference`, `quantities`, `through`, `transport_mode`. https://tarifftrust.com/api/reference/#estimate-history - `GET /facts` — List the questions an estimate may ask. https://tarifftrust.com/api/reference/#list-facts - `GET /hts` — Search the US tariff schedule: `q`, `chapter`, `offset`, `limit`. https://tarifftrust.com/api/reference/#search-hts - `GET /hts/{code}` — Read one line of the US tariff schedule: `code`. https://tarifftrust.com/api/reference/#get-hts - `GET /saved-estimates` — List the saved estimates: `offset`, `limit`. https://tarifftrust.com/api/reference/#list-saved-estimates - `POST /saved-estimates` — Calculate and save an estimate: `entry`, `estimate`, `label`. https://tarifftrust.com/api/reference/#save-estimate - `GET /saved-estimates/{id}` — Read a saved estimate: `id`. https://tarifftrust.com/api/reference/#get-saved-estimate - `GET /status` — Read the status and the coverage of the data. https://tarifftrust.com/api/reference/#get-status - Portfolios, imports, proof bundles, sharing, error reports, the assistant, support, team, keys and billing are in the portal, not the API. ## MCP tools `estimate`, `estimate_entry`, `estimate_batch`, `search_hts`, `get_hts`, `list_agreements`, `list_facts`, `estimate_history`, `list_saved_estimates`, `get_saved_estimate`, `get_status`: the operations of the API under the same names, counted as they are; `search_hts` takes its text in `query`. Errors are JSON-RPC errors, with HTTP 200 except a missing or invalid key (401) and an error of the service (500): `-32602` invalid arguments (`error.data.fields`), `-32000` a refusal with the API's code in `error.data.code` and `Retry-After` when retrying helps, `-32603` an error of the service. Send `Idempotency-Key` (a new UUID per request) to retry a calculation safely: same key and request, same response, counted once, for 7 days. ## Guides US import duties explained in plain words, for a user who knows nothing of customs (https://tarifftrust.com/learn/): - [How to find your HTS code](https://tarifftrust.com/learn/hts-code/): What the ten digits of an HTS code mean, where to find yours, and how to have it confirmed. - [Why the base duty rate is not enough](https://tarifftrust.com/learn/base-rate/): The base rate is only the first layer: what the country of origin and the date add, what a trade agreement takes off, and what stays outside. - [How to compare two countries of origin](https://tarifftrust.com/learn/compare-origins/): The same product from two countries can owe very different duties: what changes, what does not, and how to compare. - [How to read a TariffTrust estimate](https://tarifftrust.com/learn/read-an-estimate/): The total and its share of the value, each line and its source, the status, the questions, the scenarios and the date. - [How the MPF and HMF entry fees are calculated](https://tarifftrust.com/learn/entry-fees/): The merchandise processing fee and the harbor maintenance fee: their rates, the MPF's minimum and maximum, who is exempt, and why they are counted once per entry. - [How to read a Chapter 99 heading](https://tarifftrust.com/learn/chapter-99/): What the 9903 numbers of a customs entry are, how a heading of Chapter 99 is written, where its products are listed, and how to tell whether it applies to yours. - [How duties per kilogram, liter or proof liter are calculated](https://tarifftrust.com/learn/specific-duties/): Specific and compound duty rates: which quantity they count, how to work out the proof liters of spirits and the weight of garments, and the mistakes to avoid. - [How Section 301 tariffs work, on China and beyond](https://tarifftrust.com/learn/section-301/): The Section 301 duties on goods from China, the 2026 actions on 60 economies, Brazil and Nicaragua, their exclusions and exemptions, and how to tell whether your product owes one. - [How Section 232 tariffs work: metals, vehicles and more](https://tarifftrust.com/learn/section-232/): The Section 232 duties on steel, aluminum and copper, vehicles, trucks, lumber, pharmaceuticals, semiconductors and drones: what they cover, what they are charged on, how to check. - [How US import duties stack](https://tarifftrust.com/learn/stacking/): Base duty, Section 301, Section 232 and the rest: which duties add up, which exempt goods from others, which rates include the base duty, with examples calculated today. - [How trade agreements lower US import duties](https://tarifftrust.com/learn/trade-agreements/): The Special column and its symbols, the agreements the United States has, what claiming one takes, and what it changes in the duties, and what it does not. - [How to calculate the landed cost of an import](https://tarifftrust.com/learn/landed-cost/): What goods really cost once in the United States: their price, freight, insurance, duties, entry fees and broker's fees, and the customs value duties are charged on. - [IEEPA tariff refunds: where things stand](https://tarifftrust.com/learn/ieepa-refunds/): Who can get back the IEEPA duties paid in 2025 and early 2026, how CBP's CAPE refunds work, what the class action of October 2026 changes, and what to do now. - [US import duties on goods from Canada and Mexico](https://tarifftrust.com/learn/canada-mexico/): What goods of Canada and Mexico owe in 2026: the USMCA and the duties it changes, Section 232, the 2026 Section 301 rate, and the Section 338 duties on Canada. - [How TariffTrust checks its data](https://tarifftrust.com/learn/method/): Official sources only, rules read by a specialized AI and checked by programs and people, a calculation without AI, and corrections in the open. ## Facts catalog Facts are product, declaration or shipment characteristics. Ask only those the result requests. - `apparatus_value` (money, product): What is the apparatus value (USD)? - `auto_parts_treatment` (choice, product): Which auto parts treatment (Section 232) applies to these goods? - `automobile_treatment` (choice, product): Which passenger vehicle treatment (Section 232) applies to these goods? - `battery_value` (money, product): What is the battery value (USD)? - `brazil_special_exemption` (boolean, product): Brazil note 50 exemption applies? - `bus_treatment` (choice, product): Which bus treatment applies to these goods? - `cabinet_treatment` (choice, product): Which wooden cabinets and vanities treatment applies to these goods? - `cafta_dr_claimed` (boolean, product): Is entry of these goods claimed under the Dominican Republic-Central America-United States Free Trade Agreement? - `canada338_special_exemption` (boolean, product): Canada note 51 exemption applies? - `case_strap_value` (money, product): What is the case strap value (USD)? - `case_value` (money, product): What is the case value (USD)? - `certified_auto_parts_use` (boolean, product): Do you certify that these goods are automobile parts that will be used for automobile production or repair in the United States? - `certified_heavy_parts_use` (boolean, product): Do you certify that these goods are medium- or heavy-duty vehicle parts that will be used for the production or repair of such vehicles in the United States? - `certified_uk_vehicle_use` (boolean, product): Do you certify that these goods are automobile parts that will be used in automobiles that are products of the United Kingdom? - `civil_aircraft_gn6` (boolean, product): Is this an article of civil aircraft meeting the criteria of general note 6? - `contains_steel` (boolean, product): Do these goods contain steel? - `crane_pre_april2025_contract` (boolean, product): Do you attest that these cranes fulfill, in whole or in part, an executed contract for sale dated before April 17, 2025? - `donation_exemption_claimed` (boolean, product): Do you claim the exemption for donations intended to relieve human suffering? - `drone_scope_met` (boolean, product): Are these goods an unmanned aircraft, a docking station or a part that note 43(c) covers? - `drone_thermal_imaging` (boolean, product): Does this unmanned aircraft have thermal imaging? - `drone_treatment` (choice, product): Which drone treatment applies to these goods? - `entry_regime` (choice, entry): Under which regime are these goods entered? - `forced_labor_special_exemption` (boolean, product): Note 52 exemption applies? - `furniture_treatment` (choice, product): Which upholstered wooden furniture treatment applies to these goods? - `heavy_parts_treatment` (choice, product): Which medium or heavy vehicle parts treatment applies to these goods? - `heavy_vehicle_treatment` (choice, product): Which medium or heavy vehicle treatment applies to these goods? - `hmf_exempt` (boolean, entry): Is this entry exempt from the harbor maintenance fee? - `ieepa_border_treatment` (choice, product): Which IEEPA Canada or Mexico treatment applies to these goods? - `ieepa_brazil_exempt` (boolean, product): Exempt from the IEEPA Brazil duty? - `ieepa_entry_exempt` (boolean, entry): IEEPA entry exemption applies? - `ieepa_india_exempt` (boolean, product): Exempt from the IEEPA India duty? - `ieepa_reciprocal_treatment` (choice, shipment): Which IEEPA reciprocal treatment applies to these goods? - `informational_materials_claimed` (boolean, product): Do you claim the exemption for informational materials? - `intermodal_chassis` (boolean, product): Are these goods intermodal chassis, or subassemblies or parts of them, as note 31(k) describes them? - `korus_qualifying` (boolean, product): Do these goods qualify for preferential treatment under the United States-Korea Free Trade Agreement (KORUS)? - `lead_value` (money, product): What is the lead value (USD)? - `legacy_aluminum_duty_applies` (boolean, product): 2025 aluminum duty applies? - `legacy_steel_duty_applies` (boolean, product): 2025 steel duty applies? - `maritime_china_nexus` (boolean, product): Does this crane contain components, assemblies or subassemblies of China, or was it made by a company owned or controlled by a Chinese person or entity (note 31(l))? - `metal_value` (money, product): What is the metal value (USD)? - `metal_weight_threshold_met` (boolean, product): Is the weight of the applicable metal at least 15 percent of the weight of the article? - `metals_heading` (heading, product): Which Chapter 99 metals heading applies to these goods? - `metals_treatment` (choice, product): Which metals treatment (Section 232) applies to these goods? - `movement_case_value` (money, product): What is the movement case value (USD)? - `movement_value` (money, product): What is the movement value (USD)? - `mpf_exempt` (boolean, product): Are these goods exempt from the merchandise processing fee? - `nicaragua_cafta_or_entry_exemption` (boolean, product): Nicaragua CAFTA-DR or entry exemption applies? - `non_us_value` (money, product): What is the non-US value (USD)? - `particular_article_exemption_claimed` (boolean, product): Do you claim the exemption for the particular article the note names for this subheading? - `pharmaceutical_treatment` (choice, product): Which pharmaceutical treatment applies to these goods? - `pharmaceutical_use_exemption_claimed` (boolean, product): Do you claim the exemption for articles for use in pharmaceutical applications? - `quartz_treatment` (choice, product): Which quartz surface treatment applies to these goods? - `quartz_value` (money, product): What is the quartz surface value (USD)? - `russian_aluminum_content` (boolean, product): Was any primary aluminum used in these goods smelted in Russia, or were the goods cast in Russia? - `section122_treatment` (choice, shipment): Which Section 122 treatment applies to these goods? - `section122_value` (money, product): What is the value subject to Section 122 (USD)? - `section232_applies` (boolean, product): Subject to Section 232? - `section301_derived_rate_source` (choice, product): Is the entry's applied rate derived from another subheading subject to Section 301 duties? - `section301_exclusion_claimed` (boolean, product): Do you claim the Section 301 exclusion for these goods? - `section301_exclusion_eligible` (boolean, product): Do these goods match the description of a Section 301 product exclusion in effect for their statistical reporting number? - `section301_note20g_product` (boolean, product): Goods meet note 20(g)? - `section301_note20sii_product` (boolean, product): Goods meet note 20(s)(ii)? - `section301_special_rate_applies` (boolean, product): Section 301 special rate applies? - `semiconductor_exempt_use` (boolean, product): Will these semiconductor articles have a use that note 39(d) excludes from the duty, such as a U.S. data center or a repair in the United States? - `semiconductor_parameters_met` (boolean, product): Is this a logic integrated circuit, or an article containing one, that meets the technical parameters of note 39(b)? - `ship_to_shore_crane` (boolean, product): Is this a ship-to-shore gantry crane? - `solar_201_applies` (boolean, product): Covered by the solar safeguard? - `solar_cells_over_quota` (boolean, product): Solar cells over quota? - `steel_melt_and_pour_country` (country, product): In which country was the steel in these goods melted and poured? - `strap_value` (money, product): What is the strap value (USD)? - `sugar_polarization` (number, product): What is the polarization of the sugar, in degrees? - `textile_or_apparel_good` (boolean, product): Are these goods a textile or apparel good as defined in subdivision (d)(v) of general note 29? - `timber_treatment` (choice, product): Which softwood timber treatment applies to these goods? - `usmca_free_entry_claimed` (boolean, product): Are these goods entered free of duty under the United States-Mexico-Canada Agreement?