Currencies and countries introduction

This is the smallest service in the API and the one most worth reading before you write anything else. Four read-only endpoints, no state, no events — and between them they determine whether every other call you were planning to make can succeed.

The problem it solves

Sakawave can switch things off. A currency can stop accepting new accounts; a payout route can be withdrawn; a jurisdiction can become unserviceable. None of that is a failure of your integration, but all of it surfaces as an error in the middle of one — usually a 409 several calls into a flow that a user is waiting on. Reference data moves those decisions to the front:

Without it	With it
Open an account, get `409 currency_capability_unavailable`	Show only currencies with `accountIssuanceEnabled`
Build a payout form, discover the route wants a `bankCode` you never collected	Read `fieldDescriptors` and render exactly those fields
Create a customer, get rejected on `jurisdiction`	Populate the country picker from `GET /countries`
Attempt a conversion, get `409 fx_corridor_unavailable`	Check `fxEnabled` on both currencies first

When to read it

At build time, to understand the model. At runtime, cached — daily is fine for countries and currencies, and per-session is fine for routes. What you should not do is call these on every request. Nothing here changes between two calls a second apart; it changes when Sakawave deploys.

What “capability” means, and does not

A capability is a platform switch: is this currency usable for this kind of operation, for anyone. It is not a statement about your business. Your own permission is a separate question, decided by your verification, your international access, and your tier. Each is checked at a different point and fails differently:

Check	When	Failure
Platform capability	Opening an account, transferring, converting	`409 currency_capability_unavailable`
Your verification and international access	Issuing details on a non-NGN account	`403` with `code` `kyc_approval_required`, `international_questionnaire_required`, or `international_account_approval_required`
Your tier	Sending money, and deposits through account details	`403` with `reason: currency_not_available`

So accountIssuanceEnabled: true on USD means you can open a USD account. Whether you can fund it and move money through it is the accounts service’s answer.

Countries are about onboarding, not payouts

The country list answers “will Sakawave onboard someone here?” — it feeds jurisdiction on a customer and country on an address. It does not answer “can I pay someone here?”. That is a route question, and the two lists are different: a country can be perfectly onboardable with no payout route, and a route’s country coverage comes from its scheme rather than from this list.

The shape of the API

Four operations, all reads, none of them taking a body.

Operation	Auth	Rate
`GET /v1/currencies`	API key	600/min
`GET /v1/currencies/{code}/routes`	API key	600/min
`GET /v1/transfer-corridors`	API key	120/min
`GET /countries`	None	—

Corridors is the expensive one, at a fifth of the read allowance, because it resolves currencies and countries for every route. Cache it accordingly.

Getting Started

Platform Guides