Partner API
Cash Out
Cash Out moves stablecoins from the customer’s own wallet to their own US bank account. Your screens drive the flow. The customer signs one transfer in their own wallet to a deposit address for the order. Numerari never holds the funds.
The Flow
- Open a session for the customer. The response says whether they may cash out yet.
- If they are new, verify them (see Verifying a Customer).
- Add the bank account they will be paid into, and wait for it to be verified.
- Price a quote. Show the customer customer_price, the whole price ready to show.
- Place an order from the quote. You get a deposit_address.
- The customer sends exactly amount_usdc to that address from their wallet. You follow the order by webhook or by reading it, until it is paid.
No bank routing or account number is ever stored, logged or returned by Numerari. Only the last four digits come back.
Assets and Networks
asset is usdc or usdt and network is base, ethereum or polygon, in lower case, in requests and in responses. A missing asset means usdc and a missing network means base, so usdt needs its network (ethereum or polygon) spelled out. A pair is refused, never swapped for another.
- 422 asset_network_unavailable: the pair is not enabled for you.
- 422 route_not_supported: the pair’s sell side is switched off.
- 422 amount_out_of_range: outside the allowed range for the route. The message names the range.
The session response lists the routes open to you with their limits (min_usd, max_usd, advertised_min_usd, advertised_max_usd). Read them from there. They can change.
Open a Session
curl -X POST https://api.numerari.io/v1/offramp/sessions \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE" \
-H "Content-Type: application/json" \
-d '{
"external_user_id": "usr_48213",
"email": "jordan.rivera@example.com",
"name": "Jordan Rivera",
"wallet_address": "0x7A3f2B9C4E81d0a65f3C7B2e9d14a8f0c6e5C91E"
}'{
"session_id": "ofs_01jz9a2b4c6d8e0f2g4h6j8k0m",
"eligibility": "verified",
"expires_at": "2026-10-01T16:00:00Z",
"rails": [ { "id": "ach", "fee_usd": "2.00", "min_usd": "10.00", "max_usd": "100000.00" } ],
"routes": [ { "route": "usdc_base", "asset": "usdc", "network": "base", "display_name": "USDC on Base" } ]
}- Idempotent per external_user_id. While the customer has an unexpired session (60 minutes) it is returned again, with 200 instead of 201 and the eligibility read fresh.
- name must be a full name, two or more words. wallet_address is the customer’s own EIP-55 checksummed wallet, and the deposit is expected from it.
- A different wallet for an existing customer is 409 wallet_mismatch.
- Eligibility is re-read each call. Verification can be withdrawn later, and then the bank account, quote and order routes answer 409 identity_required.
| eligibility | What to do |
|---|---|
| verified | Continue to the bank account and quote. |
| needed | Verify the customer first. |
| pending | Under review, usually for a minute. Open the session again to read it. |
| rejected | The customer cannot cash out. |
Verifying a Customer
A cash out always needs a fully verified customer. When eligibility is needed, one of two things is in the session response.
In-App Onboarding (kyc_required)
- Read what to show with GET /v1/offramp/kyc/requirements. It returns the terms and privacy links with their versions, and the lists of answers to offer. Render the lists from it and never hard-code them. Show the links next to an unticked checkbox.
- Collect the customer’s details and send them in one request to POST /v1/offramp/sessions/{session_id}/kyc, after they accept the terms.
- The reply is the eligibility: verified, pending, rejected or needed.
- The date of birth, SSN and address go on to the verifier in that one call and are dropped. Numerari never stores, logs or echoes them, and your app must not log or keep them either.
- 400 validation_error names the failing fields and never their values. 429 is limited per person.
A Hosted Step (identity_frame_url)
- When the response has identity_frame_url, open that https page for the customer. It is the verifier’s own page.
- If identity_frame_frameable is false, the page refuses to be framed, so open it in a new tab. If it is absent, you can try a frame with allow="camera".
Photo ID and Selfie
A customer may be asked for a photo ID and a live selfie. The session eligibility tells you when. Send them to POST /v1/offramp/sessions/{session_id}/photo-id. Images are JPEG or PNG data URIs. The images and the document number are never stored, logged, echoed or put in an error.
- 200 returns an eligibility of verified, pending or rejected. Anything short of a clear approval is pending.
- 422 photo_id_rejected has a message that ends with the reason name, for example (document_number_invalid).
- 409 photo_id_not_available when the customer has no verification record yet.
Add a Bank Account
POST /v1/offramp/sessions/{session_id}/bank-accounts requires eligibility verified, and the account must be the customer’s own. Send the details as a JSON body. The wallet collects them and they pass straight through this API to the payout provider.
curl -X POST https://api.numerari.io/v1/offramp/sessions/ofs_01jz9a2b4c6d8e0f2g4h6j8k0m/bank-accounts \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE" \
-H "Content-Type: application/json" \
-d '{
"account_owner_name": "Jane Sample",
"owner_attested": true,
"routing_number": "000000000",
"account_number": "000000000000",
"account_type": "checking",
"address": { "line1": "100 Main St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US" }
}'{ "ref": "bnk_01jz9a3c5e7g9j1m3p5r7t9w1y", "status": "pending_details", "last4": null, "holder_name_matches": false }- The routing and account numbers exist in memory for that one call. They are never stored, logged, echoed or put in an error.
- Required: account_owner_name, routing_number, account_number, address, and owner_attested set to true. Optional: first_name, last_name, bank_name, account_type (checking or savings), owner_type (individual by default, or business).
- Address: line1 up to 35 characters, state two letters, postal_code five digits or ZIP+4, country US.
- The reply carries a ref. Pass it to the order as bank_account_ref. Read the status with GET /v1/offramp/sessions/{session_id}/bank-accounts/{ref}: pending_details, verified or rejected. Poll gently. A pending account is re-read at most every 30 seconds however often you ask.
- At most 10 accounts per customer. Rejected accounts, and forms left pending for 24 hours, do not count.
- 422 bank_details_rejected: the message ends with the reason name, for example (bank_name_required).
- With no body, the call returns a hosted bank form (bank_frame_url) for providers that offer one. 409 bank_details_unsupported means this provider has only a form, so send the request without a body.
Price a Quote
curl -X POST https://api.numerari.io/v1/offramp/quotes \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE" \
-H "Content-Type: application/json" \
-d '{
"session_id": "ofs_01jz9a2b4c6d8e0f2g4h6j8k0m",
"asset": "usdc",
"network": "base",
"amount_usdc": "250.00",
"rail": "ach",
"network_fee_bps": 175
}'{
"quote_id": "ofq_01jz9a5n7q9s1t3v5x7z9b1d3f",
"network": "base", "asset": "usdc", "rail": "ach",
"amount_usdc": "250.00",
"processing_fee": "2.00",
"network_fee_bps": 175,
"network_and_gas_fee": "4.38",
"total": "6.38",
"receive_usd": "243.62",
"provider_mode": "live",
"expires_at": "2026-10-01T15:05:00Z",
"customer_price": {
"you_send": "250.00",
"total_fee": "6.38",
"fees": [
{ "type": "processing_fee", "amount": "2.00" },
{ "type": "network_and_gas_fee", "amount": "4.38" }
],
"you_receive": "243.62"
}
}- rail is ach or wire. fednow is a Top Up rail and is 400 rail_invalid.
- amount_usdc is the amount of the stablecoin you chose, for both USDC and USDT.
- network_fee_bps is required. You state the rate, and it must be one your agreement allows, otherwise 422 network_fee_bps_not_allowed.
- The processing fee is set by the rail. The network and gas fee is network_fee_bps of the amount, rounded up to the cent. total is both, and receive_usd is amount_usdc less total.
- Show customer_price and add nothing up yourself. you_send less total_fee is always you_receive.
- A quote lives 5 minutes. An order at or after expires_at is 422 quote_expired. Quotes are limited to 20 a minute per customer.
When a Fee Transfer Is Present
If your account pays the network fee as its own transfer, the quote also carries fee_transfer with the asset, network, amount, recipient and expiry. The customer pays amount_usdc to the deposit address and fee_transfer.amount to the recipient, from the same wallet. Their total cost is unchanged; only how the fee is paid. receive_usd is then higher by that fee.
- Create the order first, then send the fee transfer, the cash-out amount and anything else together.
- Include fee_tx_hash on the order request, or report it afterwards with POST /v1/offramp/orders/{order_id}/fee-transfer. That call returns the order at once and never waits for the chain.
- A hash that is not yet verified can be replaced with that call. Once verified, a different hash is 422 fee_tx_invalid. A hash used for another order is 409 fee_tx_reused.
- A fee that is still missing 30 minutes after the order, or turns out to be the wrong transfer, does not cancel the order. The fee is billed to the customer.
Place an Order
curl -X POST https://api.numerari.io/v1/offramp/orders \
-H "Authorization: Bearer npk_test_EXAMPLE_KEY_DO_NOT_USE" \
-H "Idempotency-Key: 6f1c1d0e-6b7a-4a52-9a3b-EXAMPLE" \
-H "Content-Type: application/json" \
-d '{
"quote_id": "ofq_01jz9a5n7q9s1t3v5x7z9b1d3f",
"bank_account_ref": "bnk_01jz9a3c5e7g9j1m3p5r7t9w1y"
}'{
"order_id": "ofo_01jz9a8p0r2t4w6y8a0c2e4g6j",
"external_user_id": "usr_48213",
"status": "awaiting_deposit",
"deposit_address": "0x0000000000000000000000000000000000000001",
"network": "base", "asset": "usdc", "rail": "ach",
"amount_usdc": "250.00",
"receive_usd": "243.62",
"bank_account_ref": "bnk_01jz9a3c5e7g9j1m3p5r7t9w1y",
"failure_reason": null,
"provider_mode": "live",
"expires_at": "2026-10-01T16:00:00Z",
"completed_at": null,
"version": 1
}- Idempotency-Key is required: 1 to 200 printable ASCII characters. Make one per quote and reuse it on every retry.
- The order checks, in order: the quote is yours and unexpired; the key is not bound to another quote; the customer is still verified; the asset, network and rate are still allowed; the bank account is the customer’s own and verified.
- The customer sends exactly amount_usdc of asset on network to deposit_address, from the session wallet. A different amount may not be paid out.
- deposit_address is a per-order address. It can be null while one is still being issued, so read the order again. It is null again once the order is paid, failed or expired. Never send to an address you stored earlier.
- expires_at is the deposit window.
- There is no payout reference field. Quote the order_id to support.
Retries and Replays
| Situation | Result |
|---|---|
| Same key, same quote, same bank account | The same order, with 200. The provider is called once. |
| Same key and quote, a different bank account | 409 idempotency_key_reused. |
| The same quote under another key | 409 quote_already_used. |
| The same key for another quote | 409 idempotency_key_reused. |
| Another attempt holds the quote | 409 order_in_progress. Retry, and if you then get quote_already_used, take a new quote. |
| A timeout or 5xx: 502 provider_error | The attempt may exist. Retry with the same key. |
| A definite refusal | The quote is released and can be used again under any key. |
| A payout outside the quoted amount: 502 payout_mismatch | Nothing was created and the quote is released. |
Order Statuses
| Status | Meaning | Webhook type |
|---|---|---|
| awaiting_deposit | Waiting for the customer to send to the deposit address. | offramp_order.created |
| deposit_detected | The deposit arrived. | offramp_order.deposit_detected |
| converting | On its way to the customer’s bank. | offramp_order.converting |
| paid | Paid out to the bank. Final. | offramp_order.paid |
| failed | Failed, or refunded. Final. | offramp_order.failed |
| expired | The deposit window closed. Final. | offramp_order.expired |
- Statuses only move forward. version goes up by one on every public change. Ignore any event older than the version you hold.
- An order under review keeps its last public status. Nothing changes on your side.
- GET /v1/offramp/orders/{order_id} returns the same shape. An order that is older than 30 seconds and not final is re-read from the provider, so polling is safe.
- Another partner’s order, an unknown id, and a quote that never became an order are all the same 404 order_not_found.
Errors Specific to Cash Out
| HTTP | Code | When |
|---|---|---|
| 400 | rail_invalid | The rail is not ach or wire. |
| 400 | idempotency_key_required | The Idempotency-Key header is missing or malformed. |
| 404 | session_not_found, bank_account_not_found, quote_not_found, order_not_found | Unknown, expired, or not yours. |
| 409 | wallet_mismatch | A different wallet is on file. |
| 409 | identity_required | The customer is not verified. |
| 409 | bank_account_not_ready | The bank account is not verified yet. |
| 409 | bank_account_limit_reached | The customer has 10 accounts. |
| 409 | quote_already_used, idempotency_key_reused, order_in_progress | See Retries and Replays. |
| 422 | amount_out_of_range, quote_expired | Outside the range, or the quote ran out. |
| 422 | asset_network_unavailable, route_not_supported | The pair is not enabled, or is off. |
| 422 | network_fee_bps_not_allowed | The rate is not one your agreement allows. |
| 422 | bank_details_rejected, photo_id_rejected, fee_tx_invalid | The provider or chain refused it. The message ends with the reason name. |
| 502 | provider_error, payout_mismatch | Temporary, or the payout would fall outside the quote. |
| 503 | offramp_unavailable, bank_frame_unavailable | Cash Out is switched off for you, or no hosted form is available. |
While Cash Out is switched off for you, every Cash Out route answers 503 offramp_unavailable.