okx-outcomes

OKX Outcomes CLI

通过外部 okx-outcomes 二进制文件进行二元结果（YES / NO）事件合约交易（该二进制文件前身为 OKX Prediction Markets / okx-predict），封装在 okx outcomes <command> 下。

预检

1. 仅运行 ../_shared/preflight.md 的 步骤 1（主 CLI 自动升级）。步骤 2 和 3（OAuth/API 密钥检测、版本偏差）不适用——Outcomes 市场使用独立的凭据集。
2. 确认 okx-outcomes 二进制文件可用：

   okx outcomes status
   

   如果看到 Error: okx-outcomes binary not found in PATH，请先安装它（参见先决条件）。

先决条件

# 1. Main OKX CLI (provides the `okx outcomes` wrapper command)
npm install -g @okx_ai/okx-trade-cli

# 2. Outcomes binary
#    macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh
#    Windows: download okx-outcomes.exe from https://github.com/okx/outcomes-cli/releases
#             and place it on your PATH.

# 3. First-time setup — sign in + bind wallet.
#    In a real terminal you can run the full interactive wizard:
okx outcomes setup
#    In an agent / chat context, drive it step-by-step instead — see
#    "Setup & Onboarding" below (the full wizard needs a TTY and cannot be
#    spawned from an agent).

# 4. Verify
okx outcomes status

配置存储在 ~/.okx-outcomes/config.json（非机密）和操作系统密钥环（机密；加密文件 ~/.okx-outcomes/keyring.enc 为备用方案）中。不会自动加载 .env——如果设置了 PREDICTIONS_* 环境变量，它们只会覆盖已存储的值。

环境变量（可选覆盖项）

变量	用途	说明
PREDICTIONS_AGENT_PRIVATE_KEY	链上写入（clob create-order / cancel / ctf *）	secp256k1 十六进制值。通常由 okx outcomes setup 生成并存储在密钥环中——此环境变量只会覆盖该值。切勿分享或打印。
PREDICTIONS_API_BASE	REST 主机覆盖项	默认使用设置期间选定的区域
OKX_OUTCOMES_BIN	二进制文件路径覆盖项	适用于本地开发构建

安全：切勿在聊天中索要签名私钥。钱包由 okx outcomes setup / setup bind 创建，并存储在密钥环中。如果用户仍然贴出密钥，请拒绝并告知其撤销或轮换密钥。

命名说明：即使产品更名为 OKX Outcomes 后，环境变量仍使用 PREDICTIONS_* 前缀（上游遗留命名）。

身份验证方式

Outcomes 市场使用 OKX OAuth 登录进行经过身份验证的读取，并使用 EIP-712 签名密钥进行链上写入。这些与主 okx CLI 的 OAuth / API 密钥流程无关——请勿为 Outcomes 调用 okx auth login；Outcomes 有自己的 okx outcomes auth login。

操作类别	示例命令	凭据
公开数据	data events/event/market/ticker/candles、clob price/prices/midpoint/spread/book/books	无
经过身份验证的读取	account balance/order/orders/positions/trades（已平仓 = positions --status closed）、search、status	OAuth 会话（okx outcomes auth login）
链上写入	clob create-order / market-order / cancel-oid / cancel-all / heartbeat、ctf split / merge / redeem、wallet show	签名密钥（密钥环中的 agent_private_key，或 PREDICTIONS_AGENT_PRIVATE_KEY）

设置与引导

设置可以完全通过 Agent 完成——无需终端。用户只需在浏览器中操作（打开 URL 并输入代码，然后打开绑定短链接——在手机上会启动 OKX 应用，或在任何浏览器中打开网页备用页面）；所有命令均由 Agent 运行。

首次设置包含三个步骤，按依赖顺序执行：(1) 区域，(2) OAuth 登录，(3) EOA 钱包绑定。使用以下命令检测进度：

okx outcomes setup status --json
# → { "region": {...}, "oauth": {...}, "eoa_binding": {...}, "next_step": "...", "complete": false }

然后按 next_step 继续：

1. 区域 — okx outcomes setup region <global|us>（非交互式；由 Agent 运行）。

2. OAuth 登录（设备码） — okx outcomes auth login --manual --json。此命令会输出一行 {verificationUri, userCode, expiresIn} 信息并立即退出（不会阻塞，也不会读取 stdin）。将其转告用户："在任意设备上打开 <verificationUri>，并输入代码 <userCode>（有效期约为 N 分钟）。" 用户在浏览器中完成授权后，使用 okx outcomes auth refresh --json 验证（成功后会写入会话标记）——可采用退避策略轮询几次，或在用户告知完成后运行一次。

3. 钱包绑定 — okx outcomes setup bind --json（由 Agent 运行）：生成签名钱包，并输出钱包 address 和短链接（JSON 输出中的 deeplink 字段），格式为 https://okx.com/ul/3OauBX?eoa=<eoa>&uid=<uid>（eoa 是新钱包的公钥地址，uid 是已登录账户 ID——两者均由 CLI 填入）。原样提供短链接（不要缩短或换行），并告知用户以下三点：(a) 在手机上点按该链接会启动 OKX 应用以批准绑定；(b) 也可以将链接复制到任意浏览器中；(c) 如果链接无法打开，请复制上方显示的钱包 address，并在 OKX 应用中手动绑定：Outcomes → Profile → Settings → API Bind Wallet。如需重新显示而不轮换钱包，请使用 setup bind --keep（普通的 setup bind 每次都会重新生成钱包）。

   提供以下模板——原样转发（中文）：

   我刚为你新生成了一个签名钱包(私钥保存在本地 keyring,永远不会展示)。
   请在手机上打开下面的短链接,在 OKX App 中批准绑定这个新钱包:
   
   新钱包地址:<address>
   绑定短链:<short link>
   
   (也可以把短链复制到浏览器打开。如果打不开,请复制上面的新钱包地址,
    在 OKX App 里手动绑定:Outcomes → Profile → Settings → API 绑定钱包,
    把钱包地址粘贴进去。)
   
   ⚠️ 关于这个钱包:
   • 它只用来给你的交易做签名授权,不是一个充值钱包。
   • 不要往这个地址转任何币 —— 余额在你的 OKX 账户里,转到这个地址的资金无法使用、大概率找不回。
   • 地址可以公开(用于绑定),但它背后的私钥永远不要外泄。
   
   在 App 中批准后告诉我。
   

   英文对应版本：

   I just generated a fresh signing wallet for you (the private key
   stays in the local keyring and is never displayed). Open this short
   link on your phone — it'll launch the OKX app to approve binding
   this new wallet:
   
   New wallet address: <address>
   Binding short link: <short link>
   
   (You can also copy the link into any browser. If the link won't open,
    copy the wallet address above and bind it manually in the OKX app:
    Outcomes → Profile → Settings → API Bind Wallet.)
   
   ⚠️ About this wallet:
   • It's only used to sign your trade authorizations — it is NOT a deposit wallet.
   • Do NOT send any crypto/tokens to this address. Your balance lives in your
     OKX account; funds sent here are unusable and likely unrecoverable.
   • The address is fine to share (it's used for binding), but the private key
     behind it must never be exposed.
   
   Tell me when you've approved it in the app.
   

   address 是公开信息，可以安全展示。其对应的签名密钥始终保留在本地密钥环中。

每完成一个步骤后，重新运行 setup status --json；然后在 complete: true 时运行一次 okx outcomes status。

非 TTY / Agent 环境

okx outcomes 包装器会以继承的 stdio 启动二进制文件，因此 Agent 捕获的 stdout 会收到每条命令的输出。所有逐步设置命令均可由 Agent 运行：

• ✅ 由 Agent 直接运行：setup status、setup region、auth login --manual --json、auth refresh、auth status、setup bind（转发绑定短链接；用户可在手机上打开，也可粘贴到浏览器中）。
• 🙋 用户只需在浏览器或手机上操作（无需运行命令）：在浏览器中授权设备码 URL；打开绑定短链接（在手机上点按 → OKX 应用，或粘贴到浏览器中）；如果无法打开，则复制钱包地址并在 OKX 应用中手动绑定。
• 🚫 切勿由 Agent 启动：完整的交互式 okx outcomes setup 向导和 okx outcomes shell REPL——两者都会使用原始终端输入，没有 TTY 时会挂起或触发 EOF 错误。请改用上面的逐步子命令。

普通的 okx outcomes auth login（不带 --manual）是供用户在真实终端中使用的交互式／浏览器前台版本；Agent 必须使用 --manual。

技能路由

• YES/NO 事件合约结果市场 → 此技能
• OKX CEX 涨跌事件合约（不同的产品）→ okx-cex-trade（使用 okx event ...）
• 加密货币现货／闪兑／期货／期权 → okx-cex-trade
• 加密货币市场数据（BTC/ETH 等的价格、K 线）→ okx-cex-market
• CEX 投资组合 → okx-cex-portfolio

快速入门

# Health check
okx outcomes status

# Browse active events
okx outcomes data events --status active --limit 10

# Drill into one event with all its markets (returns YES + NO asset ids per market)
okx outcomes data event-markets <eventId>

# Live price for a YES outcome
okx outcomes clob price --asset <yesAssetId>

# Top-of-book depth
okx outcomes clob book --asset <yesAssetId> --sz 5

# My account balance / positions
okx outcomes account balance
okx outcomes account positions

# Place an order (ALWAYS dry-run first — see Operation Flow)
okx outcomes clob create-order --asset <assetId> --side buy --price 0.55 --size 100

**标志位置：**将标志放在子命令之后（okx outcomes events --json），或放在模块之前（okx --json outcomes events）。不支持 okx outcomes --json events——即将标志插在模块和子命令之间的写法。

命令索引

读取命令（无需门控）

#	命令	身份验证	说明
1	okx outcomes data events [--status active] [--category <c>] [--limit <n>]	无	列出结果事件
2	okx outcomes data event <eventId>	无	单个事件详情
3	okx outcomes data event-markets <eventId>	无	事件及其所有市场（包含 YES/NO 资产 ID）
4	okx outcomes data market <marketId>	无	单个市场详情
5	okx outcomes data trending	无	热门事件
6	okx outcomes data ticker <assetId>	无	单个结果资产的 24h 行情
7	okx outcomes data candles <assetId> [--bar 1H] [--limit 100]	无	OHLCV 蜡烛图数据
8	okx outcomes search <keyword>	OAuth	关键词搜索
9	okx outcomes clob price --asset <id> [--outcome yes|no]	无	精简价格（最新价/买价/卖价/中间价/价差）
10	okx outcomes clob prices <id1> <id2> ...	无	批量价格视图
11	okx outcomes clob midpoint --asset <id> / clob midpoints <ids...>	无	(买价+卖价)/2
12	okx outcomes clob spread --asset <id> / clob spreads <ids...>	无	买卖价差
13	okx outcomes clob book --asset <id> [--sz <n>] / clob books <ids...>	无	多档深度（默认 sz=10，最大 400）
14	okx outcomes account balance	OAuth	账户余额
15	okx outcomes account order <orderId>	OAuth	单个订单详情
16	okx outcomes account orders	OAuth	未结订单
17	okx outcomes account positions	OAuth	未平仓位（查找 status="Won" → 赎回）
18	okx outcomes account positions --status closed	OAuth	已平仓位 + 已实现盈亏
19	okx outcomes account trades	OAuth	交易历史
20	okx outcomes wallet show	signing	派生钱包地址
21	okx outcomes status	OAuth	健康检查
22	okx outcomes auth status [--json]	无	OAuth 会话状态
23	okx outcomes setup status [--json]	无	入门设置进度（地区/OAuth/绑定）

设置 / 身份验证命令

命令	身份验证	说明	Agent 可运行？
okx outcomes setup region <global|us>	无	设置地区（第 1 步）	✅ 可以
okx outcomes auth login --manual --json	无	OAuth 设备码（第 2 步）：打印 {verificationUri,userCode,expiresIn} 并退出	✅ 可以（将链接和代码转发给用户）
okx outcomes auth refresh [--json]	无	用户授权后验证/刷新会话（写入会话标记）	✅ 可以
okx outcomes setup bind [--keep] --json	signing	绑定 EOA 钱包（第 3 步）：打印地址和一个短链接（deeplink 字段，https://okx.com/ul/3OauBX?eoa=…&uid=…）；--keep 会重用现有钱包	✅ 可以（用户打开短链接，或复制地址手动绑定）
okx outcomes auth login --site <global|us>	无	交互式/浏览器前台登录（供使用真实终端的用户使用）	🚫 需要 TTY
okx outcomes setup / okx outcomes shell	—	完整交互式向导 / REPL	🚫 需要 TTY

写入命令（必须先预览 dry-run 并获得用户确认）

#	命令	风险
24	okx outcomes clob create-order --asset <id> --side buy|sell --price --size [--tif gtc|gtd|ioc|fok|alo] [--expiry <ms>] [--size-type base|quote]	高
25	okx outcomes clob market-order --asset <id> --side buy|sell --size [--tif ioc|fok] [--size-type base|quote]	高（立即撮合）
26	okx outcomes clob cancel-oid --oid <id> --asset <id>	中
27	okx outcomes clob cancel-all	高
28	okx outcomes clob heartbeat	中（5 分钟无响应后自动取消全部订单）
29	okx outcomes ctf split --market <id> --amount <xp>	高（锁定 xp）
30	okx outcomes ctf merge --market <id> --amount <xp>	高
31	okx outcomes ctf redeem --market <id>	高（销毁全部获胜余额）

别名：clob order/orders/trades 会调用对应的 account * 命令。为清晰起见，技能输出中优先使用 account *。

操作流程

步骤 0 — 检查二进制文件

okx outcomes status --json

• 如果包装脚本输出 "okx-outcomes binary not found"，请停止，并告知用户通过 curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh 安装。
• 如果 status 返回身份验证错误，说明用户尚未登录 — 检查 okx outcomes auth status --json，并引导其完成“设置与入门”（auth login）。

步骤 1 — 判断用户的请求

• 公开数据 → 直接运行命令。
• 已验证身份的读取操作 → 检查用户是否已登录（okx outcomes auth status --json）；否则转到“设置与入门”。
• 链上写入操作 → 进入步骤 2，执行 dry-run。

步骤 2 — 写入操作的 dry-run 预览（必须）

执行任何 clob create-order / clob market-order / clob cancel-* / clob cancel-all / ctf * 命令之前，先显示 dry-run 摘要：

About to execute: okx outcomes clob create-order --asset 100888000 --side buy --price 0.55 --size 100

  Market           : "Will BTC be above $100k by Dec 31, 2026?"  (mkt_t001)
  Asset            : 100888000  (YES outcome)
  Side             : buy
  Price            : 0.55 xp
  Size             : 100 shares
  TIF              : gtc
  Estimated notional: 55.00 xp
  Wallet           : 0x1234...abcd                              (from `wallet show`)
  Available (spots): 1,234.56 xp                               (from `account balance`)

Reply "confirm" to execute, or "cancel" to abort.

摘要字段：

• 市场标题 — 通过 okx outcomes data market <marketId> 获取（从资产的父市场中查找 marketId）
• 资产与结果 — 来自 event-markets <eventId> 的数字型 assetId，以及它代表的结果（YES / NO）
• 名义金额 — price * size（xp）
• 钱包 — okx outcomes wallet show --json
• 可用余额 — okx outcomes account balance --json → oddsType="spots" 对应的行中的 available 字段

只有用户回复 confirm 后，才能运行实际命令。任何其他情况（包括没有回复）都应中止。

步骤 3 — 执行并验证

执行后，立即验证状态：

okx outcomes account orders --json    # confirm order placed / cancelled
okx outcomes account positions --json # confirm position change (for ctf)

向用户报告生成的订单 ID / 交易哈希。

CLI 命令参考

各命令组的详细参数表和示例：

• references/setup-auth.md — 设置状态 / 地区 / 绑定、身份验证登录 / 刷新 / 状态、配置与密钥环存储、非 TTY 规则
• references/data-commands.md — 事件 / event / 市场 / 趋势 / 行情 / K 线 / 搜索
• references/account-commands.md — 账户余额 / 订单 / 持仓 / 交易
• references/clob-commands.md — clob 价格 / 订单 / 订单列表 / 交易 / 创建订单 / 取消 / 取消全部 / 心跳
• references/ctf-commands.md — ctf 拆分 / 合并 / 赎回
• references/workflows.md — 首次设置 / 每日简报 / 事件深入分析 / 投资组合检查 / 安全下单 / 结算并赎回

MCP 工具参考

此模块在当前版本中不提供任何 MCP 工具。Agent 会通过 Bash 直接调用 okx outcomes <command>。未来 outcomes 团队可能会独立提供 MCP 服务。

边缘情况

• okx-outcomes 不在 PATH 中：封装程序会打印安装提示并以 127 退出。告知用户运行 curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh。
• 缺少签名钱包：任何 clob create-order / market-order / ctf * 命令都会失败。运行 okx outcomes setup bind --json（可由 Agent 运行），转发短链接（deeplink 字段，https://okx.com/ul/3OauBX?eoa=…&uid=…），并让用户打开链接（在手机上轻点即可跳转到 OKX 应用，或复制到浏览器中）；如果链接无法打开，让用户复制钱包地址并在 OKX 应用中手动绑定（Outcomes → Profile → Settings → API Bind Wallet）——绝不要在聊天中索要密钥。
• 资产 ID 与市场 ID 混淆：这是最常见的错误类型。clob price/book/create-order/market-order 需要 assetId；ctf * 和 account trades --market 需要 marketId。不确定时，先运行 event-markets <eventId>——其输出会同时列出两者。
• --tif gtd 未搭配 --expiry：客户端会拒绝。请同时指定两者，或默认使用 gtc。
• --size-type quote 用于 buy + ioc 之外的情况：客户端会拒绝（create-order）。请预先告知用户，“花费 N 点”的语法要求使用 buy + IOC。
• 根据快照拒绝 FOK：当可见深度不足时，客户端会拒绝 clob market-order --tif fok——不会发送已签名消息。说明拒绝原因，并建议减小 --size 或使用 --tif ioc。
• 模式混淆：预测市场没有演示 / 实盘标志。站点在注册时选定。请留意用户使用的是哪个部署环境（主网还是测试网）——okx outcomes status 会报告相关信息。

全局说明

• 通过管道传递给其他工具或进行汇总时，始终传入 --json：如果用户全局启用了 --json 模式，封装程序会自动追加 --json。
• 价值单位：预测市场以**点数（xp）**交易，而非 USDC。所有余额、价格（[0,1] 范围内的小数）、名义金额和 CTF 金额的单位都是 xp。
• 私钥处理：绝不要在聊天中回显 PREDICTIONS_AGENT_PRIVATE_KEY（或任何以 0x 开头、后接 64 个十六进制字符的内容）。如必须提及，请将其屏蔽为 0x****。不要将其写入记忆。
• Side 使用小写：写入命令使用 --side buy / --side sell。account trades --side 接受 BUY / SELL（大写）——这是上游的不一致，请遵循各命令的签名。
• 速率限制：经过身份验证的端点遵循 OKX 风格的限流策略。遇到 429 / 速率限制错误时，请等待建议的时长后再重试。
• 封装程序是透明的：每个 okx outcomes <cmd> 都会原样转发给 okx-outcomes。权威的二进制文件文档请参阅 okx/outcomes-cli docs/cli-reference.md。
• OKX_OUTCOMES_BIN 环境变量可覆盖二进制文件路径（适用于使用 cargo build --release 构建产物的本地开发）。