Skip to content

cli-reference.md

Latest commit

 

History

History
914 lines (657 loc) · 34 KB

cli-reference.md

File metadata and controls

914 lines (657 loc) · 34 KB

OKX Outcomes — CLI Developer Reference (EN)

A command-line client for the OKX Outcomes REST and WebSocket APIs. Authoritative reference for application developers integrating with the platform: every subcommand, every flag, every authentication requirement, every wire-format gotcha.

The CLI is a thin wrapper over the underlying Rust SDK (okx-outcomes-sdk). Anything the CLI can do, the SDK can do programmatically — this document doubles as a usage guide for the SDK through its public methods.

Quick start

Installation

Distributed via GitHub.

# Pre-built binary (macOS / Linux) — pulls the latest GitHub release onto $PATH.
# Windows: download the .zip from the Releases page directly.
curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh

Build from source (needs a Rust toolchain):

git clone https://github.com/okx/outcomes-cli
cd outcomes-cli
cargo run -- --help

Prerequisites

Two things must be in place before the CLI is useful:

  1. OKX mobile app with a registered account — needed for OAuth sign-in and for binding the generated EOA address (the binding flow lives in the app).
  2. Rust 1.90+ if and only if you are building from source (cargo install / build from source). The pre-built binary download needs no Rust toolchain.

Step 1 — run the wizard

okx-outcomes setup

The wizard:

  1. Pick a region — Global / US. Selects the OAuth sign-in site, WebSocket host, and clientOrderId region tag.
  2. OAuth sign-in via the okx-auth token broker. This is the only account-authentication step — no separate API key prompt. Best-effort: failure is non-fatal and you can run auth login later.
  3. Auto-generate a signing wallet with alloy-signer-local::PrivateKeySigner::random. The 64-hex private key is not printed; only the derived EOA address (from the SDK's signer_address) is displayed. If a wallet is already stored in the keyring, a yellow warning prints the current address before it's overwritten — the old EOA binding becomes invalid and you'll need to scan the new QR.
  4. Address binding — a QR is rendered in the terminal encoding the okx://exchange/miniapp?…&eoa=… deeplink; the deeplink is also printed in plain text. Scan it with the OKX mobile app to bind the generated address. (No HTML page, no auto-opened browser tab.) Binding is one-to-one: each account binds exactly one wallet and each wallet binds to exactly one account (no one-wallet-to-many-accounts, no many-wallets-to-one-account); binding a new wallet replaces any prior binding.
  5. Save — credentials land in the OS keyring (macOS Keychain / Windows Credential Manager / Linux libsecret) with an AES-256-GCM encrypted file fallback at ~/.okx-outcomes/keyring.enc; non-secret config (region / mode / base URLs / locale) lands in ~/.okx-outcomes/config.json. okx-outcomes logout wipes stored credentials.

Every okx-outcomes setup run replaces the signing wallet — there is no menu, no keep-existing path, no import path, no private-key reveal. The signing key lives only in the OS keyring (encrypted-file fallback at ~/.okx-outcomes/keyring.enc).

Credentials

setup writes two kinds of state on success:

Credential Source Used for
OAuth access token okx-auth login (driven by setup) All authenticated REST / account / trading endpoints plus WebSocket private-channel login — account, clob, ctf, and the authenticated data calls. When not signed in, a live HMAC key from ~/.okx/config.toml is used as a fallback (see the note below).
agent_private_key Generated by setup via alloy-signer-local EIP-712 signing for write actions: clob create-order, clob cancel-*, ctf split / merge / redeem. The derived EOA address must be bound to your OKX account via the QR / deeplink the wizard prints.

The signing key is the only secret in the keyring (encrypted ~/.okx-outcomes/keyring.enc fallback on Linux or when the keyring is unavailable).

Account auth is OAuth-first, with an HMAC fallback. Sign in with okx-outcomes auth login; the OAuth bearer covers REST account/trading endpoints and private WebSocket channels alike. If no OAuth session is available, require_auth falls back to a live (non-demo) HMAC API key from the shared OKX config at ~/.okx/config.toml (the profiles table written by the agent-trade-kit CLI). The key is region-scoped — a US profile routes to the US host — and the same fallback drives the private-WS login frame. There are no PREDICTIONS_* credential env vars or --flag overrides (those were removed); ~/.okx/config.toml is the only API-key source. A demo-only profile is rejected with a hint (the outcomes API has no simulated-trading mode). You only need one of the two — a completed auth login is sufficient on its own (no need to also configure an API key in ~/.okx/config.toml), and a configured API key suffices if you haven't signed in. You never need both.

Shape of ~/.okx/config.toml (written by the agent-trade-kit CLI — okx-outcomes only reads it, never writes it):

default_profile = "live"     # present in the file, but IGNORED by okx-outcomes

[profiles.live]
api_key    = "…"
secret_key = "…"
passphrase = "…"
site       = "us"            # "global" | "us" | "eea"; if omitted, region is inferred from base_url

[profiles.demo]
api_key    = "…"
secret_key = "…"
passphrase = "…"
demo       = true            # demo profiles are skipped (Outcomes has no simulated-trading mode)

Profile selection: okx-outcomes uses the first profile, in file order, that is not demo = true and has all three of api_key / secret_key / passphrase. default_profile is not consulted. The fallback's REST host comes from that profile's site (else inferred from base_url, else Global); an eea profile is rejected (no Outcomes endpoint).

First commands

# Browse markets (no auth required)
okx-outcomes data trending
okx-outcomes data events --status active --limit 20
okx-outcomes search "election"

# Account state (auth required)
okx-outcomes account balance
okx-outcomes account orders
okx-outcomes account positions

# Place + cancel an order (auth + signing key required)
okx-outcomes clob create-order --asset 101664000 --side buy --price 0.65 --size 100 --tif gtc
okx-outcomes clob cancel-oid --oid <ORDER_ID> --asset 101664000

# Live data streams (public)
okx-outcomes ws prices 101664000
okx-outcomes ws terminal                 # ratatui trading terminal

Add --json (or -j) to any command for machine-readable output. All list commands accept --cursor <c> for pagination. The rest of this document covers every flag and edge case.

1. Configuration

The CLI reads non-secret config from ~/.okx-outcomes/config.json (written by setup or setup region <us|global>) and secrets — the OAuth session (managed by the bundled okx-auth broker) and the EIP-712 signing key (agent_private_key) — from the OS keyring (written by setup). There are no PREDICTIONS_* env-var overrides and no .env auto-loading.

Environment variables (operational only — these are the only ones the CLI reads)

Variable Required for Description
OKX_OUTCOMES_HOME Optional Override the config / keyring directory. Default: ~/.okx-outcomes
OKX_AUTH_BIN Optional Path to the bundled okx-auth token broker binary
OKX_OAUTH_CONFIG Optional Path to the OAuth broker config
OUTCOMES_DEBUG Optional Set to 1 to log HTTP + WS request/response details to stderr. Debug builds only; output may include the Authorization: Bearer header, signatures, order bodies, and private-channel frames. Do not share without redaction. Release builds compile it out.
OKX_THEME Optional Color theme: auto (default) / light / dark. auto uses the terminal's default foreground; the --theme flag overrides it

setup — interactive wizard

The fastest way to configure a fresh environment:

okx-outcomes setup

The wizard sets your region, signs you in via OAuth, generates the EIP-712 signing key (stored in the OS keyring, encrypted ~/.okx-outcomes/keyring.enc fallback), and writes non-secret config to ~/.okx-outcomes/config.json. Re-run it any time to rotate the signing key; okx-outcomes logout clears everything.

Region and sign-in

Onboarding is three steps, in dependency order (sign-in and binding depend on the region):

okx-outcomes setup region us      # or: global
okx-outcomes auth login            # OAuth browser sign-in (or: auth login --manual)
okx-outcomes setup bind            # approve the EOA wallet in the OKX mobile app

The interactive okx-outcomes setup wizard performs all three. It generates the signing wallet — it never prompts for or imports a key.

Security note: Treat the signing key (agent_private_key) as highly sensitive — it controls every write operation against your account. It lives only in the OS keyring and is never displayed.

2. Global Conventions

Output modes

Most commands accept a --json flag to switch from the human-readable colored table to machine-readable JSON:

okx-outcomes account balance           # colored table
okx-outcomes account balance --json    # pretty JSON

JSON output is serde_json::to_string_pretty-formatted. Pipe to jq for further processing:

okx-outcomes data trending --limit 1 --json | jq '.events[0].eventId'

Debug logging

Set OUTCOMES_DEBUG=1 to emit request and response details on stderr (HTTP and WebSocket frames). Debug builds only — cargo run / cargo build; release builds compile the logging out. Debug output may include auth headers, signatures, signed order bodies, and private-channel frames, so redact it before sharing. Useful for local debugging of signing failures and wire shapes:

OUTCOMES_DEBUG=1 okx-outcomes clob create-order \
    --asset 101664000 --side buy --price 0.65 --size 100

The output includes:

  • >>> POST <url> / >>> GET <url> — outgoing request line
  • >>> Authorization: Bearer ... — OAuth bearer token (sensitive; redact before sharing). On the HMAC fallback path you'll instead see >>> ok-access-*: ... signing headers (also sensitive).
  • >>> body: {...} — request JSON (write requests may include signatures)
  • <<< status: <code> — HTTP status
  • <<< body: {...} — response JSON

WebSocket streams (ws subcommands) emit their own framing notices on stderr; the captured NDJSON goes to stdout.

Pagination

List endpoints (account orders, clob trades, data events, etc.) use cursor-based pagination. Pass --cursor <token> to fetch the next page. The response prints the next cursor when more data is available:

okx-outcomes account trades
# ... 20 trades ...
# Next page: --cursor 86475

okx-outcomes account trades --cursor 86475

Error format

Errors print to stderr with a red Error: prefix and an indented chain of upstream causes. Examples:

Error: API error (100011): order not found
Error: Deserialization error: missing field `expectedField` at line 1 column 42
  caused by: missing field `expectedField` at line 1 column 42
Error: Verify error: invalid signature bytes: signature error

The process exits non-zero on CLI validation errors, signing failures, and upstream API / deserialization errors. For automation, still parse stdout / stderr or --json output for the exact error body.

3. Command Overview

Group Subcommands Auth Notes
Top-level status, setup, shell depends health check, wizard, REPL
wallet show signing key (keyring) local-only address derivation
data 7 subcommands none public data, no auth required
search 1 subcommand OAuth session keyword event search
account 6 subcommands OAuth session balance, order, orders, positions, trades
clob 17 subcommands OAuth + signing key (keyring) (writes) order book trading (prices / book / place / cancel / heartbeat); order and orders are aliases for the account versions
ctf 3 subcommands OAuth + signing key (keyring) split / merge / redeem positions
ws 14+ subcommands depends WebSocket streams
Total ~43 commands

Read-only commands need account auth — an OAuth session (auth login), or a live HMAC key in ~/.okx/config.toml as a fallback. Write commands (clob create-order, clob cancel-*, ctf *) also need the EIP-712 signing key (in the keyring) for signing.

4. Top-level Commands

4.1 status

Health check that hits both a public endpoint (events list) and an authenticated endpoint (balance) and reports OK or the error for each.

okx-outcomes status

Output:

  events: OK (5 returned)
  balance [points]: 19076.22400000 (avail 19076.22400000)

Auth: OAuth session (for the balance call). Skips the balance check if no session is present and only verifies public connectivity.

4.2 setup

Interactive credential wizard. See §1 Configuration.

okx-outcomes setup

This subcommand uses raw terminal input and is not scriptable. The individual steps can also be run separately: setup region <us|global>, auth login, and setup bind (see Region and sign-in above).

4.3 shell

REPL mode. Subcommands run without the okx-outcomes prefix:

okx-outcomes shell
okx-outcomes> data trending --limit 3
okx-outcomes> account balance
okx-outcomes> exit

Useful for interactive exploration. Ctrl-C or exit terminates.

5. wallet — Local Wallet

5.1 wallet show

Derive and print the EOA address from the signing key (agent_private_key) stored in the keyring. Performs no network requests.

okx-outcomes wallet show

Output:

  Address: 0x1234abcd...5678ef00

Auth: Signing key only (read from the keyring). No OAuth session needed.

6. data — Public Market Data

All data subcommands hit public endpoints and require no authentication. Use them to browse the market without an account.

6.1 data events

List events with optional filtering and pagination.

okx-outcomes data events
okx-outcomes data events --status active --category SPORTS --limit 10
okx-outcomes data events --sort trending --cursor <next>

Flags:

  • --status <s> — filter by event status (active, resolved, etc.)
  • --category <c> — filter by category (e.g. SPORTS, CURRENT_AFFAIRS)
  • --sort <s> — sort order (e.g. trending)
  • --cursor <c> — pagination cursor
  • --limit <n> — page size (default 20, max 100)

6.2 data trending

Alias for data events with the trending default sort. Convenient shortcut for "give me the most popular events right now."

okx-outcomes data trending --limit 5

6.3 data event <eventId>

Fetch a single event and its constituent markets.

okx-outcomes data event 17301090139211776

6.4 data event-markets <eventId>

List only the markets belonging to one event (no event metadata).

okx-outcomes data event-markets 17301090139211776

6.5 data market <marketId>

Fetch a single market by ID.

okx-outcomes data market 101664

6.6 data ticker <assetId>

Real-time ticker for one prediction-market asset. The assetId here is the asset-level identifier (e.g. 101664000), not the event-level ID.

okx-outcomes data ticker 101664000

Output includes last trade price, best bid/ask, 24-hour open/high/low, and 24-hour volume.

6.7 data candles <assetId>

OHLCV candles for one instrument.

okx-outcomes data candles 101664000 --bar 1H --limit 24
okx-outcomes data candles 101664000 --bar 1H --after 1779462000000

Flags:

  • --bar <interval> — candle interval (1m, 5m, 1H, 1D, etc.)
  • --limit <n> — number of candles to fetch
  • --after <ms> — return candles with timestamp before this cursor (Unix ms)
  • --before <ms> — return candles with timestamp after this cursor (Unix ms)

Note: OKX's pagination uses the cursor-name conventions above (counterintuitive but consistent across their API). --after walks toward older candles; --before walks toward newer ones.

7. search — Event & Market Lookup

Keyword and direct-ID search. Requires an OAuth session.

7.1 search <keyword>

Free-text search across events.

okx-outcomes search trump --limit 10
okx-outcomes search "world cup" --cursor <next>

Flags:

  • --cursor <c>, --limit <n> — pagination

8. account — Account Queries

All account subcommands require an OAuth session (auth login). No signing key required.

8.1 account balance

Account balance per odds type.

okx-outcomes account balance

Output:

  Balance
  type: points  balance: 19076.22400000  available: 19076.22400000

8.2 account order <orderId>

Fetch detail for a single order. Rendered as a one-row bordered table using the same column set (Oid / Asset / Side / Type / Price / Size / Filled / Status) as the listing in §8.3, so the two views are visually consistent. clob order <orderId> (§9.1) is an alias that delegates here.

okx-outcomes clob orders        # find one
okx-outcomes account order 11309900
okx-outcomes account order 11309900 --json

8.3 account orders

List orders. Defaults to open (active); pass --status closed for filled / cancelled / expired / failed orders. clob orders (§9.2) is an alias that delegates here.

okx-outcomes account orders
okx-outcomes account orders --status closed
okx-outcomes account orders --cursor <next>

Each row shows order ID, asset, side, type, price, size, filled size, and status.

8.4 account positions

List positions. Defaults to currently-open; use --status closed for historical / resolved positions.

okx-outcomes account positions
okx-outcomes account positions --status closed
okx-outcomes account positions --market 101664 --limit 5
okx-outcomes account positions --cursor <next>

Flags:

  • --status <open|closed> — filter by lifecycle (default open)
  • --market <id> — scope to a single market
  • --cursor <c> — pagination cursor from a previous response
  • --limit <n> — page size (max 100, default 20)

8.5 account trades

List fill history.

okx-outcomes account trades
okx-outcomes account trades --market 101664 --side BUY --limit 50
okx-outcomes account trades --start-time 1779000000000 --end-time 1779500000000
okx-outcomes account trades --cursor <next>

Flags:

  • --market <id> — filter by market ID
  • --side BUY|SELL — filter by side
  • --start-time <ms> — Unix-ms epoch lower bound (inclusive)
  • --end-time <ms> — Unix-ms epoch upper bound (inclusive)
  • --cursor <c> — pagination cursor from a previous response
  • --limit <n> — page size (max 100, default 20)

9. clob — Order Book Trading

The central limit order book commands. Reads need account auth (an OAuth session, or the HMAC ~/.okx/config.toml fallback); writes also require the EIP-712 signing key (in the keyring).

Read operations

Asset vs market — read-only price / book commands key off the asset id of the outcome token (e.g. 101664000), not the parent market id. NO-outcome data is derived locally as 1 − yes. Use --outcome yes|no (or shorthand --yes / --no) to switch; defaults to yes.

9.1 clob order <orderId>

Thin alias for account order <orderId> (§8.2) — same SDK call, same bordered-table renderer, identical output.

okx-outcomes clob order 806137

9.2 clob orders

Thin alias for account orders (§8.3) — same SDK call, same renderer. Supports --status open|closed (default open).

okx-outcomes clob orders
okx-outcomes clob orders --status closed
okx-outcomes clob orders --cursor <next>

9.3 clob trades

Thin alias for account trades (§8.6) — same SDK call, same bordered-table renderer, same --cursor pagination.

okx-outcomes clob trades --market 101664 --side BUY
okx-outcomes clob trades --cursor <next>

Flags:

  • --market <id> — filter by market ID
  • --side BUY|SELL — filter by side
  • --cursor <c> — pagination

9.4 clob price / clob prices

Trimmed price view (last / bid / ask / mid / spread) for one or many assets. prices takes asset IDs as positional arguments.

okx-outcomes clob price --asset 101664000
okx-outcomes clob price --asset 101664000 --outcome no --json
okx-outcomes clob prices 101664000 101128000 --outcome no

9.5 clob midpoint / clob midpoints

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

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

9.6 clob spread / clob spreads

Bid/ask spread, both absolute and percent.

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

9.7 clob book / clob books

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

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

Write operations

All write commands sign with the EIP-712 signing key (agent_private_key, read from the keyring) and submit the signed action to the backend.

9.8 clob create-order

Place a new order.

okx-outcomes clob create-order \
    --asset 101664000 --side buy --price 0.65 --size 100 \
    --tif gtc

# Spend 50 points buying YES, IOC the remainder
okx-outcomes clob create-order \
    --asset 101664000 --side buy --price 0.65 --size 50 \
    --tif ioc --size-type quote

Flags:

  • --asset <id> — required; the asset ID for the outcome token
  • --side buy|sell — required
  • --price <p> — required; decimal between 0 and 1 exclusive
  • --size <s> — required; with --size-type base (default) this is a share count; with --size-type quote it is a points notional budget
  • --tif gtc|gtd|ioc|fok|alo — optional; default gtc. See §12 Time-in-Force Semantics
  • --expiry <unix-ms> — required if and only if --tif gtd; expiry timestamp in milliseconds
  • --size-type base|quote — optional; default base. base reads --size as shares; quote reads it as a points (pts) notional spend. quote is only valid for --side buy --tif ioc per the OKX support matrix — the CLI rejects other combinations locally before signing.
  • --no-status — optional; skip the post-placement status lookup described below (useful for scripted / high-frequency use)

A client order ID is auto-generated and attached to the order.

On success the CLI prints a one-line summary of the submitted order and the order's live status as a table — including the placement transaction hash as a trailing column — resolved by looking the order up by its client order ID (checking closed then open orders, with a brief retry). A resting limit order shows Active; an immediately-filled IOC/FOK/market order shows Filled. Because filled orders move to positions quickly, if the order can't be found it reports "no longer on the book — likely filled. Check account positions / clob trades" (with the tx hash on its own line) rather than failing. With --json, the output becomes { tx_hash, client_order_id, order } where order is the resolved record (or null).

9.9 clob market-order

Cross the book immediately on either outcome. The SDK has no dedicated market-order type — market semantics are synthesized from a fresh book snapshot plus an aggressive limit + IOC/FOK time-in-force: walk the opposing side accumulating visible depth, take the first level where cumulative ≥ requested size as the cutoff, and sign at that price with IOC (sweep available) or FOK (atomic-or-cancel).

Select the market and outcome with --market <id> --outcome yes|no (recommended). The NO side is priced by inverting the YES book locally (no_ask = 1 − yes_bid); the NO asset id is never sent to the book endpoint (which only accepts the YES asset id), so a NO market order no longer fails with API error (51001). The order is placed on the resolved outcome's asset id, and the summary labels the outcome (NO/YES).

With --size-type quote the walk accumulates cumulative notional spend (level.size × level.price in pts) instead of cumulative shares, so a 50-pt budget walks down asks until cumulative spend covers 50 pts.

# Recommended: market-buy 10 shares of NO, IOC (priced off the inverted YES book)
okx-outcomes clob market-order --market 101663 --outcome no --side buy --size 10

# YES, base + FOK: rejected locally if visible depth < 100 shares
okx-outcomes clob market-order --market 101663 --outcome yes --side buy --size 100 --tif fok

# Quote: spend 50 points buying NO, IOC the remainder
okx-outcomes clob market-order --market 101663 --outcome no --side buy --size 50 --size-type quote

Flags:

  • --market <id> — market id (recommended form; requires --outcome)
  • --outcome yes|no — required with --market; selects which outcome to trade
  • --asset <id> — [deprecated] YES-only legacy form; use --market --outcome instead. Still works (prints a one-time deprecation notice to stderr) but cannot price/place the NO side.
  • --side buy|sell — required (quote mode requires buy)
  • --size <s> — required; shares for base, points budget for quote
  • --tif ioc|fok — optional; default ioc. fok orders that can't be filled from the current snapshot are rejected client-side — no network round-trip, no signed message wasted. quote mode requires ioc (the server rejects quote + fok).
  • --size-type base|quote — optional; default base. Same semantics as in create-order (§9.8): quote is buy + ioc only.

Exactly one of { --market (+ --outcome) } or the deprecated { --asset } must be supplied; passing both is an error.

The cutoff is a ceiling, not the price you pay. The matching engine fills against each consumed level at that level's resting price; the cutoff just caps how far the engine will walk.

9.10 clob cancel-oid

Cancel by server-assigned order ID.

okx-outcomes clob cancel-oid --oid 806137 --asset 101664000

9.11 clob cancel-all

Cancel all open orders for the authenticated account.

Immediate effect: this signs and submits a cancel-all transaction without an extra prompt. Check account orders first, and do not run it from generic smoke tests or automation unless that is the intended side effect.

okx-outcomes clob cancel-all

Optionally filter to specific asset IDs (currently a SDK feature, not exposed via CLI flag — pass them through programmatically).

9.12 clob heartbeat

Submit a heartbeat to refresh the cancel-all expiry window. Used in conjunction with a long-lived cancel-all subscription where the server will auto-cancel all open orders if no heartbeat arrives within the expiry window.

Immediate effect: this signs a dead-man cancel-all heartbeat. It is not a passive health check.

okx-outcomes clob heartbeat

10. ctf — Conditional Token Framework

The CTF lets you split points into a paired YES + NO position, merge a paired position back into points, or redeem the winning tokens of a resolved market.

All ctf subcommands are writes: OAuth session + signing key (keyring) required.

10.1 ctf split

Convert N pts into N YES + N NO outcome tokens (a "complete set" totalling 1 pts per pair).

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

Flags:

  • --market <id> — market ID
  • --amount <pts> — points to split (in pts; backend smallest-unit scaling is handled by the SDK)

10.2 ctf merge

Burn equal YES + NO amounts and receive points back at 1:1. Inverse of split.

okx-outcomes ctf merge --market 101664 --amount 50

Flags:

  • --market <id> — market ID
  • --amount <size> — token-pair amount to merge

10.3 ctf redeem

After a market has resolved, burn your winning tokens for points at 1:1. No --amount flag — redeem is all-or-nothing per market; the server burns every winning token you hold in that market on a single tx.

To find markets where you have something to claim, look at account positions (§8.4) and filter to rows whose Status column shows Won — each such row's marketId is the value to pass to --market here. The Value column on a Won row is the points payout you'll receive (= size at 1:1).

# Find claimable markets
okx-outcomes account positions

# Redeem each Won market (one tx per market)
okx-outcomes ctf redeem --market 101664

Flags:

  • --market <id> — market ID

Losing-side tokens (Status = Lost in account positions) settle to 0 pts and are not redeemable — they sit in your wallet as dust.

11. ws — WebSocket Streams

The ws subcommands open one or more WebSocket subscriptions and stream messages until you press Ctrl-C (or pass --json and pipe to a process that closes).

Pass --json for line-delimited JSON output (NDJSON); omit for the human-readable rendering.

Public channels (no auth)

Each takes one or more instrument IDs as positional arguments.

11.1 ws prices <assetId> [<assetId>...]

Prediction-market price ticks.

okx-outcomes ws prices 101664000
okx-outcomes ws prices 101664000 100168001

11.2 ws books <assetId>

Order book depth (top-of-book + levels).

okx-outcomes ws books 101664000

11.3 ws trades <assetId>

Public trade stream (every fill in the market).

okx-outcomes ws trades 101664000

11.4 ws tickers <assetId>

Ticker updates (last price, 24h volume, best bid/ask).

okx-outcomes ws tickers 101664000

11.5 ws candle<bar> <assetId>

OHLCV candle stream. Supported bars: candle1m, candle5m, candle1H, candle1D.

okx-outcomes ws candle1m 101664000

11.6 ws event-status <eventId>

Event-level status changes. Accepts the raw event ID; the command automatically prefixes with event- if needed.

okx-outcomes ws event-status 17301090139211776

Private channels (require account auth — OAuth session, or HMAC fallback)

These take no positional arguments; the channel is implicitly your account.

Command Channel What it streams
ws orders pm-order Your open / new / cancelled orders
ws positions pm-position Your position updates
ws balance pm-balance Your balance changes
ws user-trades pm-user-trade Your fills
ws pnl pm-pnl Your realized / unrealized PnL stream
ws private all of the above Combined subscription 
okx-outcomes ws orders --json
okx-outcomes ws private

Interactive TUIs

Visual interfaces, not designed for piping.

11.7 ws terminal [<assetId>]

Full-screen trading terminal with order entry and live book display.

okx-outcomes ws terminal
okx-outcomes ws terminal 101664000

12. Time-in-Force Semantics

The --tif flag on clob create-order accepts these values:

Value Name Behavior
gtc Good Till Cancel Rests on the book until filled or cancelled
gtd Good Till Date Like GTC but auto-cancels at --expiry
ioc Immediate or Cancel Fills what it can immediately, cancels the rest
fok Fill or Kill Fills entirely or rejects entirely
alo Add Liquidity Only Post-only; rejected if it would take liquidity

Combination rules (server-enforced):

  • tif=gtd requires --expiry <unix-ms>. Omitting it yields 10001 PARAM_ERROR.
  • tif=fok with sizeType=quote is rejected.
  • tif=alo with sizeType=quote or market orders is rejected.
  • tif=ioc is the only TIF valid with sizeType=quote.

13. Common Errors

Error Cause Resolution
API error (100011) Order not found Order may have been filled, cancelled, or never existed
API error (100015) Calldata invalid Action shape or sizing failed server validation
API error (100101) Signature verification failed Wrong key, wrong chain, or msgpack envelope shape diverged from backend expectation
API error (10001) PARAM_ERROR Required field missing or invalid Check the per-TIF combination rules in §12
API error (51001) Instrument ID not found Asset / market ID does not exist on this environment
API error (201001) Event not found Event ID does not exist
API error (201002) Market not found Market ID does not exist
Deserialization error Response shape changed Report to the SDK maintainers with the raw response body

For signing failures specifically, enable OUTCOMES_DEBUG=1 only in a local debug build and compare the >>> body: line against a known-good request from the same account. Redact auth headers, signatures, and private-channel frames before sharing logs.

14. Glossary

Term Meaning
Asset ID Identifier for an outcome token (YES or NO) within a market. Used as the wire-level assetId in order requests. Example: 101664000
Market ID Identifier for one prediction market (one question). Example: 101664
Event ID Identifier for a real-world event containing one or more related markets. Example: 17301090139211776 (Germany vs. Curacao)
Token ID On-chain identifier for the ERC-1155 outcome token. Example: 336
Order ID (oid) Server-assigned monotonic integer (as a string) for a submitted order
Client Order ID Caller-generated 34-character hex (0x + 32 hex chars) for idempotency and client-side tracking
YES / NO outcomes Each binary prediction market has two outcome tokens; their prices sum (approximately) to 1.0
TIF Time-in-Force; controls order lifetime. See §12
Maker / Taker Maker rests liquidity on the book; taker removes liquidity. Different fee tiers apply
Points The native points-denominated settlement unit
Worst price Simulated protection price for market orders; ensures execution does not exceed
Agent signing EIP-712 signing wrapper that wraps the msgpack-encoded action under a synthetic struct type