okx-outcomes

OKX Outcomes CLI

Binary-outcome (YES / NO) event-contract trading via the external okx-outcomes binary (formerly OKX Prediction Markets / okx-predict), wrapped under okx outcomes <command>.

Preflight

1. Run ../_shared/preflight.md Step 1 only (main CLI auto-upgrade). Steps 2 and 3 (OAuth/API-key detection, version drift) do not apply — Outcomes markets use an independent credential set.
2. Confirm okx-outcomes binary is reachable:

   okx outcomes status
   If you see Error: okx-outcomes binary not found in PATH, install it first (see Prerequisites).

Prerequisites

# 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

Configuration is stored in ~/.okx-outcomes/config.json (non-secret) and the OS keyring (secrets; encrypted ~/.okx-outcomes/keyring.enc fallback). There is no .env auto-loading — PREDICTIONS_* environment variables, if set, only override the stored values.

Environment variables (optional overrides)

Security: NEVER accept the signing private key in chat. The wallet is created by okx outcomes setup / setup bind and stored in the keyring. If the user pastes a key anyway, refuse and tell them to revoke / rotate it.

Naming note: env vars still use the PREDICTIONS_* prefix (upstream legacy naming) even after the product rebrand to OKX Outcomes.

Authentication paths

Outcomes markets use OKX OAuth sign-in for authenticated reads and an EIP-712 signing key for on-chain writes. These are not related to the main okx CLI's OAuth / API-key flow — do NOT call okx auth login for outcomes; outcomes has its own okx outcomes auth login.

Setup & Onboarding

Setup can be completed entirely from the agent — no terminal required. The user only ever acts in a browser (open a URL + enter a code, and open a bind short link — which launches the OKX app on a phone, or opens a web fallback in any browser); the agent runs every command.

First-time setup has three pieces, in dependency order: (1) region, (2) OAuth sign-in, (3) EOA wallet binding. Detect progress with:

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

Then advance the next_step:

1. Region — okx outcomes setup region <global|us> (non-interactive; agent runs it).

2. OAuth sign-in (device-code) — okx outcomes auth login --manual --json. This prints a one-line {verificationUri, userCode, expiresIn} envelope and exits immediately (it does not block or read stdin). Relay it to the user: "Open <verificationUri> on any device and enter code <userCode> (valid ~N min)." After they authorize in the browser, verify with okx outcomes auth refresh --json (writes the session marker on success) — poll a few times with backoff, or run once after the user says they're done.

3. Wallet binding — okx outcomes setup bind --json (agent runs it): generates the signing wallet and prints the wallet address plus a short link (the deeplink field of the JSON output) of the form https://okx.com/ul/3OauBX?eoa=<eoa>&uid=<uid> (the eoa is the new wallet's public address and uid is the signed-in account id — both filled in by the CLI). Surface the short link verbatim (do not shorten or wrap it) and tell the user three things: (a) tapping it on their phone launches the OKX app to approve the binding, (b) they can also copy it into any browser, and (c) if the link won't open, copy the wallet address shown above and bind it manually in the OKX app: Outcomes → Profile → Settings → API Bind Wallet. To re-display without rotating the wallet, use setup bind --keep (plain setup bind regenerates a fresh wallet every time).

   Surface template — relay verbatim (Chinese):

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

   English equivalent:

   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.

   The address is public — safe to show. The signing key behind it never leaves the local keyring.

Re-run setup status --json after each step, then okx outcomes status once complete: true.

Non-TTY / agent environments

The okx outcomes wrapper spawns the binary with inherited stdio, so the agent's captured stdout receives each command's output. All per-step setup commands are agent-runnable:

• ✅ Agent runs directly: setup status, setup region, auth login --manual --json, auth refresh, auth status, setup bind (relay the bind short link; the user opens it on their phone or pastes it into a browser).
• 🙋 User action is browser/phone only (never a command): authorize the device-code URL in a browser; open the bind short link (tap on phone → OKX app, or paste into a browser); if it won't open, copy the wallet address and bind manually in the OKX app.
• 🚫 Never spawn from an agent: the full interactive okx outcomes setup wizard and okx outcomes shell REPL — both use raw-terminal input and will hang / EOF-error without a TTY. Use the per-step subcommands above instead.

The plain okx outcomes auth login (no --manual) is the interactive/browser-foreground variant for a user at a real terminal; agents must use --manual.

Skill Routing

• YES/NO event-contract outcomes markets → this skill
• OKX CEX Up/Down event contracts (different product) → okx-cex-trade (use okx event ...)
• Crypto spot/swap/futures/options → okx-cex-trade
• Crypto market data (price, candles for BTC/ETH etc.) → okx-cex-market
• CEX portfolio → okx-cex-portfolio

Quickstart

# 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

Flag placement: put flags after the subcommand (okx outcomes events --json) or before the module (okx --json outcomes events). okx outcomes --json events — a flag wedged between the module and its subcommand — is not supported.

Command Index

Read commands (no gating)

Setup / Auth commands

Write commands (REQUIRE dry-run preview + user confirmation)

Aliases: clob order/orders/trades delegate to the corresponding account * commands. Prefer account * in skill output for clarity.

Operation Flow

Step 0 — Binary check

okx outcomes status --json

• If the wrapper prints "okx-outcomes binary not found", stop and tell the user to install via curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh.
• If status returns auth errors, the user isn't signed in — check okx outcomes auth status --json and guide them through "Setup & Onboarding" (auth login).

Step 1 — Decide what's being asked

• Public data → run command directly.
• Authenticated read → check the user is signed in (okx outcomes auth status --json); otherwise route to "Setup & Onboarding".
• On-chain write → proceed to Step 2 dry-run.

Step 2 — Dry-run preview for writes (MANDATORY)

Before executing any clob create-order / clob market-order / clob cancel-* / clob cancel-all / ctf * command, render a dry-run summary first:

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.

The summary fields:

• Market title — fetched via okx outcomes data market <marketId> (look up marketId from the asset's parent market)
• Asset + outcome — the numeric assetId from event-markets <eventId> plus which outcome (YES / NO) it represents
• Notional — price * size (xp)
• Wallet — okx outcomes wallet show --json
• Available balance — okx outcomes account balance --json → row where oddsType="spots", available field

Only after the user replies confirm do you run the real command. If anything else (including silence), abort.

Step 3 — Execute & verify

After execution, immediately verify state:

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

Report the resulting order id / tx hash to the user.

CLI Command Reference

Detailed parameter tables and examples per command group:

• references/setup-auth.md — setup status/region/bind, auth login/refresh/status, config & keyring storage, non-TTY rules
• references/data-commands.md — events / event / market / trending / ticker / candles / search
• references/account-commands.md — account balance / orders / positions / trades
• references/clob-commands.md — clob price / order / orders / trades / create-order / cancel / cancel-all / heartbeat
• references/ctf-commands.md — ctf split / merge / redeem
• references/workflows.md — first-time setup / daily brief / event deep-dive / portfolio check / safe place-order / resolve-and-redeem

MCP Tool Reference

This module does not expose any MCP tools in the current release. Agents invoke okx outcomes <command> directly via Bash. A future MCP server may be provided independently by the outcomes team.

Edge Cases

• okx-outcomes not in PATH: wrapper prints install hint and exits 127. Tell the user to run curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh.
• Signing wallet missing: any clob create-order / market-order / ctf * will fail. Run okx outcomes setup bind --json (agent-runnable), relay the short link (deeplink field, https://okx.com/ul/3OauBX?eoa=…&uid=…), and have the user open it (tap on phone → OKX app, or copy into a browser); if the link won't open, have them copy the wallet address and bind it manually in the OKX app (Outcomes → Profile → Settings → API Bind Wallet) — never ask for the key in chat.
• Asset id vs market id mix-up: the most common error class. clob price/book/create-order/market-order need assetId; ctf * and account trades --market need marketId. When unsure, run event-markets <eventId> first — its output lists both.
• --tif gtd without --expiry: rejected client-side. Pair them or default to gtc.
• --size-type quote outside buy + ioc: rejected client-side (create-order). Tell the user up front that "spend N points" syntax requires buy + IOC.
• FOK rejected from snapshot: clob market-order --tif fok is rejected client-side when visible depth is insufficient — no signed message sent. Surface the rejection and suggest reducing --size or using --tif ioc.
• Mode confusion: there is no demo / live flag for outcomes markets. The site is selected at signup. Be aware of which deployment the user is on (mainnet vs testnet) — okx outcomes status reports it.

Global Notes

• Always pass --json when piping into other tools or summarizing — the wrapper auto-appends --json if the user is in --json mode globally.
• Unit of value: outcomes markets transact in points (xp), not USDC. All balances, prices (decimal in [0,1]), notionals, and CTF amounts are xp.
• Private key handling: NEVER echo PREDICTIONS_AGENT_PRIVATE_KEY (or any 0x followed by 64 hex chars) to chat. If you must reference it, mask as 0x****. Do not write it to memory.
• Side is lowercase: --side buy / --side sell (write commands). account trades --side accepts BUY / SELL (uppercase) — the inconsistency is upstream, follow each command's signature.
• Rate limits: authenticated endpoints follow OKX-style throttling. On 429 / rate-limit errors, back off and retry after the suggested wait.
• The wrapper is transparent: every okx outcomes <cmd> forwards verbatim to okx-outcomes. Refer to okx/outcomes-cli docs/cli-reference.md for the canonical binary documentation.
• OKX_OUTCOMES_BIN env var can override the binary path (useful for local development with a cargo build --release artifact).