Build production trade
infrastructure.

The TariffOS API is a JSON over HTTPS interface for tariff intelligence, landed-cost computation, and trade compliance. It is the same engine that powers our dashboards, AI assistant, and enterprise integrations — exposed as primitives you can wire into any quoting engine, ERP, or freight platform.

All requests are made against https://api.tariffos.com and require a Bearer token. Responses are JSON, latencies are sub-100ms p95, and the surface area is versioned via the URL.

The console below executes against an in-browser sandbox using mocked responses modeled on the production schema. Swap the placeholder API key for a real sk_test_… sandbox key to hit sandbox.api.tariffos.com directly.

Try it · Sandbox TOSMock

MockLive

Enter Sandbox→

EndpointGET /v2/tariff/lookupPOST /v2/landed-costPOST /v2/classifyGET /v2/fta/eligibilityGET /v2/origin/rulesPOST /v2/scenarios/simulateGET /v2/changes/since

GEThttps://sandbox.api.tariffos.com/v2/tariff/lookup?hs=8703.80&origin=CN&destination=US

API key

Show✕ Clear

Storage

MemorySessionBrowser

Memory only. Cleared on reload — safest for shared machines.

Query string

▶ Send mock requestCopy as cURL

Response

[ awaiting request ]

Configure inputs and press Send request.

GET /api/public/market/stream?symbols=TOS.HS8703%2CTOS.FX.CNH%2CTOS.BDI&interval=1000&format=full
Accept: text/event-stream

curl -N "https://tos.sagolik.com/api/public/market/stream?symbols=TOS.HS8703%2CTOS.FX.CNH%2CTOS.BDI&interval=1000&format=full"

1. Request a key from enterprise sales or hit our self-serve sandbox.
2. Export it as TARIFFOS_KEY.
3. Call POST /v2/landed-cost with an HS code and shipment value.
4. Subscribe to tariff.changed webhooks for ongoing intelligence.

curl https://api.tariffos.com/v2/landed-cost \
  -H "Authorization: Bearer $TARIFFOS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shp_4kJ29fA" \
  -d '{
    "hs_code": "8703.80",
    "origin": "CN",
    "destination": "US",
    "value_usd": 48000,
    "incoterm": "FOB"
  }'

Major versions live in the URL (/v2/…). Field additions and new enum values are non-breaking. Removals or rename ship as /v3 with a 12-month overlap and deprecation headers.

TariffOS supports three auth modes. Use API keys for server-side integrations, OAuth 2.0 for third-party apps acting on behalf of a tenant, and request signing when calling from untrusted edges.

Keys are scoped to an environment and a workspace. Live keys are prefixed sk_live_; sandbox keys are sk_test_. Treat keys as secrets — store them in your platform's secret manager, never in source control.

GET /v2/tariff/lookup?hs=8703.80&origin=CN&destination=US HTTP/1.1
Host: api.tariffos.com
Authorization: Bearer sk_live_REPLACE_ME
Accept: application/json

For partner apps acting on behalf of a TariffOS tenant. Standard OAuth 2.1 with PKCE; access tokens expire in 1 hour, refresh tokens in 60 days.

For environments where a key cannot be embedded (browser SDK, partner edge), sign each request with a short-lived signing secret derived server-side.

{timestamp}.{method}.{path}.{sha256(body)}

X-TariffOS-Signature: t=1714694400,v1=4f2e…c0a1

Subscribe an HTTPS endpoint to receive event notifications. Deliveries are signed with HMAC-SHA256 over the raw request body and a per-endpoint signing secret. Retries follow exponential backoff (1m → 24h) for up to 72 hours.

curl https://api.tariffos.com/v2/alerts/subscribe \
  -H "Authorization: Bearer $TARIFFOS_KEY" \
  -d '{
    "url": "https://hooks.acme.com/tariffos",
    "events": ["tariff.changed", "shipment.recommendation"],
    "filters": { "lanes": ["CN>US", "VN>US"] }
  }'

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(req: { headers: Record<string,string>, rawBody: string }, secret: string) {
  const sig = req.headers["x-tariffos-signature"]; // t=...,v1=...
  const parts = Object.fromEntries(sig.split(",").map(p => p.split("=")));
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${req.rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

For low-latency dashboards, the TariffOS market and tariff feed is exposed as a long-lived Server-Sent Events connection. A single HTTP/1.1 or HTTP/2 GET opens a stream that emits typed events until the client or server closes it. The protocol is the W3C text/event-stream wire format — no client library is required, just EventSource in the browser or any framing-aware HTTP client on the server.

Endpoint

GET /api/public/market/stream?symbols=TOS.HS*,TOS.FX.CNH&interval=1000&format=delta HTTP/1.1
Host: api.tariffos.com
Accept: text/event-stream
Authorization: Bearer sk_live_REPLACE_ME

Sandbox base: https://sandbox.api.tariffos.com. The same path is mirrored on the platform domain at /api/public/market/stream for unauthenticated public market data.

Query parameters

Response headers

Event types

Every frame is a named SSE event with a JSON data payload. Listen with es.addEventListener("<event>", …); the default onmessage handler will not fire because every event is named.

event: ready
data: {"subscription":{"patterns":["TOS.HS*"],"categories":[],"intervalMs":1000,"format":"delta","symbols":[{"sym":"TOS.HS8703","label":"EV · CN→US","category":"hs","unit":"pct"}]},"serverTime":"2026-05-06T14:22:01.004Z"}

event: snapshot
data: {"source":"live","ts":"2026-05-06T14:22:01.040Z","ticks":[{"sym":"TOS.HS8703","val":27.52,"open":27.5,"unit":"pct","decimals":2,"ts":"2026-05-06T14:22:01.040Z"}]}

event: tick
data: {"source":"live","ts":"2026-05-06T14:22:02.041Z","ticks":[{"sym":"TOS.HS8703","val":27.61,"ts":"2026-05-06T14:22:02.041Z"}]}

: hb 1746540126000
event: heartbeat
data: {"seq":1,"serverTime":"2026-05-06T14:22:06.001Z"}

Heartbeat & liveness

The server emits two synchronized signals every 5000 ms:

• A raw SSE comment frame : hb <unix-ms>. Comments are required by the spec to be ignored by EventSource consumers, but they keep proxies (nginx, Cloudflare, corporate gateways) from idling out the TCP connection during quiet markets.
• A named heartbeat event with { seq: number, serverTime: string }. The sequence number is monotonically increasing per connection and resets to 1 on reconnect. Use it both to detect dropped frames and to compute server clock skew.

const STALE_MS = 12_000;   // 2.4× heartbeat cadence
const OFFLINE_MS = 30_000; // 6× heartbeat cadence — force reconnect

let lastBeat = Date.now();
let status: "connecting" | "live" | "stale" | "offline" = "connecting";

const es = new EventSource("/api/public/market/stream?symbols=TOS.HS*");

es.addEventListener("ready",     () => { lastBeat = Date.now(); status = "live"; });
es.addEventListener("snapshot",  () => { lastBeat = Date.now(); });
es.addEventListener("tick",      () => { lastBeat = Date.now(); });
es.addEventListener("heartbeat", (e) => {
  const { seq, serverTime } = JSON.parse(e.data);
  lastBeat = Date.now();
  console.debug("hb", seq, "skew", Date.now() - Date.parse(serverTime), "ms");
});

setInterval(() => {
  const silent = Date.now() - lastBeat;
  if (silent >= OFFLINE_MS) { status = "offline"; es.close(); /* reconnect */ }
  else if (silent >= STALE_MS) { status = "stale"; }
}, 1000);

Connection status semantics

Reconnect policy

Browsers retry EventSource automatically with a 3 s default backoff. For server-side consumers we recommend exponential backoff capped at 30 s with full jitter, plus a hard cap of 1 reconnect / second on a single process to avoid thundering-herd against the edge.

Error responses

Errors return a stable shape. The code field is the contract — do not branch on message, which is for humans.

{
  "error": {
    "code": "tariff_not_found",
    "message": "No tariff schedule for HS 9999.99 on lane XX>US.",
    "request_id": "req_01HZ…",
    "doc_url": "https://docs.tariffos.com/errors#tariff_not_found"
  }
}

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. On 429, respect Retry-After.

All POST endpoints accept an Idempotency-Key header (UUID v4 recommended). Replays within 24 hours return the original response, including status code. Different payloads under the same key return 409 idempotency_conflict.

List endpoints use cursor pagination. Pass ?limit=100&cursor=… — responses include next_cursor when more pages exist. Maximum page size is 500.

A zero-dependency TypeScript client generated from the OpenAPI spec at /api/public/market/openapi. Every SSE frame — ready, snapshot, tick, heartbeat — is a fully typed payload. The client also exposes a derived status stream (connecting | live | stale | offline | closed) backed by heartbeat liveness thresholds, plus exponential-backoff reconnect.

# Single file, no runtime deps — copy into your app:
src/lib/tos-market-sdk.ts

import { createMarketStream } from "@/lib/tos-market-sdk";

const client = createMarketStream({
  baseUrl: "https://tos.sagolik.com",
  symbols: ["TOS.HS*", "TOS.FX.CNH"],
  intervalMs: 1000,
  format: "delta",
});

client.on("ready", (e) => {
  // e.subscription: Subscription   (patterns, categories, intervalMs, format, symbols)
  console.log("subscribed to", e.subscription.symbols.map(s => s.sym));
});

client.on("snapshot", (e) => {
  // e.ticks: Tick[]   { sym, label, category, unit, decimals, open, val, ts }
  hydrate(e.ticks);
});

client.on("tick", (e) => {
  // delta or full depending on options
  for (const t of e.ticks) update(t.sym, t.val);
});

client.on("heartbeat", (e) => {
  // e.seq: number, e.serverTime: ISO string
  setLastBeat(e.serverTime);
});

client.on("status", (s) => {
  // "connecting" | "live" | "stale" | "offline" | "closed"
  setBadge(s);
});

client.connect();

export type Category = "hs" | "fx" | "idx";
export type Unit     = "pct" | "px";
export type Format   = "full" | "delta";
export type Source   = "live" | "synthetic";

export interface SymbolDef     { sym: string; label: string; category: Category; unit: Unit }
export interface Tick          { sym: string; label: string; category: Category; unit: Unit;
                                 decimals: number; open: number; val: number; ts: string }
export interface Subscription  { patterns: string[]; categories: Category[];
                                 intervalMs: number; format: Format; symbols: SymbolDef[] }
export interface ReadyEvent     { subscription: Subscription; serverTime: string }
export interface SnapshotEvent  { source: Source; ts: string; ticks: Tick[] }
export interface TickEvent      { source: Source; ts: string; ticks: Tick[] }
export interface HeartbeatEvent { seq: number; serverTime: string }

export type MarketEvent =
  | ({ type: "ready"     } & ReadyEvent)
  | ({ type: "snapshot"  } & SnapshotEvent)
  | ({ type: "tick"      } & TickEvent)
  | ({ type: "heartbeat" } & HeartbeatEvent);

Need a different language? The OpenAPI document at /api/public/market/openapi is consumable by openapi-generator, openapi-typescript, and orval — all event payloads are defined as named schemas so generated clients keep the same names used here.

Import the live collection — every endpoint, pre-request scripts for HMAC signing, and example sandbox keys.

https://docs.tariffos.com/postman/tariffos.postman_collection.json

The full machine-readable spec — generate clients, mock servers, or contract tests directly from it. The streaming endpoint ships a live, self-hosted spec with typed schemas for every SSE event (ready, snapshot, tick, heartbeat).

GET /api/public/market/openapi
Content-Type: application/json
# Try it:  curl -s /api/public/market/openapi | jq .paths

https://api.tariffos.com/v2/openapi.json
sha256: 9f4c…1ab2

• 2025-04-12ADDEDReciprocal tariff component

  Tariff lookup and landed cost now decompose the new reciprocal-tariff component. Existing fields are unchanged.

• 2025-03-30ADDEDEU residency endpoint

  eu.api.tariffos.com — all data plane traffic stays within EU regions.

• 2025-02-18CHANGEDStable webhook signing v1

  x-tariffos-signature now uses the stable t=…,v1=… format. Legacy x-signature is deprecated for removal 2025-08-01.

• 2025-01-04ADDEDScenario simulate endpoint

  POST /v2/scenarios/simulate — model tariff, FX, and sourcing overrides across portfolios.