AI Builder Program 接入指南

发布于 2026年8月21日更新于 2026年8月21日阅读时长 7 分钟

1. AI Builder Program 是什么

OKX AI Builder Program 面向 AI Agent、交易助手、自动化策略和开发者工具的构建者。加入计划后，你将获得唯一的 Builder Code。当用户通过你的产品使用 ATK 完成符合条件的交易时，ATK 会将 Builder Code 写入订单归因字段，OKX 据此统计交易并计算返佣。AI Builder Code 用于识别交易来源，底层对应 OKX Broker Code。在 ATK 的 MCP 和 CLI 中，对应的技术参数名为 aiBuilderCode。它不是 API Key，也不能用于访问用户账户。

2. 选择适合你的接入方式

接入方式

适合场景

认证与运行位置

MCP

Claude Desktop、Claude Code、Cursor、VS Code 或其他支持 MCP 的本地 AI 客户端

ATK 在用户设备本地运行，使用用户自己的 OKX API 凭证

CLI

本地脚本、Agent Skill、自动化任务及需要更低 token 开销的工作流

ATK 在用户设备或用户控制的环境中运行，使用用户自己的 OKX API 凭证

OAuth Broker + Fast API

你的服务器需要代表多名用户持续运行和交易

用户通过 OKX OAuth 授权；服务端按 Broker 安全模型接入

本文重点介绍 MCP 和 CLI 本地接入。若你的产品在第三方服务器上代表多名用户交易，请直接阅读第三方服务器接入；不要要求用户把 API Secret 发送给你的 Agent、网页前端或大语言模型。

3. 开始前准备

接入前请准备：

  • 一个可以正常使用相关交易产品的 OKX 账户；

  • Node.js 18 或更高版本；

  • 一个支持 MCP 的 AI 客户端，或可以运行 CLI 的本地环境；

  • AI Builder 申请通过后获得的 Builder Code；

  • 用于联调的模拟盘 API Key，或用于上线的实盘 API Key。

API Key 建议只开启以下权限：

  • Read：查询账户、持仓和订单；

  • Trade：下单、改单或撤单；

  • 不需要、也不建议开启 Withdraw。

首次接入请使用模拟盘。完成归因验证后，再以小额实盘逐步上线。

4. 申请 AI Builder

  1. 登录 OKX，进入 AI Builder Program 页面。

  2. 点击“立即申请”，选择 AI Builder 类型。

  3. 填写申请人信息和项目信息，包括项目名称、项目链接及项目简介。

  4. 阅读并接受适用的服务条款，然后提交申请。

  5. 在 AI Builder Dashboard 或申请通知中获取 Builder Code、接入资料和测试资源。

如果 Builder Code 显示为“审核中”或“未激活”，你可以先完成技术联调，但相关交易不会产生返佣。只有状态变为“已激活”后，符合条件的交易才会开始计入返佣。

5. 安装并配置 ATK

安装最新版本的 MCP Server 和 CLI：npm install -g @okx_ai/okx-trade-mcp @okx_ai/okx-trade-cli 确认安装成功：

okx --version
okx-trade-mcp --version

使用交互式向导配置 OKX 站点、模拟盘或实盘环境，以及 API 凭证：okx config init凭证默认保存在用户本机的 ~/.okx/config.toml。请勿将该文件提交到代码仓库，也不要把凭证写进 Prompt、Skill 文本、网页前端或日志。

6. 通过 MCP 接入

6.1 自动配置 MCP 客户端

如何配置MCP，需要使用者在终端运行其中一条命令：

okx-trade-mcp setup --client claude-desktop
okx-trade-mcp setup --client cursor
okx-trade-mcp setup --client claude-code
okx-trade-mcp setup --client vscode

首次联调建议只加载必要模块，例如行情、账户和现货：

okx-trade-mcp setup \
--client cursor \
--profile demo \
--modules market,account,spot

6.2 传入 aiBuilderCode

调用会产生订单或策略交易的 MCP 工具时，在工具参数中传入 aiBuilderCode。以下为参数格式示例：

{
"instId": "BTC-USDT",
"tdMode": "cash",
"side": "buy",
"ordType": "limit",
"sz": "<SIZE>",
"px": "<PRICE>",
"aiBuilderCode": "<YOUR_BUILDER_CODE>"
}

aiBuilderCode 是 ATK 面向 MCP 和 CLI 提供的参数名。ATK 会把它转换为订单归因所需的 Builder Code；在 MCP/CLI 调用中无需改用 brokerCode。请确保所有会产生交易的工具调用都传入相同的 aiBuilderCode，避免部分订单遗漏归因。

6.3 分阶段验证

建议依次完成以下测试：

  1. 查询 BTC-USDT 最新价格，验证无需认证的行情能力；

  2. 查询模拟盘账户余额，验证 API 凭证；

  3. 以只读模式检查账户和持仓；

  4. 在模拟盘预览订单参数；

  5. 经用户确认后提交一笔小额模拟订单；

  6. 查询订单状态，并在 AI Builder Dashboard 中核对交易归因。

上线初期可使用 --read-only 禁用所有写操作：

okx-trade-mcp \
--profile demo \
--modules market,account,spot \
--read-only

7. 通过 CLI 接入

CLI 适合本地脚本、Agent Skill 和自动化流程。所有会产生交易的 CLI 命令都需要传入 --aiBuilderCode。建议在代码或 wrapper 中统一追加该参数，避免 Agent 漏传。

AI_BUILDER_CODE="<YOUR_BUILDER_CODE>"

先验证行情与账户连接：

okx market ticker BTC-USDT
okx account balance

然后在模拟盘提交测试订单。下列参数仅为格式示例，请替换为符合当前市场规则和你的测试计划的值：

okx spot place \
--instId BTC-USDT \
--side buy \
--ordType limit \
--sz <SIZE> \
--px <PRICE> \
--aiBuilderCode "$AI_BUILDER_CODE"

也可以直接在单次 CLI 调用中传入 Builder Code：

okx spot place \
--instId BTC-USDT \
--side buy \
--ordType limit \
--sz <SIZE> \
--px <PRICE> \
--aiBuilderCode <YOUR_BUILDER_CODE>

如果你发布的是 Agent Skill 或 Plugin，建议采用以下方式之一：

  • 在 Skill 或 Plugin 的统一调用层为每条交易命令追加 --aiBuilderCode；

  • 提供一个内部固定 Builder Code 的 wrapper，让 Agent 只调用 wrapper；

  • 在测试中覆盖所有下单、改单、撤单和策略交易路径，确保没有绕过统一归因入口。

不要只在自然语言说明中要求 Agent “记得添加 Builder Code”。Prompt 可能被遗漏，aiBuilderCode 应由代码或 wrapper 统一传入。

8. 第三方服务器接入

如果你的服务在云端运行，并代表多名用户访问账户或交易，不应复用本地 MCP/CLI 的凭证模式。推荐申请 OAuth Broker 并接入 Fast API：

  1. 用户从你的产品跳转到 OKX 授权页；

  2. 用户在 OKX 页面登录并确认授权；

  3. 你的服务端完成 OAuth 和 Fast API 流程；

  4. 用户凭证按 Broker 安全模型生成和托管，并绑定受信任的服务器 IP；

  5. 服务端下单时携带你的 Broker Code，完成交易归因。

请参阅：OKX Broker Program、Broker API 文档和 Fast API 说明。

9. 验证交易归因

请不要把“下单成功”“订单成交”“交易归因”和“返佣结算”视为同一个状态。上线前应逐项确认：

  • 使用的是支持 AI Builder 归因的 ATK 版本；

  • Builder Code 已激活，且与你的项目一致；

  • MCP 或 CLI 的交易调用已传入正确的 aiBuilderCode；

  • 模拟盘和实盘 Profile 没有混用；

  • 测试订单已成功提交并产生预期结果；

  • AI Builder Dashboard 中可以看到对应的归因数据；

  • 返佣明细符合当前 Broker 等级和适用规则。

如果订单成功但 Dashboard 没有归因数据，请先停止扩大交易量，并检查 ATK 版本、Builder Code 状态、aiBuilderCode 参数和订单路径。归因问题未确认前，不要假设后续可以自动补记。

10. 返佣说明

符合条件的 Builder 可根据其 Broker 等级及适用规则获得返佣，最高比例可达 50%。实际资格、比例、适用产品、统计周期和结算金额，以 AI Builder Dashboard、最新 Broker 规则及你的合作协议为准。以下情况可能导致交易不计入返佣：

  • Builder Code 尚未激活、无效，或 aiBuilderCode 未正确传入；

  • 用户、账户、地区、交易产品或费率不符合适用规则；

  • 交易属于自返佣、异常交易或其他不符合计划规则的行为；

  • 订单未成交，或没有产生可计佣的净手续费。

接入 ATK 不保证获得返佣，也不保证任何交易收益。请勿将“最高 50%”表述为所有 Builder 或每笔交易均可获得 50%。最新规则请参阅 OKX Broker 规则。

11. 安全与上线检查

  • 从模拟盘开始，并在实盘阶段先使用小额交易；

  • 使用最小权限 API Key，不开启提币权限；

  • 为 API Key 绑定受信任的 IP（适用时）；

  • 不在 Prompt、浏览器前端、代码仓库、截图或日志中暴露凭证；

  • 为交易金额、频率、杠杆、产品和交易对设置限制；

  • 对真实下单、撤单、调杠杆和策略启动设置明确的用户确认；

  • 超时或返回状态未知时，先查询订单状态，不要直接重复下单；

  • 记录订单 ID、请求追踪 ID和错误码，但不要记录密钥；

  • 定期核对预期交易量、实际归因量和返佣明细。

AI 可能因模型错误、幻觉、延迟、行情波动、滑点、流动性或技术故障产生非预期交易。ATK 不提供投资建议，也不保证盈利。你和最终用户仍需独立核实信息、监督自动化策略并对交易决定负责。

12. 常见问题

MCP 和 CLI 应该选哪个？

需要让 AI 客户端通过标准工具调用交易能力时，优先选择 MCP；需要在脚本、Skill 或自动化任务中直接执行命令时，选择 CLI。两种方式可以共存，但每笔订单只能按最终生效的 Builder Code 归因。

Builder Code、aiBuilderCode 和 API Key 有什么区别？

Builder Code 是用于交易归因和返佣计算的业务标识；aiBuilderCode 是 MCP/CLI 中承载该标识的参数名；OpenAPI 直连按 Broker 文档将 Broker Code 写入订单 tag。API Key 用于访问具体用户的账户，不能由 Builder Code 替代，也不能公开。

审核期间的交易会产生返佣吗？

不会。审核期间可以联调，但只有 Builder Code 激活后产生的符合条件交易才开始计入返佣。

为什么订单成功了，却看不到返佣？

常见原因包括 Builder Code 未激活、ATK 版本不支持 aiBuilderCode、交易调用漏传或错传该参数、交易未成交、交易不符合规则，或 Dashboard 数据尚在更新。请先核对交易归因，再核对返佣结算。