Skip to content
OpenBtoB
Sign up free

Agent docs

OpenBtoB answers over MCP at https://mcp.openbtob.com/mcp and over HTTP at https://api.openbtob.com. Shipment answers cite their records and carry the date their data runs through; duty answers name their sources and say what is not covered.

Quickstart

  1. Create an account and verify your email.

  2. Create an API key in Settings. It starts with opb_. Keep it secret.

  3. Add the server to your client: the steps for Claude Desktop, Claude Code and Cursor are on the MCP page.

  4. Ask your agent, for example: “Who imports Vietnamese coffee into the United States?” or “What is the duty on HS 0901.11 from Viet Nam to China?”

Authentication

Send your key in the Authorization header on every MCP request: Authorization: Bearer opb_.... Never put the key in a URL.

  • No key or a wrong key: HTTP 401.

  • Email not verified: the call fails and tells you to verify at https://openbtob.com/verify-email.

  • Clients must accept both application/json and text/event-stream; otherwise the server answers 406.

The HTTP lookup GET /api/hs needs no key.

Tools

The MCP server has 10 tools.

ToolWhat it does

search_buyers

Find companies importing a product (buyers).

search_suppliers

Find companies exporting a product (suppliers).

get_company

Full company profile: overview, top products (HS code as stored with its digit level, HS6 code and description; a bill with no code finer than a chapter uses its heading inferred from the description, marked hs_basis 'inferred'), purchase rhythm, partners, ports, recent shipments.

get_tariff_exposure

Tariff exposure of a company's US imports only: for its top 5 products by shipment count, per HS6 and origin, the US duty layers from the loaded US tariff.

screen_buyer

Screen a company: deterministic sanctions check against OFAC SDN, EU, UK and UN lists (never a model guess) + Jev trust/risk signals.

watch

Add a company, an HS code or a tariff line (a destination tariff line plus the origin of the goods, to follow its duty) to YOUR watchlist (max 50 items of all types).

unwatch

Remove a company, HS code or tariff line from YOUR watchlist.

get_watchlist

List YOUR tracked companies/HS codes/tariff lines with current activity.

lookup_hs

Look up HS codes by product description or code prefix.

export_data

Export search results as CSV.

Response fields

Shipment answers carry citation.shipment_ids and citation.based_on_n_shipments (the records the answer is based on) and freshness.data_through (the oldest data-through date of the sources used).

HS and duty answers (lookup_hs, GET /api/hs):

  • certainty: ruling_backed when a customs ruling names the top code, suggested otherwise, needs_detail when the product is too vague to pick one code. It is a label, not a probability. It comes with a product-description query only; a code query (like the examples below) has no certainty field.

  • needs_detail and detail_options: when true, ask the user to pick one of the options (each has a country, a code and a description), then look up again with that option.

  • route: with from and to, the export side and the import side of each HS6 result. Each side has its nomenclature (which book), as_of (the date of that book in our data), its measures and its gaps.

  • gaps: what our data does not cover on that side. Show them to the user; do not drop them.

  • line and line_is_sample: when every national line under the HS6 has the same duty, line is one example and line_is_sample is true. It is not a match for the user’s goods.

  • applies: yes when an additional duty applies to the line, may_apply when it depends on facts we do not hold (description, end use, a certificate). Never add may_apply rows into a total. The API returns no total.

  • not_applied: programs that do not apply to this line, each with the reason (struck down, expired, exempt).

  • disclaimer: “Estimate, not legal advice: verify with a licensed customs broker.” Show it with any duty.

Errors and limits

  • GET /api/hs answers 400 with {"error":{"code":"invalid_query","message":"..."}} for a query under 2 characters (one Chinese character is enough), a code over 10 digits, a from or to that is not a two-letter country code, a code_country that is not the from or the to, or a lang other than vi or en.

  • MCP: 100 tool calls a day per free account, counted per UTC day. Over the limit, the call fails with rate_limit_exceeded and carries retry_after, limit and window: "utc_day".

  • export_data returns a download link valid for 60 minutes, at most 1,000 rows per export, 100 rows in total on a free account.

  • Search in Vietnamese needs diacritics.

Examples

Copied from production on . Rates change; run them yourself for today’s answer.

Viet Nam to the United States, green coffee

curl -s "https://api.openbtob.com/api/hs?q=090111&from=VN&to=US"

What to read in the answer

  • route.hs6[0].import.nomenclature: "US HTSUS, 10-digit (import)".

  • The MFN measure: rate_text "Free".

  • not_applied lists 9903.05.84 (Section 301 (forced labor), Viet Nam, + 12.5%) as exempt for coffee under U.S. note 52(b).

  • The import side's gaps.

Viet Nam to China, green coffee

curl -s "https://api.openbtob.com/api/hs?q=090111&from=VN&to=CN"

What to read in the answer

  • MFN rate_text "8".

  • The ACFTA and RCEP preferential rates ("5", each with its rules-of-origin condition).

  • Import VAT "13", "charged on the duty-paid value; not a duty".

  • The gaps.

China to the United States, green coffee

curl -s "https://api.openbtob.com/api/hs?q=090111&from=CN&to=US"

What to read in the answer

  • MFN "Free".

  • The additional row 9903.88.15 (Section 301, China lists) "+ 7.5%" with applies "yes".

  • not_applied lists the programs that do not apply, each with its reason.

The same lookup over MCP: call lookup_hs with {"product": "090111", "from": "VN", "to": "US"}.