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).

Account Commands

Authenticated account view. All commands require an OAuth session — the user signs in once via okx outcomes auth login --site <global|us> (see `setup-auth.md`). The token is stored in the OS keyring, not .env.

This OAuth session is independent from the main OKX CLI's OAuth / API key. Do not call okx auth login for outcomes — use okx outcomes auth login. Check session state any time with okx outcomes auth status --json.

Aliases: clob order <id>, clob orders, clob trades all delegate to the corresponding account * command — same SDK call, same rendering. Prefer the account * form in skill output for clarity.

---

account balance

One row per oddsType:

• spots — real market
• points — points / paper market

Each row reports:

• balance — total
• available — total − frozen by open orders

okx outcomes account balance --json

---

account order \<orderId\>

Single-order detail.

okx outcomes account order 11309900 --json

clob order <orderId> is a thin alias for this command.

---

account orders

List open orders.

okx outcomes account orders --json
okx outcomes account orders --cursor abc123

clob orders is a thin alias.

---

account positions

List positions. Defaults to open; pass --status closed for closed positions with realized PnL.

okx outcomes account positions --json                  # open (default)
okx outcomes account positions --status closed --json  # closed + realized PnL
okx outcomes account positions --cursor abc123

Each row includes a Status column. Rows showing Won mark resolved markets where you hold winning tokens — feed their marketId into okx outcomes ctf redeem --market <id>.

There is no account closed-positions subcommand — closed positions are account positions --status closed. (Calling the non-existent subcommand just prints help.)

---

account trades

Trade execution history.

okx outcomes account trades --json
okx outcomes account trades --market 12345
okx outcomes account trades --side BUY --json

clob trades is a thin alias.

---

wallet show

The wallet address derived from PREDICTIONS_AGENT_PRIVATE_KEY. Useful as a pre-trade sanity check: confirm the agent will sign with the address the user expects.

okx outcomes wallet show --json

Does not require an OAuth session — only the signing key (keyring agent_private_key, generated by okx outcomes setup / setup bind, or the PREDICTIONS_AGENT_PRIVATE_KEY env override). Never pass the key from chat.

---

status

Health check that pings the events API and reads balance.

okx outcomes status --json

Output legend:

• OK — endpoint reachable, auth succeeded
• SKIP — credentials missing (no failure, just informational)
• FAIL — endpoint reachable but auth rejected

Use this as the very first command in any outcomes session.

---

Common patterns

Pre-trade balance check

okx outcomes wallet show --json | jq '.address'
okx outcomes account balance --json | jq '.[] | select(.oddsType=="spots")'

Portfolio snapshot

okx outcomes account positions --json
okx outcomes account positions --status closed --json
okx outcomes account trades --json

Find redeemable markets after settlement

okx outcomes account positions --json | jq '.[] | select(.status=="Won") | .marketId'
# pipe each marketId into:  okx outcomes ctf redeem --market <id>

CSV export removed: the prior data export {positions|trades} subcommand is no longer available. To produce CSV, pipe --json through your own jq/csvkit/script.

CLOB Commands (EIP-712 Signed)

The CLOB family covers read-side market data keyed by asset id (no auth) and on-chain order placement / cancellation (EIP-712 signed).

Asset vs market model

• A market has exactly two outcomes (YES / NO).
• Each outcome is an asset, identified by a numeric assetId (e.g. 100888000 for YES, 100888001 for NO).
• All CLOB read commands key off the YES asset id by default. Pass --outcome no (or just use the NO asset id) to flip.

When the user asks "what's the YES price on market X", you typically need: event-markets <eventId> --json → pluck the market's YES assetId → clob price --asset <assetId>.

Credential resolution for signed commands

1. --key <hex>                          (NEVER pass this from chat — see safety note below)
2. PREDICTIONS_AGENT_PRIVATE_KEY        (env override, if set)
3. keyring entry `agent_private_key`    (generated by `okx outcomes setup` / `setup bind`)
4. Test-key fallback                    (only when API base is localhost / mock)

Safety: the skill must never ask for or pass --key directly. Rely on the keyring entry (or env override). If the user pastes a private key in chat, refuse, tell them to revoke it, and walk them through okx outcomes setup bind instead.

---

Read commands (no auth)

clob price

Trimmed price view (last / bid / ask / mid / spread) for one asset.

okx outcomes clob price --asset 100888000 --json
okx outcomes clob price --asset 100888000 --outcome no --json

clob prices

Batch price view across multiple assets (assets are positional).

okx outcomes clob prices 100888000 101128000 --json
okx outcomes clob prices 100888000 101128000 --outcome no --json

clob midpoint / clob midpoints

Mid-price (bid + ask) / 2. Same flag shape as price / prices.

okx outcomes clob midpoint --asset 100888000 --json
okx outcomes clob midpoints 100888000 101128000 --json

clob spread / clob spreads

Bid/ask spread (absolute and percent).

okx outcomes clob spread --asset 100888000 --json
okx outcomes clob spreads 100888000 101128000 --json

clob book / clob books

Multi-level order-book depth. --sz controls levels per side (max 400, default 10).

okx outcomes clob book --asset 100888000 --sz 25 --json
okx outcomes clob books 100888000 101128000 --outcome no --json

clob order \<orderId\> · clob orders · clob trades

Thin aliases for the corresponding account * queries. Prefer the account * form in skill output for clarity. See `account-commands.md`.

---

Write commands (EIP-712 signed — REQUIRE dry-run preview)

Operation flow for every command below:

1. Render dry-run summary (market title / outcome / price / size / notional / wallet / available balance)

2. Ask the user Reply "confirm" to execute, or "cancel" to abort.

3. ONLY after the literal token confirm, run the real command

4. Verify with account orders --json + account positions --json

clob create-order

Place a limit order with EIP-712 signing.

# Standard limit (default tif=gtc, size-type=base)
okx outcomes clob create-order --asset 100888000 --side buy --price 0.55 --size 100

# IOC (cancel any unfilled remainder)
okx outcomes clob create-order --asset 100888000 --side sell --price 0.65 --size 50 --tif ioc

# Good-til-date with explicit expiry
okx outcomes clob create-order --asset 100888000 --side buy --price 0.40 --size 200 --tif gtd --expiry 1735689600000

# Spend 50 xp buying YES, IOC the remainder (notional budget)
okx outcomes clob create-order --asset 100888000 --side buy --price 0.65 --size 50 --tif ioc --size-type quote

Nonce and clientOrderId are auto-generated.

Dry-run summary template:

About to place order:
  Market           : <title from data market <mkt>>
  Asset            : <assetId>  (YES outcome)
  Side             : buy
  Price            : 0.55 xp
  Size             : 100 shares
  TIF              : gtc
  Notional         : ~55.00 xp
  Wallet           : <0x... from wallet show>
  Available (spots): <from account balance>

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

clob market-order

Cross the book immediately. Synthesizes an aggressive limit walked from a fresh book snapshot, signed with IOC (sweep visible liquidity) or FOK (atomic-or-cancel).

# Buy 100 shares, IOC
okx outcomes clob market-order --asset 100888000 --side buy --size 100

# FOK — rejected locally if visible depth < 100 shares (no signed message sent)
okx outcomes clob market-order --asset 100888000 --side buy --size 100 --tif fok

# Quote mode: spend 50 xp (buy + ioc only)
okx outcomes clob market-order --asset 100888000 --side buy --size 50 --size-type quote

Use market-order only when the user explicitly wants immediate fill. For predictable fills at a known price, prefer create-order --tif ioc.

clob cancel-oid

Cancel a single order by server-assigned order id.

okx outcomes clob cancel-oid --oid 8534007 --asset 100888000

Dry-run summary template:

About to cancel order:
  Order ID  : 8534007
  Asset     : 100888000
  Market    : <title>

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

clob cancel-all

Cancel every open order for the wallet. High-risk — confirm twice.

okx outcomes clob cancel-all

Dry-run summary template:

About to cancel ALL open orders.
  Wallet     : <0x... from wallet show>
  Open count : <count from account orders>

This affects every market. Reply "confirm" to execute, or "cancel" to abort.

clob heartbeat

Dead-man switch — auto-cancels everything if not renewed within 5 minutes.

okx outcomes clob heartbeat

Do not auto-enable: only execute after the user explicitly asks for dead-man protection (e.g. "set up heartbeat", "enable dead-man"). Never assume it.

Nonce is set to now + 5 minutes.

---

Edge cases

• `--key` flag: the wrapper accepts it for completeness but the skill must never pass it. Refuse if the user asks the skill to pass a key.
• Price outside [0, 1]: binary rejects. Surface the error and tell the user to revise.
• `--tif gtd` without `--expiry`: rejected client-side. Always pair them.
• `--size-type quote` outside `buy + ioc`: rejected client-side (create-order) or implicitly forced to ioc (market-order). Tell the user this constraint up front when they ask for "spend N points".
• No agent private key configured: binary returns NotAuthenticated — guide the user to okx outcomes setup bind.
• Asset id vs market id mix-up: the most common error. Read-side keys off asset, ctf keys off market, account trades --market filters by market. Always confirm which kind the user has before invoking.

CTF (Conditional Token Framework) Commands

CTF lets the user move points in and out of YES/NO outcome tokens for a market. Three operations: split, merge, redeem.

The unit of value is the OKX Outcomes internal points (xp), not USDC. Holdings, spreads, prices, and CTF amounts are all denominated in xp.

All CTF commands are EIP-712 signed and high-risk. Same credential resolution as CLOB:

1. --key <hex>                       (NEVER pass from chat)
2. PREDICTIONS_AGENT_PRIVATE_KEY     (env override, if set)
3. keyring entry `agent_private_key` (generated by `okx outcomes setup` / `setup bind`)
4. Test-key fallback                 (localhost / mock only)

Every CTF write requires the dry-run preview + user "confirm" reply flow. See SKILL.md "Operation Flow" Step 2.

---

ctf split

Split points into paired YES + NO outcome tokens for a market. After splitting:

• 100 xp → 100 YES + 100 NO
• One outcome will pay out 1 xp per share on resolution; the other 0.

okx outcomes ctf split --market 12345 --amount 100

Dry-run summary:

About to SPLIT xp into YES+NO tokens:
  Market           : <title from data market <id>>
  Amount           : <amount> xp
  Will mint        : <amount> YES + <amount> NO shares
  Wallet           : <0x... from wallet show>
  Available (spots): <from account balance>

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

When to use: user wants to provide liquidity or hedge both sides of a market before placing orders, instead of buying through the orderbook.

---

ctf merge

Burn equal YES + NO and receive points back. Inverse of split.

okx outcomes ctf merge --market 12345 --amount 100

Dry-run summary:

About to MERGE YES+NO back to xp:
  Market           : <title>
  Amount           : <amount> YES + <amount> NO
  Will return      : <amount> xp to wallet
  Wallet           : <0x...>
  Holdings (YES)   : <from account positions>
  Holdings (NO)    : <from account positions>

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

When to use: unwind paired holdings before a market resolves, e.g. user no longer wants exposure.

---

ctf redeem

Redeem winning outcome tokens after market resolution. Burns the entire winning-token balance for that market in a single tx — there is no --amount flag.

okx outcomes ctf redeem --market 12345

Find redeemable markets:

okx outcomes account positions --json | jq '.[] | select(.status=="Won") | {marketId, marketTitle, shares}'

Each row with status="Won" is a redeem candidate.

Dry-run summary:

About to REDEEM resolved tokens:
  Market           : <title>
  Status           : settled (winning outcome: <YES|NO>)
  Holdings         : <winning shares from account positions>
  Expected payout  : <holdings> xp
  Wallet           : <0x...>

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

Pre-flight checks for redeem: 1. Confirm the market is settled — okx outcomes data event <eventId> --json (poll periodically until status == settled) 2. Verify the user holds the winning side via account positions (status Won) 3. If the user holds only the losing side, refuse — there is nothing to redeem

---

Combined workflow: split → trade → redeem

A common path for liquidity provision or aggressive directional bets:

1. Split xp into YES+NO at par (one of each) 2. Sell the side you don't want via clob create-order (SELL side) 3. Wait for resolution (or close early via opposite-side order) 4. After resolution, redeem winning shares via ctf redeem

# 1. Split 100 xp in market 12345
okx outcomes ctf split --market 12345 --amount 100

# 2. Sell 100 NO shares at 0.45 (keeps YES exposure). Use NO asset id.
okx outcomes clob create-order --asset <NO_asset> --side sell --price 0.45 --size 100

# 3. (wait for settlement — poll periodically)
okx outcomes data event <eventId> --json | jq '.status'

# 4. Redeem (only winning shares pay 1 xp each)
okx outcomes ctf redeem --market 12345

Each write step must go through the dry-run + confirm flow described above.

---

Edge cases

• Insufficient points for split: binary rejects. Prompt user to top up and retry.
• Insufficient paired holdings for merge: requires equal counts of YES and NO — if positions are unbalanced, the binary rejects.
• Redeem before settlement: binary rejects — the market must be settled with a known winning outcome.
• Wrong side held: redeem still succeeds but returns 0 xp. Always confirm status="Won" in account positions before redeeming.
• NO outcome asset id: look it up in event-markets <eventId> output — each market lists both YES and NO asset ids.

Data / Search Commands

Public market data — no auth required (the one exception is search, which needs an OAuth session; see its section below). All commands support --json for machine-readable output.

Reverse-mapping: every command below forwards verbatim to the okx-outcomes binary. The okx outcomes wrapper does not modify arguments other than auto-appending --json when the user is in global --json mode.

Concept: outcomes markets use assetId (e.g. 100888000) as the primary identity for read-side data. An asset corresponds to a single outcome token (YES or NO) under a parent market. Price/depth/candles are keyed off the YES asset by convention — pass --outcome no (or use the NO asset id) when you need the NO side.

---

events

List outcome events. Filterable, paginated.

okx outcomes data events
okx outcomes data events --status active --category sports --limit 50
okx outcomes data events --sort volume --cursor abc123 --json

---

event \<eventId\>

Single event top-level detail (no markets attached).

okx outcomes data event evt_t001
okx outcomes data event evt_t001 --json

---

event-markets \<eventId\>

Event detail with all its markets attached. The most useful command for diving into an event the user wants to trade.

okx outcomes data event-markets evt_t001 --json

---

market \<marketId\>

Single market detail.

okx outcomes data market mkt_t001 --json

---

trending

Trending events (separate API from events).

okx outcomes data trending --json

---

ticker \<assetId\>

24-hour ticker (last price, volume, open/high/low) for one outcome asset.

okx outcomes data ticker 100170100 --json

---

candles \<assetId\>

K-line OHLCV data for one outcome asset.

okx outcomes data candles 100170100 --bar 1H --limit 50 --json

---

search \<keyword\>

Keyword search across events and markets. Requires an OAuth session (okx outcomes auth login — see `setup-auth.md`); unlike the other data/read commands it is not public. For single-entity lookups by id, prefer the public data event <id> / data market <id>.

okx outcomes search BTC --limit 20
okx outcomes search "US Election" --json
okx outcomes search ETH --cursor abc123 -j

The binary no longer ships search event <id> / search market <id> subcommands. For single-entity lookups use event <id> / market <id> under data.

---

ID glossary

Knowing which ID kind a command expects is the most common source of confusion — always read the parameter table before invoking.

---

Notes

• `markets` is not a top-level command — there is no markets <sub> namespace; use data market <id> / data event-markets <id> instead.
• CSV export removed: the prior data export {positions|trades} subcommand was removed. For CSV output, pipe --json through jq and your own CSV writer, or use account trades --json and post-process.
• Sports reference data removed: sports-tags, leagues, teams were retired from the CLI. Equivalent IDs surface in events --json output (tag, league fields) when you need to filter.

Setup & Authentication

First-time onboarding and the auth model for okx outcomes. Outcomes uses OKX OAuth sign-in for authenticated reads and an EIP-712 signing key for on-chain writes. There is no HMAC API-key flow in the supported path, and no `.env` auto-loading — configuration lives in ~/.okx-outcomes/config.json (non-secret) and the OS keyring (secrets; encrypted ~/.okx-outcomes/keyring.enc fallback).

This OAuth is independent from the main okx CLI's OAuth / API key. Do not

call okx auth login for outcomes — outcomes has its own okx outcomes auth login.

Fully agent-driven: every setup command below is non-interactive and agent-runnable. The agent runs all of them; the user only acts in a browser (open a device-code URL + enter a code) and by opening 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). No terminal, no ! prefix.

---

The three setup pieces (dependency order)

Region must be set first; OAuth sign-in and wallet binding both depend on it.

1. Region — Global or US. Picks REST host, WS host, and the clientOrderId region tag. 2. OAuth sign-in — device-code flow brokered by okx-auth; the agent prints a URL + code, the user authorizes in a browser, the token is stored in the keyring (never displayed). 3. EOA wallet binding — generates the signing wallet and binds its address to the OKX account by opening a bind short link (tap on phone → OKX app, or paste into any browser); if the link won't open, copy the wallet address and bind manually in the app.

Detect progress at any time:

okx outcomes setup status --json

{
  "region":      { "done": true,  "value": "us" },
  "oauth":       { "done": false },
  "eoa_binding": { "done": false, "address": "0x…" },
  "next_step":   "oauth",
  "complete":    false
}

Advance the next_step, re-running setup status --json after each step, until complete: true, then okx outcomes status.

---

Commands

setup status

okx outcomes setup status --json

Read-only state detection (region / oauth / eoa_binding / next_step / complete). Safe to run from an agent.

setup region

okx outcomes setup region global
okx outcomes setup region us

Non-interactive; writes the choice to config.json. Safe to run from an agent.

auth login (device-code — for agents)

okx outcomes auth login --manual --json
okx outcomes auth login --manual --json --site us   # --site follows the chosen region

The --manual device-code flow prints a single-line JSON envelope and exits immediately — it does not block and does not read stdin, so an agent can run it directly:

{ "verificationUri": "https://...", "userCode": "ABCD-1234", "expiresIn": 600 }

The agent relays this to the user: "Open `<verificationUri>` on any device and enter code `<userCode>` (valid ~`expiresIn/60` min)." The user authorizes in a browser (out-of-band). The token is brokered by okx-auth and stored in the keyring — never printed.

Plain okx outcomes auth login (without --manual) is the interactive/browser-foreground

variant for a user at a real terminal — it inherits stdio and is not for agents.

auth refresh (verification) / auth status

okx outcomes auth refresh --json   # verify + refresh; writes the session marker on success
okx outcomes auth status --json    # report session presence (no secret values)

After the user authorizes the device code, auth refresh is the verification step: it fetches a token (which now succeeds) and writes the OAuth session marker, so auth status / setup status then report signed-in. Poll auth refresh a few times with backoff, or run it once after the user confirms they've authorized. Both are agent-runnable and expose no secrets.

setup bind

okx outcomes setup bind --json          # generate a fresh signing wallet, then bind
okx outcomes setup bind --keep --json   # reuse the existing wallet (idempotent re-display)

Prints the address and 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; uid is the signed-in account id — both filled in by the CLI). The private key never leaves the keyring. The agent relays the short link verbatim (do not shorten or wrap it) and tells the user:

1. Tap the link on their phone → it launches the OKX app to approve the binding. 2. Or copy it into any browser (opens a web fallback). 3. 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.

The address is public — safe to show.

Regenerates by default: plain setup bind creates a new wallet every run

(wallet: "created" | "regenerated"). To re-display the binding without rotating the

address, pass --keep (wallet: "kept"). An agent re-running bind for any reason must use

--keep, or it will orphan the previously bound address.

eoa_binding.done == true means the wallet is configured locally. If an order is later

rejected for binding, have the user re-open the link (re-run setup bind --keep to

re-show the short link).

setup (full wizard) / shell

okx outcomes setup     # interactive region → OAuth → bind, all-in-one
okx outcomes shell     # interactive REPL

Interactive, raw-terminal programs (crossterm raw-mode + read_line). Only for a user at a real terminal — agents must never spawn these; use the per-step subcommands instead.

---

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. The whole setup runs from the agent:

The only human actions are in the browser (authorize the device-code URL) and opening 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). No terminal and no ! prefix are required.

---

Environment variables (optional overrides)

Env vars, if set, override the stored config / keyring value. Still use the legacy PREDICTIONS_* prefix (upstream naming).

---

Security rules

• Never accept a signing private key in chat. The wallet is created by setup /

setup bind and stored in the keyring. If a user pastes a key, refuse and tell them to revoke / rotate it.

• Never echo PREDICTIONS_AGENT_PRIVATE_KEY (or any 0x followed by 64 hex chars).

Mask as 0x****. Wallet addresses (40 hex) and tx hashes are public — fine to show.

• When reporting credential state, show only set / unset / signed in — never values.

Cross-Command Workflows

Common composed flows. The skill should pick the matching workflow based on user intent, then chain commands.

Unit of value: outcomes markets transact in points (xp), not USDC. Balances, prices, and CTF amounts are all xp.

ID kinds: eventId (event-level), marketId (market-level, used for ctf * and account trades --market), assetId (outcome-token-level, used for clob * reads and writes). See data-commands.md "ID glossary".

---

0. First-time setup (onboarding) — fully agent-driven

User: "set me up" / "首次配置" / "sign in" / any authed command fails with not-signed-in.

Three pieces in dependency order: region → OAuth sign-in → wallet binding. The agent runs every command; the user only acts in a browser (device-code URL) and by opening the bind short link (tap on phone → OKX app, or paste into a browser). No terminal, no ! prefix.

1. okx outcomes setup status --json             → detect next_step / complete
2. okx outcomes setup region <global|us>         → (if region not done) agent runs it
3. okx outcomes auth login --manual --json       → agent runs it; capture {verificationUri,userCode,expiresIn}
   → relay to user: "Open <verificationUri> on any device, enter code <userCode> (valid ~N min)"
4. (user authorizes in browser — out-of-band, no terminal)
5. okx outcomes auth refresh --json              → agent verifies; poll w/ backoff until signed-in
                                                   (or run once after user says "done")
6. okx outcomes setup bind --json                → (if eoa not done) agent runs it; relay address + short link (deeplink field)
   → user opens link on phone/browser; if it won't open, copy wallet address & bind manually in OKX app
                                       (Outcomes → Profile → Settings → API Bind Wallet)
                                       (re-display without rotating the wallet: setup bind --keep)
7. okx outcomes setup status --json              → re-check until complete:true
8. okx outcomes status --json                    → final health check

Agent rules: all per-step commands above are agent-runnable (device-code auth login --manual

prints JSON and exits; it does NOT block or read stdin). The user's only actions are browser

(authorize the URL+code) and opening the bind short link. Never spawn the full interactive

okx outcomes setup wizard, okx outcomes shell, or plain auth login (no --manual) from an

agent — they need a TTY. See `setup-auth.md`.

---

1. Daily brief (briefing of the market state)

User: "What's happening in outcomes markets today?" / "今日预测市场" / "trending markets"

1. okx outcomes status --json                       → confirm env is OK
2. okx outcomes data trending --json                     → top events
3. okx outcomes data events --status active --limit 10 --json   → broader active list
4. okx outcomes account balance --json              → user's current balance (if authed)

Display:

• Up to 5 trending events (title + volume)
• User's spots balance + available
• Any positions with > 0 unrealized PnL (from account positions)

---

2. Event deep-dive (research before trading)

User: "Tell me more about <X event>" / "深挖 <X>"

1. okx outcomes search <keyword> --limit 5 --json   → find candidate event IDs
   (or)
   okx outcomes data events --category <c> --limit 20 --json

2. okx outcomes data event-markets <eventId> --json      → full event + all sub-markets + YES/NO asset ids

3. For each sub-market the user is interested in:
   okx outcomes data market <marketId> --json            → details
   okx outcomes clob price --asset <yesAssetId> --json   → live price (YES side)
   okx outcomes clob book --asset <yesAssetId> --sz 5 --json  → top-of-book depth
   okx outcomes data candles <yesAssetId> --bar 1H --limit 50 --json  → price history

Output should answer: "Is this tradable now? What's the spread? How has it moved?"

---

3. Portfolio check (existing positions audit)

User: "Show me my positions and PnL" / "我的持仓" / "portfolio"

1. okx outcomes wallet show --json                  → wallet address
2. okx outcomes account balance --json              → spots + points
3. okx outcomes account positions --json            → open positions (note "Won" rows for redeem)
4. okx outcomes account positions --status closed --json  → recent realized PnL

Display:

• Wallet address + balance summary
• Open positions with marketTitle / outcome / size / avgPx / mark / upl / status
• Last 5 closed positions with realized PnL
• Any rows with status="Won" → call out as redeemable

---

4. Safe place-order (the critical write flow)

User: "Buy 100 YES on market <id> at 0.55" / "下单 ..."

0. PREFLIGHT
   okx outcomes status --json                       → must be healthy
   okx outcomes wallet show --json                  → confirm wallet
   okx outcomes data event-markets <eventId> --json      → look up the YES assetId for this market
   okx outcomes data market <marketId> --json            → confirm active, fetch title
   okx outcomes clob price --asset <yesAssetId> --json   → confirm current price vs user's limit
   okx outcomes account balance --json              → spots.available ≥ price * size

1. DRY-RUN PREVIEW (render to user, do NOT execute)

About to place order: Market : <title> (mkt_<id>) Asset : <yesAssetId> (YES outcome) Side : buy Price : 0.55 xp Size : 100 shares TIF : gtc Notional : ~55.00 xp Current market : YES bid 0.54 / ask 0.55 Wallet : 0x1234...abcd Available (spots): 1,234.56 xp

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

2. WAIT for the user's exact reply.
   - "confirm" → proceed
   - Anything else (including silence, "yes", "ok", "go", "yep") → abort with a polite ask for the exact word

3. EXECUTE
   okx outcomes clob create-order \
     --asset <yesAssetId> --side buy --price 0.55 --size 100

4. VERIFY
   okx outcomes account orders --json               → confirm the order is open
   (Optional) Poll periodically until status changes from "open" to "filled"

Variations:

• "Sell 100 NO at 0.45" → look up the NO assetId from event-markets, then --asset <noAssetId> --side sell --price 0.45 --size 100
• "Spend 50 points buying YES" → notional/quote mode: --side buy --price <limit> --size 50 --tif ioc --size-type quote
• "Market buy 100 shares of YES" → okx outcomes clob market-order --asset <yesAssetId> --side buy --size 100
• "GTD until <date>" → --tif gtd --expiry <UNIX_MS> (compute Unix ms from the user's date)

Same dry-run + confirm structure applies to:

• clob cancel-oid --oid <id> --asset <id> — preview shows order + market detail
• clob cancel-all — preview shows wallet + open-order count
• ctf split/merge/redeem — preview shows market + amount + expected balance change

---

5. Resolve and redeem (after market settlement)

User: "<X event> resolved — claim my winnings" / "结算后赎回"

1. okx outcomes data event <eventId> --json              → confirm status == settled
                                                       → look at "winningOutcome"

2. okx outcomes account positions --json | jq '.[] | select(.status=="Won") | {marketId, marketTitle, shares}'
                                                       → enumerate redeemable markets

3. DRY-RUN (required for any ctf write)

About to REDEEM resolved tokens: Market : <title> Status : settled (winning outcome: YES) Holdings (YES) : 250 shares Expected payout : 250.00 xp Wallet : 0x...

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

4. EXECUTE (no --amount — redeem burns the full winning balance)
   okx outcomes ctf redeem --market <id>

5. VERIFY
   okx outcomes account balance --json              → confirm spots increased
   okx outcomes account positions --json            → confirm winning shares removed

If the user holds only the losing side: warn that redeem will return 0 xp and ask whether to skip.

---

6. Recovery — "okx-outcomes not found"

User runs any outcomes command → wrapper prints install hint.

1. Confirm curl + sh available (macOS / Linux):
   curl --version
   sh --version

2. Install prebuilt binary from GitHub Releases:
   curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh

3. Verify:
   okx-outcomes --version

4. (One-time) Complete setup — see workflow 0 (per-step in agent contexts).

5. Test:
   okx outcomes status --json

Never have the user cargo install from source unless they explicitly need a dev build.

---

7. Recovery — auth errors

Any authenticated command (account / search / status balance) returns auth failure.

1. Check session state (no secrets read): okx outcomes auth status --json and okx outcomes setup status --json 2. If the OAuth session is expired but present, try okx outcomes auth refresh --json (agent-runnable). 3. If missing, re-run the device-code sign-in (workflow 0 step 3): okx outcomes auth login --manual --json → relay the URL+code → user authorizes in a browser → okx outcomes auth refresh --json to verify. No terminal needed. 4. Run okx outcomes status --json to verify both balance and events checks pass 5. Retry the original command

If wallet show or a write fails with NotAuthenticated: the signing wallet isn't bound — 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). Do not ask them to paste the key in chat.