Skip to main content

Basic Info

REST Basic Info​

  • Some endpoints may require the user's API Key. Please refer to here for how to create an API Key.
  • The REST API base URL listed in this document: https://api.ztdx.io
  • All endpoint responses are in JSON format.
  • If a response contains an array, the array elements are sorted by time in ascending order — the earliest data comes first.
  • All times and timestamps are UNIX time in milliseconds.
  • All data types follow JAVA data type definitions.

Testnet API Info​

  • The endpoints in this document can also be used on the testnet platform.
  • Testnet REST base URL: https://api-sepolia.ztdx.io
  • Testnet WebSocket base URL: wss://api-sepolia.ztdx.io/ws

Endpoint Basic Info​

  • For GET endpoints, parameters must be sent in the query string.
  • For POST, PUT, and DELETE endpoints, parameters can be sent in the query string or in the request body (content type application/x-www-form-urlencoded). You may mix these two methods. However, if the same parameter name appears in both the query string and request body, the query string value takes precedence.
  • There is no requirement for parameter ordering.

HTTP Return Codes​

  • HTTP 4XX error codes indicate an invalid request — wrong content, behavior, or format.
  • HTTP 403 error code indicates a WAF (Web Application Firewall) restriction violation.
  • HTTP 408 return code indicates a timeout occurred while waiting for a response from the backend server.
  • HTTP 429 error code is a warning that the request rate limit has been exceeded and the IP is about to be banned.
  • HTTP 418 indicates that continued requests were made after receiving a 429, and the IP has been banned.
  • HTTP 5XX error codes indicate issues on the Binance service side.
  • If the response contains the error message "Request occur unknown error.", please retry the request later.
  • HTTP 503 indicates three possible scenarios:
    • If the response contains the error message "Unknown error, please check your request or try again later.", it means the API server has submitted the request to the business core but did not receive a response. It is important to note that this does not mean the request failed — the outcome is unknown. It may have been executed successfully, or it may have failed. Further confirmation is needed.
    • If the response contains the error message "Service Unavailable.", it means this API request has failed. The service may be temporarily unavailable, and you should retry later.
    • If the response contains the error message "Internal error; unable to process your request. Please try again.", it means this API request has failed. You may choose to retry immediately if needed.
    • If the response contains the error message "Request throttled by system-level protection. Reduce-only/close-position orders are exempt. Please try again.(-1008)". This means the node has exceeded the maximum concurrency limit and is temporarily rate-limited. Close-position, reduce-only, and cancel orders are exempt and will not trigger this error.
  • HTTP 503 Status Code: Error Types and Handling
    • A. "Unknown error, please check your request or try again later." (Execution status unknown) Meaning: The API successfully received the request but did not return a result before the timeout; the execution status is unknown (it may have succeeded). Handling: Do not retry directly as a failure; first confirm whether the order was executed via WebSocket reports or orderId queries to avoid duplicate orders. During peak periods, prefer single order placement over batch orders to reduce uncertainty. Rate limit impact: May or may not count toward the rate limit; refer to the rate count information in the response header.
    • B. "Service Unavailable." (Failure) Meaning: Service temporarily unavailable; 100% failure. Handling: Retry with backoff (e.g., 200ms → 400ms → 800ms, max 3–5 retries). Rate limit impact: Does not count toward the rate limit.
    • C. "Request throttled by system-level protection. Reduce-only/close-position orders are exempt. Please try again." (-1008, Failure) Meaning: System overloaded; 100% failure. Handling: Retry with backoff and reduce concurrency. Applicable endpoints: POST /fapi/v1/order POST /fapi/v1/batchOrders POST /fapi/v1/order/test Exemption note (applies only to C): When a request meets the reduce-only/close-position criteria (closePosition = true, or positionSide = BOTH with reduceOnly = true, or LONG+SELL, or SHORT+BUY), it will not be affected by the -1008 overload and receives priority processing to ensure risk convergence. Covered endpoints: POST /fapi/v1/order, POST /fapi/v1/batchOrders (when parameters meet the reduce-only/close-position criteria) Endpoint Error Codes Each endpoint may throw an exception. The exception response format is as follows:
{
  "code": -1121,
  "msg": "Invalid symbol."
}

For specific error codes and their explanations, see Error Codes.