先搞清楚你要用哪一类接口
很多人一上来就问“binance.com api 怎么调”,其实币安的接口分成好几套,能力边界完全不同,选错了后面全部要返工:
- REST API:一问一答的 HTTP 接口,适合下单、查余额、拉历史 K 线。绝大多数业务用它就够了。
- WebSocket 行情流:价格变动实时推送,做盘口监控、tick 级策略必须用它,比轮询 REST 省几十倍流量和限频额度。
- WebSocket 用户数据流:推送你自己的订单状态、成交、余额变化。注意它需要先用 REST 拿到 listenKey,并且要定期续期,否则会断。
- 现货 / 合约 / 期权:域名前缀和路径都不同。现货是 api.binance.com,U 本位合约是 fapi.binance.com,币本位是 dapi.binance.com。参数结构也有差异,比如合约的仓位模式、杠杆需要单独设置。
实践建议:先明确是“读数据”还是“下真单”。只读行情用公开接口,连密钥都不用;涉及账户就必须走签名流程。
API Key 的正确申请与权限隔离
在账户的 API 管理页面创建密钥时,有几个选项直接决定资金安全,务必逐项确认:
- 只勾选需要的权限。只做行情分析,就只要“允许读取”,绝不开“允许现货交易”和“允许提现”。提现权限建议永远不要开。
- 绑定 IP 白名单。这是最有效的一道防线,即使密钥泄露,别人从别的 IP 也用不了。服务器出口 IP 固定的话一定要绑。
- 不同用途不同密钥。策略 A、策略 B、数据看板各用一个,出问题能单独吊销,也方便排查是哪个程序打爆了限频。
- 密钥只放环境变量或密钥管理服务,不要写进代码仓库,更不要出现在前端 JS 里——前端调用等于把密钥公开。
签名请求:新手最容易卡住的地方
私有接口要求在请求头带上 X-MBX-APIKEY,并在参数中附带 timestamp 和 signature。签名的做法是:把所有参数拼成 query string,用 Secret Key 做 HMAC SHA256,再 hex 编码后作为 signature 参数传回。
三个高频报错值得提前记住:
- timestamp 超出 recvWindow:本机时间漂移导致的。先请求一次服务器时间接口拿到 serverTime,算出和本机的时间差,之后每次签名都加上这个偏移量。容器环境时钟漂移很常见。
- 签名不合法:多数是参数顺序或编码问题。签名时的参数顺序必须和实际发送完全一致,签名用的字符串里不要出现多余的 & 或者把已编码内容再编码一次。
- recvWindow 太小:网络抖动时容易失败,可以适当放宽,但不要设成天文数字,它本身是防重放的安全参数。
限频、错误码与稳定性设计
binance.com api 的限频是按权重计算的,不同接口权重差别很大,且响应头里会返回当前已用权重和上限,务必解析并做本地记账。
- 遇到限频错误时指数退避重试,不要在循环里立即重发,否则会越撞越死。
- 下单类接口不要盲目重试。网络超时不代表没成交,应先查询订单状态再决定,配合客户端订单号做幂等,避免重复开仓。
- 行情数据优先用 WebSocket,REST 只用于补历史缺口,能大幅降低权重消耗。
- 为断线重连设计状态机:连接断开后先重新订阅,再用 REST 校准一次本地缓存,防止用过期盘口做决策。
- 做撮合逻辑时注意精度:价格和数量必须按交易对的精度规则取整,否则会直接被拒单。
上线前的检查清单
在把资金交给程序之前,建议先跑通这几步:在测试网(spot testnet / futures testnet)完整走一遍下单、撤单、查询流程;用小额资金在主网验证一次真实成交与回调;把密钥权限收到最小、绑好 IP;给程序加上单日最大下单量、最大持仓、异常自动停机等硬性熔断。做完这些,你的 binance.com api 接入才算真正可用,而不是“本地能跑”。