WEEX API 指南：设置、调用、权限与安全

如果您希望通过代码自动获取价格、下单并管理账户，首先需要了解如何开启、调用 WEEX API，以及最关键的——如何配置其权限范围。WEEX API 是一套 WEEX 向开发者和量化交易者开放的编程接口，提供 REST 和 WebSocket 访问方式，让您无需时刻盯着屏幕即可拉取市场数据、下单撤单以及查询账户。本指南将围绕 API 的定义、使用方法、调用方式及其安全性展开，并重点讲解大多数教程容易忽略的部分：API 权限与安全，这正是资金安全最容易出问题的地方。

以下所有接口参数均来自 WEEX 官方 API 文档，反映了截至 2026 年 7 月的公开信息。API 规则可能会发生变化，请在集成前与开发者中心核实。

什么是 WEEX API：功能概览

简而言之：WEEX API 是让代码操作您账户的通道，分为“公共”和“私有”两类。公共端点用于获取市场数据和系统配置，无需身份验证；私有端点用于处理下单、撤单和账户管理，每个请求都必须签名。在产品层面，它涵盖了 100 多种资产的现货和 USDT 本位合约。

选择 REST 还是 WebSocket 取决于您是想“单次查询”还是“持续监听”。若要查询余额或发送单笔订单，使用 REST 即可；若要接收实时价格、深度变化或订单成交推送，请保持 WebSocket 连接——它更简单且更及时。

如何获取您的 WEEX API Key

登录 WEEX 网页平台，在 API 管理页面创建密钥。系统会同时生成三项内容，您需要妥善保存：

• APIKey — 算法生成的标识符，相当于您的“用户名”。
• SecretKey — 系统颁发的私钥，用于对每个请求进行签名。
• Passphrase — 您自行设置的访问短语。请务必注意：如果丢失 Passphrase 无法找回——您必须删除该密钥组并创建新的。

每个账户最多可创建 10 组 API Key，方便您按策略和环境分配不同的密钥。创建时有两个选项决定了密钥的安全底线：您勾选的权限（见下节）和绑定的 IP。WEEX 明确指出，未绑定 IP 的“无限制”密钥存在安全风险——如果您的服务器 IP 固定，请务必填写 IP 白名单。

WEEX API 权限：只读与交易的界限

本节请务必阅读两遍。新创建的 API Key 默认权限为“只读”。若要通过 API 进行交易，您必须手动启用相应的“现货”交易权限。权限过大意味着密钥泄露后的损失更大；权限过小则策略无法运行。原则只有一条：仅授予策略实际需要的最小权限。

一个容易被忽视但对安全至关重要的细节：截至 2026 年 7 月，WEEX 现货 API 快速入门文档中列出的权限仅为“只读”和“现货交易”这两项，没有单独的“提现”开关。对于大多数策略而言，这是一个功能而非缺陷：即使密钥泄露，持有者也无法直接提取资产。请以您实际创建密钥页面显示的选项为准。

如何调用：签名请求的必要条件

私有端点调用的核心门槛在于“签名”步骤。WEEX 使用 HMAC SHA256 生成签名：用您的 SecretKey 加密预签名字符串，然后对结果进行 Base64 编码。预签名字符串的拼接顺序是固定的：

timestamp + method (大写) + requestPath + "?" + queryString + body

当 queryString 为空时省略。以 GET 深度请求为例：/api/v3/market/depth?symbol=BTCUSDT&limit=20，时间戳为 1591089508404，生成的预签名字符串为 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20。

签名后，每个私有请求需携带四个请求头：

私有 WebSocket 通道的操作方式相同——对时间戳加上请求路径 /v3/ws/private 进行签名即可登录。新手最容易卡住的地方不是加密，而是时间戳：如果您的请求时间戳与服务器时间偏差超过 30 秒，请求将被直接拒绝。本地时钟错误或缓存的时间戳过期会导致莫名其妙的 401 错误。在上线前同步 NTP 时间可以省去一半的调试工作。完整字段和示例请参考官方 集成准备文档 和 签名参考。

必须了解的速率限制与访问规则

调用频率有限制。默认上限为 10 次请求/秒，部分端点在文档中会有单独说明；超过限制会返回 429 Too Many Requests。注意统计基准：已授权请求按 API Key 计算，未授权请求按公共 IP 计算——这意味着同一服务器上多个共享出口 IP 的只读脚本可能会挤占公共端点的配额。

有一条批量处理规则值得记住：一个包含 4 个交易对、每个交易对 10 个订单的批量订单请求，仅计为一次请求。通过合并订单，高频策略可以在提高吞吐量的同时节省配额。

WEEX API 安全吗？区分可控与不可控因素

“安全吗”这个问题不能简单回答。在平台端，您拥有签名验证、IP 绑定、分级权限和基于时间戳的重放保护。但在 API 实际应用中，大多数事故发生在用户侧——密钥存储不当、权限范围过大、凭证硬编码在前端或公开仓库中。可控的部分完全掌握在您手中：

• 将权限限制在最小范围内；只读策略绝不应持有交易权限。
• 为每个密钥绑定固定 IP——不要使用无限制密钥。
• 将 SecretKey 和 Passphrase 存放在环境变量或密钥管理器中，绝不要硬编码在客户端代码中或提交到 Git。
• 开发和生产环境使用不同的密钥，避免相互干扰。
• 定期轮换密钥，一旦发现异常调用，立即在网页平台删除密钥——密钥随时可以撤销并重建，这是止损的最快方法。
• 对账户活动和调用量设置监控和警报，以便异常频率或订单能立即被发现。

如需更广泛的功能概览和常见问题解答，请参阅 WEEX 关于 WEEX 是否支持 API 交易 的说明。只要做好上述检查清单，WEEX API 的安全性主要取决于您的密钥管理习惯，而非任何神秘因素。

简要总结

接入 WEEX API 的路径其实很清晰：在网页平台创建具有最小权限的 API Key（默认只读，交易需手动开启），收集 APIKey / SecretKey / Passphrase 三件套并绑定 IP；调用私有端点时，按固定格式使用 HMAC SHA256 签名，发送全部四个请求头，并遵守 30 秒时间戳窗口和 10 次/秒的速率限制；最后，严格把控密钥管理、最小权限原则、IP 白名单和监控报警。若要上手，请先在 WEEX 开发者中心 对公共市场端点进行首次请求，然后再加入私有下单功能。

常见问题解答

1. WEEX 支持 API 交易吗？

支持。WEEX 提供 REST 和 WebSocket 接口，用于自动化市场数据获取、下单撤单以及账户管理，涵盖现货和 USDT 本位合约——适用于量化、网格和做市机器人。

2. 一个账户可以创建多少个 API Key？

最多 10 组。最好按策略和环境进行拆分——例如一个只读监控密钥、一个现货交易密钥、一个开发/测试密钥——这样它们可以独立运行并单独撤销。

3. 如果忘记了 Passphrase 怎么办？

无法找回。Passphrase 是您创建时自行定义的短语，系统不会以明文形式存储。如果丢失，您只能删除该 API Key 组并重新创建。

4. 为什么我的私有请求一直被拒绝？

最常见的原因是时间戳。如果您的请求时间戳与 WEEX 服务器时间偏差超过 30 秒，请求会被拒绝——请先同步本地时钟。然后检查预签名字符串的顺序、方法名是否为大写，以及四个请求头是否齐全。

5. 如果我的 API Key 泄露，攻击者可以提走我的币吗？

对于现货 API，风险相对可控——截至 2026 年 7 月，文档中说明的权限仅为“只读”和“现货交易”，没有独立的提现权限。即便如此，也请立即在网页平台删除泄露的密钥，并检查是否有异常订单。

6. 调用有速率限制吗？

有。默认限制为 10 次请求/秒；超过限制会返回 429。已授权请求按 API Key 计算，未授权请求按 IP 计算。批量订单（例如 4 个交易对各 10 个订单）计为一次请求，高频策略可以利用这一点来节省配额。

风险提示

数字资产波动剧烈，通过 API 进行程序化交易可能会放大而非降低风险，可能导致本金部分或全部损失。API 交易特有的风险包括：密钥泄露导致的盗窃或未经授权的订单、代码逻辑错误导致的级联错误订单、网络延迟或时间戳漂移导致的订单失败、因超过调用限制被限流而错失市场，以及合约杠杆下的强平风险。请务必将密钥权限限制在最小范围，绑定 IP，妥善保管 SecretKey 和 Passphrase，并在上线前在小规模环境中进行充分测试。本文仅为技术集成指南，不构成投资建议。