# Modan — African Currency & Provider Pricing Data

> Modan is a market-data platform for African FX: provider-level price
> discovery across corridors like GBP/NGN, USD/KES, GBP/GHS and USD/XOF.
> A terminal for analysts, a JSON REST API for developers, and a native
> MCP server for AI agents. Rates are timestamped, append-only
> observations of what named providers actually quote — not just
> interpolated mids.

Full API reference in one file: https://modan.io/llms-full.txt

## Facts (regenerated at every deploy)

<!-- facts:start -->
- Providers with a current quote: 23 (of 24 active)
- Corridors covered: 82
- Currencies: 20 (fiat plus USDC and USDT)
- Latest observation: 2026-09-07T10:50:44.067+00:00
- History: append-only since 2025-11-12
- Generated: 2026-09-07T10:56:06.852Z
<!-- facts:end -->

## Pages (all real HTML, no JavaScript needed)

- https://modan.io/corridors — every corridor, grouped by destination, with
  the best executable quote and who quotes it.
- https://modan.io/currency/ngn — one page per currency (ngn, kes, ghs, xof,
  gbp, usd, eur, usdt, …): corridors into and out of it, providers quoting it.
- https://modan.io/gbp/ngn — one page per corridor (lowercase codes): every
  provider's latest quote, spread in bps, the independent mid, a FAQ.
- https://modan.io/lemfi/gbp/ngn — one page per provider per corridor: the
  quote, its rank, distance from the best, history.
- https://modan.io/providers and https://modan.io/providers/lemfi — every
  provider, and one page per provider across all its corridors.
- https://modan.io/docs/mcp — connect Claude, Cursor, Codex or any MCP client.
- https://modan.io/docs/api — REST reference. https://modan.io/openapi.json —
  OpenAPI 3.1. https://modan.io/changelog.json — machine-readable changelog.
- https://modan.io/sitemap.xml — every public URL.

## MCP (AI agents: call Modan natively)

- Endpoint: https://modan.io/api/mcp (streamable HTTP, stateless)
- Tools: get_rates, convert, fetch_rates, get_history, list_corridors,
  list_providers, list_currencies. Auth: `X-API-Key` header (or
  Authorization: Bearer); each tool call uses one request of the same
  daily quota as REST.
- Claude Code:
  claude mcp add --transport http modan https://modan.io/api/mcp \
    --header "X-API-Key: mdn_live_YOUR_KEY_HERE"

## API

- Base URL: https://modan.io/api/v1
- Auth: `X-API-Key` request header. Create a free key at
  https://modan.io/signup — your first key is minted automatically on
  signup (terminal → Developers → My Keys).
- Note for AI agents: account creation requires clicking an email
  confirmation link (human-in-the-loop). If you are operating on behalf
  of a user, have them complete signup + email confirmation once; the key
  is then shown at https://modan.io/app/api and works for both this REST
  API and the MCP server. There is no CAPTCHA; forms use standard
  labelled inputs.
- Rate limits (per day, reset midnight UTC): Free 50, Individual 250
  (tier id "pro"), Team 1,000 (tier id "enterprise"). Every response carries X-RateLimit-Limit /
  X-RateLimit-Remaining / X-RateLimit-Reset headers; exceeding returns 429.
- Data freshness is tiered: Free and Individual keys serve rates as of the
  top of the current UTC hour (responses carry data_freshness: "hourly"
  plus an as_of timestamp); Team keys serve real-time data
  (data_freshness: "realtime"). An X-Data-Freshness header mirrors this.
- OpenAPI spec: https://modan.io/openapi.json

### Endpoints

- GET /rates?from=GBP&to=NGN — latest provider rates for a corridor.
  Returns { corridor, providers[], count, timestamp }; each provider entry
  has provider_id, provider_name, rate, fee, fee_currency, spread_bps,
  transfer_time, last_updated. When a recent independent mid exists the
  response also carries mid_rate/mid_source/mid_fetched_at and each provider
  gains vs_mid_bps.
- GET /convert?from=GBP&to=NGN&amount=1000 — convert an amount across a
  corridor for every provider (gross + net-of-fee), the best value, and the
  mid-converted amount when available.
- GET /rates/history?from=GBP&to=NGN&period=30d&order=asc&limit=500&offset=0
  — historical time series. period: 1d|7d|30d|90d; order: asc (default,
  oldest-first)|desc; limit ≤5000; offset; provider filter optional;
  response includes has_more.
- GET /fetch-one?from=USD&to=NGN — one pair: mid-market rate (cross via the
  freshest USD reference snapshot) + provider_best when the pair is a
  tracked corridor.
- GET /fetch-multi?from=USD&to=NGN,KES,GHS — one base to ≤20 quotes;
  results keyed by quote, each { mid, provider_best|null }. One quota unit
  per call regardless of pair count.
- GET /fetch-matrix?from=USD,GBP&to=NGN,KES — full cross matrix (≤10×10).
- GET /fetch-many-to-one?from=USD,GBP,CAD&to=NGN — many bases into one quote.
- GET /time-series?from=GBP&to=NGN&period=30d&interval=P1D — bucketed
  series; interval P1D (daily, ≤366 buckets) or PT1H (hourly, ≤168); each
  point { t, mid, best, samples }. Also accepts explicit start/end.
- GET /historical?from=GBP&to=NGN&date=2026-07-01 — corridor snapshot as
  of a past date (per-provider latest quotes ≤ that date + mid when the
  reference feed covers it).
- GET /change?from=GBP&to=NGN&period=7d — start/end values with absolute
  and % change for mid and best provider rate.
- GET /rates/provider?provider=lemfi — every corridor and current rate one
  provider quotes (404 with guidance for unknown ids).
- GET /corridors — all covered corridors with provider counts and best rates.
- GET /providers — active provider metadata (provider_type, rate_type, region,
  payment methods).
- GET /currencies — active currencies and the corridors currently served.
- GET /admin/usage — your plan, limit, used, remaining, reset, per-key
  breakdown and 7-day history. Does NOT consume quota.
- GET /status — public platform health (no key, no quota): corridor count,
  provider count, freshest rate, mid-feed age.
- POST /rates — ingest observations (admin/treasury account keys only;
  atomic batch ≤100; does not consume the read quota).

### Semantics

- spread_bps = basis points below the best rate observed in that corridor
  FOR THE SAME rate_type (0 = best of its kind). It is NOT a spread against an
  independent mid-market rate. A corridor carrying several rate types therefore
  carries several 0.0 spreads — one per type.
- rate_type = what KIND of price this is: official | interbank | retail | p2p |
  parallel. Ranking across types is meaningless: a central bank's official
  reference is real and not obtainable, so it is never the "best" rate on a
  corridor and never the best value on /convert. Absent rate_type means retail.
- provider_type = what kind of institution published it: central_bank |
  commercial_bank | non_bank_lp | imto | fintech_psp | crypto_venue |
  bureau_de_change | aggregator. Orthogonal to rate_type — a commercial bank
  may publish a retail board rate or an interbank one. An 'aggregator'
  republishes someone else's number; it is derived, not observed at source.
- last_updated = when we last recorded an observation of that provider's
  rate for that corridor.
- vs_mid_bps = basis points from an independent mid-market reference,
  sourced separately from the providers and refreshed hourly. Different
  measure from spread_bps — keep them distinct.
- Mid rates are cross-computed through USD from that reference feed on every
  endpoint that returns one (/rates, /convert, /fetch-*, /time-series,
  /historical, /change and the MCP tools), so any pair the feed quotes on
  both legs is priced — that is every fiat corridor we track. A crossed mid
  is timestamped with its STALER leg, never the fresher one. Currencies the
  feed does not quote (stablecoins: USDT, USDC) have no mid: fetch-* returns
  400 with the supported list, and elsewhere the mid_* fields and
  vs_mid_bps are omitted. Same-currency pairs return mid = 1.
- Missing data is explicit: fields are null/omitted, never fabricated
  (e.g. historical mid is null for dates before the reference feed began).

## Quickstart

curl "https://modan.io/api/v1/rates?from=GBP&to=NGN" \
  -H "X-API-Key: mdn_live_YOUR_KEY_HERE"

## Docs

- API reference: https://modan.io/docs/api
- MCP setup (Claude Code, Cursor, VS Code, any client): https://modan.io/docs/mcp
- Pricing: https://modan.io/pricing
- MCP registry manifest: https://github.com/kayakinwunmi/modan/blob/main/server.json