Bollard · official customs exchange rates

Official rates in. Compliance out. Bollard serves the exchange rates governments legally require for customs filings — scraped from official portals, normalized, and delivered with a paper trail. These are not market rates: customs authorities publish their own rates on their own schedules, and filings must use them.

Quickstart

curl "https://<api-base>/v1/rates?country=GB¤cy=EUR&date=2026-07-01" \
  -H "Authorization: Bearer blrd_live_…"

{
  "country": "GB",
  "currency": "EUR",
  "rate": "1.1564",
  "authority": "UK HMRC",
  "effective_from": "2026-07-01",
  "effective_to": "2026-07-31",
  "published_at": "2026-06-18",
  "source_url": "https://www.trade-tariff.service.gov.uk/exchange_rates/view/2026-7",
  "freshness": "current"
}

Every response carries its own evidence — the authority, the effective window (inclusive on both ends, as authorities publish them), the publication date, and a link to the government's own page. Rates are decimal strings; nothing is ever a float.

Endpoints

Endpoint	What it answers
`GET /v1/rates`	The official rate for `country` + `currency` on `date` (default: today). Historical dates are always answerable — the ledger is append-only.
`GET /v1/rates/latest`	Everything a filer must use today for a country — never a future-dated early publication.
`GET /v1/countries`	Coverage: jurisdictions, authorities, currency counts, freshness.
`GET /v1/freshness`	The freshness ledger: per-country data age vs the authority's schedule.

Full schema: openapi.yaml.

Authentication

Bearer API keys: Authorization: Bearer blrd_live_…. Keys are stored only as SHA-256 hashes — we cannot see or recover your key; if lost, we mint a new one.

Freshness — read this before integrating

Each country's data has a publication cadence (how often the authority publishes) plus a grace allowance. Within that budget, responses say "freshness": "current". If a new publication is overdue, Bollard keeps serving the last official rate — it is usually still the legally correct one — but flips "freshness": "stale" so your compliance policy decides. Bollard never silently serves aged data, and never invents a rate.

Coverage (Phase 1)

Country	Authority	Schedule	Currencies
GB	UK HMRC	Monthly — penultimate Thursday, effective the following month	141
EU	European Central Bank (UCC IA Art. 146)	Monthly — penultimate Wednesday's reference rates, effective the following month	29

Source research dossiers: docs/sources/ in the repo. US CBP is next on the roadmap (its public feed moved into ACE in late 2025 — see the dossier).

Client guidance

Rates change at most monthly per country — cache responses and be gentle.
Retry 429/503 with exponential backoff + jitter, honoring Retry-After.
Alert on freshness != "current" if your filings are time-sensitive.

Bollard · a Maddox Hub product · dev preview