okx-outcomes-setup

okx-outcomes-setup — Onboarding (IM-friendly)

Gets a user from "nothing configured" to "ready to trade" over an IM / chat channel. Once the okx-outcomes binary is installed, the agent can drive the entire onboarding from chat — the user never needs to open a terminal. The remaining out-of-band steps are: opening one link in a browser (OAuth, on any device) and approving one deeplink/QR in the OKX mobile app (EOA binding). The skill:

1. Detects which of the three pieces is incomplete.
2. Tells the user the single next piece to complete and how.
3. Re-checks state after they say they're done, then advances.

Introduce the CLI first

On the user's first onboarding turn, briefly say what they're setting up and how it'll go from here. Something like:

OKX Outcomes is OKX's outcome-market product, and okx-outcomes is its command-line tool for browsing events, checking your account, and placing / managing orders. Before any of that, your account needs a one-time setup: choose a region, sign in with OKX, and bind your wallet. I'll walk you through it here — you'll just open one link in a browser (sign-in) and approve one deeplink in the OKX mobile app (wallet binding). No terminal commands on your end.

Then continue with the detection + step flow below. Power users who prefer a single end-to-end command can run the interactive wizard (okx-outcomes setup) in their own terminal as a fallback — but do not push this option proactively; only mention it if the user explicitly asks for "the one-shot command" or says they prefer terminal-only flows. Either way, still re-check each piece via the state probe afterward to confirm it's done.

0. The three pieces (hard order)

Region must be set first; the other two depend on it.

#	Piece	Why it depends on region	Who completes it
1	Region (US or Global)	Selects REST host (us.okx.com vs www.okx.com), WS host, OAuth --site, and clientOrderId tag.	Agent can do it — non-interactive, no secret.
2	OAuth sign-in	auth login --site <region> uses the region's site; account/private-WS auth flows from this token.	Agent + user, via --manual — agent calls the CLI, user opens the link in a browser on any device.
3	EOA wallet binding	The bind deeplink targets the region's account; binding ties the locally-generated signing wallet to the OKX account.	Agent + user, via OKX mobile app — agent fetches the deeplink with setup bind -j, user taps it on their phone to approve.

Never reorder these. If region isn't set, do region first even if the user asks about sign-in.

1. The IM-client contract

• One piece at a time. Report only the next incomplete piece; don't dump all three. After the user completes it, re-run the state check and move on.
• Secrets never transit the chat. Don't ask the user to paste an OAuth token, API key, or private key into the conversation — they get logged and retained. OAuth is a browser flow (no key to paste); the signing wallet is generated locally and never displayed.
• Out-of-band for browser / app steps. OAuth opens a browser on any device (the agent calls the CLI, the user just opens the link); binding is done in the OKX mobile app via a deeplink/QR. Surface the link / code / QR plainly, then wait for a "done" signal and verify by re-querying state — don't assume success. The user never needs to open a terminal for these.
• Region step and OAuth sign-in are agent-drivable. Region is a non-interactive command (no secret). OAuth uses the --manual device-code flow — agent calls the CLI, user opens the returned link on any device. Only EOA wallet binding still requires the OKX mobile app on the user's phone.

2. State detection — "what's left?"

Always start here. Target command (preferred):

okx-outcomes setup status -j

Expected shape (see references/setup-flow.md for the full contract):

{
  "region":      { "done": true,  "value": "us" },
  "oauth":       { "done": false },
  "eoa_binding": { "done": false, "address": "0x..." },
  "next_step":   "oauth",
  "complete":    false
}

Drive off next_step; stop when complete is true.

CLI support status: setup status, setup region, and setup bind are implemented. eoa_binding.done means a wallet is configured for binding, not a confirmed on-chain binding — confirm with the user that they approved it in the OKX app, and if a later signed order is rejected for binding, have them re-run setup bind. scripts/preflight.sh forwards setup status -j when present and falls back otherwise, so prefer it for detection:

bash skills/okx-outcomes-setup/scripts/preflight.sh | jq '{next_step, complete, steps}'

Fallbacks (older builds without setup status):

• region → read ~/.okx-outcomes/config.json region ("US" → US, "HK" → Global; anything else, incl. "EU", ⇒ not set). If that's absent, fall back to the broker's recorded site in ~/.okx/oauth/config.toml (us → US, global/hk → Global). (preflight does both.)
• oauth → the okx-auth broker is authoritative: okx-auth status --json → "status": "logged_in". okx-outcomes auth status -j → oauth_session_present now reflects that same broker session, so a sign-in done via okx-auth login directly is detected even though okx-outcomes' local marker was never written. status output carries no token (only site / TTL / scopes), so it's safe to read.
• eoa_binding → reflects whether a wallet is configured for binding; confirm the binding itself with the user.

3. Step 1 — Region (agent-drivable)

Detect: next_step == "region" (or config has no region).

1. Ask the user: US or Global? (one short question).
2. Set it — non-interactive, safe for the agent to run directly:

   okx-outcomes setup region us        # or: global
   

   (Older builds without this subcommand: have the user pick the region at the first prompt of the interactive okx-outcomes setup wizard instead.)
3. Verify: re-run the state check; confirm region.done == true with the right value.

US → us.okx.com + wss://wsus.okx.com; Global → www.okx.com + wss://ws.okx.com:8443. The choice is persisted to config.json.

4. Step 2 — OAuth sign-in (agent-led via --manual, browser on any device)

Detect: next_step == "oauth". Requires region already set. Pass the site matching the region (us → --site us, Global → --site global).

Preferred path — device-code (--manual), agent-led

The user only needs a browser on any device (phone / work laptop / their own machine) — not on the machine running the CLI. The agent drives the command; the user just opens a link and types a code.

1. Agent runs (the command exits on its own — do not background it with &):

   okx-outcomes auth login --manual --site <us|global> -j
   

   stdout contains a single line of JSON:

   {"verificationUri":"https://www.okx.com/account/device","userCode":"ABCD-1234","expiresIn":600}
   

   If instead it returns {"status":"skipped","reason":"...","..."}, treat that as a terminal broker message — relay the reason and stop. Do not retry.

2. Surface the URL and code in your assistant reply (not only the tool stdout panel — many IM/IDE chat clients hide it). Reply verbatim with this template (Chinese; substitute the four fields, do not abbreviate or re-translate):

   请在浏览器中打开下面的链接并输入验证码完成授权：
   
   站点：<site>
   链接：<verificationUri>
   验证码：<userCode>
   （有效期 <expiresIn/60> 分钟）
   
   通过链接完成授权，然后告诉我。
   

   English equivalent when the user is conversing in English:

   Please open the link below in your browser and enter the verification code:
   
   Site: <site>
   URL: <verificationUri>
   Code: <userCode>
   (Valid for <expiresIn/60> minutes)
   
   Authorize the session, then tell me when you're done.
   

   Echo verificationUri literally — do not rewrite the host (e.g. do not shorten okx.com/account/device to okx.com/device). The user code is not a secret but is phishable when paired with a wrong URL.

3. Wait for the user to signal completion ("done", "ok", "好了", "完成 了"). Do not auto-poll while waiting — the broker is rate-sensitive and the user-facing UX is "I authorize, then I tell you."

4. On the user's signal, run once:

   okx-outcomes auth refresh -j
   

   • exit 0 → token retrieved + OAuth marker written. Tell the user "登录成功，站点：" (Chinese) or "Login successful. Site: " (English), then proceed to Step 3 (eoa_binding).
   • non-zero / not_logged_in / RefreshFailed → authorization did not complete (or the user code expired). Ask whether to retry; on retry, restart from step 1 to generate a fresh code (the previous code is dead, no cleanup needed — the broker self-expires it).

Fallback path — user runs the interactive command

Use this when auth login --manual is unavailable (very old okx-auth broker; check by running step 1 once and confirming non-zero exit with a broker error like "unknown option --manual"). Older brokers can be upgraded by running okx auth install (from the okx-cex-auth skill / @okx_ai/okx-trade-cli).

1. Tell the user to run, in their own terminal:

   okx-outcomes auth login --site <us|global>
   

   This opens an OKX browser sign-in; the token is brokered by okx-auth and never displayed. Nothing is pasted into chat.
2. If the IM client can't give the user a terminal, this step has to happen on a device where they can run the CLI / complete the browser flow — surface that plainly.
3. Verify: re-run the state check; confirm oauth.done == true. The signal is the broker session — okx-auth status --json → "status": "logged_in" (also surfaced via okx-outcomes auth status -j → oauth_session_present). A user who already signed in directly with okx-auth login is recognized without re-running anything; if only the local marker is missing, okx-outcomes auth login --site <region> reconciles it, but the broker session itself is sufficient.

5. Step 3 — EOA wallet binding (agent-led, OKX mobile app)

Detect: next_step == "eoa_binding". Requires region + OAuth (the bind deeplink needs the account uid from the signed-in session).

Binding is a strict one-to-one relationship: each OKX account binds exactly one wallet, and each wallet (EOA address) binds to exactly one OKX account — never one wallet across multiple accounts, never multiple wallets on one account. Binding a new wallet replaces the prior binding, so don't re-run setup bind casually (it regenerates the wallet and forces a re-bind).

The user only needs the OKX mobile app on their phone. The agent fetches the deeplink; the user taps it (or pastes it into a chat client that opens it in the OKX app), approves the binding, and tells the agent. No terminal on the user's side.

1. A signing wallet is generated locally by the CLI (auto; the 64-hex key is never shown — stored in the OS keyring). Binding links that wallet's EOA address to the OKX account.

2. Agent runs:

   okx-outcomes setup bind -j
   

   stdout contains:

   {"address":"0x...","deeplink":"https://okx.com/ul/28G0qj?eoa=0x...&uid=...","deeplink_backup":"https://oyidl.net/ul/28G0qj?eoa=0x...&uid=...","wallet":"created"}
   

   Use -j (not the default plain output) — -j returns clean JSON the agent can parse, while the default output renders a terminal QR code that won't render reliably in IM/chat clients.

   ⚠ setup bind regenerates the signing wallet by default. Each invocation produces a fresh wallet ("wallet":"regenerated" when replacing, "created" on first run), which invalidates any prior EOA binding. Mirrors the okx-outcomes setup wizard's simplified flow — every onboarding produces a fresh wallet.

   Agent discipline:

   • Always call setup bind -j plain — no --keep. The skill flow treats EOA binding as "always start with a fresh wallet" to match wizard semantics. The user re-approves in the OKX app and the previous binding (if any) becomes obsolete.
   • Only call when next_step == "eoa_binding" (per setup status -j). Do not re-spawn setup bind -j to "verify" or "show the link again" — setup status -j answers verification, and re-spawning setup bind -j would generate yet another wallet and force yet another re-bind. If the user lost the previous link, tell them to scroll back to your earlier message.

   (--keep exists at the CLI level for power users who want to reuse a stored wallet — the skill flow does not use it.)

3. Surface the deeplink in your assistant reply (verbatim, do not shorten or wrap the URL). Chinese template:

   我刚为你新生成了一个签名钱包（私钥保存在本地 keyring，永远不会展示）。
   请在手机上打开下面的短链接，在 OKX App 中批准绑定这个新钱包：
   
   新钱包地址：<address>
   绑定链接：<deeplink>
   
   (也可以把短链接复制到浏览器打开。如果打不开，请在 OKX App 里手动绑定：
    Outcomes → Profile → Settings → API 绑定钱包，把上面的新钱包地址粘贴进去。)
   
   ⚠️ 如果之前绑过其它钱包，那个绑定会作废 —— 本次必须批准这个新地址才能下单。
   
   在 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 link:       <deeplink>
   
   (You can also paste the link into any browser. If it won't open,
    bind manually in the OKX app: Outcomes → Profile → Settings →
    API Bind Wallet, and paste the new wallet address above.)
   
   ⚠️ If you previously bound a different wallet, that binding is now
   void — you must approve this new address before you can place orders.
   
   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.

   Tell the user once, alongside the binding link (relay this — it prevents the two most common and costly mistakes):

   ⚠️ 关于这个钱包：
   • 它只用来给你的交易做签名授权，不是一个充值钱包。
   • 不要往这个地址转任何币 —— 余额在你的 OKX 账户里，转到这个地址的资金无法使用、大概率找不回。
   • 地址可以公开（用于绑定），但它背后的私钥永远不要外泄。
   

   English equivalent:

   ⚠️ 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.
   

4. Wait for the user to signal completion ("done", "已批准", "approved"). Do NOT auto-poll.

5. On the user's signal, verify:

   okx-outcomes setup status -j
   

   Check eoa_binding.done == true. This indicates a wallet is configured for binding, NOT a confirmed on-chain binding — ask the user to confirm they approved it in the OKX app. If a later signed order is rejected for binding, re-run setup bind -j and have them tap the deeplink again.

Fallback (rare): if setup bind -j is unavailable on the user's build (very old CLI), binding requires the interactive okx-outcomes setup wizard — route the user to their own terminal as a last resort. Don't push this proactively; only mention it if the agent-led path errors out with "unknown subcommand".

6. Done

When complete == true (region + oauth + binding all done), tell the user they're ready and hand off: trading → okx-outcomes-trade, market data → okx-outcomes-market. Quick smoke check: okx-outcomes status -j.

7. Pre-flight

command -v okx-outcomes || echo "NOT_INSTALLED"

Missing? This is the one and only step that requires the user to open a terminal — it can't be agent-driven. Tell the user clearly:

The okx-outcomes CLI isn't installed yet. This is the only step that needs a terminal on your end — once it's installed, the rest of setup (region, sign-in, wallet binding) all happens from here. Install via:

cargo install --locked --path .   # from a checkout of this repo

or grab the prebuilt binary if your team distributes one. Re-run this skill when done.

After install, run scripts/preflight.sh for the per-step state and continue from §3.

8. Edge cases

• Binary missing → install first; no setup step works without it.
• User asks to sign in but region unset → do region first (hard dependency), then sign-in.
• Re-running setup replaces the wallet → both okx-outcomes setup (wizard) and okx-outcomes setup bind -j (subcommand) regenerate the signing wallet on every invocation by default. The previous EOA binding becomes invalid and must be re-bound. Warn the user before any re-generate/re-bind; don't re-spawn setup bind -j casually (e.g. just to "re-show the link") — that produces another wallet and forces another re-bind. Ask the user to scroll back to the earlier link instead.
• Binding state unverifiable today → don't claim it's done from the CLI; confirm with the user and mark unverified until the CLI exposes a check.
• No terminal on the user's side → region and OAuth are both agent-driven now (OAuth via auth login --manual — user only needs a browser on any device, not a terminal). EOA binding still requires the OKX mobile app on the user's phone; say so rather than pretending.
• User code expired before they entered it → re-run okx-outcomes auth login --manual --site <X> -j to get a fresh code. The previous code is dead; no cleanup needed — the broker self-expires it. Don't blame the user; restart cleanly.
• auth refresh fails after user says "done" → don't assume the flow failed. First run okx-outcomes auth status -j and inspect the top-level oauth_session and the nested ready_for.account_read: if both are true, the session is fine and the refresh error was transient (the broker retains the session even when refresh stumbles). Only when oauth_session: false do you restart from auth login --manual. Do not loop auth refresh.

9. Resources

• references/setup-flow.md — per-step detail, the setup status JSON contract, the bind deeplink shape, and the current-vs-target CLI interface.
• scripts/preflight.sh — per-step state probe (prefers setup status -j, falls back to auth status -j + config.json), JSON output.