API reference

Most integrations need two things:

1. Create an invoice for an amount in dollars and send the customer to its hosted_url. They pick a coin, pay, and come back to your redirect_url.
2. Listen for webhooks. We POST invoice.paid once the payment has enough confirmations. That is the moment to ship the order.

That covers one-off sales. There are three ways to get paid, and you can use any mix of them:

• Buy. One payment for one order: an invoice and the hosted checkout.
• Subscriptions. A plan that renews. Customers pay ahead, and we email a renewal invoice before their paid time runs out.
• Wallet. For casinos, exchanges and apps with balances: each user gets permanent deposit addresses, and you send them payouts from your balance. The casino & wallet guide walks through the whole loop.

Every request carries a secret key in the Authorization header as a bearer token. Create keys in Dashboard → Developers. A key is shown once when you create it, so store it somewhere safe; you can revoke it at any time.

• sk_test_… keys work on test data only: test invoices, test balances, simulated payments.
• sk_live_… keys move real money. Only the account owner can create them, after confirming their email, and every new live key (or change to one) is emailed to the owners.

A key belongs to the person who made it: it stops working if they leave the team or their account is disabled. The only endpoint that needs no key is GET /v1/networks.

Errors use ordinary HTTP status codes and always have the same body. The message is written to be shown to a person, e.g. how much balance you have when a payout is too big. Branch on type and the status code, not on the message text.

List endpoints return the newest first as {"object": "list", "data": [...], "has_more": true}. Pass limit (1–100, default 20) and, for the next page, starting_after with the id of the last object you got. Keep going while has_more is true. Payments are ordered by when they were first seen, everything else by when it was created.

Every list takes a date range: created[gte], created[gt], created[lte] and created[lt], each an ISO 8601 date or time (2026-10-01, 2026-10-01T12:00:00Z) or Unix seconds. /v1/invoices also filters by status, customer and order_id; /v1/payments by status, invoice, customer, network and asset.

The few lists that return everything at once (/v1/balances, /v1/networks, a customer's /addresses) have the same shape with has_more: false.

An invoice asks for an amount in US dollars. The customer chooses what to pay with on the hosted checkout, or you pick it for them. payment is null until a coin is picked; its amount_paid counts against the current quote. amount_paid_usd is everything received so far.

Crypto can't be charged later the way a saved card can, so subscriptions here are paid ahead. A plan is a price per interval. A subscription is paid up to paid_through, and every paid invoice moves that date on by the periods it covered.

A subscription can be for several plans at once, each with a quantity (say Pro × 1 and Extra seat × 3), billed together on one invoice. These are its items. amount is one period of all of them together, and plan is the first item's plan.

1. Create a subscription and send the customer to pay_url. When that first payment confirms it becomes active.
2. About three days before paid_through (half a period on shorter plans) we email the customer a renewal invoice and send you subscription.payment_due.
3. Unpaid by paid_through, it's past_due and we remind them. After the plan's grace_days it's canceled.

Customers can pay several periods at once, at the plan's prepay discount, from their subscription page (manage_url). It also lets them cancel, and it's linked in every renewal email. Give access while the status is active or past_due.

A customer has one permanent deposit address per address family: one EVM address serves Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, Avalanche, Plasma, Arc and Tempo; Tron, Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, Solana and TON each have their own. Addresses are created the first time you ask for them.

Anything sent to them in a coin listed in the address's assets, any amount, any time, is credited to your balance minus the fee and reported as deposit.detected, then deposit.confirmed, with the customer's id. Transfers worth under ten cents are ignored as dust. If the customer has an email, they get a confirmation for each deposit.

A customer only gets addresses for networks your store (and the key that created them) accepts. Because one EVM address serves every EVM network, tell users which network to use: a coin sent on a network that's off isn't credited.

Each customer also gets a hosted deposit page at deposit_page_url (/d/<token>) listing their addresses with QR codes and their recent deposits. Link to it if you don't want to build your own.

Newest first, paginated. ?external_id=user_812 finds a customer by your own id.

Every accepted network as {network, name, assets, address, uri, qr_url}, in a list. Networks of one family share the address. qr_url is an SVG of the address, for your own deposit page.

One network, e.g. tron, btc, base (see networks), with the same fields plus confirmations_required, confirmations_required_small (deposits under $1,000) and a warning to show next to it. A network that isn't accepted for this customer gets a 400.

Deposits are payment objects that went to a customer's permanent address (not to an invoice, and not your own top-ups). Use these to reconcile or to show a user their history.

Filter with customer and status (any payment status, usually confirming or credited); paginated.

Everything sent to that customer, newest first: payouts, and refunds of invoices attached to them.

A payment is one on-chain transfer into one of your addresses: to an invoice, a customer's deposit address or your top-up address. It starts as Confirming and becomes Credited once it has the confirmations its network needs: fewer for payments under $1,000 (see networks), and confirmations_required says which applied. Payments from the same sender, or into the same address, within a few hours count together for that, so one amount sent in pieces waits like it would in one go. Its amount_usd is fixed when it is first seen. fee and net_amount are set once it's credited; net_amount is what reached your balance.

A payment to an invoice in another coin, on another chain, or after its quote ran out still counts, at its dollar value; mismatch lists which of chain, coin and late applied. It's in your balance either way. When the invoice can't settle it on its own, needs_attention says why: short (it didn't cover the invoice), canceled, refunded or extra (the invoice was already paid), and payment.needs_attention fires. You decide under Payments in the dashboard: mark the invoice paid, refund the payment, or keep it; resolution then says which.

Filter with invoice, customer or status; paginated.

Optional. Under Settings → Taxes, list the countries where you charge VAT, GST or sales tax and the rate for each (there's a button for the EU's standard VAT rates), a rate for everywhere else if you want one, and the business details your receipts need: legal name, address and tax ID.

Choose whether your prices include tax (a $49 invoice is $49, tax inside) or have it added on top ($49 plus tax). Pass customer_country when you create the invoice and the tax is worked out straight away. Leave it out and the checkout asks the customer first: until then tax.pending is true and no coin can be picked.

amount is always what the customer pays. The checkout, the receipt and the receipt email show the subtotal and tax line, and the receipt carries your details and the buyer's tax ID if they gave one. We apply your rates; what you owe and where is for you and your accountant.

You hold a balance per coin and network, in the coin you were paid in. There is no conversion: 49 USDT on Tron stays 49 USDT on Tron (minus the fee) until you withdraw it. amount_usd is today's value for reference (null if there's no price right now), and the list is sorted by it, largest first. fee_free_liquidity is the part that came from top-ups. Coins with a zero balance are left out.

New stores: in your first 30 days of taking live payments, customer payments can be sent out 72 hours after they arrive (your first week) or 24 hours after (to day 30). on_hold is the part of amount still waiting, and on_hold_until when the next part frees up. Withdrawals, payouts and refunds can use the rest, and top-ups are never held. Asking for more returns a 400 that says how much is on hold. Test mode has no hold.

Your balance is your own hot wallet: payouts and refunds are paid from it, per coin and network. To pay out more than you've taken in, send coins to your top-up addresses. They're credited to your balance like any deposit, but with no fee, and fire topup.confirmed. That money is tracked as fee-free liquidity: payouts spend fee-paid money first, and if top-up money itself leaves the platform, 0.5% of that part is charged then. Every coin pays the fee once.

Top-up addresses take every coin the platform runs, whatever your store accepts for customers. Each mode has its own set; test top-ups can only be simulated. The same addresses are on the dashboard under Balance & payouts.

Sends money from your balance to anyone: a user cashing out, a reward, a supplier. The amount leaves your balance the moment you call, and the full amount arrives. Payouts are free; we pay the gas.

• Liquidity. You can only pay out what your balance holds of that coin on that network. Otherwise you get a 400 invalid_request saying how much you have; top up first.
• Bridged versions. USDC on Polygon and USDT on Optimism each also exist as an older bridged token (USDC.e, bridged USDT). Payouts send the standard one; only when the platform holds the amount in the bridged one instead does it go out as that, and bridged_token names it (otherwise it's null). Same value, but some exchanges only credit the standard token, so check before paying out to an exchange on those two networks.
• Idempotent. Pass your own id as external_id. Sending the same external_id again returns the first payout instead of paying twice, so retrying after a timeout is safe.
• Your rules. Every payout is checked against your payout rules: it goes out within a minute, waits in your review queue (status review, webhook payout.pending_review), or is refused with a 400.
• Platform limit. Live payouts above the platform's automatic limit, per payout or per store over 24 hours, wait for the platform's OK (status pending). Refunds and withdrawals count towards the same limit.

Refused with a 400 before anything is reserved:

• an address in the wrong format or checksum, a token's own contract, or an address that belongs to this platform;
• below the network's minimum (see fees), or more than the balance holds;
• in live mode, an address on a sanctions list, frozen by a stablecoin issuer, or banned (see screening);
• in live mode, a Solana token to a wallet that has never held that token (ask the user to receive any amount of it once, or use another network).

Payouts and refunds, newest first. Filter with customer, external_id, status or kind (payout, refund). Payouts have ids starting po_, refunds ref_.

Your own rules for payouts to your users, set in Dashboard → Settings → Payout rules or over the API. They apply to POST /payouts in test and live mode. Your own withdrawals and invoice refunds skip them.

Each payout is checked in this order:

1. Refused (400, nothing is created or reserved): blocked address, below the smallest or above the largest payout, a network you turned off, no customer when you require one, or an address that belongs to this platform.
2. Held for review (status review, the amount is reserved): above the instant limit or a per-coin limit, over a per-user or store-wide limit, a user's first payout or a new address (if turned on), within the deposit cooldown, an address not on your allowed list, or the emergency hold.
3. Sent: everything else, usually within a minute.
4. Platform limit: after your approval, very large live payouts also wait for the platform admin (status pending).

Limits count every payout that wasn't rejected, over a rolling 24 hours (or hour). A "user" is the customer; without one, the address. Checks run in the same transaction that reserves the money, so parallel requests can't slip past a limit together.

Sends a payout in review. Returns the payout: approved, or pending if it also needs the platform's OK. A payout in any other status gets a 400.

Both return { "object": "payout_rules", ...rules }. Send only the rules you want to change; the rest stay as they are. Changing rules needs the Payout rules permission on a live key created by the store owner: a test key gets a 400 and a team member's key a 403, so a leaked key can't loosen live payouts. The rules apply to test and live payouts alike.

Refunds a paid (or partly paid) invoice from your balance, in the coin and network the customer paid with (the first one, if they paid in more than one). Leave out amount to refund everything they paid in that coin, less earlier refunds; pass it for a partial refund. Ask the customer for their address: the one they paid from may belong to an exchange. Needs the Payouts and refunds permission.

A refund is a payout with "object": "refund", an id starting ref_ and invoice set. It skips your payout rules, but the network minimum, address checks, screening and the platform limit apply as for payouts. It fires payout.* events, then invoice.refunded once sent, and emails the customer. The 0.5% fee on the original payment isn't returned. Once refunded, the invoice can't be paid again.

Overpayments. When a customer pays an invoice too much, the paid page offers them the extra back: they enter their address and it's refunded in the coin they paid with, less a fee you keep (1%, at least $1, by default). Set it to go out on its own, wait for your review, or not be offered at all under Settings → Payout rules. It's an ordinary refund with external_id overpay_inv_…, so the same webhooks fire. One request per invoice, within 30 days, and only when everything was paid in the quoted coin. Only the payer can ask: the browser they paid with, or the link in their receipt email (so pass customer_email when you can). Anyone else who opens the invoice just sees that there was an extra.

Sends part or all of a balance to your own wallet. The amount is taken from your balance straight away and the full amount arrives: withdrawals are free. Needs a key with the Withdrawals permission.

In live mode the address must be one of your saved payout addresses (Balance & payouts), saved at least 24 hours earlier, and the account owners get an email for every withdrawal. Adding a payout address also emails them. Your payout rules don't apply to withdrawals.

Withdrawals under the platform's automatic limit (per withdrawal and per store over 24 hours) go out by themselves, usually within a couple of minutes. Larger ones wait for a quick manual review. Statuses: Pending (in review) → Approved → Processing → Sent, or Rejected with the amount returned to your balance. Events are withdrawal.*, not payout.*.

In the dashboard, live withdrawals, refunds and payouts can only be made by the owner or a team member the owner allowed to move money, and each one is confirmed with a code from an authenticator app or email. Over the API, the key's permissions decide, so give the Withdrawals permission only to keys that need it.

Your withdrawals (ids starting wd_), newest first; paginated.

Balance transactions are every movement of your balance, one per event: payment, topup, withdrawal, payout, refund, withdrawal_reversal (a transfer that didn't go out, back in the balance) and adjustment. amount is what moved (negative going out), fee what you paid for it, net the change to your balance. USD values are at the time. available_at is when a payment could be sent on, later than created_at while a new store's payments are held. Filter with type, network, asset and the date range.

Exports are files of your records for a date range: balance_transactions, invoices, payments, payouts (withdrawals, payouts and refunds, with a kind column), customers or subscriptions, as csv (flat columns, UTF-8, opens in Excel) or json (the full API objects). from is inclusive, to exclusive. They're made in the background, usually within seconds; poll GET /v1/exports/:id and download with the same key. Files are kept for 7 days. Any key can make them, read-only ones included.

For accounting tools. balance_transactions also comes ready to import: xero (a bank statement in USD, fees on their own lines), quickbooks (QuickBooks Online bank upload: Date, Description, Amount in USD), koinly (Koinly's universal CSV in coin amounts, payments tagged other income) and cointracking (CoinTracking's CSV import: payments as Income, fees as Other Fee, top-ups and withdrawals as Deposit and Withdrawal, payouts and refunds as Spend). Dates are UTC. A movement with a fee can be two lines, so rows counts lines.

Receipts. A paid invoice has receipt_url and receipt_pdf_url; GET /v1/invoices/:id/pdf returns the same PDF with your key.

Monthly statements. Opening and closing balance per coin, everything in and out and the fees, for each calendar month (UTC), as a page, PDF and CSV under Reports in the dashboard. On the 1st, last month's live statement is emailed to everyone with Monthly statement on under Settings → Emails, including addresses like billing@ that don't have a login.

For anything where users hold a balance with you and come and go: casinos, sportsbooks, wallets, games, exchanges.

1. One customer per user. POST /customers with external_id set to your user id. It returns the existing customer if there is one, so call it whenever the user opens the deposit screen.
2. Show their address. GET /customers/:id/addresses/:network. It never changes, so users can save it. Or link to deposit_page_url.
3. Credit on deposit.confirmed. The payment's net_amount is what reached your balance. Use the payment id so a resent webhook can't credit twice. Never credit on deposit.detected, and leave payment.held deposits alone.
4. Pay out with POST /payouts. Pass the user's customer id and your withdrawal id as external_id. Mark it done on payout.sent; put the money back on payout.rejected. If your payout rules hold it, payout.pending_review fires: show the user "under review" until you approve or reject it.
5. Keep liquidity. Deposits fill your balance; if users withdraw more than they put in (winners, a different coin than they deposited), top up. Watch GET /balances.

Set an endpoint URL in Dashboard → Developers and we POST every event for your store to it as JSON: {id, type, livemode, created, data}, where created is a Unix timestamp in seconds. Test and live mode each have their own URL and their own signing secret: set the live one with the dashboard in live mode. Test events are only ever signed with the test secret, so keep the live secret out of dev and staging.

Each request is signed with the secret of its mode (whsec_… live, whsec_test_… test, shown in Developers). The ZeroFive-Signature header looks like t=1792491271,v1=5257a8…:

1. Split the header on , and each part on = to get t (Unix seconds) and v1.
2. Compute the hex HMAC-SHA256 of `${t}.${rawBody}` with your secret. Use the raw body: re-serialised JSON won't match.
3. Compare it with v1 in constant time, and reject timestamps more than a few minutes old so a captured request can't be replayed.

Answer with any 2xx within 10 seconds; redirects aren't followed. Anything else, or a timeout, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours: eight tries over almost two days. Every delivery is listed in the dashboard with its response and can be resent. Events can arrive more than once and out of order, so make your handler idempotent on id and check the object's current status. Endpoints must be public URLs without a user name or password in them, and https in live mode (http is accepted for test mode only): private and local addresses are refused.

data is the object, or several of them, as described per event below. Objects in events have the same shape as in the API, except invoice.refunded, where invoice is just the id.

The keys below are what network means everywhere in the API, and asset is the coin's symbol in capitals. Tokens are matched by contract address, never by name, so look-alike tokens are ignored. Dollar stablecoins count 1:1 with the dollar; EURC is priced at the euro rate, so its amount_usd moves with EUR/USD.

Read GET /v1/networks instead of hard-coding this list. The platform can switch single networks or coins off (and new ones on), and the endpoint always returns what can be paid with right now. Your store and each API key can narrow that further. Asking for a coin that's off gets a 400.

Payments under $1,000 need fewer confirmations than larger ones, so most customers are done in seconds. Each payment's confirmations_required says which applied. min_withdrawal_usd is the smallest payout, refund or withdrawal on that network; withdrawal_fee_usd is always 0.