What the API covers
Which of the three interfaces to reach for, and the technical limits on each.
There are three interfaces, and they divide cleanly by whether you are asking a question, acting on a price, or waiting to be told something happened.
| You want to | Use |
|---|---|
| Stream live prices | WebSocket |
| Execute against a streamed price | WebSocket |
| Name a beneficiary for delivery on execution | WebSocket |
| Query account balances | REST |
| Retrieve trade or transaction history | REST |
| Query your credit limit and how much of it is used | REST |
| Retrieve settlement parties, their bank accounts and wallets | REST |
| Move funds between your own accounts | REST |
| Request a withdrawal, or cancel one you have raised | REST |
| List tradable instruments | REST |
| Be notified of a trade, deposit, withdrawal or settlement | Webhook |
The short version: REST for state, WebSocket for prices and execution, webhooks for what happened while you were not looking.
REST
| Protocol | HTTPS |
| Authentication | API key and HMAC signature on every request |
| Format | JSON, both directions |
| Rate limit | 30 requests per second per IP |
| Versioning | In the path — /api/3/ |
Almost everything is a POST, including reads, because the signature is
computed over the request body.
Positions and history
POST /api/3/account # balances, per account and account group
POST /api/3/user/limit # credit limit, exposure and utilisation
POST /api/3/trades # executed trades
POST /api/3/transaction/list # transactions
Trades return one record per trade; transactions return one record per leg.
A single trade therefore appears once under trades and at least twice under
transaction/list, as a debit and a credit. Reconcile against transactions;
report against trades.
Moving your own funds
POST /api/3/transfer # move funds between your accounts
POST /api/3/transfer/list # history of those movements
Withdrawals
Withdrawals are requests: you submit one, it is reviewed, and you can list or cancel it while it is outstanding. Crypto and fiat are separate endpoints throughout.
POST /api/3/withdrawal/crypto # request a digital-asset withdrawal
POST /api/3/withdrawal/fiat # request a fiat withdrawal
POST /api/3/withdrawal/crypto/list # outstanding and past crypto requests
POST /api/3/withdrawal/fiat/list # outstanding and past fiat requests
POST /api/3/withdrawal/crypto/{uuid}/cancel
POST /api/3/withdrawal/fiat/{uuid}/cancel
A request names an account group, a currency, an amount, an optional comment,
and a destination held on file — walletParticipantUuid for crypto,
bankAccountUuid for fiat.
You do not send a raw wallet address or account number. The destination is one
of the wallets or bank accounts already registered against a settlement party,
which is why those records carry whitelisted and verified per address: a
destination that is not in good standing cannot be the target of a request.
Settlement parties
Three endpoints, one shape. They return the same record and differ only in which party they describe:
POST /api/3/originator # you, as onboarded
POST /api/3/beneficiaries # who may receive from you
POST /api/3/senders # who may deliver on your behalf
- Originator is your own side of the relationship.
- Beneficiaries receive from your trades.
- Senders — collection accounts — deliver to Zodia Markets on your behalf, with the contra-currency settling to your named account.
Each record carries both settlement rails:
| Includes | |
|---|---|
bankAccounts | Bank and branch name, account number, IBAN, SWIFT/BIC, currency, holder name, bank address, memo, and intermediary bank details |
wallets | Blockchain, asset, address, alias, type, memo, VASP, execution provider, and which is the default |
Alongside those sit the party's own details — entity or individual, contact details, identification documents, associated persons, and whether the party is a VASP.
enabled, verified and whitelisted appear at both levels: on the party and
on each individual account or address. A party can be verified while a
particular wallet is not whitelisted, so check the one you intend to settle to
rather than the party alone — that is the difference between finding out now
and finding out at settlement.
Instruments
GET /zm/rest/available-instruments
The tradable set, as <base>.<quote> — BTC.USD. Note it is a GET, and that
it sits outside /api/3/.
WebSocket
| Protocol | WSS |
| Authentication | A token obtained over REST, then passed on connect |
| Format | JSON messages |
| Rate limit | 30 messages per second per account |
| Update rate | 4 updates per second per connection |
Connecting is a two-step exchange rather than a direct handshake: authenticate over REST to get a token, then open the socket with it. Long-lived connections refresh the token periodically.
Webhooks
Registered against an API key, and delivered as transactions reach a terminal state — trade legs, and crypto and fiat deposits and withdrawals.
A webhook tells you that something happened. Reconciling what it was is a REST call, and the codes on the payload are the same ones the transaction endpoints use.