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

PREDICTIONS_AGENT_PRIVATE_KEY

okx outcomes setup

PREDICTIONS_API_BASE

OKX_OUTCOMES_BIN

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.

okx outcomes

• ✅ 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

.

• 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

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>

Aliases:

clob order/orders/trades

delegate to the corresponding

account *

commands. Prefer

account *

in skill output for clarity.

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

  ).

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

clob create-order

clob market-order

clob cancel-*

clob cancel-all

ctf *

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.

• 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

confirm

• 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

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

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