什么是合约 API？如何调用并确保其安全性

合约 API 是一组加密货币交易所开放的程序化接口，让您的代码（而非鼠标）能够交易合约（永续或交割合约）：下单和撤单、获取市场数据以及管理仓位。 在中文里，这些被称为“合约”，因此合约 API 有时也被称为“期货 API”——两者是一回事。手动交易是指您在网页或移动应用中点击“买入/卖出”。使用合约 API，软件会为您发送相同的指令——速度更快，且全天候运行。

如果您在量化、跟单、网格或套利设置中经常遇到“合约 API”（或 Futures API），但从未搞清楚它到底是什么、如何调用，或者调用它是否有风险，本指南将按顺序解答四个问题——它是什么、如何调用、如何连接、是否安全——并以 WEEX 开发者文档作为连接流程的具体、可验证的示例。

什么是合约 API：拆解“合约”与“API”

从词义开始。API（应用程序编程接口）是软件与软件对话的渠道：您的程序以约定的格式发送请求，交易所则以约定的格式回复数据。“合约”（Futures）是指永续或交割合约等衍生品：它带有杠杆、资金费率以及保证金和仓位管理。将它们结合起来，合约 API 就是专门为操作衍生品而构建的接口，与仅处理币币交易的现货 API 不同。

成熟的合约 API 通常公开三组功能。以 WEEX 合约 API 文档为例（截至 2026 年 7 月为 V3 BETA 版，V2 仍可用），端点分为三个模块：

市场端点通常无需身份验证即可读取；账户和交易端点涉及资金，因此必须使用您的 API Key 进行签名。理解这三个模块，您就理解了合约 API 能为您做什么。

合约 API vs 现货 API vs 手动交易

这是大多数新手真正卡住的地方。这三者不可互换：

合约 API 比现货 API 更难，不是因为端点代码更复杂，而是因为其背后的产品更复杂。您必须处理杠杆档位、全仓与逐仓、资金费率结算以及强平价格——这些在现货中都不存在。换句话说，调用端点是简单部分；真正的工作是将合约的风险逻辑写入您的代码中。在 WEEX 上，BTCUSDT 等永续合约支持高达 500 倍杠杆（截至 2026 年 7 月），杠杆越高，程序中一个错误方向或缺失止损的 Bug 代价就越大。

如何调用合约 API：REST 和 WebSocket

调用合约 API 主要通过两种协议进行，大多数交易所（包括 WEEX）都提供这两种协议。在实践中，您可以将它们结合使用：

典型的合约策略如下：通过 WebSocket 订阅实时市场数据，当价格达到您的条件时，通过 REST 端点发送订单。这样既能获得毫秒级数据，又能保持交易所需的可靠请求-响应路径。REST 端点带有速率限制（每秒请求上限）；一旦触发，请求将被暂时拒绝——这就是为什么经验丰富的操作者将市场数据推送到 WebSocket，并将 REST 配额留给交易。

基础 URL、签名算法和每个端点的字段因交易所而异，因此请参考官方文档——切勿复制其他交易所的参数。WEEX 的完整接口参考位于其 合约 API 开发者文档 中，分为市场、账户和交易模块，并支持 WebSocket 和模拟模式。

连接合约 API 的四个步骤

抛开代码不谈——连接任何交易所的合约 API 都是相同的四个步骤。以下是它们在 WEEX 上的操作，直接映射到实际页面：

1. 创建 API Key。 前往 API 管理页面 并生成 Key。您将获得 API Key 和 Secret Key，WEEX 还需要一个 Passphrase 作为额外检查。Secret Key 和 Passphrase 仅显示一次——请离线保存。
2. 设置权限和 IP 白名单。 仅授予您需要的权限（读取、交易和提现通常是分开授权的），并绑定 IP 白名单——WEEX 最多支持 10 个地址。仅允许您自己的服务器 IP 可以阻止绝大多数 Key 被盗。
3. 先在模拟模式中验证。 使用记录在案的模拟环境运行完整的下单、撤单、检查持仓循环，确认您的签名和参数正确，然后再切换到真实资金。
4. 上线，并加入风险控制。 转向生产环境，并在让程序进行真实交易之前，添加止损、最大持仓上限和断线重连逻辑。

最容易让人吃亏的两个步骤是第 2 步和第 3 步：权限过大，以及跳过模拟直接使用真实资金。小额起步、先模拟、先只读是连接合约 API 最稳妥的顺序。在自动化之前，先在 WEEX 合约页面 上熟悉产品本身会有所帮助。

合约 API 安全吗？几乎一切取决于您的 Key

合约 API 本身是标准技术——“安全与否”并不真正取决于接口。真正的风险在于您如何存储 Key 以及如何设置权限范围。 加密货币历史上的交易所“API 黑客事件”很少是因为端点被攻破；它们通常是 Secret Key 泄露或权限设置过宽。做好以下几点，大部分风险就会消失：

• 关闭不需要的权限。 如果您只运行量化交易，请勿授予提现权限。泄露的带有提现权限的 Key 等于将资金拱手让人。WEEX 的 API 页面明确指出：请勿分享您的 Secret Key，以避免资产损失。
• 绑定 IP 白名单。 将 Key 锁定到固定的服务器 IP，这样即使 Key 被盗，对其他人也毫无用处。
• 切勿将 Secret Key 提交到代码库。 使用环境变量或密钥管理器——不要硬编码，也永远不要将其推送到 GitHub，因为泄露的 Key 通常会在几分钟内被抓取。
• 轮换和最小化。 Key 可以随时删除并重新创建；如果您怀疑泄露，请立即撤销旧的 Key。

安全逻辑一句话总结：接口是公开的，Key 是私有的，您的资产安全取决于您管理 Key 和权限的能力。 交易所提供工具——白名单、Passphrase、模拟模式——但您是否使用它们，以及是否正确使用，全在于您自己。

谁在使用合约 API

一旦搞清楚了“它是什么”和“如何使用”，用户群就很明显了。自主、低频交易者使用网页应用即可。真正需要 API 的人是那些追求速度和纪律的人：每秒处理 Tick 并发送订单的量化策略、不停下单撤单的网格和马丁格尔机器人、在毫秒间捕捉价差的跨市场套利，以及将一个信号分发到多个账户的跟单或资产管理系统。人类无法手动完成这些——而程序与交易所之间的唯一渠道就是合约 API。

常见问题解答

1. 合约 API 和现货 API 是一样的吗？

不。它们通常是两个独立的接口，具有不同的域名、参数，有时还有不同的身份验证方式。合约 API 针对衍生品，增加了杠杆、保证金、资金费率和强平机制；现货 API 仅处理币币交易。连接前，请找到文档的“合约”部分——不要尝试通过现货端点下合约订单。

2. “合约 API”和“期货 API”是一回事吗？

是的。“合约 API”是中文“合约 API”的直译，而合约是指永续或交割合约，即期货。英语交易所和交易者更常说“Futures API”，但有些（包括 WEEX 自己的文档路径）使用“Contract”。它们指的是同一个衍生品接口。

3. 我可以在不编程的情况下使用合约 API 吗？

直接调用端点需要一些编程（Python、Node.js 等）。但如果您只是想使用现有的量化平台或跟单工具，通常只需将交易所生成的 API Key 粘贴到该工具中即可——无需自己编写签名逻辑。即便如此，在将高权限 Key 交给不熟悉的第三方软件之前，请务必了解权限和 IP 白名单。

4. 通过 API 交易会增加强平的可能性吗？

工具本身不会增加您的强平概率，但它会放大您策略的后果。程序执行时没有情绪，因此错误的止损、过高的杠杆或断线且无重连机制都会被快速且不加区分地执行。这正是为什么在模拟模式中验证并以小额资金开始实盘至关重要的原因。

5. WEEX 目前的合约 API 是什么版本？

截至 2026 年 7 月，WEEX 合约 API 文档显示 V3 (BETA) 版本与 V2 并存，端点分为市场、账户和交易模块，并支持 WebSocket 和模拟模式。请以最新的官方开发者文档作为确切端点的真实来源。

风险提示

合约（永续/交割合约）交易是一种高杠杆衍生品：价格波动剧烈，可能会抹去您的部分或全部保证金，在极端情况下，损失可能超过您的初始资本。通过合约 API 进行自动化交易增加了技术和操作风险——逻辑错误、连接中断、速率限制、Key 泄露或权限过大都可能导致意外订单或资产损失。本文仅供教育参考，不构成投资建议或操作指南。在开始之前，请务必了解杠杆、保证金和强平机制；保护好您的 API Key；禁用不需要的权限并绑定 IP 白名单；先在模拟环境中以小额资金验证您的策略；且仅投入您能承受损失的资金，并参考 How to Keep Your Crypto Safe? Everything You Need to Know 来提升安全性。