API Documentation

0xSwap Partner API

Backend integration reference for currencies, live quotes, automatic order creation, status lookup, client IP forwarding, aliases, and legacy route compatibility.

Base URL

https://zeroxswap.com

HTTPS only

JSON request bodies

Backend-only credentials

Overview

How integrations should work

Call from your backend

Partner credentials must never be exposed in browser code.

Pass clientIp

Send the real end-user IP when your server proxies order creation.

Store order data

Persist orderNumber and token immediately after create-order succeeds.

Quick start

curl -X POST https://zeroxswap.com/api/partner/price \
  -H "Content-Type: application/json" \
  -H "X-API-Public-Key: $OXSWAP_PUBLIC_KEY" \
  -H "X-API-Secret-Key: $OXSWAP_SECRET_KEY" \
  -d '{
    "fromCcy": "BTC",
    "toCcy": "USDTTRC",
    "direction": "from",
    "amount": 0.015
  }'

Runtime contract

Order lifecycle and polling

Create the order

Call create-order from your backend and return the deposit address to the user.

Persist identifiers

Store orderNumber, token, local user id, local order id, and initial status before showing success.

Poll until terminal

Check order status after creation and continue polling until DONE, EXPIRED, or REFUND.

Finalize idempotently

Fulfill the user only once when a terminal success status is received.

Required polling pattern

const terminalStatuses = new Set([
  "DONE",
  "COMPLETE",
  "COMPLETED",
  "EXPIRED",
  "REFUND"
]);

async function poll0xSwapOrder(orderNumber) {
  let delayMs = 10000;

  while (true) {
    const response = await fetch(
      `https://zeroxswap.com/api/partner/order/${orderNumber}`,
      { headers: partnerAuthHeaders }
    );
    const payload = await response.json();
    const status = payload.data?.status;

    await saveStatus(orderNumber, status, payload.data);

    if (terminalStatuses.has(status)) {
      return payload.data;
    }

    await sleep(delayMs);
    delayMs = 30000;
  }
}

Do not stop at NEW

The create response is only the initial state. A single immediate status check can still return NEW because the user has not paid yet or the provider has not finished.

Keep polling

NEW, PENDING, EXCHANGE, WITHDRAW

Stop on terminal

DONE, COMPLETE, COMPLETED, EXPIRED, REFUND

Preflight

Integration checklist

Credentials are used only from server-side code.

Real end-user IP is sent as clientIp for server-to-server creates.

orderNumber is stored before the checkout/deposit screen is shown.

Status polling continues until a terminal status, not just once after create.

DONE fulfillment is idempotent and safe to retry.

Network and 5xx errors retry without marking the local order failed.

Partner secrets, API keys, and raw signatures are never written to logs.

Support requests include orderNumber and local order id when available.

Security

Authentication

Route familyPartner

HeadersX-API-Public-Key, X-API-Secret-Key

NotesRecommended for new integrations. Keep both headers on your backend only.

Route familyLegacy v1

HeadersX-API-KEY, X-API-SIGN

NotesSignature is HMAC-SHA256 over the raw JSON body.

Route family	Headers	Notes
Partner	X-API-Public-Key, X-API-Secret-Key	Recommended for new integrations. Keep both headers on your backend only.
Legacy v1	X-API-KEY, X-API-SIGN	Signature is HMAC-SHA256 over the raw JSON body.

Context

Client IP and timezone forwarding

For server-to-server create requests, include clientIp. Without it, the order will show the IP of your backend server.

Fallback extraction order is cf-connecting-ip, x-real-ip, then the first x-forwarded-for value.

Optional client time fields are clientLocalTime, clientTimezone, and clientUtcOffset.

GET/api/partner/ccies

Currencies

Returns enabled currencies in the same priority order used by the public exchange selector.

Request fields

Fieldnone

Type-

Required-

DescriptionNo request body.

Field	Type	Required	Description
none	-	-	No request body.

Response fields

Fieldcode

Typestring

DescriptionCurrency code accepted by the API.

Fieldcoin

Typestring

DescriptionBase asset symbol.

Fieldnetwork

Typestring

DescriptionNetwork name, for example BTC, ETH, TRC20.

Fieldrecv / send

Typeboolean

DescriptionWhether the asset can be deposited or paid out.

Fieldtag

Typestring | null

DescriptionRequired memo/tag field name when the network needs one.

Fieldpriority

Typenumber

DescriptionSorting priority used by the public selector.

Field	Type	Description
code	string	Currency code accepted by the API.
coin	string	Base asset symbol.
network	string	Network name, for example BTC, ETH, TRC20.
recv / send	boolean	Whether the asset can be deposited or paid out.
tag	string \| null	Required memo/tag field name when the network needs one.
priority	number	Sorting priority used by the public selector.

POST/api/partner/price

Live quote

Returns pair limits and an estimated route amount for direction = from or direction = to.

Request fields

FieldfromCcy

Typestring

Requiredyes

DescriptionAsset the user sends. Alias-compatible.

FieldtoCcy

Typestring

Requiredyes

DescriptionAsset the user receives. Alias-compatible.

Fielddirection

Type"from" | "to"

Requiredyes

DescriptionUse from for send amount, to for receive target.

Fieldamount

Typenumber

Requiredyes

DescriptionPositive amount in the selected direction.

Field	Type	Required	Description
fromCcy	string	yes	Asset the user sends. Alias-compatible.
toCcy	string	yes	Asset the user receives. Alias-compatible.
direction	"from" \| "to"	yes	Use from for send amount, to for receive target.
amount	number	yes	Positive amount in the selected direction.

Response fields

Fieldfrom / to

Typeobject

DescriptionResolved amounts, coin, network, limits, and rate.

Fielderrors

Typearray

DescriptionProvider or validation hints. Empty on success.

Fieldmode

Typestring

DescriptionCurrent route mode.

Field	Type	Description
from / to	object	Resolved amounts, coin, network, limits, and rate.
errors	array	Provider or validation hints. Empty on success.
mode	string	Current route mode.

Request example

{
  "fromCcy": "BTC",
  "toCcy": "ETH",
  "direction": "from",
  "amount": 0.01
}

Response example

{
  "code": 0,
  "data": {
    "from": {
      "code": "BTC",
      "coin": "BTC",
      "network": "BTC",
      "amount": "0.01",
      "min": "0.0000127",
      "max": "1000000",
      "rate": 35.84
    },
    "to": {
      "code": "ETH",
      "coin": "ETH",
      "network": "ETH",
      "amount": "0.3584",
      "min": "0.0022",
      "max": "1000000",
      "rate": 35.84
    },
    "errors": [],
    "mode": "auto"
  }
}

POST/api/partner/create-order

Create order

Creates an automatic provider-backed order and returns a deposit address plus tracking token.

Request fields

FieldfromCcy

Typestring

Requiredyes

DescriptionAsset the user sends. Alias-compatible.

FieldtoCcy

Typestring

Requiredyes

DescriptionAsset the user receives. Alias-compatible.

Fielddirection

Type"from" | "to"

Requiredyes

DescriptionDirection used for amount.

Fieldamount

Typenumber

Requiredyes

DescriptionPositive amount.

FieldtoAddress

Typestring

Requiredyes

DescriptionDestination payout address.

FieldtoTag

Typestring | null

Requiredconditional

DescriptionRequired when the selected payout currency has a tag field.

FieldclientIp

Typestring

Requiredrecommended

DescriptionReal end-user IP for server-to-server integrations.

FieldclientLocalTime

Typestring

Requiredoptional

DescriptionClient local timestamp for support context.

FieldclientTimezone

Typestring

Requiredoptional

DescriptionIANA timezone, for example Europe/Berlin.

FieldclientUtcOffset

Typestring

Requiredoptional

DescriptionUTC offset, for example UTC +02:00.

Field	Type	Required	Description
fromCcy	string	yes	Asset the user sends. Alias-compatible.
toCcy	string	yes	Asset the user receives. Alias-compatible.
direction	"from" \| "to"	yes	Direction used for amount.
amount	number	yes	Positive amount.
toAddress	string	yes	Destination payout address.
toTag	string \| null	conditional	Required when the selected payout currency has a tag field.
clientIp	string	recommended	Real end-user IP for server-to-server integrations.
clientLocalTime	string	optional	Client local timestamp for support context.
clientTimezone	string	optional	IANA timezone, for example Europe/Berlin.
clientUtcOffset	string	optional	UTC offset, for example UTC +02:00.

Response fields

FieldorderNumber

Typestring

DescriptionPublic order id. Automatic orders use C-prefixed ids.

Fieldtoken

Typestring

DescriptionSecret tracking token. Store it server-side.

Fieldfrom.address

Typestring

DescriptionDeposit address for the user.

FieldtimeLeft

Typenumber

DescriptionRemaining deposit window in seconds.

Field	Type	Description
orderNumber	string	Public order id. Automatic orders use C-prefixed ids.
token	string	Secret tracking token. Store it server-side.
from.address	string	Deposit address for the user.
timeLeft	number	Remaining deposit window in seconds.

Request example

{
  "fromCcy": "BTC",
  "toCcy": "USDTTRC",
  "direction": "from",
  "amount": 0.015,
  "toAddress": "TRON_DESTINATION_ADDRESS",
  "toTag": null,
  "clientIp": "203.0.113.14",
  "clientLocalTime": "2026-05-20 00:33:25",
  "clientTimezone": "Europe/Berlin",
  "clientUtcOffset": "UTC +02:00"
}

Response example

{
  "code": 0,
  "data": {
    "orderNumber": "C4M2Q9",
    "token": "secure-order-token",
    "status": "NEW",
    "from": {
      "code": "BTC",
      "amount": "0.015",
      "address": "bc1q...",
      "tag": null,
      "txId": null
    },
    "to": {
      "code": "USDTTRC",
      "amount": "1543.42",
      "address": "TRON_DESTINATION_ADDRESS",
      "tag": null,
      "txId": null
    },
    "timeLeft": 1200,
    "timeExpiration": 1770000000
  }
}

GET/api/partner/order/:orderNumber

Order status

Returns latest local status. Automatic orders sync with the provider before response when possible.

Request fields

FieldorderNumber

Typepath string

Requiredyes

DescriptionPublic order number returned by create-order.

Field	Type	Required	Description
orderNumber	path string	yes	Public order number returned by create-order.

Response fields

Fieldstatus

Typestring

DescriptionCurrent order status.

Fieldfrom.txId

Typestring | null

DescriptionDeposit transaction hash when known.

Fieldto.txId

Typestring | null

DescriptionPayout transaction hash when known.

FieldtimeExpiration

Typenumber

DescriptionUnix timestamp for order expiration.

Field	Type	Description
status	string	Current order status.
from.txId	string \| null	Deposit transaction hash when known.
to.txId	string \| null	Payout transaction hash when known.
timeExpiration	number	Unix timestamp for order expiration.

Response example

{
  "code": 0,
  "data": {
    "orderNumber": "C4M2Q9",
    "status": "EXCHANGE",
    "from": {
      "code": "BTC",
      "amount": "0.015",
      "address": "bc1q...",
      "txId": "deposit_tx_hash",
      "confirmations": 2
    },
    "to": {
      "code": "USDTTRC",
      "amount": "1543.42",
      "address": "TRON_DESTINATION_ADDRESS",
      "txId": null
    },
    "timeLeft": 840,
    "timeExpiration": 1770000000,
    "createdAt": "2026-05-20T00:33:25.000Z"
  }
}

Runtime

Errors, statuses, and aliases

Error codes

Code0

MeaningSuccess. Read the data field.

Code1

MeaningValidation, disabled currency, min amount, invalid address, or provider business-rule error.

Code2

MeaningAuthentication failed. Check API credentials and headers.

Code3

MeaningOrder was not found.

Code5

MeaningUnexpected server or upstream provider error. Retry safely or contact support with request context.

Code	Meaning
0	Success. Read the data field.
1	Validation, disabled currency, min amount, invalid address, or provider business-rule error.
2	Authentication failed. Check API credentials and headers.
3	Order was not found.
5	Unexpected server or upstream provider error. Retry safely or contact support with request context.

Order statuses

StatusNEW

MeaningOrder created and waiting for deposit.

StatusPENDING

MeaningDeposit detected or confirming.

StatusEXCHANGE

MeaningSwap is being processed.

StatusWITHDRAW

MeaningPayout transaction is being sent.

StatusDONE

MeaningOrder completed successfully.

StatusEXPIRED

MeaningDeposit window expired or the order cannot continue.

StatusREFUND

MeaningRefund handling is required or already in progress.

Status	Meaning
NEW	Order created and waiting for deposit.
PENDING	Deposit detected or confirming.
EXCHANGE	Swap is being processed.
WITHDRAW	Payout transaction is being sent.
DONE	Order completed successfully.
EXPIRED	Deposit window expired or the order cannot continue.
REFUND	Refund handling is required or already in progress.

Alias compatibility

Accepted inputUSDTTRC

Internal codeUSDTTRC20

Accepted inputUSDTARBITRUM

Internal codeUSDTARB

Accepted inputUSDTAVAX

Internal codeUSDTAVAXC

Accepted input	Internal code
USDTTRC	USDTTRC20
USDTARBITRUM	USDTARB
USDTAVAX	USDTAVAXC

Business error

{
  "code": 1,
  "error": "Minimum exchange amount: 0.0000127 BTC"
}

Compatibility

Legacy v1 routes

Keep these routes only for existing integrations that already rely on signed v1 requests. New partners should use /api/partner/*.

POST/api/v1/ccies

Legacy currency list with X-API-KEY / X-API-SIGN auth.

POST/api/v1/price

Legacy quote endpoint. Envelope: code / msg / data.

POST/api/v1/create

Legacy create endpoint. Supports clientIp body override.

POST/api/v1/order

Legacy order lookup by id and token in request body.

Need access or integration review?

Use support for API credentials, rollout questions, or contract verification.

Open support