Developers
Partner API
The Partner API lets your app offer Top Up, Cash Out and Swap to your own customers. Your server calls Numerari; Numerari never holds the customer's funds and never takes custody of their wallet. The base URL is https://api.numerari.io.
What You Can Offer
| Product | What it does | How it works |
|---|---|---|
| Top Up | US dollars from the customer’s bank account to their own wallet. | A hosted flow. Your server opens a session and hands one token to the Top Up module in your page. |
| Cash Out | Stablecoins from the customer’s own wallet to their own US bank account. | Driven by your screens. Your server opens a session, adds a bank account, prices a quote and places an order. |
| Swap | One token for another, inside the customer’s own wallet. | Your server opens a session and hands one token to the Swap module in your page. The customer’s wallet signs. |
Getting Access
Partner access is set up with us during onboarding. We issue you a partner API key, a webhook signing key, and turn on the products and routes your agreement covers. Ask at support@numerari.io.
- Test and live are separate keys. A test key starts with npk_test_ and a live key with npk_live_.
- Keys stay on your server, in a secret store. Never put one in a browser, a mobile app, a repository or a log.
- Numerari stores only a hash of your key, and a key can be rotated with an overlap so nothing stops.
Authentication
Send your key on every request.
curl https://api.numerari.io/v1/offramp/kyc/requirements \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE"A missing, unknown or revoked key is 401 unauthorized with no detail about which it was. These routes send no CORS headers, so a browser cannot call them.
Conventions
| Topic | Rule |
|---|---|
| Format | JSON in and out. Unknown request fields are refused with 400 validation_error, and the response never repeats what you sent. |
| Money | Decimal strings, never JSON numbers. Cash Out amounts have two decimals. Top Up delivered_amount_usdc has six, the exact amount that reached the wallet. |
| Ids | Opaque and prefixed: ses_, ord_ and evt_ for Top Up; ofs_, bnk_, ofq_ and ofo_ for Cash Out; sws_ for a Swap session and swo_ for a Swap order. Treat them as strings. |
| Times | RFC 3339 UTC with a Z. |
| Headers | Every Top Up and Cash Out response carries Request-Id, which you can quote to support, and Cache-Control: no-store. Swap responses carry Cache-Control: no-store but no Request-Id: quote the ref (N2xx) of a Swap error to support instead. |
| Nullable fields | Present with the value null, never left out. |
| Rate limits | 429 rate_limited with a Retry-After header, in seconds. |
| Test mode | A Cash Out quote or order has provider_mode of mock or live. Never show or send funds to a mock order outside your own development or staging environment. |
Errors
Every Top Up and Cash Out error has the same nested shape, shown below. Swap errors are flat (type, code, message, ref) and are documented on the Swap page. Branch on code, never on message.
{
"error": {
"code": "validation_error",
"message": "Some details look incomplete. Check them and try again. (N2)",
"fields": ["wallet_address"],
"ref": "N2"
}
}- fields lists field paths only, never values.
- ref is a permanent reference such as N23. It is also at the end of message in brackets. Give it to support and they can name the exact failure. References are never renumbered or reused.
- A provider failure is 502 provider_error. The provider’s own wording is never passed through. It is temporary, so retry.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | validation_error | A field is missing or invalid. fields names it. |
| 401 | unauthorized | Bad or missing key. |
| 404 | order_not_found | Unknown id, or another partner’s order. |
| 409 | wallet_mismatch | A different wallet is already on file for this customer. |
| 409 | identity_required | The customer is not verified, or verification was withdrawn. |
| 422 | amount_out_of_range | The amount is outside the allowed range. The message names the range. |
| 422 | route_not_supported | The asset and network is not offered, or is switched off. |
| 422 | network_fee_bps_not_allowed | The rate is not one your agreement allows. |
| 429 | rate_limited | Wait Retry-After seconds. |
| 502 | provider_error | A temporary failure. Retry. |
| 503 | onramp_unavailable, offramp_unavailable | The product is switched off for you. |
Each product page lists the codes that are specific to it.
Webhooks
For Top Up and Cash Out, Numerari sends every public status change of an order to your webhook URL, which must be https. Swap sends no webhook events. Headers are Numerari-Event-Id and Numerari-Signature, in the form t=<unix seconds>,v1=<hex>.
- Verify against the raw bytes, before you parse the JSON. v1 is the hex HMAC-SHA256 of "<t>.<raw body>" under your webhook key.
- Compare in constant time, and reject the event when the time is more than 300 seconds from now.
- Dedupe on the event id.
- Apply an order only when data.order.version is higher than the one you hold. Delivery order is not guaranteed.
- Return any 2xx to mark an event delivered. Each attempt has a 10 second timeout. Anything else is retried after 1 minute, 5, 15, 1 hour, 3, 6, then every 6 hours, for 72 hours, then abandoned.
- Never in a webhook: bank details, identity details, or the ids of any provider.
Verifying a Signature
import { createHmac, timingSafeEqual } from 'node:crypto'
// rawBody: the exact bytes you received (a Buffer), before any JSON parsing.
// header: the Numerari-Signature header, "t=<unix seconds>,v1=<hex>".
export function verify(rawBody, header, webhookKey) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const t = Number(parts.t)
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false
const expected = createHmac('sha256', webhookKey)
.update(t + '.')
.update(rawBody)
.digest('hex')
const a = Buffer.from(expected, 'hex')
const b = Buffer.from(parts.v1 ?? '', 'hex')
return a.length === b.length && timingSafeEqual(a, b)
}You can rotate a webhook key without downtime. During a rotation, accept a signature that matches either the current or the previous key.
Going Live
- Build against a test key until a full Top Up and a full Cash Out work end to end.
- Check that your webhook handler verifies the signature, dedupes, and ignores stale versions.
- Check that you refuse to show or send funds to an order with provider_mode of mock.
- Store no bank account number, routing number, SSN or document image. Numerari does not, and your app should not.
- Ask support@numerari.io to switch on the live key, your webhook URL and the routes you need.