Partner API
Swap
Swap lets a customer exchange one token for another inside their own wallet. Your server opens a session. The customer’s browser, through the Numerari swap module, prices the swap and places it. The customer’s wallet signs and sends it. Numerari never holds the funds.
How It Works
- Your server calls POST /v1/swap/sessions for your signed-in customer, naming the token they pay with and the token they get. You receive a client_token.
- Your page hands only the client_token to the Numerari swap module. Embedding details are shared with you during onboarding.
- The module, in the customer’s browser, shows a price, places the order and asks the customer’s wallet to sign. Those calls go from the browser to Numerari with the client token, never with your key.
- The customer’s wallet signs and sends the transaction itself. Numerari never holds the funds and never has the customer’s keys.
The wallet is fixed when you open the session, and the module only ever works with that wallet. The browser cannot change it.
Authentication
- The three server routes on this page take your partner API key, the same key you use for Top Up and Cash Out: Authorization: Bearer <key>. Keep it on your server.
- The server routes send no CORS headers, so a browser cannot call them.
- The browser routes take the short-lived client token from the session, as Authorization: Bearer <client_token>. The module sends it. You do not call these routes yourself.
- A missing, unknown or revoked key is 401 unauthorized, with no detail about which it was. While Swap is switched off for the whole service, the answer is 503 swap_unavailable before the key is checked.
Routes and Availability
A route is one token on one network for another token on one network, for example USDC on Base for ETH on Base. You name it in the session request with from and to. The first route Numerari offers is USDC for ETH on Base.
- Supported routes are per partner. Treat the list as something Numerari enables for you, and ask us which routes your agreement covers.
- A request for a route that is not enabled for you answers 422 swap_no_route. It does the same for a pair Numerari does not offer, so do not retry it.
- Nothing else in the request names a token, a network or a destination. Numerari takes them from the route.
When Swap Is Switched Off
- Swap switched off for the whole service: all three server routes answer 503 swap_unavailable, before your key is checked.
- Swap switched off for your account: POST /v1/swap/sessions answers 503 swap_unavailable, after your key, the rate limit and the body have been checked. GET /v1/swap/sessions/{session_id} and GET /v1/swap/orders keep answering, so you can still read what already exists.
- Your partner account disabled: all three server routes answer 503 swap_unavailable, not 401.
Open a Session
curl -X POST https://api.numerari.io/v1/swap/sessions \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE" \
-H "Content-Type: application/json" \
-d '{
"user_id": "usr_48213",
"wallet_address": "0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E",
"from": { "network": "base", "symbol": "USDC" },
"to": { "network": "base", "symbol": "ETH" }
}'It answers 201 Created.
{
"session_id": "sws_EXAMPLE_SESSION_ID",
"route": "usdc_base_to_eth_base",
"client_token": "nsw_EXAMPLE_TOKEN_DO_NOT_USE",
"expires_at": "2026-10-01T16:20:00Z"
}| Field | Rules |
|---|---|
| user_id | Your stable id for the customer. 1 to 128 characters from A-Z, a-z, 0-9 and . _ : @ + -. |
| wallet_address | The customer’s own wallet, as a 0x address of 40 hex characters. The zero address and the burn address are refused. |
| from, to | Objects with network and symbol, for example base and USDC. Matched without regard to case. |
- All four fields are required, and any other field is refused with 400 validation_error. The response never repeats what you sent.
- The body is read first: invalid JSON or an unknown field is 400 validation_error. Then the route is checked: a from or to that is missing or empty, or a route that is not offered to you, is 422 swap_no_route. Only after that are user_id and wallet_address checked, and a missing or invalid one is 400 validation_error.
- Opening a session does not move any funds.
- route in the response is the name of the route the session is locked to.
- Opening sessions is rate limited per partner. A 429 rate_limited carries a Retry-After header, in seconds. The rate limit is checked after your key and before the body is read, so a 429 can come before a 400.
The Client Token
- It starts with nsw_ and goes to the customer’s browser only. Never log it or put it in a URL.
- It is shown once, in this response. Numerari stores only a hash, and GET /v1/swap/sessions/{session_id} never returns it.
- It is short-lived. Read expires_at from the response rather than assuming a lifetime. The module can still read and finish an order it already placed for some time after that, but new prices and new orders need a session that has not ended.
- Open a new session each time you open the module. An unknown, ended or malformed token is 401 session_expired on the browser routes.
Read a Session
curl https://api.numerari.io/v1/swap/sessions/sws_EXAMPLE_SESSION_ID \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE"{
"session_id": "sws_EXAMPLE_SESSION_ID",
"route": "usdc_base_to_eth_base",
"user_id": "usr_48213",
"wallet_address": "0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E",
"expires_at": "2026-10-01T16:20:00Z"
}- It returns your own sessions only. An unknown id and another partner’s session are the same 404 not_found.
- It tells you which customer, wallet and route a session is for. It does not carry the swap itself or its status. Read the swaps with GET /v1/swap/orders.
List Swaps
Your server can read the swaps one of your customers has placed. Both user_id and wallet_address are required, and the list is only ever answered for that user and that wallet.
curl "https://api.numerari.io/v1/swap/orders?user_id=usr_48213&wallet_address=0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E&limit=20" \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE"It answers 200 OK with the newest swap first. A customer with no swaps gets an empty list.
{
"items": [
{
"order_id": "swo_EXAMPLE_ORDER_ID",
"status": "completed",
"route": "usdc_base_to_eth_base",
"user_id": "usr_48213",
"wallet_address": "0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E",
"pay": { "amount": "25", "symbol": "USDC", "network": "base" },
"get": { "amount": "0.0071", "symbol": "ETH", "network": "base" },
"created_at": "2026-10-01T16:00:00Z",
"updated_at": "2026-10-01T16:05:00Z"
}
]
}| Query parameter | Rules |
|---|---|
| user_id | Required. The id you sent when you opened the session: 1 to 128 characters from A-Z, a-z, 0-9 and . _ : @ + -. Matched exactly. |
| wallet_address | Required. A 0x address of 40 hex characters, matched without regard to letter case. |
| limit | Optional. A whole number of 1 or more. Without it you get up to 50 swaps. A larger number is cut to 100, the most one answer returns, but a number too large to read as a whole number is 400 validation_error. Anything else is 400 validation_error. |
| Field | Meaning |
|---|---|
| order_id | The swo_ id of the swap. |
| status | One of the statuses in Order Statuses. |
| route | The route name the swap was placed on. |
| user_id, wallet_address | The values from the session that placed it, so you can check every row is for who you asked about. |
| pay | What the wallet sends: amount as a decimal string, symbol and network. |
| get | What the wallet receives, with the same three fields. Left out until the amount is known. |
| created_at, updated_at | RFC 3339 UTC with a Z. |
- You only ever see swaps placed through sessions your own key opened, for the user and the wallet you name. Another partner’s, another user’s and another wallet’s swaps are never returned. They are not an error either: they are simply not in the list.
- The list is read from what Numerari has stored. It does not ask anyone else, so it is as fresh as the last status change Numerari received.
- No signing request, token or outside reference appears in it.
- It is rate limited per partner. A 429 rate_limited carries a Retry-After header, in seconds. A bad user_id, wallet_address or limit is a 400, and that is checked before the rate limit.
- It keeps answering while Swap is switched off for your account only.
What the Module Does
You do not build the browser side. For your information, with the client token the module:
- Reads the session (GET /v1/swap/client/session) to learn the wallet and the route.
- Asks for a price (POST /v1/swap/client/quotes), either for an amount to pay or for an amount to get. The response carries the amounts, any fees as lines, whether the wallet must first give a token approval, and when the price runs out. The module shows what the response says and works out nothing of its own.
- Places the order from a price (POST /v1/swap/client/orders). A price that has run out is 409 swap_quote_expired, and a price that moved is 409 swap_price_moved. The customer gets a new price.
- Asks the customer’s wallet to sign the transaction or transactions the order returns, then reports the transaction hashes (POST /v1/swap/client/orders/{order_id}/transaction).
- Follows the order (GET /v1/swap/client/orders/{order_id}) until it is final.
These routes answer cross-origin calls only from the origins Numerari has set up for the module. They are not part of your server integration, and they are not in the API Reference.
Order Statuses
Every order the module reads, and every item in the list of swaps, has one of these statuses.
| Status | Final |
|---|---|
| created | No |
| pending | No |
| delayed | No |
| completed | Yes |
| partial | Yes |
| refunded | Yes |
| failed | Yes |
| expired | Yes |
| canceled | Yes |
- A completed order shows the amount received once it is known.
- The transactions the wallet must sign are offered only while an order is open and recent. A final order offers none.
- An order whose status Numerari cannot read yet shows as pending, and no signing request is offered until it can.
Webhooks
Swap does not send events to your webhook URL today. There is no Swap event type, and the Numerari-Signature checks on the Partner API page do not apply to it.
- The module follows the order status in the customer’s browser.
- To follow Swap orders on your server, read them with GET /v1/swap/orders. GET /v1/swap/sessions/{session_id} returns the session only.
- If you need Swap events pushed to your server, tell us at the support address on the Partner API page.
Errors
Swap errors are flat, not wrapped in an error object, and every one has a permanent reference in the N200 to N299 range. Branch on code, never on message.
{
"type": "error",
"code": "swap_no_route",
"message": "This swap is not available for this partner. (N206)",
"ref": "N206"
}- ref 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.
- No internal detail is passed through, and nothing from your request is repeated.
- Responses carry Cache-Control: no-store. Swap responses have no Request-Id header: quote the ref to support.
| HTTP | Code | Ref | Meaning |
|---|---|---|---|
| 400 | validation_error | N201 | The body is invalid JSON or has an unknown field, or, once the route is accepted, user_id or wallet_address is missing or invalid. On the list of swaps, user_id, wallet_address or limit is missing or invalid. |
| 401 | unauthorized | N202 | Bad or missing partner key. |
| 401 | session_expired | N203 | The client token is unknown, malformed or too old. Open a new session. |
| 404 | not_found | N204 | Unknown id, or another partner’s session. |
| 409 | swap_quote_expired | N208 | The price ran out. Get a new one. |
| 409 | swap_price_moved | N209 | The price changed. Get a new one. |
| 422 | swap_no_route | N206 | The pair is not offered, or not enabled for you. |
| 422 | swap_refused | N207 | The swap could not be priced. Try a different amount. |
| 429 | rate_limited | N210 | Wait Retry-After seconds. |
| 503 | swap_unavailable | N205 | Swap is switched off, or your partner account is disabled, as described in When Swap Is Switched Off. |
| 502 | swap_unavailable | N230 | A temporary failure on our side. Retry shortly. |
| 500 | internal_error | N230 | Something went wrong. Retry. |
The server routes can answer 400, 401, 404 (the session route only), 422 swap_no_route (opening a session only), 429, 500, 502 and 503. The rest are answers the module handles for the customer.