FAQ

HTX交易所
开发者FAQ

HTX交易所API接入常见问题与故障排查,涵盖速率限制、WebSocket连接、订单延迟、认证错误、历史数据等15+个开发者高频问题。

API接入基础

Q1: HTX交易所API的速率限制是多少?超限后会怎样? +

HTX交易所对不同类型的API端点设置了差异化速率限制:

  • 行情公共接口:200次/秒(无需认证)
  • 交易私有接口:100次/秒(需HMAC签名)
  • 账户查询接口:50次/秒

超限后API返回HTTP 429 Too Many Requests状态码,响应体包含err-code: "api-signature-not-valid"或"rate-limit-exceeded"。建议实现指数退避重试(Exponential Backoff),初始等待1秒,最大等待32秒。VIP用户可申请更高配额。

Q2: REST API和WebSocket API应该如何选择? +

选择建议:

  • REST API:适用于下单、撤单、查询余额、获取历史交易等请求-响应场景。每次操作需要独立HTTP请求。
  • WebSocket API:适用于实时行情推送、深度数据订阅、订单状态变更等实时流场景。建立连接后服务端主动推送数据。

量化交易推荐组合:使用WebSocket接收行情数据驱动策略决策,使用REST API执行下单操作。这样既能获得最低延迟的行情数据,又能可靠地执行交易指令。

Q3: HMAC-SHA256签名认证失败怎么排查? +

HTX交易所HMAC签名错误常见原因及排查步骤:

  • 时间戳偏移:确保服务器UTC时间与HTX交易所服务器时间偏差不超过±30秒。使用GET /v1/common/timestamp校准。
  • 参数排序错误:所有查询参数必须按ASCII码升序排列后拼接。
  • URL编码问题:时间戳中的冒号:不需要编码,但空格必须编码为%20(不是+)。
  • Secret Key错误:确认使用的是Secret Key而非Access Key进行HMAC运算。
  • 签名方法声明:参数中必须包含SignatureMethod=HmacSHA256和SignatureVersion=2。
Q4: IP白名单和HMAC认证有什么区别?两者都需要吗? +

HMAC-SHA256认证是必需的,用于验证请求的合法性和完整性。每个私有API请求都必须携带有效签名。

IP白名单是可选但强烈推荐的额外安全层。设置后,即使API密钥泄露,攻击者也无法从非白名单IP发起请求。

最佳实践:两者同时启用。HMAC确保请求未被篡改,IP白名单限制请求来源。生产环境务必设置IP白名单。

Q5: HTX交易所API支持哪些K线(Candlestick)时间间隔? +

HTX交易所K线接口/market/history/kline支持以下时间周期:

  • 分钟级:1min, 5min, 15min, 30min, 60min
  • 小时级:4hour
  • 日/周/月级:1day, 1week, 1mon
  • 年级:1year

单次请求最多返回2000根K线。获取更长历史数据需要分页请求。WebSocket也支持K线订阅:market.btcusdt.kline.1min。

WebSocket连接与故障排查

Q6: WebSocket连接经常断开,如何实现稳定重连? +

HTX交易所WebSocket连接断开的常见原因和重连策略:

  • 心跳超时:服务端每20秒发送Ping,客户端必须在5秒内回复Pong,否则断开。
  • 网络抖动:使用指数退避重连:1s → 2s → 4s → 8s → 16s → 最大30s。
  • 订阅恢复:重连后必须重新发送所有订阅消息,连接状态不会保留。
  • 连接数限制:单IP最多50个并发WebSocket连接。超出将被拒绝。

推荐实现:维护一个订阅列表,在on_open回调中自动重新订阅所有频道。使用threading.Timer实现心跳检测。

Q7: WebSocket接收到的数据是乱码? +

HTX交易所WebSocket推送的数据经过GZIP压缩。你需要先解压再解析JSON:

json.loads(gzip.decompress(message).decode('utf-8'))

如果使用的WebSocket客户端不支持自动解压,务必在on_message回调中手动处理。Python的websocket-client库接收的是二进制帧,需要用gzip.decompress()解压。

Q8: 如何订阅多个交易对的深度数据? +

在同一个WebSocket连接中可以发送多个订阅消息。每个订阅使用唯一的id标识:

{"sub": "market.btcusdt.depth.step0", "id": "depth_btc"}
{"sub": "market.ethusdt.depth.step0", "id": "depth_eth"}

深度数据支持5个精度级别:step0(无聚合)到step5(最大聚合)。高频策略推荐使用step0获取完整深度。单连接最多100个订阅。

Q9: WebSocket订阅订单更新需要认证吗? +

是的。HTX交易所的私有WebSocket频道(订单更新、账户余额变更)需要认证。连接建立后,发送认证消息:

{"action": "req", "ch": "auth", "params": {"authType": "api", "accessKey": "...", "signatureMethod": "HmacSHA256", "signatureVersion": "2.1", "timestamp": "...", "signature": "..."}}

认证成功后可订阅:orders#btcusdt(订单更新)、accounts.update#2(余额变更)。认证有效期与连接生命周期相同。

Q10: WebSocket消息延迟过高怎么优化? +

降低HTX交易所WebSocket消息处理延迟的方法:

  • 就近部署:将服务器部署在AWS东京(ap-northeast-1)或新加坡(ap-southeast-1),靠近HTX交易所API节点。
  • 异步处理:使用asyncio + aiohttp替代同步库,避免回调阻塞。
  • 减少订阅:只订阅策略所需的频道,减少数据解析负担。
  • 消息队列:使用asyncio.Queue将解压和解析放入独立协程。
  • 正常延迟基准:市场数据<50ms,订单更新<100ms。

交易执行与数据获取

Q11: 订单下达到成交的延迟是多少?如何优化? +

HTX交易所REST API下单延迟基准(从请求发出到收到确认):

  • 市价单:50-150ms(取决于网络和服务器负载)
  • 限价单:30-100ms(挂单无需撮合)
  • 批量下单:100-300ms(最多支持10单/批)

优化建议:使用批量下单接口/v1/order/batch-orders减少HTTP往返次数。保持HTTP连接Keep-Alive复用TCP连接。生产环境使用专用VPS,避免共享网络带宽。

Q12: 如何获取HTX交易所历史交易数据用于回测? +

HTX交易所提供多种历史数据获取方式:

  • K线数据:GET /market/history/kline?symbol=btcusdt&period=1min&size=2000,单次最多2000条。
  • 成交记录:GET /market/history/trade?symbol=btcusdt&size=2000,返回最近成交记录。
  • 深度快照:GET /market/depth?symbol=btcusdt&type=step0&depth=150,当前时刻深度。

对于大规模回测数据(数月/数年),建议自建数据采集管道:用定时任务或WebSocket持续录制Tick数据到本地数据库(推荐ClickHouse或TimescaleDB)。

Q13: 批量撤单接口有什么限制? +

HTX交易所批量撤单接口POST /v1/order/orders/batchcancel:

  • 单次最多撤销50个订单
  • 支持按订单ID列表撤销,也支持按交易对全撤
  • 速率限制:50次/秒
  • 部分失败不影响其他订单的撤销

紧急全撤推荐使用:POST /v1/order/orders/batchCancelOpenOrders,按交易对或账户维度一次性撤销所有挂单。

Q14: 常见API错误代码及其含义? +

HTX交易所API常见错误代码参考:

  • api-signature-not-valid — HMAC签名验证失败,检查签名算法。
  • invalid-parameter — 请求参数格式或值不正确。
  • order-accountbalance-error — 账户余额不足以下单。
  • order-limitorder-price-error — 限价单价格超出允许范围(偏离市价过大)。
  • order-value-min-error — 订单金额低于最小交易额(通常5 USDT)。
  • order-orderprice-precision-error — 价格精度超出交易对规定的小数位数。
  • base-not-found — 请求的资源或接口路径不存在。
  • account-frozen-balance-insufficient-error — 冻结余额不足(有挂单占用)。
Q15: 如何查询交易对的精度和最小交易量? +

使用HTX交易所交易对信息接口:GET /v1/common/symbols

返回字段包括:

  • price-precision — 价格小数位数(如BTC/USDT为2位)
  • amount-precision — 数量小数位数(如BTC为6位)
  • min-order-amt — 最小下单数量
  • min-order-value — 最小下单金额(USDT计价)
  • limit-order-min-order-amt — 限价单最小数量
  • sell-market-min-order-amt — 市价卖单最小数量

建议在交易机器人启动时调用此接口缓存所有交易对参数,避免因精度错误导致下单失败。

Q16: 如何监控API密钥的使用情况? +

HTX交易所目前未提供直接的API使用量查询接口。推荐的监控方案:

  • 在交易机器人中实现请求计数器,记录每秒/每分钟的API调用次数
  • 监控HTTP响应头中的X-RateLimit-Remaining字段(如有)
  • 记录所有429响应,触发告警通知
  • 使用Grafana + Prometheus可视化API调用模式
  • 定期审查HTX交易所账户的登录日志和操作记录

详细安全监控方案请参阅 HTX交易所安全配置指南。

保护你的API密钥

了解HTX交易所API密钥权限管理、IP白名单配置与HMAC签名安全最佳实践。

安全配置 → API指南 →