FAQ

May 12, 2026 · View on GitHub

General

What is OKX Agent Trade Kit?

OKX Agent Trade Kit is a local MCP server that connects AI assistants (Claude Desktop, Cursor, VS Code, Windsurf, etc.) to the OKX REST API. It runs entirely on your machine as a stdio process — no cloud service, no third-party relay. Your API credentials never leave your device.

What trading pairs / symbols are supported?

All symbols currently tradable through OKX APIs and your account permissions. You are not limited to BTC/ETH examples. Use valid instrument IDs — for example BTC-USDT for spot, BTC-USDT-SWAP for perpetual swaps, or BTC-USD-250328 for futures. Call market_get_instruments first to query available instruments for a given market before placing orders.

What risks should I understand before using MCP for trading?

Disclaimer: OKX Agent Trade Kit is a technical interface and does not constitute financial or investment advice. AI-generated actions can trigger real trades and may cause losses due to model errors, network latency, market volatility, or incorrect parameters.

Recommended precautions:

  • Protect API credentials: store keys only in ~/.okx/config.toml with restricted file permissions.
  • Least-privilege permissions: enable only Read and Trade — never enable Withdraw unless explicitly required.
  • Bind trusted IPs: restrict your API key to known IP addresses in OKX account settings.
  • Use --read-only mode while exploring or debugging to prevent accidental write operations.
  • Test with demo mode first: create a demo API key on OKX and use --profile demo before going live.

Setup

What API key permissions do I need?

Enable Read and Trade permissions. Withdraw permission is not needed and not recommended.

Where are my API keys stored?

Only in ~/.okx/config.toml on your local machine. The MCP server is a local stdio process — keys are never sent to any cloud service. Both the CLI (okx) and the MCP server (okx-trade-mcp) read this file independently — they are separate binaries with no dependency on each other.

Can I use the market module without an API key?

Yes. Market data is public. You can run:

okx-trade-mcp --modules market

No ~/.okx/config.toml entry required.

Demo Mode

How do I get a demo API key?

OKX website → Trading → Demo Trading → API Management. Create a key there — it is separate from your live API key.

Safety

What does --read-only mode do?

It disables all write operations at the server level regardless of which tools your AI tries to call. This includes placing orders, amending orders, cancelling orders, changing leverage, creating/stopping bots, and modifying account settings.

Read operations (balance, positions, market data, order history) still work normally.

Can I limit which modules are loaded?

Yes, use --modules:

# Only market and spot, no swap/futures/bot
okx-trade-mcp --profile live --modules market spot account

Available modules: market spot swap futures account bot

Troubleshooting

How do I detect errors when using the CLI?

The CLI exits with code 1 on any failure. This covers network errors, authentication errors, argument validation errors, and OKX business rejections (e.g. insufficient balance, invalid instrument).

okx spot place --instId BTC-USDT --side buy --ordType market --sz 100 --json
echo $?   # 0 = success, 1 = failed

How do I read an error from the MCP server?

When a tool call fails, your AI client shows a structured error block:

{
  "tool": "swap_place_order",
  "error": true,
  "type": "OkxApiError",
  "code": "51020",
  "message": "Order quantity invalid",
  "suggestion": "Check order size against instrument minSz and lotSz.",
  "endpoint": "POST /api/v5/trade/order",
  "traceId": "abc123def456",
  "timestamp": "2026-03-03T10:00:00.000Z",
  "serverVersion": "1.0.4"
}
  • code — OKX API error code. Look it up in the OKX API docs.
  • suggestion — Actionable hint generated by the server.
  • traceId — Paste this when contacting OKX support; they can trace the server-side request.
  • serverVersion — Tells you which release you're running.

MCP server fails to start — config parse error

Cause: Your ~/.okx/config.toml contains special characters (#, \, ", ') in the passphrase or API keys that are not properly quoted.

Fix: Open ~/.okx/config.toml and wrap the value in the correct quotes:

# Contains # \ " → use single quotes
passphrase = 'my#pass\word'

# Contains ' → use double quotes
passphrase = "my'pass"

# Contains both ' and # \ " → use triple single quotes
passphrase = '''my'#pass'''

Or re-run okx config init to regenerate the file (handles quoting automatically).

okx-trade-mcp command not found after npm install -g

Cause: The npm global bin directory is not in your $PATH. The executable is installed but the shell cannot find it.

Diagnose:

# Find where npm puts global binaries
npm prefix -g
# Check if that path is in $PATH
echo $PATH | grep "$(npm prefix -g)"

If the second command returns nothing, the path is missing.

Fix: Add the npm global bin directory to your shell profile:

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Use ~/.bashrc instead if you're on bash. Then verify:

which okx-trade-mcp
okx-trade-mcp --help

If the path is correct but the command still fails: Check that the package was published with its build output. The entry file must start with #!/usr/bin/env node.

Claude Desktop reports "Failed to spawn process" or {metadata: undefined}

Symptoms: After configuration, Claude Desktop shows Failed to spawn process: No such file or directory, or the connection log shows server started and connected successfully {metadata: undefined} but no tools load.

Cause: Claude Desktop uses the system Node.js (typically /usr/local/bin/node or /usr/bin/node), which is different from the version managed by nvm/fnm in your terminal. If okx-trade-mcp was installed via the terminal's npm, the system Node environment used by Claude Desktop cannot find the package.

Diagnose: Run which node in your terminal and compare it to the path Claude Desktop actually uses.

Fix: Reinstall using the system Node's npm:

/usr/local/bin/npm install -g @okx_ai/okx-trade-mcp

Then restart Claude Desktop.

The AI says a tool is "not available" or "not found"

The module containing that tool is probably not loaded. Check your --modules argument. Run system_get_capabilities tool to see what's currently enabled.

Orders are rejected with "insufficient balance"

Make sure you're on the right profile. If default_profile = "demo" in your config but you're trying to use live funds, specify --profile live explicitly in the server args.

How do I report a bug?

Open a GitHub issue and include the full error block (for MCP) or full stderr output (for CLI). The traceId and serverVersion fields are automatically included — no extra steps needed.

Cursor shows "Error" for all MCP servers

Cause: Cursor enforces a client-side limit of ~40 tools per MCP server and ~80 tools total (as of early 2026). okx-trade-mcp has 128 tools across 13 modules — loading --modules all exceeds this limit and causes every MCP server in Cursor to show Error status.

Fix: Use --modules to limit the tools loaded. Recommended combinations that fit within the Cursor limit:

Use caseModulesTools
Trading (spot + swap)market,account,spot,swap61
Contract + Botmarket,account,swap,bot.grid,bot.dca55
Earnmarket,account,earn.savings,earn.onchain,earn.dcd,earn.autoearn48
Minimal (market data + account)market,account27

Update your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "okx-trade": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "market,account,spot,swap"]
    }
  }
}

See Client Setup — Cursor for full details.

API Coverage

Which OKX API features are NOT supported by the MCP server or CLI?

The MCP server and CLI currently cover the following modules, focused on the core trading lifecycle:

ModuleTools
marketTickers, order book, candlesticks, instruments
spotPlace, amend, cancel orders; order history
swapPerpetual swaps + algo/conditional orders
futuresDelivery futures
optionOptions trading
accountBalances, positions, leverage, fees
botGrid trading bots

The following OKX REST API modules are not yet supported:

ModuleReason
Asset (deposit / withdrawal / transfer)Involves on-chain operations; excluded for security
Convert (flash swap)Narrow use case, lower priority
Sub-accountInstitutional feature, not needed by most users
Earn / Savings / StakingFinancial products, outside core trading
Copy TradingNewer API endpoints, under evaluation
Spread TradingProfessional strategy, limited audience
Recurring BuySimple operation, lower priority
Block Trading / RFQInstitutional OTC trading
Broker / AffiliatePlatform-level APIs, not end-user features

Want a specific module added? Open an issue with the label idea.

常见问题（中文）

概述

OKX Agent Trade Kit 是什么？

OKX Agent Trade Kit 是一个本地 MCP Server，将 AI 助手（Claude Desktop、Cursor、VS Code、Windsurf 等）连接到 OKX REST API。它完全运行在你的本机，作为 stdio 进程启动——无云端服务，无第三方中转，API 凭证不会离开你的设备。

支持哪些交易对/品种？

支持所有通过 OKX API 可交易、且你账户权限范围内的品种，不限于 BTC/ETH 示例。请使用有效的 Instrument ID——例如现货用 BTC-USDT，永续合约用 BTC-USDT-SWAP，交割合约用 BTC-USD-250328。下单前建议先调用 market_get_instruments 查询目标市场的可用合约。

使用 MCP 进行交易前需要了解哪些风险？

免责声明：OKX Agent Trade Kit 是技术接口，不构成投资建议或财务建议。AI 生成的操作可触发真实交易，并可能因模型错误、网络延迟、市场波动或参数有误而造成损失。

建议注意事项：

  • 保护 API 凭证：Key 仅存于 ~/.okx/config.toml，并限制文件权限。
  • 最小权限原则：仅开启读取和交易权限，除非明确需要，不要开启提币权限。
  • 绑定可信 IP：在 OKX 账户设置中将 API Key 限制为已知 IP 地址。
  • 使用 --read-only 模式：探索或调试时启用，防止意外写操作。
  • 先用模拟盘测试：在 OKX 创建模拟盘 API Key，使用 --profile demo 验证逻辑后再切换实盘。

设置

需要哪些 API Key 权限？

开启 读取 和 交易 权限即可。提币权限不需要，也不建议开启。

API Key 存在哪里？

仅存储在你本机的 ~/.okx/config.toml 文件中。MCP Server 是本地 stdio 进程，Key 不会发送到任何云端服务。

不用 API Key 能否使用 market 模块？

可以。行情数据是公开的，直接运行：

okx-trade-mcp --modules market

无需配置 ~/.okx/config.toml。

模拟盘

如何获取模拟盘 API Key？

OKX 官网 → 交易 → 模拟交易 → API 管理。在此创建 Key——与实盘 Key 相互独立。

安全控制

--read-only 模式有什么作用？

在 Server 层面禁用所有写操作，无论 AI 尝试调用哪个工具。包括：下单、改单、撤单、修改杠杆、创建/停止机器人、修改账户设置。

读取操作（余额、持仓、行情、历史订单）不受影响，正常使用。

能否限制加载的模块？

可以，使用 --modules 参数：

# 仅加载行情和现货，不加载永续/交割/Bot
okx-trade-mcp --profile live --modules market spot account

可用模块：market spot swap futures account bot

故障排查

使用 CLI 时如何检测错误？

CLI 在任何失败时都会以退出码 1 退出，涵盖：网络错误、鉴权错误、参数校验错误，以及 OKX 业务拒绝（如余额不足、合约不存在）。

okx spot place --instId BTC-USDT --side buy --ordType market --sz 100 --json
echo $?   # 0 = 成功，1 = 失败

如何读取 MCP Server 的报错？

工具调用失败时，AI 客户端会显示结构化错误块：

{
  "tool": "swap_place_order",
  "error": true,
  "type": "OkxApiError",
  "code": "51020",
  "message": "Order quantity invalid",
  "suggestion": "Check order size against instrument minSz and lotSz.",
  "endpoint": "POST /api/v5/trade/order",
  "traceId": "abc123def456",
  "timestamp": "2026-03-03T10:00:00.000Z",
  "serverVersion": "1.0.4"
}
  • code — OKX API 错误码，可在 OKX API 文档中查询。
  • suggestion — Server 生成的操作建议。
  • traceId — 联系 OKX 客服时提供，可追溯服务端请求。
  • serverVersion — 当前运行的版本号。

MCP Server 启动失败 — 配置文件解析错误

原因：~/.okx/config.toml 中的 passphrase 或 API Key 包含特殊字符（#、\、"、'），未正确加引号。

解决方法：打开 ~/.okx/config.toml，用正确的引号包裹：

# 包含 # \ " → 用单引号
passphrase = 'my#pass\word'

# 包含 ' → 用双引号
passphrase = "my'pass"

# 同时包含 ' 和 # \ " → 用三单引号
passphrase = '''my'#pass'''

或重新运行 okx config init 自动生成（程序会自动处理引号）。

npm install -g 安装后提示 command not found

原因：npm 全局 bin 目录不在 $PATH 中，可执行文件已安装但 shell 找不到它。

排查：

# 查看 npm 全局 bin 路径
npm prefix -g
# 检查该路径是否在 $PATH 中
echo $PATH | grep "$(npm prefix -g)"

如果第二条命令没有输出，说明路径缺失。

解法：将 npm 全局 bin 目录加入 shell 配置：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

如果使用 bash，将 ~/.zshrc 替换为 ~/.bashrc。然后验证：

which okx-trade-mcp
okx-trade-mcp --help

路径正确但命令仍失败：检查包发布时是否包含构建产物，入口文件首行必须是 #!/usr/bin/env node。

Claude Desktop 报 "Failed to spawn process" 或 {metadata: undefined}

现象：配置完成后 Claude Desktop 提示 Failed to spawn process: No such file or directory，或连接日志显示 server started and connected successfully {metadata: undefined}，工具列表无法加载。

原因：Claude Desktop 使用的是系统 Node.js（通常是 /usr/local/bin/node 或 /usr/bin/node），与终端里通过 nvm/fnm 管理的版本不同。如果 okx-trade-mcp 是用终端的 npm 安装的，Claude Desktop 对应的 Node 环境里找不到这个包。

排查：在终端运行 which node，对比 Claude Desktop 实际使用的路径是否一致。

解法：用系统 Node 对应的 npm 重新安装一次：

/usr/local/bin/npm install -g @okx_ai/okx-trade-mcp

安装完成后重启 Claude Desktop 即可。

AI 提示工具"不可用"或"未找到"

该工具所属模块可能未加载，检查 --modules 参数。可调用 system_get_capabilities 工具查看当前已启用的模块。

下单提示"余额不足"

确认使用的 Profile 是否正确。如果 config.toml 中 default_profile = "demo"，但要操作实盘资金，需在 Server 启动参数中明确指定 --profile live。

如何提交 Bug？

在 GitHub 开 Issue，附上完整错误块（MCP）或完整 stderr 输出（CLI）。traceId 和 serverVersion 会自动包含在错误信息中，无需额外步骤。

Cursor 中所有 MCP Server 显示 "Error"

原因：Cursor 客户端限制每个 MCP Server 最多约 40 个工具，所有 Server 合计不超过约 80 个（截至 2026 年初）。okx-trade-mcp 共有 128 个工具（13 个模块），使用 --modules all 超出此限制，导致 Cursor 中所有 MCP Server 均显示 Error 状态。

解决方法：使用 --modules 限制加载的工具数量。以下组合均在 Cursor 限制范围内：

使用场景模块工具数
交易（现货 + 合约）market,account,spot,swap61
合约 + 机器人market,account,swap,bot.grid,bot.dca55
赚币market,account,earn.savings,earn.onchain,earn.dcd,earn.autoearn48
最小化（行情 + 账户）market,account27

更新 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "okx-trade": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "market,account,spot,swap"]
    }
  }
}

详见 客户端配置 — Cursor 章节。

API 覆盖范围

MCP Server 和 CLI 目前不支持哪些 OKX API 功能？

MCP Server 和 CLI 当前覆盖 7 个模块 / 77 个工具，聚焦核心交易链路：

模块功能
market行情、深度、K 线、合约信息
spot现货下单、改单、撤单、历史查询
swap永续合约 + 条件单 / 止盈止损
futures交割合约
option期权交易
account余额、持仓、杠杆、手续费
bot网格机器人

以下 OKX REST API 模块暂未支持：

模块原因
Asset（充值 / 提币 / 划转）涉及链上操作，出于安全考虑暂不开放
Convert（闪兑）使用场景较窄，优先级较低
Sub-account（子账户）面向机构用户，大多数用户不需要
Earn / Savings / Staking金融产品类，非交易核心链路
Copy Trading（跟单）API 较新，评估中
Spread Trading（价差交易）专业策略工具，覆盖面较窄
Recurring Buy（定投）操作简单，优先级较低
Block Trading / RFQ（大宗交易）面向机构 OTC
Broker / Affiliate平台级接口，非终端用户功能

希望新增某个模块？请在 GitHub Issues 中提交，标签选 idea。