ZanoX Public API
v1 — Three APIs on one base URL (https://zanox.io/api/v1): the Swap API for cross-chain swaps to and from ZANO and fUSD, the read-only Data API for prediction markets and sports betting, and the Trading API for placing orders from your own wallet.
Get an API key
Every request to every API below needs a key in the X-API-Key header. API keys are reviewed by hand. Approved keys are sent to the contact email you provide.
Key types and scopes
Every key is zx_ followed by 64 hexadecimal characters (67 characters in total). A key only works for the scopes it was issued with. Swap scopes additionally require the key to be enrolled as a swap partner.
| Scope | API | Grants |
|---|---|---|
| swap:read | Swap | GET /currencies, GET /exchange/{id}, GET /commissions; Changelly getCurrencies, getCurrenciesFull, getStatus |
| swap:quote | Swap | GET /pairs, GET /estimate; Changelly getPairsParams, getMinAmount, getExchangeAmount, getFixRateForAmount |
| swap:create | Swap | POST /exchange; Changelly createTransaction, createFixTransaction |
| predictions:read | Data | Prediction market data |
| sports:read | Data | Sports betting data |
| predictions:trade | Trading | Place and manage prediction-market orders |
| sports:trade | Trading | Place and manage sports-betting orders |
Key handling
- A key is shown only once, and keys are hashed at rest, so store it securely.
- Use it server-side only. Never ship it in a mobile app, browser bundle or other client-side code.
- To rotate a key, ask us for a new one; there is no self-service rotation endpoint.
Swap API
scopes: swap:read, swap:quote, swap:createBase URL: https://zanox.io/api/v1/swap. Currency tickers and network names are returned lowercase. Amounts are decimal strings in human units (for example "1.5"), never base units.
Overview and non-custodial model
Quote and create cross-chain swaps to and from ZANO and fUSD (Freedom Dollar) through hosted exchanges. The API is non-custodial: the user deposits to an address generated by the executing provider and the provider pays out directly to the user's address. ZanoX never holds funds.
Quotes are floating-rate and indicative; the rate is re-priced when the order is created. Orders are filled by one of the hosted exchanges WizardSwap, Exolix or Mistex, whichever quotes the highest payout for the request; the API picks per order and does not expose the provider. Not covered: the Freedom Dollar fUSD bridge, on-Zano ionic swaps, and Tron.
Authentication, scopes and rate limits
Send your key on every request:
X-API-Key: <your key>
The key must carry the right scope and be enrolled as a swap partner. A valid key that is not enrolled returns 403 forbidden (“not enrolled as a swap partner”); a suspended partner returns 403 forbidden (“partner account is suspended”). A missing, unknown, inactive or expired key returns 401 unauthorized.
swap:read—GET /currencies,GET /exchange/{id},GET /commissionsswap:quote—GET /pairs,GET /estimateswap:create—POST /exchange
Rate limits. Per key, per fixed one-minute window aligned to the clock minute (not a rolling window). Swap keys issued by us default to 300 requests per minute; your actual limit is the X-RateLimit-Limit value. Counters are held in memory per server process, so treat the limit as approximate. Responses carry:
X-RateLimit-Limit— requests allowed per windowX-RateLimit-Remaining— requests left in the current windowX-RateLimit-Reset— ISO 8601 timestamp when the window resets
Every 429 (code rate_limited) carries X-RateLimit-Limit, X-RateLimit-Remaining: 0, X-RateLimit-Reset and Retry-After (whole seconds, at least 1). Wait Retry-After seconds (or until X-RateLimit-Reset), then retry. Error responses generated after authentication by the endpoint itself (for example bad_request) may omit the rate-limit headers.
Every response carries Cache-Control: private, no-store and Vary: X-API-Key. Do not cache responses on shared infrastructure.
Integration checklist
- Call
GET /currenciesand cache the list for a few minutes; always sendfromNetwork/toNetworkfor multi-chain tickers such as USDT. - Check limits with
GET /pairsand show a quote withGET /estimate; treat the quote as indicative and show the final amount from thePOST /exchangeresponse. - Send a unique
Idempotency-Keyon everyPOST /exchange, and reuse the same key when retrying after a timeout or 5xx. - Always collect and send
refundAddress(andrefundExtraIdwhen the source chain needs a tag); it is mandatory. - Show the user
payinAddress, the exactfromAmount, andpayinExtraId(withpayinExtraIdName) when non-null. Persist the orderid. - Poll
GET /exchange/{id}every 30–60 s untilfinished,failed,refundedorexpired. Webhooks tell you about changes sooner; keep polling as the fallback. - If you register a webhook URL, verify every delivery with the HMAC signature and de-duplicate on
X-ZanoX-Delivery. - Honour
429: back off untilX-RateLimit-Reset. Logmeta.request_idfor support requests. - Keep the API key on your backend only; call this API from your server, never from end-user devices.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /api/v1/swap/currencies | swap:read | List assets routable against ZANO or fUSD |
| GET | /api/v1/swap/pairs | swap:quote | Min/max range for a pair |
| GET | /api/v1/swap/estimate | swap:quote | Indicative quote by fromAmount |
| POST | /api/v1/swap/exchange | swap:create | Create an order (returns the deposit address) |
| GET | /api/v1/swap/exchange/{id} | swap:read | Fetch an order and refresh its status |
| GET | /api/v1/swap/commissions | swap:read | Commission statement, optional monthly statement, payout history |
| POST | /api/v1/swap/changelly | per method | Changelly-compatible JSON-RPC 2.0 |
1. List currencies — GET /currencies
Scope swap:read, no parameters. Lists assets routable against ZANO or fUSD, one entry per (ticker, network) because tickers collide across chains. The catalogue is cached server-side for 15 minutes.hasExternalId and isExtraIdSupported are both true when the network needs a memo/tag; extraIdName is its label. buy and sell are always true; minAmount may be null.
curl -s https://zanox.io/api/v1/swap/currencies \ -H "X-API-Key: $ZANOX_SWAP_KEY"
{
"data": {
"count": 3,
"currencies": [
{
"ticker": "zano", "name": "Zano", "network": "zano",
"image": "https://example.invalid/icons/zano.svg",
"hasExternalId": false, "isExtraIdSupported": false, "extraIdName": null,
"minAmount": 0.5, "buy": true, "sell": true
},
{
"ticker": "xrp", "name": "XRP", "network": "xrp",
"image": "https://example.invalid/icons/xrp.svg",
"hasExternalId": true, "isExtraIdSupported": true, "extraIdName": "Destination Tag",
"minAmount": 20, "buy": true, "sell": true
}
// ...
]
},
"meta": { "timestamp": "2026-10-28T14:03:11.402Z", "request_id": "6f1c0d52-..." }
}2. Pair limits — GET /pairs
Scope swap:quote. Effective min/max range for a pair across every provider that can serve it: minAmount is the smallest provider minimum, maxAmount the largest ceiling (null when no ceiling is published). Because some providers publish no reliable floor, minAmount is verified with a live quote (at most six provider calls, cached for 10 minutes per pair), so it is an amount that will quote, within about 30% above the true floor. A first call for a pair can take a few seconds; cache the result on your side. flow is standard (floating) or fixed-rate. No route returns 422 unsupported_pair.
| Field | Type | Required | Description |
|---|---|---|---|
| fromCurrency | string | yes | Ticker |
| toCurrency | string | yes | Ticker |
| fromNetwork | string | no | Disambiguates multi-chain tickers |
| toNetwork | string | no | Destination network |
| amount | number | no | Probe amount for routing; defaults to 1. Ignored if not a positive number |
curl -s "https://zanox.io/api/v1/swap/pairs?fromCurrency=usdt&fromNetwork=eth&toCurrency=zano" \ -H "X-API-Key: $ZANOX_SWAP_KEY"
{
"data": {
"fromCurrency": "usdt",
"toCurrency": "zano",
"fromNetwork": "eth",
"toNetwork": null,
"minAmount": 10,
"maxAmount": null,
"flow": "standard"
},
"meta": { "timestamp": "2026-10-28T14:03:12.118Z", "request_id": "b0a9c3e1-..." }
}3. Estimate — GET /estimate
Scope swap:quote. Indicative quote for the best executable route. toAmount is the amount the end user receives; no ZanoX markup is deducted from it. Quotes are by fromAmount only; passing type=reverse or toAmount returns 400 bad_request. rateId and validUntil are always null (an estimate does not lock the rate); rate is a number and may be null. When the best route is rate-locked, flow is fixed-rate, rateType is fixed and warningMessage is null. Out-of-range amounts return below_min / above_max.
| Field | Type | Required | Description |
|---|---|---|---|
| fromCurrency | string | yes | Ticker |
| toCurrency | string | yes | Ticker |
| fromNetwork | string | no | Disambiguates multi-chain tickers |
| toNetwork | string | no | Destination network |
| fromAmount | number | yes | Positive; otherwise invalid_amount |
curl -s "https://zanox.io/api/v1/swap/estimate?fromCurrency=usdt&fromNetwork=eth&toCurrency=zano&fromAmount=250" \ -H "X-API-Key: $ZANOX_SWAP_KEY"
{
"data": {
"fromCurrency": "usdt",
"toCurrency": "zano",
"fromNetwork": "eth",
"toNetwork": null,
"fromAmount": "250",
"toAmount": "61.4823",
"amountExpectedFrom": "250",
"amountExpectedTo": "61.4823",
"rate": 0.24593,
"flow": "standard",
"rateType": "floating",
"rateId": null,
"validUntil": null,
"minAmount": 10,
"maxAmount": null,
"warningMessage": "Floating rate — the payout re-prices at settlement"
},
"meta": { "timestamp": "2026-10-28T14:03:13.907Z", "request_id": "1d2c4f60-..." }
}4. Create an order — POST /exchange
Scope swap:create. The route is re-quoted at creation, so the final amount can differ from your last estimate. The user then sends fromAmount of fromCurrency to payinAddress (plus payinExtraId when it is non-null). Send Content-Type: application/json. The body must be a JSON object; null, an array or a bare string returns 400 bad_request, as does any field over its length limit (nothing is stored).
| Field | Type | Required | Description |
|---|---|---|---|
| fromCurrency | string | yes | Source ticker |
| toCurrency | string | yes | Destination ticker |
| fromNetwork | string | no | Disambiguates multi-chain tickers such as USDT |
| toNetwork | string | no | Destination network |
| fromAmount | number or numeric string | yes | Positive amount in human units |
| address | string | yes | End-user payout address (max 256 characters, printable ASCII only) |
| extraId | string | no | Payout memo/tag (max 128) |
| refundAddress | string | yes | Missing returns 400 bad_request (max 256, same character rule as address) |
| refundExtraId | string | no | Refund memo/tag (max 128) |
| partnerRef | string | no | Your own correlation id, stored on the order (max 128; not compared for idempotency) |
| idempotencyKey | string | no | Alternative to the Idempotency-Key header (the header wins; max 128 either way) |
Idempotency. Send an Idempotency-Key header (optional but strongly recommended; the body field idempotencyKey is an alternative and the header wins if both are sent). Keys are scoped to your API key. The same key with the same body returns the existing order (HTTP 200) instead of creating a new one; a first-time create returns HTTP 201. The same key with a different body (any change to fromCurrency, toCurrency, fromNetwork, toNetwork, fromAmount, address, extraId, refundAddress or refundExtraId; currency codes compare case-insensitively, partnerRef is not compared) is rejected with HTTP 409 idempotency_conflict and no order is returned: use a new key for a different order. Without a key, every request creates a new order and a new deposit address.
curl -s -X POST https://zanox.io/api/v1/swap/exchange \
-H "X-API-Key: $ZANOX_SWAP_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wallet-tx-8841-attempt-1" \
-d '{
"fromCurrency": "usdt",
"fromNetwork": "eth",
"toCurrency": "zano",
"fromAmount": 250,
"address": "ZxD3...userZanoAddress",
"refundAddress": "0x4b1e...userEthAddress",
"partnerRef": "wallet-tx-8841"
}'{
"data": {
"id": "0b5e3a52-6c1f-4d0c-a8d7-3e2f9b7c1a44",
"status": "waiting",
"fromCurrency": "usdt",
"toCurrency": "zano",
"fromNetwork": "eth",
"toNetwork": "zano",
"fromAmount": "250",
"toAmount": "61.4823",
"amountExpectedFrom": "250",
"amountExpectedTo": "61.4823",
"payinAddress": "0x9a7c...providerDepositAddress",
"payinExtraId": null,
"payinExtraIdName": null,
"payoutAddress": "ZxD3...userZanoAddress",
"payoutExtraId": null,
"refundAddress": "0x4b1e...userEthAddress",
"refundExtraId": null,
"flow": "standard",
"rateType": "floating",
"validUntil": null,
"payinHash": null,
"payoutHash": null,
"amountReceive": null,
"createdAt": "2026-10-28T14:05:02.331Z",
"updatedAt": "2026-10-28T14:05:02.331Z"
},
"meta": { "timestamp": "2026-10-28T14:05:02.640Z", "request_id": "e7c2a19b-..." }
}idis the ZanoX order id; use it for polling. The provider's own order id is not exposed.payinExtraId/payinExtraIdNameare set when the deposit needs a memo/tag; include it in the user's deposit.rateTypeisfixed,floatingornull;flowisfixed-rateonly whenrateTypeisfixed, otherwisestandard.validUntilis the order's expiry timestamp when the provider supplies one, elsenull.toAmount/amountExpectedTois the amount expected at creation;amountReceiveis the delivered amount once known.fromNetwork/toNetworkreflect the network the route resolved to, which can be set even if you omitted it.payinHash/payoutHashare filled as the provider reports transactions.
Errors specific to creation: below_min, above_max, unsupported_pair, bad_request (also when the provider rejects the payout or refund address for the selected network), provider_unavailable (the pending order is marked failed server-side; no usable order is returned) and idempotency_conflict.
5. Get an order — GET /exchange/{id}
Scope swap:read. Returns the order object shown above. Lookups are scoped to your key: an id belonging to another partner, or a malformed id, returns 404 not_found. Each call to a non-terminal order refreshes its status from the provider before responding; if the provider refresh fails, the last known state is returned without error.
curl -s https://zanox.io/api/v1/swap/exchange/0b5e3a52-6c1f-4d0c-a8d7-3e2f9b7c1a44 \ -H "X-API-Key: $ZANOX_SWAP_KEY"
{
"data": {
"id": "0b5e3a52-6c1f-4d0c-a8d7-3e2f9b7c1a44",
"status": "finished",
"...": "same fields as above, plus:",
"payinHash": "0x7d1f...depositTx",
"payoutHash": "a41c...payoutTx",
"amountReceive": "61.31",
"updatedAt": "2026-10-28T14:21:44.870Z"
},
"meta": { "timestamp": "2026-10-28T14:22:00.012Z", "request_id": "5a3f9c10-..." }
}Order status lifecycle
| Status | Terminal | Meaning |
|---|---|---|
| waiting | no | Order open; awaiting the user’s deposit. All orders start here. |
| confirming | no | Deposit seen; accumulating confirmations. |
| verifying | no | Compliance/AML hold at the provider (WizardSwap only). No confirmation count. |
| exchanging | no | Provider is executing the trade. |
| sending | no | Payout broadcast in flight. |
| finished | yes | Settled; payout delivered to the payout address. |
| failed | yes | Provider rejected the order. |
| refunded | yes | Funds returned to the refund address. |
| expired | yes | Deposit window elapsed with no deposit. |
Status is refreshed from the provider when you call GET /exchange/{id} (or the Changelly getStatus method) and, independently, by a ZanoX background poller about every 30 seconds. If you registered a webhook URL you receive an order.status_changed event on every later change. The initial waiting status is not delivered as a webhook: you already have it in the 201 response to POST /exchange. Keep polling every 30–60 seconds per open order as the fallback until a terminal status, then stop.
Fees and partner commission
Your users always receive the full provider amount. Swaps are non-custodial: the user pays the executing provider directly and the payout never passes through ZanoX, so partners add nothing on top of the quote. Instead, ZanoX shares its own revenue with you under one fixed rule.
Commission policy, the same for every partner and not negotiable: every API partner earns 50% of the revenue ZanoX confirms receiving on that partner's orders. If ZanoX earns 1% on an order, the partner receives 0.5%. If ZanoX earns 0.5%, the partner receives 0.25%. There is no per-key rate.
Commission accrues when ZanoX's own revenue on the order is confirmed as received, valued in fUSD (Freedom Dollar, a USD-pegged asset on the Zano network) at that time, whatever pair was swapped. It is paid in fUSD to a dedicated Zano address (Zx...) reserved for commissions, given on the key request or later via your account contact. Do not reuse an address that also receives swap payouts, so the commission stays separately auditable.
Confirmation happens in batches, not per order: provider revenue reaches ZanoX in periodic withdrawals, and when one is received and recorded, the orders that finished in that period move from accrued (estimated) to confirmed, scaled to the amount actually received. Until then your statement shows the accrued figure as an estimate.
Payouts. Once your confirmed commission reaches 100 fUSD it is grouped into a payout, approved by ZanoX and sent in fUSD to your commission address; a payout.paid webhook follows if you have one. Payouts need a commission address on file; without one the balance keeps accruing.
Commission statement — GET /commissions
Scope swap:read. Returns the policy, your commission address, totals in fUSD and your last 50 payouts. All statement amounts are JSON numbers (not strings) with at most 6 decimals.
curl -s https://zanox.io/api/v1/swap/commissions -H "X-API-Key: $ZANOX_SWAP_KEY"
{
"data": {
"policy": { "share_bps": 5000, "description": "50% of confirmed ZanoX revenue on your orders, paid in fUSD", "settlement_asset": "fUSD", "min_payout_fusd": 100 },
"commission_address": "ZxD3...yourCommissionAddress",
"totals": { "accrued_estimate_fusd": 12.41, "confirmed_unpaid_fusd": 3.2, "pending_payout_fusd": 0, "paid_fusd": 120 },
"payouts": [
{ "id": "7c1e...", "amount_fusd": 120, "status": "paid", "tx_hash": "a41c...", "paid_at": "2026-10-30T00:12:09.000Z", "created_at": "2026-10-29T00:00:03.000Z" }
]
},
"meta": { "timestamp": "...", "request_id": "..." }
}accrued_estimate_fusd: orders that finished but whose ZanoX revenue is not yet confirmed; an estimate, not owed yet.confirmed_unpaid_fusd: confirmed commission not yet grouped into a payout.pending_payout_fusd: grouped, awaiting or in payment.paid_fusd: lifetime paid.
Monthly statement — GET /commissions?month=YYYY-MM
Scope swap:read. month is a UTC calendar month. The response is the statement above plus a month object (inside data) with what you accumulated on the orders that settled in that month and what you were paid during it.
curl -s "https://zanox.io/api/v1/swap/commissions?month=2026-10" \ -H "X-API-Key: $ZANOX_SWAP_KEY"
"month": {
"month": "2026-10",
"period_start": "2026-10-01T00:00:00.000Z",
"period_end": "2026-11-01T00:00:00.000Z",
"orders": { "finished": 42, "voided": 1 },
"order_value_fusd": 61250.5,
"commission": { "accrued_estimate_fusd": 4.1, "confirmed_fusd": 148.9, "paid_fusd": 120, "unpaid_fusd": 28.9, "total_fusd": 153 },
"payouts_received": { "count": 1, "amount_fusd": 120 }
}- Orders belong to the month in which they reached
finished(settlement time, UTC).voidedcounts orders that accrued and were later refunded or failed; they carry no commission. commission.total_fusdis the commission accumulated on the month's orders:accrued_estimate_fusd(ZanoX revenue not yet confirmed; an estimate) plusconfirmed_fusd.paid_fusdandunpaid_fusdsplit the confirmed part by whether it has been paid out yet.payouts_receivedis cash basis: payouts whosepaid_atfalls in the month, which can include commission earned in earlier months. Reconcilepayouts_received.amount_fusdagainstcommission.paid_fusdacross months.- A
monththat is notYYYY-MM(or is before 2020 / after 2100) returns400 bad_request. A month with no activity returns zeros, not an error.
Payout statuses
pending_approval— Grouped from confirmed commission; waiting for ZanoX approval.approved— Approved; the payout daemon will send it.sending— The daemon is sending it now.unknown— A send was attempted but its outcome is not yet known (for example a wallet timeout). ZanoX checks the wallet history and resolves it to paid (with the transaction hash) or failed. It is never sent twice while unknown.paid— Sent; tx_hash and paid_at are set and a payout.paid webhook follows.failed— Definitely not sent (a pre-send check failed or the wallet rejected the transfer). ZanoX re-sends the same payout or cancels it.cancelled— Withdrawn by ZanoX; its commission returns to confirmed_unpaid_fusd for a later payout.
Webhooks
Optional. Give us an https webhook URL when your key is issued (or later via your account contact) and you receive a webhook_secret once. Deliveries are sent by a ZanoX background dispatcher, not by the request that changed the order. Webhook URLs must be https with a public host and no credentials; localhost, *.local, *.internal and hosts that are or resolve to private, loopback, link-local or other special-purpose addresses (including IPv4 embedded in IPv6) are refused. Setting a URL on an account without a secret issues one once; ZanoX can rotate it, and the new secret is shown once.
order.status_changed — every status transition after creation on one of your orders. The initial waiting status is not delivered (you receive it in the 201 create response).
{
"event": "order.status_changed",
"order": { /* the same object GET /exchange/{id} returns */ },
"previous_status": "waiting",
"occurred_at": "2026-11-01T12:00:00.000Z"
}payout.paid — a commission payout to you was sent.
{
"event": "payout.paid",
"payout": { "id": "...", "amount_fusd": 120, "asset": "fUSD", "tx_hash": "...", "paid_at": "..." },
"occurred_at": "..."
}Headers on every delivery:
Content-Type: application/jsonUser-Agent: ZanoX-Webhooks/1.0X-ZanoX-Event— the event nameX-ZanoX-Delivery— unique delivery id; use it to de-duplicateX-ZanoX-Timestamp— unix secondsX-ZanoX-Signature: v1=<hex>
Verification. The signing string is the timestamp, a dot, and the raw request body: hex(HMAC-SHA256(webhook_secret, X-ZanoX-Timestamp + "." + raw body)). Compare it to the v1 value with a constant-time comparison and reject deliveries whose timestamp is more than 300 seconds from your clock. Verify against the raw body bytes, before any JSON parsing.
import crypto from 'node:crypto';
export function verifyZanoxWebhook(secret, headers, rawBody) {
const ts = headers['x-zanox-timestamp'];
const sig = (headers['x-zanox-signature'] || '').replace(/^v1=/, '');
if (!ts || !sig || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
return expected.length === sig.length &&
crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(sig, 'hex'));
}Delivery rules. Respond with any 2xx within 10 seconds. Anything else is retried at 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours (6 attempts in total), then marked failed and visible to ZanoX support. Order of delivery is not guaranteed and the same delivery id can arrive twice, so de-duplicate on X-ZanoX-Delivery, treat the order object as the authoritative state, and ignore events older than the state you already hold.
Errors
Every error, including auth and rate-limit errors, uses this envelope with lowercase codes. details is null unless stated below; auth-layer errors may include details: { "upstream_code": "..." }. Successful responses are { "data": ..., "meta": { "timestamp", "request_id" } }.
{
"error": {
"code": "below_min",
"message": "Amount is below the minimum for this pair",
"details": { "minAmount": 0.5 }
},
"meta": { "timestamp": "2026-10-28T14:03:11.402Z", "request_id": "6f1c0d52-7a47-4b0e-9d0b-0d1d2a1e7c11" }
}| Code | HTTP | Meaning |
|---|---|---|
| bad_request | 400 | Missing or malformed parameter, invalid JSON body (must be a JSON object), over-long field, non-printable-ASCII address, payout or refund address rejected by the provider for the selected network, or unsupported request (for example a reverse quote). Also returned when fromCurrency and toCurrency are the same asset on the same network, and for an invalid month on /commissions. |
| invalid_amount | 400 | fromAmount is missing, not a number, or not greater than zero |
| below_min | 400 | Amount is below the pair minimum. details is { "minAmount": number } when a numeric bound is known, otherwise null and the reason is in message |
| above_max | 400 | Amount is above the pair maximum or what can be filled. details is { "maxAmount": number } when known, otherwise null |
| unsupported_pair | 422 | No server-executable route for this pair/amount |
| unauthorized | 401 | Missing, invalid, inactive or expired API key |
| forbidden | 403 | Key lacks the required scope, is not enrolled as a swap partner, or the partner is suspended |
| rate_limited | 429 | Per-key per-minute limit exceeded; carries X-RateLimit-* and Retry-After |
| not_found | 404 | No order with that id for this key |
| idempotency_conflict | 409 | The Idempotency-Key was already used with a different request body (use a new key), or a concurrent create with the same key was racing and its order could not be found yet (retry) |
| provider_unavailable | 503 | The executing provider is temporarily unavailable (upstream 502, timeout) at quote or create time. details.provider_message carries the provider wording. Retry with backoff; the pair is not dead |
| service_unavailable | 503 | Partner lookup failed; retry shortly |
| internal | 500 | Unexpected server error |
Changelly-compatible JSON-RPC
Wallets that already speak Changelly's method names can POST https://zanox.io/api/v1/swap/changelly (JSON-RPC 2.0). Same core logic and same X-API-Key auth as the REST API; the scope required depends on the method.
| Method | Scope | Params | Returns |
|---|---|---|---|
| getCurrencies | swap:read | none | Array of unique lowercase tickers. |
| getCurrenciesFull | swap:read | none | Array of { name, ticker, fullName, enabled, fixRateEnabled, network, extraIdName, image }. fixRateEnabled is always false. |
| getStatus | swap:read | { "id": "<order id>" } | Status string (see the status lifecycle). |
| getPairsParams | swap:quote | One { from, to } object, or an array of at most 20 (more returns -32602) | Array of { from, to, minAmountFloat, maxAmountFloat, minAmountFixed, maxAmountFixed } (strings or null). |
| getMinAmount | swap:quote | { from, to } | Min amount string or null. |
| getExchangeAmount | swap:quote | { from, to, amountFrom } (amount also accepted); optional fromNetwork, toNetwork | Estimated receive amount as a string. |
| getFixRateForAmount | swap:quote | { from, to, amountFrom } | { id, result, from, to, amountFrom, amountTo, min, max, expiredAt }. |
| createTransaction | swap:create | from, to, amountFrom (or amount), address, refundAddress (required); optional extraId, refundExtraId, fromNetwork, toNetwork | Order object (example below). |
| createFixTransaction | swap:create | Same as createTransaction | Same as createTransaction. |
curl -s -X POST https://zanox.io/api/v1/swap/changelly \
-H "X-API-Key: $ZANOX_SWAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "createTransaction",
"params": {
"from": "usdt",
"fromNetwork": "eth",
"to": "zano",
"amountFrom": "250",
"address": "ZxD3...userZanoAddress",
"refundAddress": "0x4b1e...userEthAddress"
}
}'{
"jsonrpc": "2.0",
"id": 1,
"result": {
"id": "0b5e3a52-6c1f-4d0c-a8d7-3e2f9b7c1a44",
"type": "float",
"status": "waiting",
"currencyFrom": "usdt",
"currencyTo": "zano",
"amountExpectedFrom": "250",
"amountExpectedTo": "61.4823",
"payinAddress": "0x9a7c...providerDepositAddress",
"payinExtraId": null,
"payoutAddress": "ZxD3...userZanoAddress",
"payoutExtraId": null,
"refundAddress": "0x4b1e...userEthAddress",
"refundExtraId": null,
"createdAt": "2026-10-28T14:05:02.331Z"
}
}Behaviour specific to the shim
- Method-level failures return HTTP 200 with a JSON-RPC
errorobject:-32700parse error,-32600invalid request (method missing),-32601unknown method,-32602invalid params (for example more than 20 pairs, or a non-string network/extra id), and-32000any other failure. There are no ZanoX error codes in RPC errors. - Authentication failures (missing/invalid key, wrong scope, not enrolled, rate limit) return the REST error envelope with HTTP 401/403/429, not a JSON-RPC error; your client must handle both. An unknown method is rejected before authentication.
- Batch requests (JSON arrays) are not supported.
- Fixed-rate is a soft binding:
getFixRateForAmountreturns an indicativeid(prefixind_) and anexpiredAt60 seconds out (Unix seconds). The id is not checked later;createFixTransactionignores it and re-quotes at creation. Whether the created order is fixed or floating depends on the route that wins; checktypein the result. fromNetwork,toNetwork,extraIdandrefundExtraIdmust be strings when present. Input problems return their message; any other server-side failure returns the generic messageRequest failedwith code-32000.createTransaction/createFixTransactionhave no idempotency and nopartnerRef: there is noIdempotency-Keyhandling, and a retry creates a new order with a new deposit address. UsePOST /exchangefor idempotent creation.getStatusreturns only the status string, and refreshes from the provider like the REST endpoint.
Changelog
- 2026-11-01 — Minimum commission payout raised from 5 to 100 fUSD (policy.min_payout_fusd); confirmed commission below it keeps accruing.
- 2026-11-01 — GET /commissions?month=YYYY-MM adds a monthly statement (commission accumulated on orders settled in the month, payouts received in the month); statement amounts documented as JSON numbers.
- 2026-11-01 — Every 429 carries X-RateLimit-* and Retry-After; an Idempotency-Key reused with a different body returns 409 idempotency_conflict; a provider-rejected payout/refund address returns 400 bad_request (was 503 provider_unavailable); addresses must be printable ASCII.
- 2026-11-01 — Webhooks (order.status_changed, payout.paid, HMAC-signed), background status poller, GET /commissions statement, commission accrual/confirmation/payout ledger.
- 2026-10-31 — Ledger hardening: payout status unknown (send attempted, outcome not yet known; resolved by ZanoX to paid or failed); failed now always means not sent; documented that the initial waiting status is not sent as a webhook; stricter webhook URL rules (public https hosts only) and one-time secret issue/rotation; POST /exchange rejects non-object bodies and over-long fields with 400 bad_request; Changelly getPairsParams capped at 20 pairs and unexpected errors return a generic message.
- 2026-10-31 — Partner commission is now fixed policy: 50% of confirmed ZanoX revenue, paid in fUSD; commission_address collected on key requests; per-key fee_bps removed.
- 2026-10-31 — Documented the planned partner commission settlement: calculated and paid in fUSD.
- 2026-10-28 — Initial release.
Data API
read-onlyRead-only access to prediction markets and sports betting data. The Authentication, Rate Limits, Response Format, Error Codes and JavaScript Example sections below apply to the Data API only; the Swap API has its own (see above) and so does the Trading API.
curl -H "X-API-Key: $ZANOX_DATA_KEY" \ "https://zanox.io/api/v1/predictions/markets"
Authentication
Include your API key in every request via the X-API-Key header. Keys are scoped with permissions:
predictions:read— Access prediction market datasports:read— Access sports betting data
Rate limits
Default: 60 requests per minute per API key.
Rate limit status is returned in response headers:
X-RateLimit-Limit— Max requests per windowX-RateLimit-Remaining— Requests left in windowX-RateLimit-Reset— Window reset timestamp (ISO 8601)
Response format
All successful responses use a consistent envelope:
{
"data": [ ... ],
"meta": {
"timestamp": "2026-11-01T12:00:00.000Z",
"request_id": "a1b2c3d4-..."
},
"pagination": {
"page": 1,
"per_page": 20,
"total": 142,
"total_pages": 8,
"has_more": true
}
}Error responses (uppercase codes, listed below):
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please wait and try again.",
"details": {
"limit": 60,
"reset_at": "2026-11-01T12:01:00.000Z"
}
},
"meta": {
"timestamp": "2026-11-01T12:00:30.000Z",
"request_id": "e5f6g7h8-..."
}
}Prediction Markets
scope: predictions:readSports Betting
scope: sports:readError codes
| Code | HTTP | Description |
|---|---|---|
| MISSING_API_KEY | 401 | No X-API-Key header provided |
| INVALID_API_KEY | 401 | Key not recognized |
| EXPIRED_API_KEY | 401 | Key past its expiration date |
| INACTIVE_API_KEY | 403 | Key has been deactivated |
| INSUFFICIENT_PERMISSIONS | 403 | Key lacks the required scope |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests in the current window |
| NOT_FOUND | 404 | The requested resource does not exist |
| BAD_REQUEST | 400 | Invalid or missing parameters |
| INTERNAL_ERROR | 500 | An unexpected server error occurred |
JavaScript example
const API_KEY = process.env.ZANOX_DATA_KEY; // keep keys server-side
const BASE = 'https://zanox.io/api/v1';
async function getMarkets() {
const res = await fetch(`${BASE}/predictions/markets?status=active&per_page=10`, {
headers: { 'X-API-Key': API_KEY },
});
const json = await res.json();
console.log(json.data); // Array of markets
console.log(json.pagination); // { page, per_page, total, ... }
}
getMarkets();Trading API
Place orders programmatically using your own Zano wallet. Supports both prediction markets (fUSD) and sports betting (ZANO or fUSD), with limit and market orders.
Prerequisites
You need the following before you can trade via API:
- A trade-scoped API key — Request one with
predictions:tradeand/orsports:tradepermissions (see Get an API key above). - A Zano wallet with a registered alias — Your wallet must have an on-chain alias (e.g.
@youralias). You can register one in the Zano desktop app. - Zano simplewallet running in RPC mode — The trading API requires you to sign challenges with your wallet. Start simplewallet with:
./simplewallet --wallet-file your_wallet.wallet \ --password YOUR_PASSWORD \ --rpc-bind-ip 127.0.0.1 --rpc-bind-port 12233 \ --daemon-address 127.0.0.1:11211
On macOS with the Zano app installed, the binary is at
/Applications/Zano.app/Contents/MacOS/simplewallet - Funds in your wallet — fUSD for prediction markets, ZANO for sports betting. Both are Zano confidential assets on the same blockchain.
How It Works
Every trade follows this flow:
- Authenticate — Prove you own the wallet by signing a server-issued challenge. You get a 24-hour trading token.
- Place order — Submit order details (market, side, price, size). For buys, the API returns payment instructions (address, amount, asset ID, payment ID).
- Send payment — Transfer the exact amount from your wallet to the platform address using the provided payment details.
- Confirm — Submit the transaction hash. The order enters the orderbook and matching begins.
- Settlement — The platform verifies the on-chain payment amount (10 block confirmations). For Polymarket-linked markets, a mirror trade is placed automatically.
Sell orders skip steps 3–4 — they list immediately since you're selling shares you already own.
Trading authentication
Trading requires two credentials on every request:
X-API-Keyheader — your API key (identifies your app, enforces rate limits)Authorization: Bearer <trading_token>header — your 24-hour wallet token (proves wallet ownership)
The trading token is obtained by signing a challenge with your wallet. The platform's daemon cryptographically verifies the signature matches your alias's public key. Tokens expire after 24 hours; request a new one by repeating the challenge/verify flow.
Step 1: Get a Trading Token
With your simplewallet running in RPC mode, complete the three-step auth handshake:
# Step 1: Request challenge
curl -X POST -H "X-API-Key: $ZANOX_TRADE_KEY" \
-H "Content-Type: application/json" \
-d '{"address": "ZxYourAddress...", "alias": "youralias"}' \
"https://zanox.io/api/v1/trade/auth/challenge"
# Response includes challenge_base64
# Step 2: Sign with your wallet RPC
curl -X POST http://127.0.0.1:11212/json_rpc \
-d '{"jsonrpc":"2.0","id":0,"method":"sign_message","params":{"buff":"<challenge_base64>"}}'
# Response: { "result": { "pkey": "abc...", "sig": "def..." } }
# Step 3: Verify signature and get trading token
curl -X POST -H "X-API-Key: $ZANOX_TRADE_KEY" \
-H "Content-Type: application/json" \
-d '{"address":"ZxYourAddress...","alias":"youralias","challenge":"<original_challenge>","signature":"<sig>","pkey":"<pkey>"}' \
"https://zanox.io/api/v1/trade/auth/verify"
# Response: { "data": { "trading_token": "eyJ...", "expires_in": 86400 } }Step 2: Place an Order
All trade endpoints require both X-API-Key and Authorization: Bearer <trading_token>.
POST /api/v1/trade/orders parameters:
| Field | Type | Required | Description |
|---|---|---|---|
| market_type | string | yes | "prediction" or "sports" |
| market_id | uuid | yes | Market UUID |
| outcome_id | uuid | yes | Outcome UUID |
| side | string | yes | Predictions: "buy"/"sell". Sports: "yes"/"no" |
| order_type | string | no | "limit" (default) or "market". Limit orders sit in the orderbook at your price. Market orders fill at best available. |
| price | number | yes | Price per share, between 0 and 1 (exclusive). E.g. 0.65 = 65 cents. |
| size | number | yes | Number of shares. Minimum 0.1. |
| currency | string | no | Sports only: "ZANO" (default) or "FUSD". Predictions always use fUSD. |
# Limit order: sits in orderbook at your price until filled or cancelled
curl -X POST -H "X-API-Key: $ZANOX_TRADE_KEY" \
-H "Authorization: Bearer <trading_token>" \
-H "Content-Type: application/json" \
-d '{
"market_type": "prediction",
"market_id": "uuid-of-market",
"outcome_id": "uuid-of-outcome",
"side": "buy",
"order_type": "limit",
"price": 0.65,
"size": 10
}' \
"https://zanox.io/api/v1/trade/orders"
# Market order: fills immediately at best available price
curl -X POST -H "X-API-Key: $ZANOX_TRADE_KEY" \
-H "Authorization: Bearer <trading_token>" \
-H "Content-Type: application/json" \
-d '{
"market_type": "sports",
"market_id": "uuid-of-market",
"outcome_id": "uuid-of-outcome",
"side": "yes",
"order_type": "market",
"price": 0.70,
"size": 5,
"currency": "ZANO"
}' \
"https://zanox.io/api/v1/trade/orders"
# Response includes payment instructions for buy orders:
# { "data": { "order_id": "...", "status": "pending",
# "payment": { "address": "Zx...", "amount": 7.15,
# "payment_id": "01abc...", "asset_id": "86143..." } } }Step 3: Send Payment and Confirm
# Send payment from your wallet
curl -X POST http://127.0.0.1:11212/json_rpc \
-d '{"jsonrpc":"2.0","id":0,"method":"transfer","params":{
"destinations":[{"address":"Zx...","amount":7150000000000,
"asset_id":"86143388bd056a8f0bab669f78f14873fac8e2dd8d57898cdb725a2d5e2e4f8f",
"payment_id":1234567890123456}],
"fee":10000000000,"mixin":15}}'
# Confirm with tx_hash
curl -X PUT -H "X-API-Key: $ZANOX_TRADE_KEY" \
-H "Authorization: Bearer <trading_token>" \
-H "Content-Type: application/json" \
-d '{"tx_hash": "<64_char_hex_hash>"}' \
"https://zanox.io/api/v1/trade/orders/<order_id>/confirm"Trading Endpoints Reference
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/trade/auth/challenge | Request signing challenge |
| POST | /api/v1/trade/auth/verify | Submit signature, receive trading token |
| POST | /api/v1/trade/orders | Place order (returns payment instructions for buys) |
| GET | /api/v1/trade/orders | List your orders |
| PUT | /api/v1/trade/orders/:id/confirm | Confirm payment with tx_hash |
| DELETE | /api/v1/trade/orders/:id | Cancel an open order |
| GET | /api/v1/trade/positions | List your open positions |
| GET | /api/v1/trade/account | Account summary |
Order Types
Limit orders
Placed at a specific price. The order sits in the orderbook until another trader matches it at your price or better. Use for precise entry points and better prices.
Market orders
Fill immediately against the best available orders in the book. Use when you want instant execution and are willing to accept the current best price.
Polymarket Mirror Thresholds
Prediction markets linked to Polymarket will automatically mirror your orders on the Polymarket CLOB after payment confirmation (10 block confirmations). Polymarket enforces minimum order sizes:
| Action | Minimum | Notes |
|---|---|---|
| Buy | 5 shares | Order value must also exceed ~$1 USDC equivalent |
| Sell | 5 shares | Same minimum applies to sell/close orders |
Orders below these thresholds will still execute on ZanoX's P2P orderbook but will not be mirrored to Polymarket. The order response does not indicate whether a mirror will occur — check the market's polymarket_id field to know if mirroring is available.
Order Lifecycle
Buy orders: pending (awaiting payment) → open (paid, in orderbook) → partial → filled
Sell orders: open (listed immediately, no payment needed) → partial → filled
Market orders: fill immediately after payment confirmation; any unfilled remainder may stay open or cancel depending on liquidity
Cancellation: open or partial orders can be cancelled via DELETE
Support
Need a key or have a question? Request an API key, or reach us on Telegram, Discord or X (@ZanoX_io). Include meta.request_id from the response when reporting a problem.
