基本信息

API基本信息

• REST 接口 baseurl：
  • 现货 / 杠杆：https://openapi.bitbaby.com/spot/open
  • 合约：https://openapi.bitbaby.com/futures/open
• WebSocket baseurl：
  • 现货行情：wss://openapi.bitbaby.com/spot/ws
  • 合约行情：wss://openapi.bitbaby.com/futures/ws
• 所有接口都会返回一个 JSON object 或者 array。
• 响应中如有数组，数组元素以时间倒序排列，越早的数据越提前。
• 所有时间、时间戳均为 UNIX 时间，单位为毫秒。

HTTP返回代码

• HTTP 4XX 错误码用于指示错误的请求内容、行为、格式.
• HTTP 429 错误码表示警告访问频次超限，即将被封IP.
• HTTP 418 表示收到429后继续访问，于是被封了.
• HTTP 5XX 返回错误码是内部系统错误；这说明这个问题是在服务器这边。在对待这个错误时，千万 不要把它当成一个失败的任务，因为执行状态 未知，有可能是成功也有可能是失败.
• HTTP 504 表示API服务端已经向业务核心提交了请求但未能获取响应，特别需要注意的是504代码不代表请求失败，而是未知。很可能已经得到了执行，也有可能执行失败，需要做进一步确认.
• 任何接口都可能返回ERROR(错误); 错误的返回payload如下:

{
  "code": -1121,
  "msg": "Invalid symbol."
}

接口通用信息

• 所有请求基于 HTTPS 协议，请求头信息中Content-Type需要统一设置为：application/json
• GET方法的接口, 参数必须在query string中发送.
• POST方法的接口, 参数必须在request body中发送.
• 对参数的顺序不做要求。

访问限制

• 在每个接口下面会有限频的说明.
• 违反频率限制都会收到 HTTP 429，这是一个警告.
• 当收到429告警时，调用者应当降低访问频率或者停止访问.

接口鉴权类型

• 每个接口都有自己的鉴权类型，鉴权类型决定了访问时应当进行何种鉴权
• 如果需要 API-key，应当在 HTTP 头中以X-CH-APIKEY字段传递
• API-key 与 API-secret 是大小写敏感的
• 可以在网页用户中心修改 API-key 所具有的权限，例如读取账户信息、发送交易指令、发送提现指令

鉴权类型	描述
NONE	不需要鉴权的接口
TRADE	需要有效的 API-KEY 和签名
USER_DATA	需要有效的 API-KEY 和签名
MARKET_DATA	需要有效的 API-KEY

需要签名的接口（TRADE 与 USER_DATA）

调用 TRADE 或 USER_DATA 接口时，必须同时携带以下三个请求头：

Header	说明
X-CH-APIKEY	您的 API-Key
X-CH-TS	客户端时间戳，毫秒，例如 1767867649647
X-CH-SIGN	使用 API-Secret 对 PreHash 字符串做 HMAC-SHA256 后输出的 小写十六进制 字符串

PreHash 拼接公式

PreHash = timestamp + method + requestPath
        + ("?" + queryString)?    // 仅当 queryString 非空时拼接
        + body?                   // 仅当 body 非空时拼接（POST 必带，GET 省略）

• timestamp：与 X-CH-TS 完全相同的字符串。
• method：HTTP 方法，字母全部大写：GET / POST。
• requestPath：API 路径，例如 /sapi/v1/order、/fapi/v1/openOrders。
• queryString：URL 中 ? 后的部分，例如 symbol=BTCUSDT&limit=10。注意 ? 由公式拼接，不要把 ? 写进 queryString 本身。
• body：POST 请求的 原始请求体字符串（即 HTTP 实际发送的字节），与 Content-Type: application/json 配套；GET 请求 省略 body，不要传入空对象 {} 也不要传入空串以外的占位符。

关键提示（最常踩的坑）

requestPath 不要带网关前缀 /spot/open 或 /futures/open。 网关在路由到后端业务前会先剥掉前缀，因此签名校验使用的 requestPath 始终是 /sapi/v1/... 或 /fapi/v1/...。

例如完整 URL 是 https://openapi.bitbaby.com/futures/open/fapi/v1/openOrders?contractName=E-ETH-USDT，签名时使用的 requestPath 是 /fapi/v1/openOrders，不是 /futures/open/fapi/v1/openOrders。

关于 POST body

POST 时用于签名的 body 必须与 HTTP 实际发送的字节 逐字符相同。这意味着：

• 不要让 HTTP 客户端在你计算完签名后再做一次 JSON 序列化（字段顺序、空格、数字精度都会改变 body）。
• 推荐做法：先 json.dumps/JSON.stringify 出最终字符串 → 用这个字符串做 HMAC → 再用同一个字符串作为 HTTP body 发送。
• 如果业务确实没有 body（例如某些 POST 仅依赖 query），约定使用空字符串 ""，不要使用 {}。

时间同步安全

• 签名接口均需在 HTTP 头中以 X-CH-TS 字段传递时间戳，单位为毫秒。
• 服务器收到请求时会判断请求中的时间戳，如果是 5000 毫秒之前发出的，则请求会被认为无效。这个时间窗口可以通过可选参数 recvWindow 来调整（POST 写在 body 中，GET 写在 query 中）。
• 如果客户端时间戳比服务器时间快 1 秒以上，请求也会被拒绝。
• 校验逻辑伪代码：

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
  // process request
} else {
  // reject request
}

关于交易时效性： 互联网状况并不 100% 可靠，本地到交易所的网络时延会有抖动。这正是 recvWindow 的意义所在。如果你从事高频交易，可以适当调小 recvWindow；不推荐使用大于 5000ms 的值。

---

签名示例

下面给出 GET 与 POST 两种典型场景的端到端示例，apikey 与 secretkey 仅供示范。

Key	Value
apiKey	vmPUZE6mv9SD5V5e14y7Ju91duEh8A
secretKey	902ae3cb34ecee2779aa4d3e1d226686

示例 1：GET /sapi/v1/openOrders?symbol=BTCUSDT&limit=10

• PreHash：

1588591856950GET/sapi/v1/openOrders?symbol=BTCUSDT&limit=10

• HMAC-SHA256 签名（bash + openssl）：

echo -n "1588591856950GET/sapi/v1/openOrders?symbol=BTCUSDT&limit=10" \
  | openssl dgst -sha256 -hmac "902ae3cb34ecee2779aa4d3e1d226686"

• 完整 curl 调用：

curl -X GET 'https://openapi.bitbaby.com/spot/open/sapi/v1/openOrders?symbol=BTCUSDT&limit=10' \
  -H 'X-CH-APIKEY: vmPUZE6mv9SD5V5e14y7Ju91duEh8A' \
  -H 'X-CH-TS: 1588591856950' \
  -H 'X-CH-SIGN: <上一步算出的 hex>' \
  -H 'Content-Type: application/json'

示例 2：POST /sapi/v1/order/test

参数	取值
symbol	BTCUSDT
side	BUY
type	LIMIT
volume	1
price	9300

• body（用于签名与 HTTP 发送的字符串完全一致）：

{"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"}

• PreHash：

1588591856950POST/sapi/v1/order/test{"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"}

• HMAC-SHA256 签名（bash + openssl）：

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 调用：

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