如何调用交易所 API：密钥、签名与错误代码

大多数第一次尝试调用交易所 API 的人，失败的原因并非交易逻辑，而是握手环节——比如时间戳滞后 40 秒、漏勾选了权限复选框，或者密码短语中包含连字符。交易所拒绝请求并返回一个数字，而他们参考的教程却并未解释该数字的含义。

本指南将带你走完全程：了解什么是交易所 API、哪些调用需要密钥、签名是如何构建的，以及几乎没人公开的部分——针对你遇到的具体错误代码提供修复方案。示例使用了 WEEX API 集成指南，因为它是为数不多公开其权限模型、传播延迟和单操作速率限制的交易所开发者中心之一。以下所有内容均已于 2026 年 7 月 28 日对照 WEEX 实时开发者文档核对；该平台的现货 API 常见问题解答 的最后更新时间为 2026 年 4 月 14 日。

交易所 API 的作用及哪些调用需要密钥

交易所 API 是一组 HTTP 和 WebSocket 端点，允许你的软件执行原本需要手动点击的操作：读取价格、检查余额、下单、撤单。仅此而已，并无神秘之处。

操作层面上，关键在于公共端点与私有端点的区分。公共端点提供市场数据和平台配置，无需任何身份验证——你可以直接从浏览器访问。私有端点涉及你的账户，且每一项都必须携带签名。

一个实际的建议：你可以在生成密钥之前，先构建并测试机器人的所有数据部分。先做这一步，因为它零成本，且能在风险为零时发现你的符号格式和 K 线对齐错误。

如何创建 API 密钥并设置权限范围

在 WEEX 上，流程为：账户 → API 管理 → 创建 API 密钥，随后进行安全验证。每个账户最多可持有 10 个 API 密钥组，这足以让你为研究、测试和生产环境分别运行不同的密钥——你应该这样做，因为这样一旦密钥泄露，仅为局部事件而非整体风险。

该界面会生成三个凭证，它们不可互换：

• APIKey — 交易所用于识别你的公开标识符。
• SecretKey — 你的代码用于签名的私钥。它仅显示一次。
• Passphrase — 你设置的密码短语。如果丢失，无法找回或重置；你只能删除密钥并重新开始。WEEX 还要求它不包含特殊字符——仅限字母数字。这是一个硬性约束而非建议，密码短语中包含标点符号是导致身份验证失败的常见原因。

权限模型是值得仔细研究的部分。新创建的密钥默认仅为只读，交易权限需手动开启且相互独立。

从该表中可得出两点结论。首先，如果你构建了现货机器人却只勾选了“只读”，那么你发送的每一笔订单都会被拒绝——这是关于“我的密钥无法工作”最常见的投诉。其次，更重要的一点：列表中没有提现权限。WEEX API 密钥无法将资金转移出平台。这一结构性限制比任何密钥安全建议都更有价值，因为它将攻击者利用被盗密钥造成的损失限制在“未经授权的交易”范围内，而非清空钱包。

离开该页面前，请绑定 IP 地址。WEEX 明确将未受限的密钥视为安全风险，白名单是区分“密钥泄露导致紧急状况”与“仅造成困扰”的关键。

文档中明确指出但大多数第三方指南忽略的一个时间陷阱：新创建或修改的 API 密钥大约需要 15 分钟才能在系统中生效。 如果你在勾选新权限后立即调用失败，请耐心等待，不要急于重写签名代码。很多人曾为此调试了整整一个小时。

完整的逐项设置步骤请参考 WEEX API 集成准备指南。

如何调用交易所 API：四个标头与签名字符串

以下是剥离冗余后的核心机制。每个私有请求都携带四个身份验证标头以及内容类型。交易所会根据收到的请求独立重新计算你的签名；如果其结果与你的匹配，则请求即为真实有效。

签名本身是你按固定顺序拼接字符串后的哈希值：

时间戳 + 大写 HTTP 方法 + 请求路径 + ? + 查询字符串 + 正文

将它们连接起来，使用你的 SecretKey 进行 HMAC SHA256 哈希处理，然后对结果进行 Base64 编码。如果没有查询字符串，请省略 ? 和查询部分。如果没有正文，则省略正文。方法必须大写。路径是端点路径，而非完整 URL。

三个细节导致了大多数签名不匹配问题：

1. 时间戳窗口为 30 秒。 WEEX 会拒绝任何 ACCESS-TIMESTAMP 与服务器时间偏差超过 30 秒的请求。如果你的机器时钟漂移——容器和虚拟机经常会这样——你将遇到间歇性的随机失败。请在启动时查询交易所的服务器时间端点，计算偏移量并应用。不要信任本地时钟。
2. 你签名的正文必须与发送的正文字节完全一致。 在签名和发送之间重新序列化 JSON 会导致键顺序改变或数字格式变化，从而导致哈希值不匹配。请对你实际传输的字符串进行签名。
3. 符号（交易对）区分大小写且必须大写，并且必须是平台产品/符号端点返回的精确值。猜测格式是导致资产明明存在却报“无效符号”错误的原因。

端点根据产品线分布在不同的域名上——现货请求发送至 api-spot.weex.com，合约至 api-contract.weex.com，WebSocket 流位于 ws-spot.weex.com。将现货调用指向 合约 主机产生的错误看起来像身份验证问题，但实际上并非如此。

为什么我的第一次 API 调用失败？错误代码解读

这是教程通常结束而支持工单开始的地方。下表列出了你在首次集成中最可能看到的身份验证和权限错误，以及它们的实际原因和修复方案。

那个 WebSocket 403 值得特别说明。它与你的凭证无关，没有错误代码可查，是由大多数 HTTP 库静默遗漏导致的。这种错误往往会浪费你一下午的时间。

完整列表请参考 WEEX API 错误代码参考。

交易所 API 的速率限制是多少？

速率限制在测试时表现正常，但在生产环境中会崩溃，因为它们只在波动加剧、机器人频繁触发时才会生效。WEEX 的默认限制为每秒 10 次请求，特定操作有更严格的公开上限。

该表有两层含义值得注意。批量规则非常重要：跨越四个交易对、每个交易对十个订单的批量操作仅计为一次请求。任何逐个提交订单的做市或网格策略都在无谓地消耗预算。撤单限制比下单限制宽松，说明平台预期报价会频繁变动——报价策略有预算空间，而单笔订单的垃圾请求则不然。

当你触发 429 错误时，请进行指数级退避。在紧密循环中立即重试会导致账户触发风险控制，WEEX 会自动禁用生成持续高频无效请求账户的 API 权限。恢复权限需要联系客服。已发布的速率限制和权限说明请参考 WEEX API 常见问题解答。

交易所 API 交易安全吗？

“安全”这个词用得不对。API 密钥是一种有界的授权委托，问题在于你限制得有多紧。

结构性保护起到了大部分作用。权限范围意味着只读密钥无法交易。WEEX 密钥没有提现权限，意味着任何密钥都无法将你的资金转出平台。IP 白名单意味着被盗密钥在攻击者的网络中毫无用处。独立的现货和合约权限意味着现货机器人的漏洞无法开启杠杆头寸。将这四者结合，现实中最坏的情况从“账户被清空”降级为“来自已知 IP 的非预期交易”——这是可恢复且可检测的。

剩下的工作取决于你：

• 永远不要将密钥提交到代码仓库或嵌入客户端代码中。使用环境变量或密钥管理器。
• 为每个环境运行独立的密钥，这样撤销泄露的测试密钥不会影响生产环境。
• 按计划轮换密钥，并在怀疑泄露时立即删除。
• 记录所有响应，包括失败记录。错误率激增通常是异常的第一信号，你无法看到未记录的内容。
• 在机器人内部构建熔断机制——最大订单频率、最大滑点、最大持仓——因为交易所的限制是为了保护交易所，而非你的盈亏。

真正让人亏钱的失败模式很少是因为密钥被盗。而是一个没有终止开关的机器人，在波动剧烈的一小时内持续交易错误的信号。在编写策略之前，先写好终止开关。

在发送实盘订单前进行模拟测试

WEEX 提供模拟合约端点——余额、下单、持仓、订单历史——它们镜像了实时界面，并以测试资产而非真实 USDT 进行结算。这是测试你的堆栈中最难安全验证部分的正确场所：部分成交、撤单/改单竞争、WebSocket 断开后的重连逻辑，以及你的持仓核算在重启后是否依然有效。

一个有效的阶段性部署流程：仅公共端点 → 针对实时数据的只读密钥 → 订单生命周期的模拟端点 → 最小规模的实时密钥 → 扩大规模。每个阶段都能捕获不同类别的错误，且只有最后一个阶段涉及资金成本。

另一个导致长期运行的机器人崩溃的操作细节：WebSocket 服务器会定期发送 ping，你的客户端必须回复 pong。如果回复失败超过十次，服务器将关闭连接。“几小时后随机停止接收数据”的机器人，几乎总是因为缺少 pong 处理程序。

首次实盘调用前的检查清单

正确调用交易所 API 是一系列具体事项的清单，而非难题。将密钥权限限制在策略所需的范围内，不多不少。绑定 IP。保持密码短语为字母数字组合，并存放在不会丢失的地方。对发送的精确字节进行签名。将时钟同步至交易所而非你的服务器。批量处理订单。在重写代码前先阅读错误代码——它通常会告诉你答案。给平台 15 分钟时间来传播新密钥，然后再下结论说哪里坏了。

如果你想在构建之前了解交易所 API 堆栈支持的更广泛内容，WEEX 关于 WEEX API 交易 的概述涵盖了 REST 和 WebSocket 的覆盖范围、用例和评估标准。当你准备好生成凭证并开始集成时，WEEX API 页面 直接链接到密钥创建和完整的开发者文档。

常见问题解答

1. 我可以在不写代码的情况下调用交易所 API 吗？

你无法直接调用，但不必自己编写客户端。投资组合追踪器、税务工具和第三方机器人平台接受交易所 API 密钥并为你处理请求。除非它们确实需要交易，否则请给这些工具只读密钥——大多数并不需要。

2. 公共市场数据端点需要 API 密钥吗？

不需要。价格、K 线、订单簿深度和交易对列表在 WEEX 和大多数主流交易所上都是无需验证的。唯一的例外是 WebSocket 连接，即使在公共频道上也需要 User-Agent 标头，否则防火墙将返回 403。

3. 为什么我的 API 密钥可以查询余额但不能下单？

因为交易权限与读取权限是分开的，且默认关闭。在 API 管理中启用现货或合约权限，然后等待约 15 分钟让更改生效后再重试。在此之前，你将持续看到权限不足的错误。

4. 如果有人偷了我的 API 密钥，他们可以提现我的资金吗？

在 WEEX 上不行——API 密钥仅限于读取和交易，没有提现权限。被盗密钥仍然可以进行非预期的交易，这就是为什么 IP 白名单和及时删除密钥很重要的原因，但它无法将资产移出平台。

5. 什么是时间戳错误，我该如何修复？

如果签名的时间戳与交易所服务器时间偏差超过 30 秒，请求将被拒绝。修复方法是在应用程序启动时查询服务器时间端点，存储偏移量，并将其应用于每个签名，而不是读取会发生漂移的本地系统时钟。

6. WEEX 支持 TradingView 警报或 FIX API 吗？

截至 2026 年 4 月的平台文档更新，两者均不支持。集成必须通过 REST 和 WebSocket 接口进行。在围绕此构建之前，请检查当前的开发者文档，因为支持的协议会发生变化。

7. 一个账户可以拥有多少个 API 密钥？

最多 10 个密钥组。请利用好这个空间——为开发、测试和生产环境分别使用不同的密钥，意味着撤销一个泄露的凭证不会导致你的整个业务离线。

风险提示

加密资产波动剧烈，交易可能导致部分或全部资本损失。API 交易在上述基础上增加了一层独特的风险：自动化系统以机器速度执行错误，逻辑错误、陈旧的市场数据源或缺失的终止开关可能比手动交易更快地积累损失。通过 API 开设的杠杆合约头寸可能会被完全清算。速率限制、连接丢失和 WebSocket 断开可能导致头寸在最需要管理时处于无人管理状态。API 凭证是持有人秘密——任何持有它们的人都可以交易你的账户，虽然 WEEX 密钥没有提现权限，但未经授权的交易仍可能造成实际损失。请在模拟模式下测试，从最小规模开始，对一切进行监测，且永远不要投入你无法承受损失的资本。本文内容不构成投资建议。