WEEX API 接入指南：从创建 API Key 到完成首个行情请求

对于需要通过程序获取行情或连接交易系统的开发者、数据分析人员和量化研究团队来说，API 是将交易所行情与自身系统连接起来的基础工具。通过 API，可以把公开市场数据接入行情看板、研究脚本或告警系统；在完成安全鉴权后，也可以进一步接入账户和订单管理能力。

本文以 WEEX 现API 为例，完成一条最小接入路径：理解接口类型、创建 API Key、调用第一个无需鉴权的行情接口，并建立一套可扩展的安全接入习惯。

一、先理解：REST、WebSocket 与 API Key 分别解决什么问题？

初次接入时，最容易把所有 API 都理解成“下单接口”。实际上，一个完整的交易系统通常至少包含三类能力：

可以把它理解为：

· REST 像“主动查询”：当系统需要某一刻的数据时，向服务端发起一次请求；

· WebSocket 像“持续订阅”：连接建立后，服务端会持续推送数据变化；

· API Key 是私有能力的身份凭证：用于账户和订单等敏感操作，不应出现在前端代码、公开仓库或聊天记录中。

WEEX 官方文档将接口分为公共接口和私有接口：公共接口可获取配置与行情数据，无需认证；私有接口用于订单和账户管理，必须使用 API Key 并按规范完成签名.

如果你的目标只是做行情看板、价格提醒或数据研究，完全可以从公共接口开始，不必一开始就创建或使用交易权限。

二、创建 API Key 前，先确定权限边界

如需调用私有接口，在官网【账户】-【API 管理】中创建 API Key，并按页面提示完成安全验证。

创建时建议遵循“最小权限”原则：

1. 仅在确有账户或订单管理需求时创建 API Key；

2. 为服务端固定出口 IP 设置白名单；

3. 不要把 Secret Key 写入浏览器端、移动端 App 或公开代码仓库；

4. 为开发、测试、生产环境分别创建不同密钥；

5. 定期轮换密钥；团队成员变动或怀疑泄露时立即停用并重建。

一个常见误区是：以为 API Key 本身足够安全。实际上，私有请求通常还会携带时间戳和签名，服务端借此校验请求的来源与完整性。WEEX 现货 API 文档显示，私有请求签名采用 HMAC SHA256 后再进行 Base64 编码；签名时间戳为毫秒级，且需要处于服务端允许的时间窗口内。

三、完成第一个请求：获取 24 小时行情

建议把“拿到第一个公开行情数据”作为 API 接入的第一步：它不需要 API Key，能先验证网络、请求格式和数据解析流程是否正常。

在实际项目中，不建议将接口返回的原始 JSON 直接展示在自建看板或业务页面上。更合理的做法是先确认字段含义，再将所需的价格、成交量和涨跌幅等数据映射到自己的数据模型中。这样做的话，即使未来接口字段扩展，业务层也更容易维护。

四、为什么首个请求应从“公开行情”开始？

从工程实践看，公共行情接口是验证接入链路的低风险方式。完成这一环之后，你可以进一步拆分不同场景：

WEEX API 页面列出的公开行情能力包括实时价格、24 小时涨跌与成交量、K 线、深度及最新成交；后续可根据系统需求逐步扩展，而不是在首日就接入全部接口。

五、接入时最容易忽略的三个问题

1、不要把限频当成固定数字

API 请求限制往往会随接口、权重和版本变化。当前 WEEX 现货文档说明：除下单接口外，接口主要按 IP 限频；单笔和批量下单则按账户维度的订单频率限制。响应头会返回已使用与剩余权重，超限后会收到 HTTP 429。

因此，程序应具备以下能力：

· 读取并记录限频响应头；

· 遇到 429 时停止高频重试，采用退避策略；

· 对非实时需求设置合理缓存；

· 不用轮询代替实时订阅。

2、HTTP 200 不等于业务处理完成

HTTP 200 只表示服务端成功响应了请求。对于私有交易类请求，还需要进一步检查响应体中的业务结果、订单状态及后续推送信息。

从第一天起，就应把“网络状态”“HTTP 状态”和“业务状态”分层记录。这样后续接入下单、撤单和订单查询时，排查问题会更高效。

3、不要把密钥安全留到上线后

最常见的安全事故并非加密算法失效，而是密钥管理不当：密钥被提交到 Git、写进前端环境变量、出现在截图中，或被多人共用且无法追溯。

一个实用原则是：前端只调用你自己的业务服务；业务服务在受控环境中保存密钥并调用交易所私有 API。

六、下一步：从单次查询走向实时数据

完成第一个 REST 行情请求后，下一步可以尝试接入 WebSocket 公共频道，获取实时价格、K 线、深度和成交变化。

REST 适合“我现在想查一次”；WebSocket 更适合“只要数据变化就通知我”。对于实时行情看板、盘口观察和策略研究系统，WebSocket 通常是更合适的基础设施。

WEEX 现货 API 文档提供公共行情、交易、账户和 WebSocket 等模块，且当前版本标注为 V3（BETA）。在上线前，请以官方文档的更新日志、接口参数与错误码为最终依据。

接入检查清单

✅ 已明确项目只需公开行情，还是需要私有账户/订单能力

✅ 已验证 REST 域名、接口路径和交易对参数

✅ 已为请求设置超时、错误处理和日志

✅ 已处理 429 限频响应，避免无节制重试

✅ API Key 未存放在前端、代码仓库或公开环境

✅ 私有接口已启用 IP 白名单，并完成密钥轮换机制设计

✅ 上线前已复核官方 API 文档版本与接口规则

本文仅介绍 API 技术接入与数据处理，不构成任何投资、交易或收益承诺。接口能力、参数和限制可能更新，上线前请以 WEEX 官方文档为准。