okxoutcomes

okx-outcomes

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.

Installation

Distributed via GitHub.

Pre-built binary (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh

This 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 --help

Prerequisites

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

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

First-time setup

Run the wizard from a terminal in the directory where you want to keep your config:

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 bundled okx-auth token 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 run okx-outcomes auth login later.
3. 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.
4. 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.
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 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 setup invalidates 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).

Skills for AI assistants (Claude Code / Codex)

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.

Claude Code