币案API接口文档详解与常见问题解答指南

最近工作室在搞量化交易系统，需要接入行情数据和交易执行接口，对比了好几家，最后选了币案API。说实话，刚开始看官方文档的时候，头还是有点大的，感觉写得不够直白，有些细节藏着掖着。折腾了两三天，踩了不少坑，总算是把该通的都通了。今天就把我这几天摸爬滚打的经验整理一下，主要是给那些准备用币案API或者正在被币案API折磨的朋友们一个参考，省得你们再走弯路。

币案API的接入流程到底怎么走？

首先你得去币案官网注册一个账号，这个没啥好说的。注册完之后，别急着去翻文档，先去个人中心找到API管理那一栏。创建API Key的时候，它会让你选权限，比如只读、交易、提现这些。这里一定要想清楚，如果只是拿行情数据，就勾只读权限，别手贱全勾上，安全第一。

创建好之后，你会拿到一串Access Key和Secret Key。Secret Key只在创建的时候显示一次，一定要复制粘贴保存好，丢了就只能重新创建了。我当时就是没注意，随手把页面关了，后来又重新创建了一次，挺耽误时间的。

搞定密钥之后，接下来就是看文档了。币案API的文档结构还算清晰，主要分为行情接口、交易接口和账户接口三大块。我个人建议，先从行情接口入手，把数据拉通了，再去碰交易接口，这样心里比较有底。

接口调用时的鉴权方式有哪些讲究？

这块是很多新手容易卡壳的地方。币案API的鉴权方式用的是标准的HMAC SHA256签名。简单来说，就是把请求参数按照一定规则拼接起来，然后用你的Secret Key去加密生成一个签名，最后放在请求头里发过去。

具体拼接规则文档里有写，但我觉得它写得太嗦了。我自己总结下来就三步：第一，把所有请求参数（除了sign本身）按照参数名的ASCII码从小到大排序；第二，把排序后的参数用&连接成字符串，如果请求体是JSON格式，那就先转成查询字符串格式；第三，用Secret Key对拼接好的字符串进行HMAC SHA256加密，得到的结果再转成十六进制字符串，这就是你的签名。

这里有个小坑，就是Timestamp参数。币案API要求你传当前时间的Unix时间戳（秒级），而且服务器会校验这个时间跟它自己时间的误差。如果偏差超过30秒，请求会被直接拒绝。我当时就是服务器时间没同步，一直报签名无效的错误，排查了半天才发现是时区问题，后来装了NTP服务自动同步时间才解决。所以大家如果遇到鉴权失败，先看看自己服务器时间准不准。

另外，请求头里除了签名，还要带上Access Key，有些接口还需要传passphrase，这个在创建API Key的时候会让你设置，也是一次性的，忘记了就只能重置。

核心接口调用时那些参数坑你避开了吗？

先说行情接口，像获取K线、实时价格这些，参数相对简单。但有个地方要注意，就是K线的时间粒度。币案API支持1min、5min、15min、30min、1hour、4hour、1day这些值，你得传对应的枚举值，比如传个"60"它是不认的，会直接报参数错误。刚开始我以为是传分钟数，传了个60，结果返回错误码，看了文档才发现要用特定字符串。

交易接口这块，坑就更多了。首先，下单的时候，价格和数量精度问题要特别留意。每个交易对都有自己最小下单量、价格精度和小数位数限制。你如果价格精度不对，比如它支持小数点后两位，你传了三位小数，接口不会给你四舍五入，而是直接报错。所以下单前，最好先调一下交易规则接口，把那边的tick_size和step_size拉下来，在本地做一下格式化。

还有就是订单类型，币案API支持限价单、市价单、止损限价单这些。市价单的话，不需要传价格，但要传金额或者数量，具体看你是按金额买还是按数量买。这里有个容易混淆的地方，就是市价买单可能需要传金额（quoteOrderQty），而市价卖单则传数量（quantity），传反了也会报错。我当时测试市价单的时候，就因为这个参数理解错了，反复报参数错误，差点怀疑人生。

另外，撤单接口和查单接口，都必须传原始订单ID（orderId），这个是下单成功时接口返回的。如果你用了你自己的客户端订单ID（clientOid），那么查询的时候要用对应的查询接口，别搞混了。我自己由于开发的时候没注意，用clientOid去调了查单接口，结果一直查不到订单状态，后来才发现接口用错了。

遇到常见的报错代码怎么快速解决？

币案API的报错信息还算友好，一般都会在返回的JSON里带一个code字段和msg字段。我总结几个我遇到过的和网上大家常问的：

最常见的就是40001，签名无效。这个大概率是签名算法写错了，或者是时间戳偏差过大。先检查时间，再检查参数排序和编码格式，特别是URL编码那块，有些字符编码不一致会导致签名对不上。

40002，参数错误。这个就是字面意思，你传的参数不符合接口要求。对照文档，检查参数名是否拼错、参数值类型是否对、是否超出了枚举范围。另外，如果是数字类型，别传字符串，有些语言会自动转换，但有些不会，容易出错。

40003，权限不足。这个是你创建的API Key权限不够。比如你只开了只读权限，却去调用交易接口，就会报这个错。回到后台去修改权限，或者重新创建一个有交易权限的Key。

40004，请求频率超限。币案API对访问频率有严格控制，尤其是行情接口，虽然免费但限频很厉害。比如获取K线，可能每秒只能请求几次。解决方法是做好本地缓存，别频繁拉取数据，或者升级账户的VIP等级，提高频次限制。

还有一个是40005，大概是IP白名单限制。如果你在创建API Key的时候设置了IP白名单，那么只有在白名单里的IP才能访问。这个是为了安全，但有时候你换了网络环境就会忘记这茬，导致请求被拒。没啥好说的，去后台把当前IP加进去就行。

WebSocket连接订阅数据稳定吗？

如果你做的是高频交易或者实时行情展示，用REST接口轮询肯定不行，延迟高还容易被限频。币案API也提供了WebSocket接口，用来订阅实时行情和账户变动。

连接方式没啥特别的，就是用标准的WebSocket协议连上去，然后发送订阅消息。不过要注意，连接建立后，你需要定期发送心跳包（ping），服务器才会保持连接。币案API要求每30秒发送一次ping，如果超过一定时间没收到pong，连接就会被断开。

我实际用下来，连接稳定性还行，但偶尔也会遇到断线重连的情况。所以代码里一定要做好断线重连机制，并且要维护好订阅状态。比如你订阅了BTC-USDT的深度数据，断线重连后，需要重新发送订阅消息，否则收不到数据。这里建议用第三方库来管理连接和自动重连，不要自己裸写WebSocket，不然光处理各种异常状态就够你喝一壶的。

还有一点，WebSocket推送的数据量很大，尤其是深度数据，如果你服务器带宽不够或者处理不过来，容易造成消息积压，导致程序越来越卡。建议在接收端做异步处理，或者只订阅你需要的深度档位，比如只订阅第一档（盘口最优价），这样数据量会小很多。