Zano
ZanoX

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.

ScopeAPIGrants
swap:readSwapGET /currencies, GET /exchange/{id}, GET /commissions; Changelly getCurrencies, getCurrenciesFull, getStatus
swap:quoteSwapGET /pairs, GET /estimate; Changelly getPairsParams, getMinAmount, getExchangeAmount, getFixRateForAmount
swap:createSwapPOST /exchange; Changelly createTransaction, createFixTransaction
predictions:readDataPrediction market data
sports:readDataSports betting data
predictions:tradeTradingPlace and manage prediction-market orders
sports:tradeTradingPlace 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:create

Base 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 /commissions
  • swap:quote — GET /pairs, GET /estimate
  • swap: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 window
  • X-RateLimit-Remaining — requests left in the current window
  • X-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 /currencies and cache the list for a few minutes; always send fromNetwork / toNetwork for multi-chain tickers such as USDT.
  • Check limits with GET /pairs and show a quote with GET /estimate; treat the quote as indicative and show the final amount from the POST /exchange response.
  • Send a unique Idempotency-Key on every POST /exchange, and reuse the same key when retrying after a timeout or 5xx.
  • Always collect and send refundAddress (and refundExtraId when the source chain needs a tag); it is mandatory.
  • Show the user payinAddress, the exact fromAmount, and payinExtraId (with payinExtraIdName) when non-null. Persist the order id.
  • Poll GET /exchange/{id} every 30–60 s until finished, failed, refunded or expired. 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 until X-RateLimit-Reset. Log meta.request_id for support requests.
  • Keep the API key on your backend only; call this API from your server, never from end-user devices.

Endpoints

MethodPathScopeDescription
GET/api/v1/swap/currenciesswap:readList assets routable against ZANO or fUSD
GET/api/v1/swap/pairsswap:quoteMin/max range for a pair
GET/api/v1/swap/estimateswap:quoteIndicative quote by fromAmount
POST/api/v1/swap/exchangeswap:createCreate an order (returns the deposit address)
GET/api/v1/swap/exchange/{id}swap:readFetch an order and refresh its status
GET/api/v1/swap/commissionsswap:readCommission statement, optional monthly statement, payout history
POST/api/v1/swap/changellyper methodChangelly-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.

FieldTypeRequiredDescription
fromCurrencystringyesTicker
toCurrencystringyesTicker
fromNetworkstringnoDisambiguates multi-chain tickers
toNetworkstringnoDestination network
amountnumbernoProbe 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.

FieldTypeRequiredDescription
fromCurrencystringyesTicker
toCurrencystringyesTicker
fromNetworkstringnoDisambiguates multi-chain tickers
toNetworkstringnoDestination network
fromAmountnumberyesPositive; 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).

FieldTypeRequiredDescription
fromCurrencystringyesSource ticker
toCurrencystringyesDestination ticker
fromNetworkstringnoDisambiguates multi-chain tickers such as USDT
toNetworkstringnoDestination network
fromAmountnumber or numeric stringyesPositive amount in human units
addressstringyesEnd-user payout address (max 256 characters, printable ASCII only)
extraIdstringnoPayout memo/tag (max 128)
refundAddressstringyesMissing returns 400 bad_request (max 256, same character rule as address)
refundExtraIdstringnoRefund memo/tag (max 128)
partnerRefstringnoYour own correlation id, stored on the order (max 128; not compared for idempotency)
idempotencyKeystringnoAlternative 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-..." }
}
  • id is the ZanoX order id; use it for polling. The provider's own order id is not exposed.
  • payinExtraId / payinExtraIdName are set when the deposit needs a memo/tag; include it in the user's deposit.
  • rateType is fixed, floating or null; flow is fixed-rate only when rateType is fixed, otherwise standard.
  • validUntil is the order's expiry timestamp when the provider supplies one, else null.
  • toAmount / amountExpectedTo is the amount expected at creation; amountReceive is the delivered amount once known.
  • fromNetwork / toNetwork reflect the network the route resolved to, which can be set even if you omitted it.
  • payinHash / payoutHash are 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

StatusTerminalMeaning
waitingnoOrder open; awaiting the user’s deposit. All orders start here.
confirmingnoDeposit seen; accumulating confirmations.
verifyingnoCompliance/AML hold at the provider (WizardSwap only). No confirmation count.
exchangingnoProvider is executing the trade.
sendingnoPayout broadcast in flight.
finishedyesSettled; payout delivered to the payout address.
failedyesProvider rejected the order.
refundedyesFunds returned to the refund address.
expiredyesDeposit 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). voided counts orders that accrued and were later refunded or failed; they carry no commission.
  • commission.total_fusd is the commission accumulated on the month's orders: accrued_estimate_fusd (ZanoX revenue not yet confirmed; an estimate) plus confirmed_fusd. paid_fusd and unpaid_fusd split the confirmed part by whether it has been paid out yet.
  • payouts_received is cash basis: payouts whose paid_at falls in the month, which can include commission earned in earlier months. Reconcile payouts_received.amount_fusd against commission.paid_fusd across months.
  • A month that is not YYYY-MM (or is before 2020 / after 2100) returns 400 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/json
  • User-Agent: ZanoX-Webhooks/1.0
  • X-ZanoX-Event — the event name
  • X-ZanoX-Delivery — unique delivery id; use it to de-duplicate
  • X-ZanoX-Timestamp — unix seconds
  • X-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" }
}
CodeHTTPMeaning
bad_request400Missing 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_amount400fromAmount is missing, not a number, or not greater than zero
below_min400Amount is below the pair minimum. details is { "minAmount": number } when a numeric bound is known, otherwise null and the reason is in message
above_max400Amount is above the pair maximum or what can be filled. details is { "maxAmount": number } when known, otherwise null
unsupported_pair422No server-executable route for this pair/amount
unauthorized401Missing, invalid, inactive or expired API key
forbidden403Key lacks the required scope, is not enrolled as a swap partner, or the partner is suspended
rate_limited429Per-key per-minute limit exceeded; carries X-RateLimit-* and Retry-After
not_found404No order with that id for this key
idempotency_conflict409The 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_unavailable503The 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_unavailable503Partner lookup failed; retry shortly
internal500Unexpected 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.

MethodScopeParamsReturns
getCurrenciesswap:readnoneArray of unique lowercase tickers.
getCurrenciesFullswap:readnoneArray of { name, ticker, fullName, enabled, fixRateEnabled, network, extraIdName, image }. fixRateEnabled is always false.
getStatusswap:read{ "id": "<order id>" }Status string (see the status lifecycle).
getPairsParamsswap:quoteOne { from, to } object, or an array of at most 20 (more returns -32602)Array of { from, to, minAmountFloat, maxAmountFloat, minAmountFixed, maxAmountFixed } (strings or null).
getMinAmountswap:quote{ from, to }Min amount string or null.
getExchangeAmountswap:quote{ from, to, amountFrom } (amount also accepted); optional fromNetwork, toNetworkEstimated receive amount as a string.
getFixRateForAmountswap:quote{ from, to, amountFrom }{ id, result, from, to, amountFrom, amountTo, min, max, expiredAt }.
createTransactionswap:createfrom, to, amountFrom (or amount), address, refundAddress (required); optional extraId, refundExtraId, fromNetwork, toNetworkOrder object (example below).
createFixTransactionswap:createSame as createTransactionSame 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 error object: -32700 parse error, -32600 invalid request (method missing), -32601 unknown method, -32602 invalid params (for example more than 20 pairs, or a non-string network/extra id), and -32000 any 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: getFixRateForAmount returns an indicative id (prefix ind_) and an expiredAt 60 seconds out (Unix seconds). The id is not checked later; createFixTransaction ignores it and re-quotes at creation. Whether the created order is fixed or floating depends on the route that wins; check type in the result.
  • fromNetwork, toNetwork, extraId and refundExtraId must be strings when present. Input problems return their message; any other server-side failure returns the generic message Request failed with code -32000.
  • createTransaction / createFixTransaction have no idempotency and no partnerRef: there is no Idempotency-Key handling, and a retry creates a new order with a new deposit address. Use POST /exchange for idempotent creation.
  • getStatus returns 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-only

Read-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 data
  • sports: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 window
  • X-RateLimit-Remaining — Requests left in window
  • X-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:read

Sports Betting

scope: sports:read

Error codes

CodeHTTPDescription
MISSING_API_KEY401No X-API-Key header provided
INVALID_API_KEY401Key not recognized
EXPIRED_API_KEY401Key past its expiration date
INACTIVE_API_KEY403Key has been deactivated
INSUFFICIENT_PERMISSIONS403Key lacks the required scope
RATE_LIMIT_EXCEEDED429Too many requests in the current window
NOT_FOUND404The requested resource does not exist
BAD_REQUEST400Invalid or missing parameters
INTERNAL_ERROR500An 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:

  1. A trade-scoped API key — Request one with predictions:trade and/or sports:trade permissions (see Get an API key above).
  2. 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.
  3. 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

  4. 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:

  1. Authenticate — Prove you own the wallet by signing a server-issued challenge. You get a 24-hour trading token.
  2. Place order — Submit order details (market, side, price, size). For buys, the API returns payment instructions (address, amount, asset ID, payment ID).
  3. Send payment — Transfer the exact amount from your wallet to the platform address using the provided payment details.
  4. Confirm — Submit the transaction hash. The order enters the orderbook and matching begins.
  5. 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-Key header — 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:

FieldTypeRequiredDescription
market_typestringyes"prediction" or "sports"
market_iduuidyesMarket UUID
outcome_iduuidyesOutcome UUID
sidestringyesPredictions: "buy"/"sell". Sports: "yes"/"no"
order_typestringno"limit" (default) or "market". Limit orders sit in the orderbook at your price. Market orders fill at best available.
pricenumberyesPrice per share, between 0 and 1 (exclusive). E.g. 0.65 = 65 cents.
sizenumberyesNumber of shares. Minimum 0.1.
currencystringnoSports 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

MethodPathDescription
POST/api/v1/trade/auth/challengeRequest signing challenge
POST/api/v1/trade/auth/verifySubmit signature, receive trading token
POST/api/v1/trade/ordersPlace order (returns payment instructions for buys)
GET/api/v1/trade/ordersList your orders
PUT/api/v1/trade/orders/:id/confirmConfirm payment with tx_hash
DELETE/api/v1/trade/orders/:idCancel an open order
GET/api/v1/trade/positionsList your open positions
GET/api/v1/trade/accountAccount 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:

ActionMinimumNotes
Buy5 sharesOrder value must also exceed ~$1 USDC equivalent
Sell5 sharesSame 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.