A command-line client for OKX Outcomes. Browse events and markets, place CLOB orders, subscribe to real-time WebSocket streams, and run a full-screen trading terminal, all from your shell.
Distributed via GitHub.
Pre-built binary (macOS / Linux):
curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | shThis pulls the latest binary from the GitHub Releases page and puts it on your $PATH. On Windows, download the .zip from the Releases page directly.
Build from source (needs a Rust toolchain):
git clone https://github.com/okx/outcomes-cli
cd outcomes-cli
cargo install --path .
okx-outcomes --helpTwo things must be in place before the CLI is useful:
- OKX mobile app with a registered account — for OAuth sign-in and for binding the generated EOA address to your OKX account (the binding flow lives in the app). Download: https://www.okx.com/download
- Rust 1.90+ if and only if you're building from source (
cargo install/ build from source). The pre-built binary download needs no Rust toolchain.
Run the wizard from a terminal in the directory where you want to keep your config:
okx-outcomes setupThe wizard:
- Pick a region — Global / US. Selects the OAuth sign-in site, WebSocket host, and clientOrderId region tag.
- OAuth sign-in via the bundled
okx-authtoken broker. This is the only account-authentication step — there's no separate API key prompt. If sign-in fails (offline, broker missing, cancelled) the wizard continues and you can runokx-outcomes auth loginlater. - Auto-generate a signing wallet with
alloy-signer-local. The 64-hex private key is not displayed — it's stored only in the OS keyring. The derived EOA address (the value you'll bind to your OKX account) is shown. - Scan to bind — a QR code rendered in the terminal encodes an
okx://exchange/miniapp?…&eoa=…deeplink. Scan with the OKX app to bind the generated address to your account. The deeplink is also printed in plain text for headless / SSH use. - 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 logoutwipes everything.
⚠️ About the signing key — read this once. The generated key has exactly one purpose: signing your trade authorizations (EIP-712). It is not a funding wallet.
- Never share or expose the private key. Anyone who has it can sign orders as you. The CLI never displays it and never needs you to type it back — if a tool, page, or person asks you to paste it, that's a scam.
- Never send crypto or tokens to the derived EOA address. Your trading balance lives in your OKX account, not at this on-chain address. Funds sent to the EOA sit there unused and are likely unrecoverable. To add balance, top up your OKX account through the app — not this address.
- The address is only an identity bound to your OKX account so the backend can verify your signatures. Sharing the address (not the key) is harmless — it's public, like an account number.
- Binding is one-to-one. Each OKX account binds exactly one wallet, and each wallet (EOA address) binds to exactly one OKX account — you cannot bind one wallet to multiple accounts, nor multiple wallets to one account. Binding a new wallet to an account replaces the previous binding (which is why re-running
setupinvalidates the old one).
Re-running setup replaces the wallet. Every run generates a fresh signing key; if one is already stored the wizard prints a yellow warning with the current address before overwriting. The old EOA binding becomes invalid, and you need to scan the new QR to re-bind. There is no menu, no [k]eep, no import path, no private-key backup export — the signing key lives only in the OS keyring (encrypted-file fallback at ~/.okx-outcomes/keyring.enc).
This repository also ships two skills that let an AI coding assistant drive the CLI for you in plain language:
okx-outcomes-market— read-only: events, market data, candles, CLOB quotes / book, public WebSocket streams. No signing key.okx-outcomes-trade— account state (OAuth reads), EIP-712 signed writes (orders / cancels / heartbeat / CTF split / merge / redeem), private WebSocket channels, setup wizard, TUI terminal.
Both shell out to the okx-outcomes binary, so install the CLI (see Installation) and run okx-outcomes setup (see First-time setup) first — those are prerequisites for the skills to work.
/plugin marketplace add okx/outcomes-cli
/plugin install okxoutcomes@okxoutcomes
The first line registers this repo as a plugin marketplace. No central marketplace publishing is required — Claude Code's marketplaces are decentralized, so /plugin marketplace add accepts a GitHub owner/repo and reads .claude-plugin/marketplace.json straight from the repo (it just needs to be accessible; public is easiest). The second line installs the okxoutcomes plugin (both skills); the @okxoutcomes part is the marketplace name from that manifest, not the repo name. Once installed, just ask in natural language — e.g. "list trending outcomes events" routes to the market skill.
git clone https://github.com/okx/outcomes-cli.git ~/.codex/outcomes-cli
mkdir -p ~/.agents/skills
ln -sfn ~/.codex/outcomes-cli/skills ~/.agents/skills/outcomes
# restart Codex so it discovers the new skillsWindows (mklink), updating, verifying, and uninstall steps are in .codex/INSTALL.md.
Safety. Every write operation in the trade skill goes through a dry-run + exact
confirm <action>two-step protocol, and the skills never echo your signing key (agent_private_key).
The wizard saves two kinds of state on success — an OAuth session (managed by okx-auth) and the locally-generated EIP-712 signing key:
| Credential | Source | Used for |
|---|---|---|
| OAuth access token | okx-auth login (run by setup) |
REST account / trading endpoints and private WebSocket channels — covers account, clob, ctf, and authenticated data calls. When you're not signed in, a live HMAC key from ~/.okx/config.toml is used instead (see the note below). |
agent_private_key |
Generated by setup (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. It sits in the OS keyring by default; on Linux (or when Keychain / Credential Manager rejects writes) it goes to ~/.okx-outcomes/keyring.enc, encrypted with a 32-byte machine-bound identity at ~/.okx-outcomes/machine-identity (mode 0600).
Account auth is OAuth-first, with an HMAC fallback. Sign in with
okx-outcomes auth login; the OAuth bearer covers both REST account/trading endpoints and private WebSocket channels. If no OAuth session is available, the CLI falls back to a live (non-demo) HMAC API key read from the shared OKX config at~/.okx/config.toml(theprofilestable written by the agent-trade-kit CLI) — it's region-scoped and used for both REST calls and the private-WSloginframe. There are noPREDICTIONS_API_*env vars or--flagoverrides for credentials (those were removed); that shared config file is the only API-key source. You only need one of the two — a completedokx-outcomes auth loginis sufficient on its own (no need to also put API keys in~/.okx/config.toml), and a configured API key there is sufficient if you haven't signed in. You never need both.
What the file fallback does and does not protect. The
keyring.encencryption key is derived from a random per-machine identity stored right beside it inmachine-identity, so the protection is narrow: it helps only ifkeyring.encleaks on its own, without that identity file — a backup or copy that grabbed just the single file. It gives you nothing once the whole~/.okx-outcomes/directory is copied, synced, or backed up together, because the key material travels with it. And it does not defend against an attacker who can already read your home directory — unattended decryption needs the key locally recoverable, so it sits next to the ciphertext by necessity. For real protection rely on the OS keyring (the default).
Each section below has a handful of examples to get you productive in 90 seconds. The full subcommand reference lives in docs/cli-reference.md.
Output is colored, paginated, and human-readable by default. Add --json (or -j) to any command for machine-readable output:
okx-outcomes account balance # pretty cards
okx-outcomes account balance --json | jq # JSON pipelineokx-outcomes data trending # hot events right now
okx-outcomes data events --status active --limit 20
okx-outcomes data event 17301090139211776 # one event + its markets
okx-outcomes data market 101664 # one market + order book preview
okx-outcomes data candles 101664000 --bar 1H
okx-outcomes search "world cup" # full-text searchokx-outcomes account balance # one row per odds type (points)
okx-outcomes account orders # open orders
okx-outcomes account positions # open positions (default)
okx-outcomes account positions --status closed # historical positions
okx-outcomes account trades --limit 50 # recent fillsAll of the above accept --cursor <c> for pagination.
Order writes are signed locally with the EIP-712 signing key (agent_private_key, stored in the keyring) and submitted via the OKX REST API.
Warning:
clob create-order,clob cancel-*,clob heartbeat, andctf split/merge/redeemare signed write operations that take effect immediately. AI assistant skills add their own dry-run + exact-confirmation protocol; the raw CLI examples below do not prompt again.
# Place a limit order. --asset is the asset_id of the YES or NO outcome.
okx-outcomes clob create-order \
--asset 101664000 --side buy --price 0.65 --size 100 --tif gtc
# Cancel by server-assigned order id
okx-outcomes clob cancel-oid --oid <ORDER_ID> --asset 101664000
# Cancel everything across all your markets
okx-outcomes clob cancel-all
# Renew the dead-man's switch protecting your active orders.
# Call this more often than every 5 minutes; if heartbeats stop, the server
# auto-cancels all your active orders.
okx-outcomes clob heartbeat
# Inspect a recent order or fills
okx-outcomes clob order <ORDER_ID>
okx-outcomes clob tradesSupported --tif values: gtc, gtd (requires --expiry <unix-ms>), ioc, fok, alo.
okx-outcomes ctf split --market 101664 --amount <PTS> # PTS -> YES + NO
okx-outcomes ctf merge --market 101664 --amount <SIZE> # YES + NO -> pts
okx-outcomes ctf redeem --market 101664 # redeem winnings after settlementPublic channels need no authentication. Pass one or more inst IDs as positional arguments.
okx-outcomes ws prices 101664000
okx-outcomes ws books 101664000
okx-outcomes ws trades 101664000
okx-outcomes ws tickers 101664000
okx-outcomes ws event-status 17301090139211776
okx-outcomes ws candle1H 101664000 # any candle bar size: candle1m, candle5m, candle1H, ...Private channels need account auth. The preferred path is a signed-in OAuth session (set up by setup's built-in auth login step, or by running okx-outcomes auth login standalone): the OAuth bearer is attached on the WS handshake (Authorization: Bearer). If you're not signed in, the CLI falls back to sending an HMAC login frame using the live API key from ~/.okx/config.toml.
okx-outcomes ws orders # your order updates (pm-order)
okx-outcomes ws positions # your position changes (pm-position)
okx-outcomes ws balance # your balance changes (pm-balance)
okx-outcomes ws user-trades # your fills (pm-user-trade)
okx-outcomes ws pnl # floating P&L (pm-pnl)
okx-outcomes ws private # subscribe to all five at onceokx-outcomes ws terminal # ratatui trading terminal with Quick Trade
okx-outcomes shell # interactive REPL across all subcommandsThere are no PREDICTIONS_* env vars. Configuration lives in two places, both written by setup:
- Non-secret config (REST host / WS host / region / env tag / mode / lang / timeout) —
~/.okx-outcomes/config.json, written byokx-outcomes setuporokx-outcomes setup region <us|global>. - Secrets — the OAuth session (managed by the bundled
okx-authbroker) and the EIP-712 signing key (agent_private_key) in the OS keyring.
The only environment variables the CLI reads are operational:
| Variable | Purpose |
|---|---|
OKX_OUTCOMES_HOME |
Override the config / keyring directory (default ~/.okx-outcomes). |
OKX_AUTH_BIN |
Path to the bundled okx-auth token broker binary. |
OKX_OAUTH_CONFIG |
Path to the OAuth broker config. |
OUTCOMES_DEBUG |
Set to 1 to log HTTP + WS request/response details to stderr (debug builds only). |
OKX_THEME |
Color theme: auto (default) / light / dark. The --theme flag overrides it. |
okx-outcomes status— full health check: REST reachability, auth, balance, time sync.
If setup ran but commands still fail with not authenticated, run okx-outcomes logout and re-run setup to refresh the keyring entry. On macOS this re-prompts for Keychain access — pick "Always Allow". Check ~/.okx-outcomes/ exists with mode 0700 and contains machine-identity + (optionally) keyring.enc.
- Source: https://github.com/okx/outcomes-cli
- Full command reference: docs/cli-reference.md
- Rust SDK (library): https://github.com/okx/outcomes-sdk
- File an issue: https://github.com/okx/outcomes-cli/issues
After cloning, activate the project's git hooks once so cargo fmt --check runs before every commit:
git config core.hooksPath .githooksCI runs the same cargo fmt --check and will reject unformatted code, so this just catches it earlier.
Open-source software licensed under the MIT license.