Okx Outcomes

SKILL.md

---
name: okx-outcomes
description: "Use this skill for OKX Outcomes markets (YES/NO event contracts, formerly OKX Predictions) via the okx-outcomes binary. Triggers: 'list prediction events', '预测市场', 'event detail', 'place prediction order', '预测下单', 'buy YES', 'buy NO', '撤单 预测', 'split xp', '拆分 xp', 'merge YES NO', '赎回 预测', 'prediction positions', '预测持仓', 'live prediction price', '预测行情', 'OHLCV candles', 'K线', 'CTF', 'polymarket'. Auth: OAuth sign-in via 'okx outcomes auth login'; writes need a signing key configured by 'okx outcomes setup'. Do NOT use for OKX CEX event contracts (use okx-cex-trade event), spot/swap/futures (okx-cex-trade), crypto market data (okx-cex-market), or CEX portfolio (okx-cex-portfolio). Namespace required: account: balance/positions/order/orders/trades; clob: price/prices/midpoint/midpoints/spread/spreads/book/books; data: events/event/event-markets/market/trending/ticker/candles; ctf: split/merge/redeem; wallet: show; auth: login/refresh/status; setup: status/region/bind."
license: MIT
metadata:
  author: okx
  version: "1.3.5"
  homepage: "https://www.okx.com"
  agent:
    requires:
      bins: ["okx", "okx-outcomes"]
    install:
      - id: npm-cli
        kind: node
        package: "@okx_ai/okx-trade-cli@1.3.5"
        bins: ["okx"]
        label: "Install okx CLI (npm)"
---

# 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`](../_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:
   ```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 | `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`:

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

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

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

| # | 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`](references/setup-auth.md) — setup status/region/bind, auth login/refresh/status, config & keyring storage, non-TTY rules
- [`references/data-commands.md`](references/data-commands.md) — events / event / market / trending / ticker / candles / search
- [`references/account-commands.md`](references/account-commands.md) — account balance / orders / positions / trades
- [`references/clob-commands.md`](references/clob-commands.md) — clob price / order / orders / trades / create-order / cancel / cancel-all / heartbeat
- [`references/ctf-commands.md`](references/ctf-commands.md) — ctf split / merge / redeem
- [`references/workflows.md`](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`](https://github.com/okx/outcomes-cli/blob/main/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).