zerocap-api

Python SDK for the Zerocap DMA API: ZerocapRestClient places and queries orders, requests quotes and reads balances, transfers and wallets; ZerocapWebsocketClient streams prices and order and trade updates. Requires Python 3.8 or later.

pip install zerocap-api

API keys are issued by Zerocap; contact Zerocap to register. Both clients take env='sandbox' (for testing) or env='prod' and sign every request for you. The full API reference is at https://docs.zerocap.com/reference.

Contents

• REST API
  1. Create an order
  2. Fetch an order
  3. Fetch orders
  4. Request for quote
  5. Get instruments
  6. Get balances
  7. Get transfers
  8. Get time
  9. Get risk
  10. Request for firm quote
  11. Accept quote
  12. Get external wallets
  13. Initiate withdrawal
  14. Initiate transfer
  • Errors
• Websocket
  1. Market data
  2. Order updates
  3. Trades
• Changelog

REST API

import time
from zerocap_api import ZerocapRestClient

# API key and secret are required, please contact zerocap to register.
# Environments: 'prod' and 'sandbox' (any other value raises ValueError).

api_key = "***"
api_secret = "***"
client = ZerocapRestClient(api_key, api_secret, env='sandbox')

The client adds the authentication headers itself. The raw-request examples below show them for reference: api-key, timestamp (integer Unix seconds) and signature (lowercase hex HMAC-SHA256 of the timestamp string, keyed with your API secret).

1. Create an order

result = client.create_order(
                    symbol='USDT/AUD', 
                    side='buy', 
                    type='limit', 
                    amount='100', 
                    price='1000', 
                    )

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

data = 
{
    "symbol": "USDT/AUD",
    "side": "buy",
    "type": "limit",
    "amount": "1000",
    "price": "1000",
}

Response data:

Response example:

{
	"id": "d8dabfbd-e541-4262-b6c2-9f841ef220f6",
	"timestamp": 1692346145000,
	"last_trade_timestamp": 1692346145000,
	"status": "closed",
	"symbol": "USDT/AUD",
	"type": "limit",
	"time_in_force": "FOK",
	"side": "sell",
	"price": 1,
	"average": 1.48249,
	"amount": 500,
	"filled": 500,
	"remaining": 0,
	"cost": 741.245,
	"fee": 0,
	"error_message": "",
	"client_order_id": "",
	"trades": [
		{
			"id": "e86fcf94-88e6-46d8-8cc6-e06891eab6cf",
			"timestamp": 1692346145000,
			"symbol": "USDT/AUD",
			"order": "d8dabfbd-e541-4262-b6c2-9f841ef220f6",
			"type": "limit",
			"side": "sell",
			"taker_or_maker": "taker",
			"price": 1.48249,
			"amount": 500,
			"cost": 741.245,
			"fee": 0
		}
	]
}

2. Fetch an order

result = client.fetch_order(
                        id='',
                        )

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

data = 
{
    "id": "d8dabfbd-e541-4262-b6c2-9f841ef220f6",
}

Response data:

Response example:

{
	"id": "d8dabfbd-e541-4262-b6c2-9f841ef220f6",
	"timestamp": 1692346145000,
	"last_trade_timestamp": 1692346145000,
	"status": "closed",
	"symbol": "USDT/AUD",
	"type": "limit",
	"time_in_force": "FOK",
	"side": "sell",
	"price": 1,
	"average": 1.48249,
	"amount": 500,
	"filled": 500,
	"remaining": 0,
	"cost": 741.245,
	"fee": 0,
	"error_message": "",
	"trades": [
		{
			"id": "e86fcf94-88e6-46d8-8cc6-e06891eab6cf",
			"timestamp": 1692346145000,
			"symbol": "USDT/AUD",
			"order": "d8dabfbd-e541-4262-b6c2-9f841ef220f6",
			"type": "limit",
			"side": "sell",
			"taker_or_maker": "taker",
			"price": 1,
			"amount": 500,
			"cost": 741.245,
			"fee": 0
		}
	]
}

3. Fetch orders

result = client.fetch_orders(
                    symbol='USDT/AUD',
                    end_datetime=int(time.time() * 1000),
                    start_datetime=int(time.time() * 1000 - 10*86400*1000),
                    limit=10,
                    )

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

data = 
{
    "symbol": "USDT/AUD",
    "start_datetime": 0,
    "end_datetime": 0,
    "page": 1,
    "limit": 500,
    "ids": "",
    "status": "",
    "sort_order": "",
    "order_type": "",
    "side": "",
}

Response data:

Response example:

{
	"order_list": [
		{
			"id": "e1af8ae0-3247-4755-87ad-f683fed3aff5",
			"timestamp": 1690797504000,
			"last_trade_timestamp": 1690797504000,
			"status": "closed",
			"symbol": "USDT/AUD",
			"type": "limit",
			"time_in_force": "FOK",
			"side": "buy",
			"price": 21.1,
			"average": 2.98442,
			"amount": 101,
			"filled": 101,
			"remaining": 0,
			"cost": 301.426,
			"fee": 0,
			"error_message": "",
			"client_order_id": "",
			"trades": [
				{
					"id": "e1b3329c-4fc3-455a-82ed-ab5497b286cc",
					"timestamp": 1690797504000,
					"symbol": "USDT/AUD",
					"order": "e1af8ae0-3247-4755-87ad-f683fed3aff5",
					"type": "limit",
					"side": "buy",
					"taker_or_maker": "taker",
					"price": 21.1,
					"amount": 101,
					"cost": 301.426,
					"fee": 0
				}
			]
		}
	],
	"status": "success",
	"total": 14087,
	"page": 1
}

4. Request for quote

result = client.request_for_quote(
                    symbol='USDT/AUD', 
                    side='buy', 
                    amount='100', 
                    client_order_id='', 
                    )

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

data = 
{
    "symbol": "USDT/AUD",
    "side": "buy",
    "amount": "100",
    "client_order_id": ""
}

Response data:

Response example:

{
    "rfq_id": "3ec2f335-1995-4c59-9d3a-8e3a4d048d23",
    "client_order_id": "",
    "amount": 100.0,
    "side": "buy",
    "symbol": "USDT/AUD",
    "price": 1.4882,
    "created": "2024-01-15T02:49:17.658142Z"
}

5. Get instruments

result = client.get_instruments()

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

Response data:

Response example:

{
    "status": "successful",
    "instruments": [
        {
            "name": "USDT/AUD",
            "type": "SPOT",
            "is_tradable": false,
            "quantity_precision": 2.0,
            "max_quantity": 50000.0,
            "min_quantity": 1.0,
            "price_precision": 4.0
        }
    ]
}

6. Get balances

result = client.get_balances()

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

Response data:

Response example:

{
    "status": "successful",
    "datetime": "2024-01-16T05:21:38Z",
    "timestamp": 1705382498277,
    "BTC": {"custody": {"free": 100, "total": 100, "used": 0}},
    "AUD": {
        "DiscountNote": {"free": 1080, "total": 1080, "used": 0},
        "YieldEntryNotes": {"free": 3, "total": 3, "used": 0},
        "custody": {"free": 3092.07032787879, "total": 3092.07032787879, "used": 0},
        "prime": {"free": 3024064.624523521, "total": 3024064.624523521, "used": 0},
        "prime_locked": {"free": 103.107987, "total": 103.107987, "used": 0},
    },
    "custody": {
        "CAD": {"free": 98111.56, "total": 98111.56, "used": 0},
        "ETH": {"free": 0, "total": 0, "used": 0},
    },
    "prime": {
        "AUD": {"free": 3024064.624523521, "total": 3024064.624523521, "used": 0},
        "BTC": {"free": 10.387466098753459, "total": 10.387466098753459, "used": 0},
    },
    "prime_locked": {
        "AUD": {"free": 103.107987, "total": 103.107987, "used": 0},
        "USDT": {"free": 12609.60579, "total": 12609.60579, "used": 0},
    },
    "savings": {
        "BTC": {"free": 0.1003151580555734, "total": 0.1003151580555734, "used": 0}
    },
    "staking": {"DIVI": {"free": 300, "total": 300, "used": 0}},
    "term_3M": {
        "USDT_ETH_TEST3_EA4E": {
            "free": 0.9939347875558201,
            "total": 0.9939347875558201,
            "used": 0,
        }
    },
    "term_6M": {
        "USDT_TRX_TEST4": {
            "free": 9.80542196309589,
            "total": 9.80542196309589,
            "used": 0,
        }
    },
    "unlock": {"BTC": {"free": 2.6246, "total": 2.6246, "used": 0}},
}

7. Get transfers

result = client.get_transfers(start_datetime=1706767455959,
                          end_datetime=1706770184310,
                          asset_id="ETH,AUD",
                          type="external_deposit,external_withdrawal",
                          page=1,
                          limit=20,
                          sort_order="desc")

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

data = {
    "start_datetime": 1706767455959,
    "end_datetime": 1706770184310,
    "asset_id": "ETH,AUD",
    "type": "external_deposit,external_withdrawal",
    "page": 1,
    "limit": 20,
    "sort_order": "desc"
}

Response data:

Response example:

{
    "status": "successful",
    "total": 78,
    "user_id": "",
    "fiat_transactions": [
        {
            "user_id": "",
            "asset_id": "AUD",
            "amount": 1.22,
            "type": "",
            "from_account_type": "",
            "to_account_type": "",
            "amount_usd": 0.8004786,
            "note": "",
            "source_address": "",
            "destination_address": "",
            "tx_id": "a7ff3ee8-d62e-413d-8bf1-1e1305604883auto_sweep",
            "fee": 0.0,
            "fee_currency": "",
            "comment": "",
            "status": "COMPLETED",
            "created_at": 1702267616000
        },
    ],
    "crypto_transactions": [
        {
            "user_id": "",
            "asset_id": "AUD",
            "amount": 1.22,
            "type": "",
            "from_account_type": "",
            "to_account_type": "",
            "amount_usd": 0.8004786,
            "interest_earned": 0.0,
            "note": "",
            "tx_hash": "",
            "source_address": "",
            "destination_address": "",
            "tx_id": "a7ff3ee8-d62e-413d-8bf1-1e1305604883auto_sweep",
            "fee": 0.0,
            "fee_currency": "",
            "comment": "",
            "status": "COMPLETED",
            "created_at": 1702267616000
        },
    ]
}

8. Get time

result = client.get_time()

Public endpoint: no parameters and no authentication headers (the client sends none). Use it to check your clock before signing, since requests with a timestamp more than 30 s off are rejected with 408.

Response data:

Response example:

{
    "server_time": "1709654622"
}

9. Get risk

result = client.get_risk()

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

headers = {
    'api-key': api_key,
    'signature': signature,
    'Content-Type': 'application/json',
    'timestamp': str(timestamp),
}

Response data:

Response example:

{
    "max_risk_limit": "100000",
    "risk_exposure": "0",
    "equity": "17048.35"
}

10. Request for firm quote

result = client.request_for_firm_quote(symbol='USDT/AUD', side='buy', amount='100', currency='', client_order_id='')

Returns a fixed-price quote with a quote_id (plus client_order_id, amount, side, symbol, price, created, currency, base_amount, quote_amount and expires_at, the expiry time in milliseconds). Pass the quote_id to accept_quote before expires_at.

11. Accept quote

result = client.accept_quote(quote_id='<quote_id from request_for_firm_quote>', client_order_id='')

Accepts a firm quote and creates a FOK order.

12. Get external wallets

result = client.get_external_wallets()

Returns external_wallets: a list of external_wallet_id, name, address, label, status, asset, network, asset_id.

13. Initiate withdrawal

result = client.initiate_withdrawal(asset_id='USDC', amount='100', external_wallet_id='<id from get_external_wallets>', from_account='trading', note='')

from_account is trading or custody (fiat supports trading only). The response contains transfer with status (PENDING, COMPLETED, REJECTED), transaction_id and message.

14. Initiate transfer

result = client.initiate_transfer(asset_id='USDC', amount='100', from_account='trading', note='')

Moves funds between the custody and trading accounts; the response has the same shape as Initiate Withdrawal.

Errors

Non-200 responses raise zerocap_api.ZerocapAPIError with status_code and body. Common cases: 401 (Unauthorized., encryption check is fail, Unauthorized IP address., invalid timestamp when timestamp is not an integer), 408 (timestamp skew over 30 s), 422 (validation, including characters outside the allowed set in symbol, currency, asset_id or quote_id), 429 (limit of 50 requests/second per endpoint per IP).

Websocket

The server pushes an unsolicited {"type": "message", "message": "pong"} roughly every 5 s. Send any message at least every 30 s (the SDK's heartbeat thread sends one every 5 s); after 30 s of silence the server sends {"type": "error", "error_code": 400, "error_message": "ping timeout"} and closes the connection. See https://docs.zerocap.com for the full Websocket Overview. Order trades is always a list. price timestamps are float seconds; order and trade timestamps are integer milliseconds.

import time
from zerocap_api import ZerocapWebsocketClient

# API key and secret are required, please contact zerocap to register.

api_key = "***"
api_secret = "***"
websocket = ZerocapWebsocketClient(api_key, api_secret, env='sandbox')

# Create Ws Connection

timestamp = int(time.time())
websocket_connect = websocket.create_connection(timestamp)
connect_result = websocket.recv(websocket_connect)
print(connect_result)

create_connection() opens the socket and returns an iterator of raw messages. recv(websocket_connect) reads the next message from that iterator; recv() with no argument reads straight from the live socket, so keeping the iterator is optional. The connection stays open until websocket.close() or websocket_connect.close() is called; calling create_connection() again closes the previous connection first.

Response example:

{
    "type": "message",
    "message":"Successfully connected."
}

{
    "type": "error",
    "error_code": 401,
    "error_message":"Unauthorized"
}

1. Subscribe to market data

websocket.send({"type": 'price', "symbols": ["USDT/AUD"]})
while True:
    # Get messages
    message = websocket.recv(websocket_connect)
    print(f"Receiving message from server: \n{message}")

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

header={"api-key": api_key, "signature": signature, "timestamp": str(timestamp)}

wss://dma-ws.zerocap.com/v2        # prod
wss://sandbox-ws.zerocap.com/v2    # sandbox

Response data:

Response example:

{
    "type": "error",
    "error_code": 400,
    "error_message":"invalid message"
}

{
    "type": "message",
    "message":"price Subscription successful."
}

{

    "type": "message",
    "message": "pong"
}

{
    "type": "price",
    "data": {
        'timestamp': 1692340935.4283478,
        'symbol': 'USDT/AUD',
        'exchange': 'zerocap',
        'bids': [
            [1.47386, 5000.0],
            [1.47238, 10000.0],
            [1.4709, 20000.0],
            [1.46941, 30000.0]
        ],
        'asks': [
            [1.57236, 5000.0],
            [1.57392, 10000.0],
            [1.57548, 20000.0],
            [1.57705, 30000.0]
        ]
    }
}

{
    "type": "message",
    "message":"Price stream unavailable."
}

2. Subscribe to order updates

websocket.send({"type": 'order'})
while True:
    # Get  messages
    message = websocket.recv(websocket_connect)
    
    print(f"Receiving message from server: \n{message}")

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

header={"api-key": api_key, "signature": signature, "timestamp": str(timestamp)}

wss://dma-ws.zerocap.com/v2        # prod
wss://sandbox-ws.zerocap.com/v2    # sandbox

order Response data:

Response example:

{
    "type": "error",
    "error_code": 400,
    "error_message":"invalid message"
}

{
    "type": "message",
    "message":"order Subscription successful."
}

{
    "type": "message",
    "message": "pong"
}

{
"type":"order",
"data":{
    "id":"f7fc4e4f-c099-4b18-a231-f032adc8ae87",
    "timestamp":1692354083000,
    "last_trade_timestamp":1692354083000,
    "status":"open",
    "symbol":"USDT/AUD",
    "type":"limit",
    "time_in_force":"FOK",
    "side":"buy",
    "price":3,
    "average":0,
    "amount":3,
    "filled":0,
    "remaining":3,
    "cost":9,
    "error_message":"",
    "fee":0,
    "trades":[]
    }
}

{
"type":"order",
"data":{
    "id":"f7fc4e4f-c099-4b18-a231-f032adc8ae87",
    "timestamp":1692354083000,
    "last_trade_timestamp":1692354083000,
    "status":"closed",
    "symbol":"USDT/AUD",
    "type":"limit",
    "time_in_force":"FOK",
    "side":"buy",
    "price":3,
    "average":1.474899,
    "amount":3,
    "filled":3,
    "remaining":0,
    "cost":9,
    "error_message":"",
    "fee":0,
    "trades":[{
        "id":"fa9cbef5-54ce-4a3a-8115-3db8af1f1617",
        "timestamp":1692354083000,
        "symbol":"USDT/AUD",
        "order":"f7fc4e4f-c099-4b18-a231-f032adc8ae87",
        "type":"limit",
        "side":"buy",
        "taker_or_maker":"taker",
        "price":1.474899,
        "amount":3,
        "cost":4.424,
        "fee":0
        }]
    }
}

3. Subscribe to trades

websocket.send({"type": 'trade'})
while True:
    # Get  messages
    message = websocket.recv(websocket_connect)
    
    print(f"Receiving message from server: \n{message}")

Request parameters:

Request parameters: examples (cannot be used directly, you need to replace your own parameters)

header={"api-key": api_key, "signature": signature, "timestamp": str(timestamp)}

wss://dma-ws.zerocap.com/v2        # prod
wss://sandbox-ws.zerocap.com/v2    # sandbox

Transaction Record Response data:

Response example:

{
    "type": "error",
    "error_code": 400,
    "error_message":"invalid message"
}

{
    "type": "message",
    "message":"trade Subscription successful."
}

{

    "type": "message",
    "message": "pong"
}

{
"type":"trade",
"data":{
    "id":"fa9cbef5-54ce-4a3a-8115-3db8af1f1617",
    "timestamp":1692354083000,
    "symbol":"USDT/AUD",
    "order":"f7fc4e4f-c099-4b18-a231-f032adc8ae87",
    "type":"limit",
    "side":"buy",
    "taker_or_maker":"taker",
    "price":1.474899,
    "amount":3,
    "cost":4.424,
    "fee":0,
    "client_order_id":""
    }
}

Changelog

0.1.37

• create_order accepts coinroutes_customer_id again, as a deprecated keyword (default None, sent only when given), so integrations written for 0.1.35 and earlier keep working. 0.1.36 had removed it, which made those calls fail with TypeError.
• Websocket: discarding the iterator returned by create_connection() no longer closes the connection. The socket stays open until close() is called on the client or on the iterator, or a new create_connection() replaces it, so create_connection() followed by recv() / send() without arguments works.
• Packaging: wheel published alongside the sdist, Source and Changelog project links, Python 3.8 to 3.13 classifiers.
• README: introduction and table of contents, REST sample without unused imports, Get Time without authentication headers, integer start_datetime/end_datetime/page/limit in fetch_orders (and page/limit in get_transfers), sandbox websocket URL next to production.

0.1.36 (2026-10-16)

• Websocket errors keep their original type (e.g. websockets.exceptions.ConnectionClosed) instead of being wrapped in a bare Exception.
• request_for_quote: symbol, side and amount are required, matching the API.
• create_order: the coinroutes_customer_id argument is removed (it only applied to the Coinroutes integration and is no longer part of the public API).
• Order channel trades is always a list, and messages no longer carry internal_extra_data (server-side change).
• Fix websocket reconnect: breaking out of a create_connection() generator and calling create_connection() again no longer closes the new connection when the old generator is garbage collected. Each generator and heartbeat thread is now bound to its own socket, and a new create_connection() closes the previous connection first.

0.1.35 (2026-10-16)

• Only prod and sandbox environments are supported; unknown env raises ValueError.
• REST client: default 30 s timeout (timeout= argument), non-200 responses raise ZerocapAPIError (status_code, body), price is now required in create_order, coinroutes_customer_id is deprecated and only sent when set.
• New REST methods: request_for_firm_quote, accept_quote, get_external_wallets, initiate_withdrawal, initiate_transfer; request_for_quote gained currency.
• README: removed internal fields from examples (counterparty, order_from), snake_case field names, amount in request_for_quote, crypto_transactions in get_transfers, websocket symbols/is_subscribe/heartbeat notes.
• get_time is sent without authentication headers.
• Websocket client: socket opens in create_connection() (so send() works immediately), heartbeat thread is a daemon and stops on close(); verify_identity() removed.