跳到主要内容

基本信息

Rest 基本信息​

  • 接口可能需要用户的 API Key，如何创建API-KEY请参考这里
  • 本篇列出REST接口的baseurl https://api.ztdx.io
  • 所有接口的响应都是JSON格式
  • 响应中如有数组，数组元素以时间升序排列，越早的数据越提前。
  • 所有时间、时间戳均为UNIX时间，单位为毫秒
  • 所有数据类型采用JAVA的数据类型定义

Testnet API 信息​

  • 本篇接口亦可接入testnet测试平台使用
  • testnet的 REST baseurl 为 https://api-sepolia.ztdx.io
  • testnet的 Websocket baseurl 为 wss://api-sepolia.ztdx.io/ws

接口的基本信息​

  • GET方法的接口, 参数必须在query string中发送.
  • POST, PUT, 和 DELETE 方法的接口, 参数可以在 query string中发送，也可以在 request body中发送(content type application/x-www-form-urlencoded)。允许混合这两种方式发送参数。但如果同一个参数名在query string和request body中都有，query string中的会被优先采用。
  • 对参数的顺序不做要求。

HTTP 返回代码​

  • HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。
  • HTTP 403 错误码表示违反WAF限制(Web应用程序防火墙)。
  • HTTP 408 返回代码表示在等待后端服务器响应时发生了超时。
  • HTTP 429 错误码表示警告访问频次超限，即将被封IP
  • HTTP 418 表示收到429后继续访问，于是被封了。
  • HTTP 5XX 错误码用于指示Binance服务侧的问题。
  • 如果返回内容里包含了报错信息 "Request occur unknown error."，请稍后重试请求。
  • HTTP 503 表示三种可能：
    • 如果返回内容里包含了报错信息 "Unknown error, please check your request or try again later."，则表示API服务端已经向业务核心提交了请求但未能获取响应，特别需要注意的是其不代表请求失败，而是未知。很可能已经得到了执行，也有可能执行失败，需要做进一步确认。
    • 如果返回内容里包含了报错信息 "Service Unavailable."，则表示本次API请求失败。这种情况下可能是服务暂不可用，您需要稍后重试。
    • 如果返回内容里包含了报错信息 "Internal error; unable to process your request. Please try again."，则表示本次API请求失败。这种情况下您如果需要的话可以选择立即重试。
    • 如果返回内容里包含了报错信息 "Request throttled by system-level protection. Reduce-only/close-position orders are exempt. Please try again.(-1008)"。这表示节点已超出最大并发限制，正在临时限流。平仓、仅减仓与取消订单均予以豁免，不会触发该错误。
  • HTTP 503 状态码：错误类型与处理
    • A. “Unknown error, please check your request or try again later.”（执行状态未知） 语义：API 成功接收请求，但在超时前未返回结果；执行状态未知（可能已成功）。 处理： 不要直接当失败重试；先通过 WebSocket 回报或 orderId 查询确认是否已执行，避免重复下单。 高峰期尽量使用单笔下单替代批量下单以降低不确定性。 是否计入限速：可能计入，也可能不计入, 请参考header中的rate计数信息
    • B. “Service Unavailable.”（失败） 语义：服务暂不可用；100% 失败。 处理：退避重试（如 200ms → 400ms → 800ms，上限 3–5 次）。 是否计入限速：不计入
    • C. "Request throttled by system-level protection. Reduce-only/close-position orders are exempt. Please try again."（-1008，失败） 语义：系统过载；100% 失败。 处理：退避重试并降低并发； 适用接口： POST /fapi/v1/order POST /fapi/v1/batchOrders POST /fapi/v1/order/test 仅适用于 C 的豁免说明：当请求满足只减仓/平仓条件时（closePosition = true，或 positionSide = BOTH 且 reduceOnly = true，或 LONG+SELL，或 SHORT+BUY），不会受 -1008 过载的影响或享有优先处理，以保障风险收敛。 覆盖接口：POST /fapi/v1/order、POST /fapi/v1/batchOrders（当参数满足只减仓/平仓判定） 接口错误代码 每个接口都有可能抛出异常 异常响应格式如下：
{
  "code": -1121,
  "msg": "Invalid symbol."
}

具体的错误码及其解释在错误代码