First API Call - WhiteBIT

Make a first WhiteBIT API call — public data with no authentication, then a private request with HMAC-SHA512 signing. The walkthrough is for developers integrating the v4 REST API for the first time and includes curl and Python examples for each API call.

WhiteBIT does not offer a public testnet or sandbox environment — all API calls in this guide execute against the live API. Steps 1 and 2 are read-only public calls, safe to run freely. Step 4 only reads account balances — it places no orders and moves no funds.

Prerequisites

curl or Python 3.x installed
Steps 1–2: No account required
Steps 3–4: WhiteBIT account (register), 2FA enabled, API key with Info + Trading permissions (create key)

Check server time (public, no auth)

Verify connectivity by calling the public server time endpoint — no authentication needed.Endpoint: GET https://whitebit.com/api/v4/public/time (API Reference)

cURL
Python

curl -X GET https://whitebit.com/api/v4/public/time

import requests

response = requests.get("https://whitebit.com/api/v4/public/time")
print(response.json())

Expected response:

{
  "time": 1700000000
}

The time field is a Unix timestamp in seconds.For Go and PHP examples, see SDKs.

Fetch market data (public, no auth)

Retrieve the list of available markets — spot, futures, and TradFi futures. The endpoint requires no authentication.Endpoint: GET https://whitebit.com/api/v4/public/markets (API Reference)

cURL
Python

curl -X GET https://whitebit.com/api/v4/public/markets

import requests

response = requests.get("https://whitebit.com/api/v4/public/markets")
markets = response.json()
# Print first 3 markets
for market in markets[:3]:
    print(market["name"], market["minAmount"], market["tradesEnabled"])

Expected response (truncated — the full response contains 900+ markets):

[
  {
    "name": "BTC_USDT",
    "stock": "BTC",
    "money": "USDT",
    "stockPrec": "6",
    "moneyPrec": "2",
    "makerFee": "0.001",
    "takerFee": "0.001",
    "minAmount": "0.0001",
    "minTotal": "1",
    "tradesEnabled": true
  }
]

Key fields: name (pair), minAmount (minimum order size in base asset), tradesEnabled (pair active status).

For risk-free Spot trading practice, activate Demo Tokens (DBTC + DUSDT) from the WhiteBIT Codes page. The DBTC_DUSDT pair supports the same API endpoints as any Spot market — place, query, and cancel orders without risking real funds. No KYC required.

Generate an API key

All private endpoints require an API key. Skip this step if a key is already available.

Navigate to API key settings.
Enable 2FA if not already active — key creation requires active 2FA.
Create a new key with Info + Trading permissions.
Optionally whitelist the current IP address (up to 50 addresses per key).
Save the API key and secret immediately — the portal displays the secret only once and offers no way to retrieve it later.

Store the API secret securely in an environment variable or secrets manager. Never commit secrets to version control or embed credentials in client-side code.

Authenticated balance check (private)

Read the Trade account balance. This call requires HMAC-SHA512 signing.Endpoint: POST https://whitebit.com/api/v4/trade-account/balance (API Reference)Every private request requires three headers computed from the request body:

X-TXC-APIKEY — the API key string
X-TXC-PAYLOAD — Base64-encoded JSON request body
X-TXC-SIGNATURE — HMAC-SHA512 of the Base64 payload, hex-encoded, signed with the API secret

The JSON request body must include request (the endpoint path) and nonce (an ever-increasing integer — use Unix milliseconds).See Authentication for the full signing walkthrough.

Python
cURL

import requests
import hmac
import hashlib
import base64
import json
import time

API_KEY = "YOUR_API_KEY"        # Replace with actual API key
API_SECRET = "YOUR_API_SECRET"  # Replace with actual API secret

url = "https://whitebit.com/api/v4/trade-account/balance"
payload = {
    "request": "/api/v4/trade-account/balance",
    "nonce": int(time.time() * 1000)
}
# Use compact separators: the server validates the body against a
# canonical (no-whitespace) serialization and rejects spaced JSON
# with HTTP 400 `{"code":9,"message":"Invalid payload."}`.
payload_json = json.dumps(payload, separators=(",", ":"))
payload_base64 = base64.b64encode(payload_json.encode()).decode()
signature = hmac.new(
    API_SECRET.encode(),
    payload_base64.encode(),
    hashlib.sha512
).hexdigest()

headers = {
    "Content-Type": "application/json",
    "X-TXC-APIKEY": API_KEY,
    "X-TXC-PAYLOAD": payload_base64,
    "X-TXC-SIGNATURE": signature,
}
response = requests.post(url, headers=headers, data=payload_json)
print(response.json())

# The payload and signature must be computed before calling curl.
# Use the Python example for a complete signing implementation.
# Replace BASE64_PAYLOAD and HMAC_SIGNATURE with computed values.

curl -X POST https://whitebit.com/api/v4/trade-account/balance \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"request":"/api/v4/trade-account/balance","nonce":1700000000000}'

Expected response:

{
  "BTC": {
    "available": "0.00100000",
    "freeze": "0"
  },
  "USDT": {
    "available": "100.00000000",
    "freeze": "0"
  }
}

Each key is an asset ticker. available is the amount ready to trade; freeze is the amount locked in open orders. An empty response ({}) means the Trade balance holds no assets — transfer funds from Main first. See Balances & Transfers for details on Main, Trade, and Collateral account types.

Troubleshooting

Invalid signature error

The payload used for Base64 encoding must be the exact same JSON string sent as the request body. Verify:

The request field matches the endpoint path exactly (e.g., "/api/v4/trade-account/balance").
The nonce is an integer larger than the previous request’s nonce — use Unix milliseconds.
The API secret is current — regenerating the key invalidates the old secret.
The HMAC uses the Base64-encoded string as input, not the raw JSON.

See Authentication for the complete signing walkthrough.

API key not found or 401 Unauthorized

Verify:

Copy the API key exactly — no leading or trailing spaces.
The key is active. Keys auto-deactivate after 14 days of inactivity. Reactivate at whitebit.com/settings/api.
The key has Info + Trading permissions for balance endpoints.

IP address not allowed

If the API key has IP whitelisting enabled, the request must come from a whitelisted IP address. Add the current IP at whitebit.com/settings/api.

Nonce is too small

The nonce must be greater than the previous request’s nonce for the same API key. Use int(time.time() * 1000) to generate a millisecond-precision Unix timestamp. Avoid reusing nonces across requests.

What’s Next

Spot Trading Quickstart

Place a first order on a spot market.

WebSocket Quickstart

Stream real-time prices over WebSocket.

Market Data Overview

Browse the 14 public endpoints for tickers, orderbooks, trades, and funding rates.

​Prerequisites

​Troubleshooting

​What’s Next

Spot Trading Quickstart

WebSocket Quickstart

Market Data Overview

Prerequisites

Troubleshooting

What’s Next