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
Run ../_shared/preflight.mdStep 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.
Confirm okx-outcomes binary is reachable:
bash
okx outcomes status
If you see Error: okx-outcomes binary not found in PATH, install it first (see Prerequisites).
Prerequisites
bash
# 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.
secp256k1 hex. Normally generated by okx outcomes setup and stored in the keyring — this env var only overrides it. NEVER share or print.
PREDICTIONS_API_BASE
REST host override
Defaults to the region picked during setup
OKX_OUTCOMES_BIN
Binary path override
Useful for local dev builds
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.
Operation class
Example commands
Credential
Public data
data events/event/market/ticker/candles, clob price/prices/midpoint/spread/book/books
none
Authenticated reads
account balance/order/orders/positions/trades (closed = positions --status closed), search, status
signing key (keyring agent_private_key, or PREDICTIONS_AGENT_PRIVATE_KEY)
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:
Region — okx outcomes setup region <global|us> (non-interactive; agent runs it).
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.
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).
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
Crypto market data (price, candles for BTC/ETH etc.) → okx-cex-market
CEX portfolio → okx-cex-portfolio
Quickstart
bash
# 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)
#
Command
Auth
Description
1
okx outcomes data events [--status active] [--category <c>] [--limit <n>]
none
List outcome events
2
okx outcomes data event <eventId>
none
Single event detail
3
okx outcomes data event-markets <eventId>
none
Event + all its markets (includes YES/NO asset ids)
4
okx outcomes data market <marketId>
none
Single market detail
5
okx outcomes data trending
none
Trending events
6
okx outcomes data ticker <assetId>
none
24h ticker for one outcome asset
7
okx outcomes data candles <assetId> [--bar 1H] [--limit 100]
Aliases: clob order/orders/trades delegate to the corresponding account * commands. Prefer account * in skill output for clarity.
Operation Flow
Step 0 — Binary check
bash
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:
text
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.
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).