Basic Information

API Basics Base URL for REST endpoints: https://api.xxx.com/spot/open

All interfaces return a JSON object or array.

Response arrays are sorted in reverse chronological order (earliest first).

All timestamps use UNIX time in milliseconds.

HTTP Response Codes HTTP 4XX codes indicate invalid requests (content, behavior, or format issues).

HTTP 429 warns of excessive request frequency (IP blocking imminent).

HTTP 418 indicates IP blocked after ignoring 429 warnings.

HTTP 5XX codes signify server-side errors. Never assume task failure – execution status is unknown (could be success or failure).

HTTP 504 means the API server submitted the request but received no response from the business core. Crucially: 504 does not denote failure but unknown status. Execution may have succeeded or failed – further verification is required.

Any endpoint may return ERROR. Error payload format:

java { "code": -1121, "msg": "Invalid symbol." } General Interface Information All requests use HTTPS. Request headers must include: 'Content-Type': 'application/json'

For GET methods, parameters must be sent in the query string.

For POST methods, parameters must be sent in the request body.

Parameter order is insignificant.

Access Limits Rate limits are specified under each endpoint.

Violating limits triggers HTTP 429 (warning).

Upon receiving 429, the caller must reduce or cease requests.

Endpoint Authentication Types Auth Type Description NONE No authentication required TRADE Valid API-KEY + Signature required USER_DATA Valid API-KEY + Signature required USER_STREAM Valid API-KEY required MARKET_DATA Valid API-KEY required Each endpoint has its own authentication type.

For API-KEY authentication, include it in the X-CH-APIKEY header field.

API-KEY and API-SECRET are case-sensitive.

Permissions (e.g., account read, trade, withdraw) can be modified for API-KEYs in the web user center.

Signature Requirements (TRADE & USER_DATA) For TRADE or USER_DATA endpoints, include the signature in the X-CH-SIGN header.

Signature uses HMAC SHA256 with the API-SECRET as the key.

X-CH-SIGN is generated from: timestamp + method + requestPath + body (where + denotes string concatenation).

timestamp: Value matches the X-CH-TS header.

method: Uppercase HTTP method (e.g., GET, POST).

requestPath: Full endpoint path (e.g., /sapi/v1/order?orderId=211222334&symbol=BTCUSDT).

body: Request body string (POST only). Omit for GET requests.

Signature is case-insensitive.

Timestamp Security Signed requests must include the X-CH-TS header with the UNIX timestamp (milliseconds) of request generation (e.g., 1528394129373).

The server rejects requests if:

timestamp is older than serverTime - recvWindow (default 5000 ms).

timestamp is newer than serverTime + 1000 ms.

Logic (pseudocode):

java if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) { // Process request } else { // Reject request } Trading Timeliness Note: Network reliability varies. Set recvWindow according to your latency tolerance and trading strategy. Avoid recvWindow > 5000 ms for high-frequency trading.

POST /sapi/v1/order/test Example Example using Linux echo, openssl, and curl (demo keys only):

Key Value apiKey vmPUZE6mv9SD5V5e14y7Ju91duEh8A secretKey 902ae3cb34ecee2779aa4d3e1d226686 Parameter Value symbol BTCUSDT side BUY type LIMIT volume 1 price 9300 Signature Generation Request Body:

json {"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"} HMAC SHA256 Signature:

bash [linux]$ echo -n "1588591856950POST/sapi/v1/order/test{"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"}" | openssl dgst -sha256 -hmac "902ae3cb34ecee2779aa4d3e1d226686" (stdin)= c50d0a74bb9427a9a03933d0eded03af9bf50115dc5b706882a4fcf07a26b761 Curl Command:

bash [linux]$ curl -H "X-CH-APIKEY: vmPUZE6mv9SD5V5e14y7Ju91duEh8A" -H "X-CH-SIGN: c50d0a74bb9427a9a03933d0eded03af9bf50115dc5b706882a4fcf07a26b761" -H "X-CH-TS: 1588591856950" -H "Content-Type: application/json" -X POST 'https://api.xxx.com/spot/open/sapi/v1/order/test' -d '{"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"}'