Partner API
Top Up
Top Up moves US dollars from the customer’s bank account into their own wallet as a stablecoin. It is a hosted flow: Numerari’s module collects what it needs from the customer and shows the bank instructions. Your server opens a session and follows the order.
How It Works
- Your server calls POST /v1/onramp/sessions for your signed-in customer. You get a client_token.
- Your page loads the Top Up module and passes it only the client_token. Embedding details are shared with you during onboarding.
- The customer picks an amount and a bank rail. The module handles verification steps, shows a quote, and then shows the bank transfer instructions for the order.
- The customer sends the transfer from their bank. When it arrives, the stablecoin is delivered to the wallet you named. You see each step by webhook, or by reading the order.
The destination can never be changed by the browser. The wallet is fixed when you open the session, and the module and the customer only ever see that wallet.
Open a Session
curl -X POST https://api.numerari.io/v1/onramp/sessions \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE" \
-H "Content-Type: application/json" \
-d '{
"external_user_id": "usr_48213",
"first_name": "Jordan",
"last_name": "Rivera",
"email": "jordan.rivera@example.com",
"wallet_address": "0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E"
}'{
"session_id": "ses_01jz8pzk3m5n7q9s1t3v5x7z9b",
"client_token": "nct_EXAMPLE_TOKEN_DO_NOT_USE",
"expires_at": "2026-10-01T16:00:00Z"
}- external_user_id is your stable id for the customer: 1 to 128 characters from A-Z, a-z, 0-9 and _ . : -.
- first_name and last_name are the name the customer is verified under and their bank details are issued in. email is required.
- wallet_address is the customer’s own wallet as an EIP-55 checksummed address. The zero address and the burn address are refused.
- The first call for an external_user_id creates the customer. Until they are verified, a repeat call refreshes their name and email. After that the verified values are kept.
- A different wallet for an existing customer is 409 wallet_mismatch, because the funds land in the stored wallet. Changing it is a support request.
The Client Token
- It starts with nct_ and goes to the browser only. Never log it or put it in a URL.
- It is shown once, in this response. Numerari stores only a hash.
- It expires about 60 minutes after you create it by default, and is not renewed. Read expires_at from the response rather than assuming a lifetime.
- The module reuses the token for that one module session, so do not discard it after the first call. One token is one module session.
- Open a new session each time you open the module, including after a verification step returns the customer to your app.
- An expired, unknown or revoked token makes the module show its expired screen.
Choosing an Asset and Network
Leave asset and network out and the session is for USDC on Base. Name either and the session is locked to that route. Other routes are enabled for you individually.
| Field | Values | Notes |
|---|---|---|
| asset | usdc, usdt | Lower case in requests. Responses use the symbol, USDC or USDT. |
| network | base, ethereum, polygon | Which routes are open to you is part of your agreement. |
- 422 route_not_supported: not a route Numerari offers, or it is switched off. USDT on Base is never offered.
- 422 route_not_enabled_for_partner: offered, but not enabled for you.
- 400 invalid_destination: the wallet cannot be a destination.
- When you name a route, the response also carries asset, network and destination_address (the customer’s own wallet).
The module shows the amount limits for the route and rail. They are returned by the API and can change, so read them rather than copying a number.
Fees
Every quote and order shows its fees as dollar amounts, never as a hidden spread.
| Field | Meaning |
|---|---|
| amount_usdc | What the customer asked to receive. |
| rail_fee_usd | The fee for the bank rail they chose. |
| fees_usd | Network and gas fees. |
| total_usd | What the customer sends from their bank. rail_fee_usd + fees_usd = total_usd − amount_usdc. |
When your session carries a network_fee_bps, fees_usd is split into processing_fee_usd and network_and_gas_fee_usd. Send only a rate your agreement allows, otherwise the session is 422 network_fee_bps_not_allowed. A rate below your standard is for one amount: the session must carry amount_usdc, the most the customer may top up in it, and a quote above that is 422 session_amount_exceeded.
Order Statuses
| Status | Meaning | Webhook type |
|---|---|---|
| awaiting_funds | Bank instructions issued, waiting for the transfer. | onramp_order.awaiting_funds |
| funds_received | The transfer arrived and the funds are on their way. | onramp_order.funds_received |
| delivered | The funds are in the customer’s wallet. tx_hash is the transaction. | onramp_order.delivered |
| cancelled | The customer cancelled, or the order was cancelled. | onramp_order.cancelled |
| expired | The payment window closed with no transfer. | onramp_order.expired |
| failed | Refunded, returned or failed. | onramp_order.failed |
- Statuses only move forward. cancelled, expired and failed are final, and so is delivered.
- An order is delivered only once the funds are in the customer’s own wallet.
- An order that has reached funds_received is never aged out. Its money has arrived, so it stays there until it is delivered or resolved.
- version goes up by one on every public change. Ignore any event or read older than the version you hold.
Read an Order
curl https://api.numerari.io/v1/onramp/orders/ord_01jz8q7b2d4f6h8k0m2p4r6t8v \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE"{
"order_id": "ord_01jz8q7b2d4f6h8k0m2p4r6t8v",
"external_user_id": "usr_48213",
"session_id": "ses_01jz8pzk3m5n7q9s1t3v5x7z9b",
"status": "delivered",
"rail": "ach",
"amount_usdc": "250.00",
"rail_fee_usd": "2.00",
"fees_usd": "4.38",
"total_usd": "256.38",
"delivered_amount_usdc": "250.003700",
"wallet_address": "0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E",
"network": "base",
"asset": "USDC",
"tx_hash": "0x9f2c...9f1a",
"explorer_url": "https://basescan.org/tx/0x9f2c...9f1a",
"created_at": "2026-10-01T15:02:00Z",
"expires_at": "2026-10-08T15:02:00Z",
"funds_received_at": "2026-10-01T15:11:40Z",
"delivered_at": "2026-10-01T15:20:02Z",
"updated_at": "2026-10-01T15:20:02Z",
"version": 3
}- Another partner’s order and an id that does not exist are the same 404 order_not_found.
- Bank deposit instructions are not part of this shape. They belong to the customer and are shown in the module.
- Some stablecoins complete at the quoted estimate. The order then has approximate set to true until the final amount is known.
Errors Specific to Top Up
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_destination | The wallet cannot be a destination. |
| 409 | wallet_mismatch | A different wallet is already on file. |
| 422 | route_not_supported | The asset and network is not offered, or is off. |
| 422 | route_not_enabled_for_partner | Offered, but not enabled for you. |
| 422 | network_fee_bps_not_allowed | The rate is not one your agreement allows. |
| 429 | rate_limited | Too many sessions in a minute. |
| 503 | onramp_unavailable | Top Up is switched off for you. |