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

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

Environment variables (optional overrides)

Var	Used for	Notes
`PREDICTIONS_AGENT_PRIVATE_KEY`	On-chain writes (clob create-order / cancel / ctf *)	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

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`	OAuth session ( `okx outcomes auth login` )
On-chain writes	`clob create-order / market-order / cancel-oid / cancel-all / heartbeat` , `ctf split / merge / redeem` , `wallet show`	signing key (keyring `agent_private_key` , or `PREDICTIONS_AGENT_PRIVATE_KEY` )

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

OAuth session (

okx outcomes auth login

)

On-chain writes

clob create-order / market-order / cancel-oid / cancel-all / heartbeat

ctf split / merge / redeem

wallet show

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:

bash

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

Then advance the

next_step

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

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

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)


okx outcomes data events [--status active] [--category <c>] [--limit <n>]
okx outcomes data event <eventId>
okx outcomes data event-markets <eventId>
okx outcomes data market <marketId>
okx outcomes data trending
okx outcomes data ticker <assetId>
okx outcomes data candles <assetId> [--bar 1H] [--limit 100]
okx outcomes search <keyword>
okx outcomes clob price --asset <id> [--outcome yes|no]
okx outcomes clob prices <id1> <id2> ...
okx outcomes clob midpoint --asset <id>
okx outcomes clob spread --asset <id>
okx outcomes clob book --asset <id> [--sz <n>]
okx outcomes account balance
okx outcomes account order <orderId>
okx outcomes account orders
okx outcomes account positions
okx outcomes account positions --status closed
okx outcomes account trades
okx outcomes wallet show
okx outcomes status
okx outcomes auth status [--json]
okx outcomes setup status [--json]

#	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]`	none	OHLCV candles
8	`okx outcomes search <keyword>`	OAuth	Keyword search
9	`okx outcomes clob price --asset <id> [--outcome yes\|no]`	none	Trimmed price (last/bid/ask/mid/spread)
10	`okx outcomes clob prices <id1> <id2> ...`	none	Batch price view
11	`okx outcomes clob midpoint --asset <id>` / `clob midpoints <ids...>`	none	(bid+ask)/2
12	`okx outcomes clob spread --asset <id>` / `clob spreads <ids...>`	none	Bid/ask spread
13	`okx outcomes clob book --asset <id> [--sz <n>]` / `clob books <ids...>`	none	Multi-level depth (default sz=10, max 400)
14	`okx outcomes account balance`	OAuth	Account balance
15	`okx outcomes account order <orderId>`	OAuth	Single order detail
16	`okx outcomes account orders`	OAuth	Open orders
17	`okx outcomes account positions`	OAuth	Open positions (look for status="Won" → redeem)
18	`okx outcomes account positions --status closed`	OAuth	Closed positions + realized PnL
19	`okx outcomes account trades`	OAuth	Trade history
20	`okx outcomes wallet show`	signing	Derived wallet address
21	`okx outcomes status`	OAuth	Health check
22	`okx outcomes auth status [--json]`	none	OAuth session state
23	`okx outcomes setup status [--json]`	none	Onboarding progress (region/oauth/binding)

Setup / Auth commands

Command	Auth	Description	Agent-runnable?
`okx outcomes setup region <global\|us>`	none	Set region (step 1)	✅ yes
`okx outcomes auth login --manual --json`	none	OAuth device-code (step 2): prints `{verificationUri,userCode,expiresIn}` and exits	✅ yes (relay URL+code to user)
`okx outcomes auth refresh [--json]`	none	Verify/refresh session after the user authorizes (writes session marker)	✅ yes
`okx outcomes setup bind [--keep] --json`	signing	Bind EOA wallet (step 3): prints address + a short link ( `deeplink` field, `https://okx.com/ul/3OauBX?eoa=…&uid=…` ); `--keep` reuses existing wallet	✅ yes (user opens the short link, or copies the address to bind manually)
`okx outcomes auth login --site <global\|us>`	none	Interactive/browser-foreground sign-in (for a user at a real terminal)	🚫 needs a TTY
`okx outcomes setup` / `okx outcomes shell`	—	Full interactive wizard / REPL	🚫 needs a TTY

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


okx outcomes clob create-order --asset <id> --side buy|sell --price --size [--tif gtc|gtd|ioc|fok|alo] [--expiry <ms>] [--size-type base|quote]
okx outcomes clob market-order --asset <id> --side buy|sell --size [--tif ioc|fok] [--size-type base|quote]
okx outcomes clob cancel-oid --oid <id> --asset <id>
okx outcomes clob cancel-all
okx outcomes clob heartbeat
okx outcomes ctf split --market <id> --amount <xp>
okx outcomes ctf merge --market <id> --amount <xp>
okx outcomes ctf redeem --market <id>

#	Command	Risk
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]`	High
25	`okx outcomes clob market-order --asset <id> --side buy\|sell --size [--tif ioc\|fok] [--size-type base\|quote]`	High (immediate cross)
26	`okx outcomes clob cancel-oid --oid <id> --asset <id>`	Medium
27	`okx outcomes clob cancel-all`	High
28	`okx outcomes clob heartbeat`	Medium (5-min dead-man auto cancel-all)
29	`okx outcomes ctf split --market <id> --amount <xp>`	High (locks xp)
30	`okx outcomes ctf merge --market <id> --amount <xp>`	High
31	`okx outcomes ctf redeem --market <id>`	High (burns full winning balance)

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:

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:

bash

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

okx-outcomes

NPX Install

Tags

SKILL.md Content

OKX Outcomes CLI

Preflight

Prerequisites

Environment variables (optional overrides)

Authentication paths

Setup & Onboarding

Non-TTY / agent environments

Skill Routing

Quickstart

Command Index

Read commands (no gating)

Setup / Auth commands

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

Operation Flow

Step 0 — Binary check

Step 1 — Decide what's being asked

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

Step 3 — Execute & verify

CLI Command Reference

MCP Tool Reference

Edge Cases

Global Notes