okx-outcomes

OKX Outcomes CLI

外部のokx-outcomesバイナリ（旧称 OKX Prediction Markets／okx-predict）をokx outcomes <command>としてラップした、バイナリーアウトカム（YES／NO）のイベントコントラクト取引です。

事前確認

1. ../_shared/preflight.mdのステップ 1 のみを実行します（メイン CLI の自動アップグレード）。ステップ 2 と 3（OAuth／API キーの検出、バージョンの不一致）は適用されません。Outcomes 市場では独立した認証情報を使用します。
2. okx-outcomesバイナリにアクセスできることを確認します。

   okx outcomes status
   

   Error: okx-outcomes binary not found in PATHが表示された場合は、先にインストールしてください（「前提条件」を参照）。

前提条件

# 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

設定は~/.okx-outcomes/config.json（機密情報以外）と OS のキーチェーン（機密情報。フォールバックとして暗号化された~/.okx-outcomes/keyring.enc）に保存されます。.envの自動読み込みはありません。PREDICTIONS_*環境変数が設定されている場合、保存済みの値を上書きする場合にのみ使用されます。

環境変数（任意の上書き）

変数	用途	備考
PREDICTIONS_AGENT_PRIVATE_KEY	オンチェーン書き込み（clob create-order／cancel／ctf *）	secp256k1 の 16 進数文字列です。通常はokx outcomes setupで生成され、キーチェーンに保存されます。この環境変数はその値を上書きする場合にのみ使用されます。絶対に共有したり、表示したりしないでください。
PREDICTIONS_API_BASE	REST ホストの上書き	デフォルトでは、セットアップ時に選択したリージョンが使用されます
OKX_OUTCOMES_BIN	バイナリパスの上書き	ローカル開発ビルドに便利です

セキュリティ：チャットで署名用秘密鍵を受け取らないでください。ウォレットはokx outcomes setup／setup bindで作成され、キーチェーンに保存されます。ユーザーが鍵を貼り付けた場合は受け取りを拒否し、失効またはローテーションするよう伝えてください。

命名に関する注記：製品名が OKX Outcomes に変更された後も、環境変数には引き続きPREDICTIONS_*のプレフィックスが使用されています（上流の旧命名規則）。

認証方法

Outcomes 市場では、認証が必要な読み取りに OKX のOAuth サインインを、オンチェーン書き込みにEIP-712 署名鍵を使用します。これらはメインのokx CLI の OAuth／API キー認証フローとは無関係です。Outcomes の操作でokx auth loginを実行しないでください。Outcomes には専用のokx outcomes auth loginがあります。

操作の種類	コマンドの例	認証情報
公開データ	data events/event/market/ticker/candles、clob price/prices/midpoint/spread/book/books	なし
認証が必要な読み取り	account balance/order/orders/positions/trades（決済済みの場合はpositions --status closed）、search、status	OAuth セッション（okx outcomes auth login）
オンチェーン書き込み	clob create-order / market-order / cancel-oid / cancel-all / heartbeat、ctf split / merge / redeem、wallet show	署名鍵（キーチェーンのagent_private_key、またはPREDICTIONS_AGENT_PRIVATE_KEY）

セットアップとオンボーディング

セットアップはすべてエージェントから完了できます。ターミナルは不要です。ユーザーが操作するのはブラウザーだけです（URL を開いてコードを入力し、バインド用の短縮リンクを開きます。このリンクを開くと、スマートフォンでは OKX アプリが起動し、それ以外のブラウザーではウェブ版が開きます）。コマンドはすべてエージェントが実行します。

初回セットアップは、依存関係の順に次の3 つの手順で構成されます。（1）地域、（2）OAuth サインイン、（3）EOA ウォレットのバインド。進行状況は次のように確認します。

okx outcomes setup status --json
# → { "region": {...}, "oauth": {...}, "eoa_binding": {...}, "next_step": "...", "complete": false }

その後、next_step に進みます。

1. 地域 — okx outcomes setup region <global|us>（非対話形式。エージェントが実行します）。

2. OAuth サインイン（デバイスコード） — okx outcomes auth login --manual --json。このコマンドは {verificationUri, userCode, expiresIn} を含む 1 行のデータを出力してただちに終了します（処理をブロックせず、標準入力も読み取りません）。次の内容をユーザーに伝えます。「任意のデバイスで <verificationUri> を開き、コード <userCode> を入力してください（有効期限は約 N 分です）。」 ブラウザーでの認証後、okx outcomes auth refresh --json で確認します（成功するとセッションマーカーが書き込まれます）。バックオフを入れて数回ポーリングするか、ユーザーが完了したと伝えてから 1 回実行します。

3. ウォレットのバインド — okx outcomes setup bind --json（エージェントが実行します）。署名用ウォレットを生成し、ウォレットの address と、https://okx.com/ul/3OauBX?eoa=<eoa>&uid=<uid> の形式の短縮リンク（JSON 出力の deeplink フィールド）を出力します（eoa には新しいウォレットの公開アドレス、uid にはサインイン済みアカウント ID が CLI によって設定されます）。短縮リンクはそのまま表示してください（短縮したり、折り返したりしないでください）。また、次の 3 点をユーザーに伝えてください。（a）スマートフォンでリンクをタップすると OKX アプリが起動し、バインドを承認できます。（b）リンクは任意のブラウザーにコピーして開くこともできます。（c）リンクを開けない場合は、上に表示されたウォレットの address をコピーし、OKX アプリで手動でバインドしてください：Outcomes → Profile → Settings → API Bind Wallet。ウォレットをローテーションせずに再表示するには setup bind --keep を使用します（通常の setup bind は毎回新しいウォレットを生成します）。

   表示用テンプレート — 次の内容をそのまま伝えます（中国語）。

   我刚为你新生成了一个签名钱包(私钥保存在本地 keyring,永远不会展示)。
   请在手机上打开下面的短链接,在 OKX App 中批准绑定这个新钱包:
   
   新钱包地址:<address>
   绑定短链:<short link>
   
   (也可以把短链复制到浏览器打开。如果打不开,请复制上面的新钱包地址,
    在 OKX App 里手动绑定:Outcomes → Profile → Settings → API 绑定钱包,
    把钱包地址粘贴进去。)
   
   ⚠️ 关于这个钱包:
   • 它只用来给你的交易做签名授权,不是一个充值钱包。
   • 不要往这个地址转任何币 —— 余额在你的 OKX 账户里,转到这个地址的资金无法使用、大概率找不回。
   • 地址可以公开(用于绑定),但它背后的私钥永远不要外泄。
   
   在 App 中批准后告诉我。
   

   英語版：

   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.
   

   address は公開情報なので、表示しても問題ありません。署名鍵はローカルのキーチェーンから外に出ることはありません。

各手順の後に setup status --json を再実行し、complete: true になったら okx outcomes status を実行します。

非 TTY／エージェント環境

okx outcomes ラッパーは継承した標準入出力を使ってバイナリを起動するため、エージェントが取得する標準出力に各コマンドの出力が届きます。セットアップの各手順のコマンドはすべてエージェントが実行できます。

• ✅ エージェントが直接実行：setup status、setup region、auth login --manual --json、auth refresh、auth status、setup bind（バインド用の短縮リンクをユーザーに伝えます。ユーザーはスマートフォンで開くか、ブラウザーに貼り付けます）。
• 🙋 ユーザーの操作はブラウザー／スマートフォンのみ（コマンドの実行は不要）：ブラウザーでデバイスコードの URL を開いて認証する。バインド用の短縮リンクを開く（スマートフォンでタップ → OKX アプリが起動するか、ブラウザーに貼り付ける）。リンクを開けない場合は、ウォレットのアドレスをコピーし、OKX アプリで手動でバインドする。
• 🚫 エージェントから起動しないでください：対話型の okx outcomes setup ウィザード全体と okx outcomes shell REPL は、どちらもターミナルからの直接入力を使用するため、TTY がないとハングするか EOF エラーになります。代わりに上記の各手順のサブコマンドを使用してください。

通常の okx outcomes auth login（--manual なし）は、実際のターミナルを使うユーザー向けの対話型／ブラウザー前面表示版です。エージェントは必ず --manual を使用してください。

スキルの振り分け

• YES/NO イベント契約のアウトカム市場 → このスキル
• OKX CEX の Up/Down イベント契約（別のプロダクト）→ okx-cex-trade（okx event ... を使用）
• 暗号資産の現物／スワップ／先物／オプション → okx-cex-trade
• 暗号資産の市場データ（BTC／ETH などの価格、ローソク足）→ okx-cex-market
• CEX ポートフォリオ → okx-cex-portfolio

クイックスタート

# 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

フラグの配置： フラグはサブコマンドの後（okx outcomes events --json）、またはモジュールの前（okx --json outcomes events）に置きます。モジュールとサブコマンドの間にフラグを挟む形式の okx outcomes --json events はサポートされていません。

コマンド一覧

読み取りコマンド（ゲーティングなし）

#	コマンド	認証	説明
1	okx outcomes data events [--status active] [--category <c>] [--limit <n>]	なし	アウトカムイベントの一覧
2	okx outcomes data event <eventId>	なし	単一イベントの詳細
3	okx outcomes data event-markets <eventId>	なし	イベントとその全マーケット（YES/NO のアセット ID を含む）
4	okx outcomes data market <marketId>	なし	単一マーケットの詳細
5	okx outcomes data trending	なし	トレンドのイベント
6	okx outcomes data ticker <assetId>	なし	1 つのアウトカムアセットの 24 時間ティッカー
7	okx outcomes data candles <assetId> [--bar 1H] [--limit 100]	なし	OHLCV ローソク足
8	okx outcomes search <keyword>	OAuth	キーワード検索
9	okx outcomes clob price --asset <id> [--outcome yes|no]	なし	主要価格（最終価格／買値／売値／中央値／スプレッド）
10	okx outcomes clob prices <id1> <id2> ...	なし	一括価格表示
11	okx outcomes clob midpoint --asset <id> / clob midpoints <ids...>	なし	（買値＋売値）/2
12	okx outcomes clob spread --asset <id> / clob spreads <ids...>	なし	買値／売値のスプレッド
13	okx outcomes clob book --asset <id> [--sz <n>] / clob books <ids...>	なし	複数レベルの板情報（デフォルト sz=10、最大 400）
14	okx outcomes account balance	OAuth	アカウント残高
15	okx outcomes account order <orderId>	OAuth	単一注文の詳細
16	okx outcomes account orders	OAuth	未約定注文
17	okx outcomes account positions	OAuth	保有ポジション（status="Won" → 償還）
18	okx outcomes account positions --status closed	OAuth	決済済みポジションと実現損益
19	okx outcomes account trades	OAuth	取引履歴
20	okx outcomes wallet show	signing	派生ウォレットアドレス
21	okx outcomes status	OAuth	ヘルスチェック
22	okx outcomes auth status [--json]	なし	OAuth セッションの状態
23	okx outcomes setup status [--json]	なし	オンボーディングの進捗（地域／OAuth／バインド）

セットアップ／認証コマンド

コマンド	認証	説明	エージェントから実行可能？
okx outcomes setup region <global|us>	なし	地域を設定（ステップ 1）	✅ はい
okx outcomes auth login --manual --json	なし	OAuth デバイスコード（ステップ 2）：{verificationUri,userCode,expiresIn} を出力して終了します	✅ はい（URL とコードをユーザーに中継）
okx outcomes auth refresh [--json]	なし	ユーザーによる認証後にセッションを検証／更新します（セッションマーカーを書き込みます）	✅ はい
okx outcomes setup bind [--keep] --json	signing	EOA ウォレットをバインド（ステップ 3）：アドレスと短縮リンク（deeplink フィールド、https://okx.com/ul/3OauBX?eoa=…&uid=…）を出力します。--keep を指定すると既存のウォレットを再利用します	✅ はい（ユーザーが短縮リンクを開くか、アドレスをコピーして手動でバインド）
okx outcomes auth login --site <global|us>	なし	対話型／ブラウザー前面でのサインイン（実際の端末を操作するユーザー向け）	🚫 TTY が必要です
okx outcomes setup / okx outcomes shell	—	対話型ウィザード／REPL 全体	🚫 TTY が必要です

書き込みコマンド（ドライランでのプレビューとユーザーの確認が必須）

#	コマンド	リスク
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]	高
25	okx outcomes clob market-order --asset <id> --side buy|sell --size [--tif ioc|fok] [--size-type base|quote]	高（即時に反対注文と約定）
26	okx outcomes clob cancel-oid --oid <id> --asset <id>	中
27	okx outcomes clob cancel-all	高
28	okx outcomes clob heartbeat	中（5分間のデッドマントリガーで自動的に全注文をキャンセル）
29	okx outcomes ctf split --market <id> --amount <xp>	高（xpをロック）
30	okx outcomes ctf merge --market <id> --amount <xp>	高
31	okx outcomes ctf redeem --market <id>	高（勝ち残高を全額消却）

エイリアス：clob order/orders/trades は、対応する account * コマンドに処理を委譲します。わかりやすさを優先し、スキルの出力では account * を使用してください。

操作フロー

ステップ 0 — バイナリの確認

okx outcomes status --json

• ラッパーが「okx-outcomes binary not found」と出力した場合は、停止し、curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh でインストールするようユーザーに伝えてください。
• status が認証エラーを返した場合、ユーザーはサインインしていません。okx outcomes auth status --json を確認し、「セットアップとオンボーディング」（auth login）の手順を案内してください。

ステップ 1 — 要求内容の判断

• 公開データ → コマンドを直接実行します。
• 認証が必要な読み取り → ユーザーがサインインしていることを確認します（okx outcomes auth status --json）。サインインしていない場合は「セットアップとオンボーディング」に案内してください。
• オンチェーンへの書き込み → ステップ 2 のドライランに進みます。

ステップ 2 — 書き込み前のドライランプレビュー（必須）

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.

概要に含める項目：

• マーケット名 — okx outcomes data market <marketId> で取得します（アセットの親マーケットから marketId を調べます）
• アセットと結果 — event-markets <eventId> の数値の assetId と、それが表す結果（YES ／ NO）
• 名目額 — price * size（xp）
• ウォレット — okx outcomes wallet show --json
• 利用可能残高 — okx outcomes account balance --json の oddsType="spots" の行にある available フィールド

ユーザーが confirm と返信した後に限り、実際のコマンドを実行してください。それ以外の場合（無応答も含む）は中止してください。

ステップ 3 — 実行と検証

実行後、直ちに状態を確認してください。

okx outcomes account orders --json    # confirm order placed / cancelled
okx outcomes account positions --json # confirm position change (for ctf)

結果の注文 ID ／トランザクションハッシュをユーザーに報告してください。

CLI コマンドリファレンス

コマンドグループごとの詳細なパラメーター表と例：

• references/setup-auth.md — セットアップ状況／地域／バインド、認証ログイン／更新／状態、設定とキーリングの保存、非TTYでのルール
• references/data-commands.md — イベント／イベント詳細／マーケット／トレンド／ティッカー／ローソク足／検索
• references/account-commands.md — アカウント残高／注文／ポジション／取引
• references/clob-commands.md — clobの価格／注文／注文一覧／取引／注文作成／キャンセル／全キャンセル／ハートビート
• references/ctf-commands.md — ctfの分割／統合／償還
• references/workflows.md — 初回セットアップ／日次概要／イベントの詳細分析／ポートフォリオ確認／安全な注文／決着後の償還

MCP ツールリファレンス

このモジュールは、現在のリリースでは MCP ツールを公開していません。エージェントは Bash 経由で okx outcomes <command> を直接実行します。今後、outcomes チームが独立して MCP サーバーを提供する可能性があります。

エッジケース

• okx-outcomes が PATH にない：ラッパーはインストール方法を表示して、終了コード 127 で終了します。curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh を実行するようユーザーに伝えてください。
• 署名用ウォレットがない：clob create-order／market-order／ctf * はすべて失敗します。okx outcomes setup bind --json を実行し（エージェントから実行可能）、短縮リンク（deeplink フィールド、https://okx.com/ul/3OauBX?eoa=…&uid=…）をユーザーに伝えて、開いてもらってください（スマートフォンでタップして OKX アプリを開くか、ブラウザーにコピーします）。リンクを開けない場合は、ウォレットアドレスをコピーして OKX アプリで手動でバインドしてもらってください（Outcomes → Profile → Settings → API Bind Wallet）。チャットでキーを尋ねてはいけません。
• アセット ID とマーケット ID の取り違え：最もよくあるエラーです。clob price/book/create-order/market-order では assetId が必要です。ctf * と account trades --market では marketId が必要です。判断に迷ったら、まず event-markets <eventId> を実行してください。出力には両方が一覧表示されます。
• --expiry なしの --tif gtd：クライアント側で拒否されます。両方を指定するか、gtc をデフォルトとして使用してください。
• buy + ioc 以外での --size-type quote：クライアント側で拒否されます（create-order）。「N ポイント分を使う」構文には buy + IOC が必要であることを、あらかじめユーザーに伝えてください。
• スナップショットにより FOK が拒否される場合：表示されている板の厚みが不十分な場合、clob market-order --tif fok はクライアント側で拒否され、署名済みメッセージは送信されません。拒否されたことを伝え、--size を減らすか --tif ioc を使うよう提案してください。
• モードの混同：Outcomes マーケットには、デモ／ライブを切り替えるフラグはありません。サイトは登録時に選択されます。ユーザーがどのデプロイメント（メインネットかテストネットか）を利用しているか確認してください。okx outcomes status で確認できます。

全般的な注意事項

• 他のツールに渡す場合や要約する場合は、必ず --json を指定してください。ユーザーがグローバルに --json モードを有効にしている場合、ラッパーは自動的に --json を追加します。
• 値の単位：Outcomes マーケットで取引されるのは USDC ではなく**ポイント（xp）**です。すべての残高、価格（[0,1] の範囲の小数）、想定元本、CTF 額の単位は xp です。
• 秘密鍵の取り扱い：PREDICTIONS_AGENT_PRIVATE_KEY（または 0x の後に 64 桁の 16 進数が続く文字列）をチャットに絶対に出力しないでください。言及が必要な場合は 0x**** のようにマスクしてください。メモリに書き込まないでください。
• サイドは小文字：書き込みコマンドでは --side buy／--side sell を指定します。account trades --side では BUY／SELL（大文字）を受け付けます。これは上流の仕様の不統一です。各コマンドのシグネチャに従ってください。
• レート制限：認証済みエンドポイントには OKX スタイルのスロットリングが適用されます。429／レート制限エラーが発生した場合は、バックオフして、指定された待機時間の後に再試行してください。
• ラッパーは透過的です：okx outcomes <cmd> はすべて、そのまま okx-outcomes に転送されます。バイナリーの正式なドキュメントについては、okx/outcomes-cli docs/cli-reference.md を参照してください。
• OKX_OUTCOMES_BIN 環境変数を使ってバイナリーのパスを上書きできます（cargo build --release でビルドした成果物を使ったローカル開発に便利です）。