# usaref — North American government reference data

No account. No API key. No signup. Pay per call with x402.

Clean, cited JSON for North American government reference values — central-bank
policy rates, VAT, minimum wages, CPI inflation, corporate & personal income tax,
and public holidays across 10 countries. Every response includes the
official source URL, effective date, last_confirmed date and a stale flag.

## If you sell over x402, start here
Making a cross-border digital sale? Before you settle, know who accounts for the VAT:
- POST https://usaref.dev/v1/vat/determine {seller_country, buyer_country, buyer_type?}
  → place of supply, who accounts for VAT, rate basis, registration trigger — each
    cited to the statute (EU / UK / South Africa). Wallet-only buyer with no tax id →
    treated as B2C and flagged. Out-of-scope country pairs are refused FREE (422),
    never guessed. $0.10/call.

## Sources & licence
Every value is compiled from official government sources — central banks,
finance and labour ministries, revenue authorities, statistical offices — and
each response cites the exact official source URL it was verified against.
Independent service, not affiliated with any government. Verify against the
cited official source before legal or financial use.

## How to call a paid endpoint (x402)
1. Call the endpoint with no payment. You get HTTP 402. The payment challenge is in the
   base64-encoded `payment-required` RESPONSE HEADER (the body is an empty `{}`); decode it to see
   price, asset (USDC), network (eip155:8453 = Base) and pay-to address.
2. Sign the payment with any x402 client — @x402/fetch wraps fetch and does
   steps 1-3 automatically.
3. Retry with the signed X-PAYMENT header. You get HTTP 200 + the data;
   the settlement receipt is returned in the PAYMENT-RESPONSE header.
Bad input is rejected FREE (4xx before the payment gate) — you never pay to fail.
Free, no payment: https://usaref.dev/catalog · https://usaref.dev/llms.txt · https://usaref.dev/openapi.json · public holidays.

## Pricing ladder
- $0.001/call — any single series value, its history, or the change feed
- $0.02 — full regional snapshot (/v1/all) · VAT breakdown · working-days calculator
- $0.05 — minimum-wage compliance check · income-tax computation
- $0.10 — gross-to-net payroll (NG, KE) · cross-border VAT determination · webhook alerts
Licensed tiers / API keys: api@3l-groupconsulting.co.za

## Machine-readable discovery
- x402 resource map: https://usaref.dev/.well-known/x402.json
- Agent card: https://usaref.dev/.well-known/agent.json
- OpenAPI: https://usaref.dev/openapi.json
- MCP server (streamable HTTP): https://usaref.dev/mcp — tools: list_series, get_public_holidays (free); get_series, get_series_history, get_snapshot (paid via x402 or api_key)


## Sub-national holiday calendars
Public holidays are not national in every country. Where a region sets its own days we hold them
separately, each cited to that region's own statute rather than inferred from the national list.
The two endpoints expose this differently, and the difference matters:
- GET https://usaref.dev/v1/{country}/public-holidays (free) returns the NATIONAL days in `value`, plus every
  region inline under `subdivisions`, keyed by ISO 3166-2 (the scheme is named in
  `subdivisions_standard`). Each region's list contains only that region's ADDITIONAL days — it is
  not a merged calendar, so a full regional calendar is `value` plus that region's entries. This
  endpoint does NOT take a `subdivision` query parameter; passing one has no effect.
- POST /v1/answers/working-days DOES take `subdivision`. Give it an ISO 3166-2 code and the count
  is computed on (national − that region's exclusions) + that region's own days. Omit it for the
  national calendar. An unrecognised code is refused FREE with `available_subdivisions` listed —
  we never silently fall back to the national calendar, because that would quietly hand you the
  wrong working-day count.
Regions currently held:
- Canada (ca): 13 regions — CA-ON, CA-QC, CA-BC, CA-AB, …
- United States (us): 10 regions — US-CA, US-TX, US-FL, US-NY, …

## Calendar coverage, and what we refuse
Holiday calendars currently span 2026–2027. Coverage is not uniform and the API tells you so
rather than guessing:
- A range outside a country's covered years is refused FREE (422, `calendar_coverage_exhausted`)
  with the exact covered period. We do not extrapolate: moving feasts, weekend-substitution days
  and ad-hoc proclamations are not derivable from prior years, so counting uncovered days would
  silently treat public holidays as working days.
- Some entries carry `date: null` with a `pending_window`: the holiday is statutory but the date
  is not yet gazetted. We publish the placeholder rather than inventing a date.
- Holiday entries may carry a `note` explaining how that day behaves in that specific year
  (substitution, transfer, or why it was NOT moved). The `name` field is the stable holiday
  name and is safe to match on across years; `note` is the year-specific commentary.

## What we refuse to answer (and never charge for)
Refusals are the point of this service, not a limitation of it. Every one below is FREE — validated
before the payment gate, so you are never charged for a question we know we cannot answer well:
- Out-of-coverage calendar ranges (above).
- Unknown subdivision codes on POST /v1/answers/working-days, with the valid list returned.
- Countries where no single statutory rate exists (e.g. a VAT regime mid-transition) — refused
  with the explanation rather than collapsed to one misleading number.
- Out-of-scope country pairs on /v1/vat/determine.
- Settlement dates where we hold no verified convention for the market, or where the convention
  was not in force on the trade date — `no_verified_convention` /
  `convention_not_in_force_on_trade_date`, never a guessed cycle.
Some series are deliberately ABSENT for the same reason: where a rate could not be verified against
its own statute we omit the series rather than estimate it, and the endpoint 404s.

## Series
- GET /v1/bs/policy-rate — The Bahamas: Central Bank of The Bahamas Discount Rate (Bank Rate)
- GET /v1/bs/vat — The Bahamas: VAT standard rate
- GET /v1/bs/minimum-wage — The Bahamas: National minimum wage (weekly)
- GET /v1/bs/public-holidays — The Bahamas: Public holidays (free)
- GET /v1/bs/cpi — The Bahamas: CPI inflation (year-on-year)
- GET /v1/bs/corporate-tax — The Bahamas: Corporate income tax rate
- GET /v1/bs/income-tax — The Bahamas: Personal income tax brackets
- GET /v1/ca/policy-rate — Canada: Policy Interest Rate
- GET /v1/ca/vat — Canada: Goods and Services Tax (GST)
- GET /v1/ca/minimum-wage — Canada: Federal Minimum Wage
- GET /v1/ca/public-holidays — Canada: General (Statutory) Holidays (free)
- GET /v1/ca/cpi — Canada: Consumer Price Index (Inflation Rate)
- GET /v1/ca/corporate-tax — Canada: Federal Corporate Income Tax Rate
- GET /v1/ca/income-tax — Canada: Federal Personal Income Tax Rates
- GET /v1/ca/fx-reference — Canada: Bank of Canada exchange rates
- GET /v1/cr/policy-rate — Costa Rica: BCCR monetary policy rate (TPM)
- GET /v1/cr/vat — Costa Rica: IVA standard rate
- GET /v1/cr/minimum-wage — Costa Rica: Minimum wage (lowest generic monthly rate)
- GET /v1/cr/public-holidays — Costa Rica: Public holidays (free)
- GET /v1/cr/cpi — Costa Rica: CPI inflation (year-on-year)
- GET /v1/cr/corporate-tax — Costa Rica: Corporate income tax rate
- GET /v1/cr/income-tax — Costa Rica: Personal income tax brackets
- GET /v1/do/policy-rate — Dominican Republic: BCRD monetary policy rate (TPM)
- GET /v1/do/vat — Dominican Republic: ITBIS standard rate
- GET /v1/do/minimum-wage — Dominican Republic: Minimum wage (lowest non-sectorized tier — microempresas)
- GET /v1/do/public-holidays — Dominican Republic: Public holidays (free)
- GET /v1/do/cpi — Dominican Republic: CPI inflation (year-on-year)
- GET /v1/do/corporate-tax — Dominican Republic: Corporate income tax rate
- GET /v1/do/income-tax — Dominican Republic: Personal income tax brackets
- GET /v1/gt/policy-rate — Guatemala: Banguat tasa de interés líder de política monetaria
- GET /v1/gt/vat — Guatemala: IVA standard rate
- GET /v1/gt/minimum-wage — Guatemala: Minimum wage (lowest rate in the activity x circumscription matrix)
- GET /v1/gt/public-holidays — Guatemala: Public holidays (free)
- GET /v1/gt/cpi — Guatemala: CPI inflation (year-on-year)
- GET /v1/gt/corporate-tax — Guatemala: Corporate income tax rate
- GET /v1/gt/income-tax — Guatemala: Personal income tax brackets
- GET /v1/hn/policy-rate — Honduras: Tasa de Política Monetaria (TPM)
- GET /v1/hn/vat — Honduras: Impuesto Sobre Ventas (ISV)
- GET /v1/hn/minimum-wage — Honduras: Salario Mínimo
- GET /v1/hn/public-holidays — Honduras: Días Feriados Nacionales (free)
- GET /v1/hn/cpi — Honduras: Inflación Interanual (IPC)
- GET /v1/hn/corporate-tax — Honduras: Impuesto Sobre la Renta - Personas Jurídicas
- GET /v1/hn/income-tax — Honduras: Impuesto Sobre la Renta - Personas Naturales (Tabla Progresiva 2026)
- GET /v1/mx/policy-rate — Mexico: Banxico overnight target rate
- GET /v1/mx/vat — Mexico: IVA standard rate
- GET /v1/mx/minimum-wage — Mexico: General minimum wage (daily)
- GET /v1/mx/public-holidays — Mexico: Public holidays (free)
- GET /v1/mx/cpi — Mexico: CPI inflation (year-on-year)
- GET /v1/mx/corporate-tax — Mexico: Corporate income tax rate
- GET /v1/mx/income-tax — Mexico: Personal income tax brackets
- GET /v1/mx/fx-reference — Mexico: Banxico FIX exchange rate
- GET /v1/pa/policy-rate — Panama: Monetary policy rate
- GET /v1/pa/vat — Panama: ITBMS (VAT) standard rate
- GET /v1/pa/minimum-wage — Panama: Minimum wage (lowest general statutory floor)
- GET /v1/pa/public-holidays — Panama: National public holidays (free)
- GET /v1/pa/cpi — Panama: CPI inflation (year-over-year)
- GET /v1/pa/corporate-tax — Panama: Corporate income tax (ISR personas jurídicas)
- GET /v1/pa/income-tax — Panama: Personal income tax (ISR personas naturales)
- GET /v1/sv/policy-rate — El Salvador: Central bank policy rate
- GET /v1/sv/vat — El Salvador: VAT (IVA) standard rate
- GET /v1/sv/minimum-wage — El Salvador: Minimum wage (lowest general statutory floor)
- GET /v1/sv/public-holidays — El Salvador: Public holidays (free)
- GET /v1/sv/cpi — El Salvador: CPI inflation (year-on-year)
- GET /v1/sv/corporate-tax — El Salvador: Corporate income tax (ISR) standard rate
- GET /v1/sv/income-tax — El Salvador: Personal income tax (ISR) brackets
- GET /v1/us/policy-rate — United States: Federal funds target range (upper bound)
- GET /v1/us/vat — United States: Value added tax
- GET /v1/us/minimum-wage — United States: Federal minimum wage (FLSA)
- GET /v1/us/public-holidays — United States: Federal public holidays 2026 (free)
- GET /v1/us/cpi — United States: Consumer Price Index (CPI-U), 12-month change
- GET /v1/us/corporate-tax — United States: Federal corporate income tax rate
- GET /v1/us/income-tax — United States: Federal individual income tax brackets (single filer, tax year 2026)

History: GET /v1/{country}/{series}/history?from=YYYY-MM-DD&to=YYYY-MM-DD — e.g. GET /v1/bs/policy-rate/history?from=2026-01-01
Changes + freshness (FREE, unmetered): GET /v1/changes?since=YYYY-MM-DD — what changed, plus how many of our 72 series were re-verified against their official source in the last 1/7/30/90 days, and which one has gone longest without a check. `since` is optional (defaults to 30 days).

## Answers (computed verdicts, POST JSON)
- POST /v1/answers/wage-check {country, amount, period, schedule?} — at/above/below the statutory minimum? Pass "schedule" to be measured against a sectoral/zonal/grade floor instead of the general one (Kenya 55, South Africa 24); omit it and we say so, because "above the national floor" is not "compliant". Keys: GET /catalog ($0.05)
- POST /v1/answers/vat {country, amount, mode?, band?} — net/tax/gross breakdown incl. levy components. Pass "band" for a statutory reduced/zero/super-reduced rate; we publish what each band covers in the authority's own words but do not classify supplies into bands. Keys: GET /catalog ($0.02)
- POST /v1/answers/working-days {country, from, to} — working days, holidays hit, next working day ($0.02)
- POST /v1/answers/income-tax {country, taxable_income} — statutory income tax + per-bracket workings ($0.05)
- POST /v1/answers/settlement-date {trade_date, calendars[], business_days | market + instrument_class} — settlement/value date: T+n business days across one or more national statutory calendars intersected, with a per-day trail, each calendar's basis and source, and the market cycle cited to its primary instrument where we hold one ($0.05). Cited cycles and what we deliberately refuse to cite: GET /settlement-conventions (free)
- POST /v1/vat/determine {seller_country, buyer_country, buyer_type?} — cross-border VAT treatment of a digital-services sale: place of supply, who accounts, rate basis, registration trigger, with the applied rule cited to the statute. EU, UK, South Africa; unknown buyer → B2C-default, flagged; out-of-scope pairs refused FREE (422), never guessed, never charged ($0.10)