# nairarate.dev

> Nigerian FX intelligence across three markets in one call: the CBN official
> rate, the parallel ("black market") rate, and USDT/USDC street prices — plus
> the spreads between them, 7-day trends, and a confidence score.

Paid per call in USDC on Base via the x402 protocol (eip155:8453). No API key, no
account, no subscription. All rates are NGN per unit of the quoted currency.

## Why this exists

No global FX API publishes Nigeria's parallel market rate or USDT/NGN street
price. Frankfurter, ExchangeRate-API and similar carry the official mid only. The
spread between official, parallel and stablecoin rates is the signal that matters
for anything priced in or around naira, and it is not otherwise available as a
structured API.

## Endpoints

GET /health                 Free. Per-source freshness. Check before paying.
GET /v1/rates               $0.03. All markets and currencies, spreads, 7-day trends.
                            ?currencies=USD,USDT   optional filter
                            ?markets=official|parallel|crypto_street|all
GET /v1/rates/history       up to $0.05. Daily series for one currency and market.
                            ?currency=USD (required)
                            ?market=official|parallel|crypto_street (required)
                            ?days=1..365 (default 7)

  Pricing scales with the window, via the `upto` scheme:
    1-7d $0.01, 8-30d $0.02, 31-90d $0.03, 91-365d $0.05
  The amount settled is echoed in the x-settlement-usd response header.
  Paying with `exact` instead settles the $0.05 cap regardless of window —
  `exact` is offered only because it is more widely implemented.
GET /.well-known/x402       Free. Machine-readable manifest.
GET /methodology            Free. How the rates are derived and screened.

## Coverage is asymmetric — read this before requesting

Official + parallel:  USD, EUR, GBP, CAD, AED, CNY, ZAR, XOF, XAF
Stablecoin street:    USDT, USDC
Official only:        CHF, JPY, DKK, SAR

Requesting a market a currency does not carry — or a window with no rows —
returns 400 with an explanation. No payment is settled on a 4xx: the verified
payment is cancelled rather than captured, so you are never charged for an empty
result. Currencies without a counterpart market report null for that market and a
null spread — never a fabricated value.

Official history reaches back to 2001-12-10. Parallel and street history
accumulates from this deployment's first daily roll-up, so it is shallower.

## Conventions

bid   NGN received per unit of foreign currency (the low side)
ask   NGN paid per unit of foreign currency (the high side)
mid   midpoint, or the single published rate where only one side exists

provider_count is the number of independent street quotes behind a parallel rate.
It ranges from 43 (USD) down to 1 for thinly quoted currencies — check it before
relying on a rate.

confidence is high | medium | low | degraded, from source freshness. Data is
always returned, even at degraded: a stale rate is more useful to an agent
mid-task than an error. warnings explains any downgrade.

## Notes

- CBN publishes weekdays only, and partially — some currencies lag others by a
  day. Each carries its own updated_at.
- Parallel rates are screened before aggregation: the central bank and reference
  feeds quote inside the upstream provider list, and remittance corridors report
  a missing side as zero. Unscreened, USD reads ~1181 against a true ~1392.
  See https://nairarate.dev/methodology.

## Example

  curl https://nairarate.dev/health
  curl https://nairarate.dev/v1/rates?currencies=USD,USDT