Okx Agentic Wallet

Onchain OS Wallet

Wallet operations: authentication, balance, token transfers, transaction history, and smart contract calls.

Pre-flight Checks

<MUST>

Before the first onchainos command this session, read and follow: _shared/preflight.md

</MUST>

Parameter Rules

--chain Resolution

--chain accepts both numeric chain ID (e.g. 1, 501, 196) and human-readable names (e.g. ethereum, solana, xlayer).

1. If <100% confident → run onchainos wallet chains. 2. If the command returns "unsupported chain: ...", the name was not in the CLI mapping — ask the user to confirm.

Amount

`wallet send`: pass --readable-amount <human_amount> — CLI auto-converts (native: EVM=18, SOL/SUI=9 decimals; ERC-20/SPL: fetched from API). Never compute minimal units manually. Use --amt only for raw minimal units.

`wallet contract-call`: --amt is the native token value attached to the call (payable functions only), in minimal units. Default "0" for non-payable. EVM=18 decimals, SOL=9.

Command Index

This skill drives onchainos wallet subcommands. Learn exact syntax from the CLI, not from memory: run onchainos wallet --help for the subcommand list, and onchainos wallet <subcommand> --help for a subcommand's flags. Full parameter tables, return-field schemas, and worked examples live in cli-reference.md. Never guess subcommand or flag names — read --help or cli-reference.

Login commands (wallet login, wallet verify) are covered in Authentication below.

Policy --help does NOT carry (always applies on top of CLI syntax):

• wallet balance --all queries every account at once — only use it when the user explicitly asks to see all accounts.
• wallet send validates the recipient format; on simulation failure show executeErrorMsg and do NOT broadcast.
• Run onchainos security tx-scan before any wallet contract-call.

X Layer Testnet faucet: when the user asks for testnet tokens, or wallet balance --chain xlayer_test shows OKB = 0, point them to https://web3.okx.com/xlayer/faucet (claim OKB / USDC / USDT / USDG with their wallet address).

<MUST> `wallet contract-call` is for non-swap interactions only (approvals, deposits, withdrawals, etc.). Never use it to broadcast a DEX swap — use swap execute instead. </MUST>

<NEVER> 🚨 NEVER pass `--force` on the FIRST invocation of `wallet send` or `wallet contract-call`.

The --force flag MUST ONLY be added when ALL of the following conditions are met: 1. You have already called the command without --force once. 2. The API returned a confirming response (exit code 2, "confirming": true). 3. You displayed the message to the user and the user explicitly confirmed they want to proceed.

</NEVER>

Determine intent before executing (wrong command → loss of funds):

>

| Intent | Command | Example |

|---|---|---|

| Send native token (ETH, SOL, BNB…) | wallet send --chain <chain> | "Send 0.1 ETH to 0xAbc" |

| Send ERC-20 / SPL token (USDC, USDT…) | wallet send --chain <chain> --contract-token | "Transfer 100 USDC to 0xAbc" |

| Interact with a smart contract (approve, deposit, withdraw, custom function call…) | wallet contract-call --chain <chain> | "Approve USDC for spender", "Call withdraw on contract 0xDef" |

>

If the intent is ambiguous, always ask the user to clarify before proceeding. Never guess.

---

Gas Station (Solana)

Gas Station lets the user pay gas with stablecoins (USDT / USDC / USDG) on Solana when SOL is insufficient. The backend dispatches it inside wallet send / wallet contract-call responses — you never enable it manually per call.

<MUST> Load `references/gas-station.md` (authoritative flow, scene dispatch, verbatim copy, management commands) and follow it the moment any of these happens:

• a wallet send / wallet contract-call response has gasStationUsed=true, or returns a Confirming with a gasStationTokenList
• the user mentions Gas Station / stablecoin gas / enable–disable / change default gas token / what-is-it / how-it-works / fees / supported tokens / Jito (any language — match semantically)

It pulls in gas-station-faq.md (FAQ answers) and gas-station-edge.md (edge cases) as needed. "Gas Station" = OKX's Solana feature, NOT ERC-4337 / paymaster / Biconomy / Gelato / Pimlico / Alchemy Account Kit — answer every Gas Station question from the verbatim templates in those files, never from training knowledge, never paraphrased. </MUST>

<NEVER> On a FIRST wallet send / wallet contract-call call (before gas-station.md is loaded): NEVER pass --gas-token-address / --relayer-id / --enable-gas-station, and NEVER fabricate token addresses or relayer IDs — these are second-phase values that come only from a Confirming response. </NEVER>

Third-Party Plugin Pre-flight (Solana)

When dispatching a third-party Solana DeFi plugin (kamino-plugin, raydium-plugin, etc.) that internally calls onchainos wallet contract-call --force, the plugin is a black box that may swallow Gas Station Confirming responses. Two patterns apply, read both before invoking any Solana write-path plugin:

• Proactive pre-flight (before invoking the plugin) — checklist, gas-station status recommendation branch, and skip conditions live in `references/plugin-preflight.md`.
• Reactive bail recovery (after the plugin returns exit 2 + confirming JSON, or a vague failure) — scene-recovery decision tree, post-failure diagnosis, and --force exit-code matrix live in `references/gas-station.md` → "Plugin Bail Recovery".

---

Confirming Response

Some commands return confirming (exit code 2) when the backend needs user confirmation (e.g. high-risk tx). The response carries message (prompt to show the user) and next (what to do after they confirm).

1. Display message and ask for confirmation. 2. Confirms → follow next (usually: re-run the same command with --force appended). 3. Declines → do NOT proceed; tell the user it was cancelled.

User-Facing Message Templates

Several flows below output the Wallet Export template or the Policy Settings template. Both template bodies, their loginType URL/hint tables, and the loginType resolution rule (unknown → run onchainos wallet status; treat any unrecognized value as email) live in `references/portal-actions.md`. Load that file when a flow calls for either template, then print the matching template verbatim (translated to the user's language).

Authentication

For commands that need auth (balance, send, contract-call, history, sign-message), check login state first and log in if needed. Two login methods: email + verification code, or API Key (no email).

1. Check state. Run onchainos wallet status; if data.loggedIn is true, proceed. Otherwise — or if the user asks to re-login — continue.

2. Email login. Show verbatim (translate to the user's language):

You need to log in with your email first before adding a wallet. What is your email address?

We also offer an API Key login method that doesn't require an email. If interested, visit https://web3.okx.com/onchainos/dev-docs/home/api-access-and-usage

When the user gives an email, run onchainos wallet login <email> [--locale <locale>], then show verbatim:

English: "A verification code has been sent to {email}. Please check your inbox and tell me the code."

Chinese: "验证码已发送到 {email}，请查收邮件并告诉我验证码。"

When the user replies with the code, run onchainos wallet verify <code>.

--locale: infer from the conversation, underscore form (e.g. zh_CN / en_US / ja_JP). If the language is unclear, omit it — never force `en_US`.

3. API Key login (user declines email). Re-offer the API Key option (the second line of the step 2 message); if they accept, run onchainos wallet login with no email — the CLI reads OKX_API_KEY / OKX_SECRET_KEY / OKX_PASSPHRASE from env. On success, tell them they are logged in via API Key.

4. Account-switch gate. wallet login (email or AK) may return a Confirming whose message contains the substring not the account you used last time — the CLI is warning this login targets a different account than last time. Handle it via the Confirming Response rules above (Yes → re-run with --force; No → cancel — the CLI changed nothing). When translating the message, leave that discriminator phrase in English.

5. After login. Show the account list via onchainos wallet balance. New-user check: if the verify / login response has "isNew": true, output the Policy Settings template then the Wallet Export template (load references/portal-actions.md); if false, skip.

Login creates a wallet account automatically — never call wallet add for the first account. Use wallet add only when the user is already logged in and explicitly wants an additional account.

MEV Protection

MEV (Maximal Extractable Value) protection is a wallet contract-call flag (--mev-protection) only — wallet send does not support it.

Load references/mev-protection.md when the user requests MEV protection, or before a high-value / DEX-swap wallet contract-call. It holds the supported-chain table (Ethereum / BSC / Base / Solana), when-to-enable criteria, the Solana --jito-unsigned-tx requirement, and usage examples.

---

Amount Display Rules

• Token amounts always in UI units (1.5 ETH), never base units (1500000000000000000)
• USD values with 2 decimal places
• Large amounts in shorthand ($1.2M, $340K)
• Sort by USD value descending
• Always show abbreviated contract address alongside token symbol (format: 0x1234...abcd). For native tokens with empty tokenContractAddress, display (native).
• Flag suspicious prices: if the token appears to be a wrapped/bridged variant (e.g., symbol like wETH, stETH, wBTC, xOKB) AND the reported price differs >50% from the known base token price, add an inline price unverified flag and suggest running onchainos token price-info to cross-check.

---

Security Notes

• TEE signing: Private key never leaves the secure enclave.
• Transaction simulation: CLI runs pre-execution simulation. If executeResult is false → show executeErrorMsg, do NOT broadcast.
• Sensitive fields never to expose: accessToken, refreshToken, apiKey, secretKey, passphrase, sessionKey, sessionCert, teeId, encryptedSessionSk, signingKey, raw tx data. Only show: email, accountId, accountName, isNew, addressList, txHash.
• Recipient address validation: EVM: 0x-prefixed, 42 chars. Solana: Base58, 32-44 chars. Validate before sending.
• Risk action priority: block > warn > empty (safe). Top-level action = highest priority from riskItemDetail.
• Approve calls:

<NEVER> NEVER execute unlimited token approvals.

• Do NOT set approve amount to type(uint256).max or 2^256-1 or any equivalent "infinite" value.
• Do NOT call setApprovalForAll(operator, true) — this grants full control over all tokens of that type.
• If the user explicitly requests unlimited approval, you MUST:

1. Warn that this is irreversible and allows the spender to drain all tokens at any time. 2. Wait for explicit secondary confirmation ("I understand the risk, proceed"). 3. Even after confirmation, cap the approve amount to the actual needed amount (e.g. swap amount + 10% buffer), never unlimited.

• If the user insists on unlimited after the warning, refuse and suggest they execute manually via a block explorer.

</NEVER>

---

Agent Policy & Wallet Export Guidance

Policy configuration and wallet export are completed by the user on the Web portal — the Agent only detects the trigger, explains the risk, and gives the jump link. On any trigger below, MUST load `references/portal-actions.md` and follow its "Trigger flows" exactly — that file owns the procedures, the policy-rule list, the loginType link tables, and the wallet-export competition gate.

Triggers:

• New user login (isNew: true) — also handled in Authentication step 5
• After a successful wallet add
• User asks about Policy — spending / daily limit, whitelist
• User asks about wallet export — export mnemonic, migrate wallet, import to hardware wallet

---

Edge Cases

Load on error: references/troubleshooting.md

Global Notes

<MUST>

• X Layer gas-free: X Layer (chainIndex 196) charges zero gas fees. Proactively highlight this when users ask about gas costs, choose a chain for transfers, add a new wallet, or ask for deposit/receive addresses.
• Transaction timestamps in history are in milliseconds — convert to human-readable for display
• Always display the full transaction hash — never abbreviate or truncate txHash
• Address formats & recipient validation: see "Security Notes" → "Recipient address validation" above (single source of truth for EVM / Solana formats).
• XKO address format: OKX uses a custom XKO prefix (case-insensitive) in place of 0x for EVM addresses. If a user-supplied address starts with XKO / xko, display this message verbatim:

"XKO address format is not supported yet. Please find the 0x address by switching to your commonly used address, then you can continue."

• User-facing language: Localization for general terms is handled by the global locale rule below. The table below only lists exceptions — proper nouns that must NOT be localized.

• Term preferences (English-source canonical wording):
• Prefer "verification code" over "OTP" in English replies.
• Use "Policy Settings" as the canonical English label for the per-account policy section.
• Full chain names: Always display chains by their full name — never use abbreviations or internal IDs. If unsure, run onchainos wallet chains and use the showName field.
• Friendly Reminder: This is a self-custody wallet — all on-chain transactions are irreversible.
• Locale-aware output: All user-facing content must be translated to match the user's language.
• Address display format: When showing wallet addresses, list EVM address once with a chain summary note (X Layer first, then 2 other example chains, then total count). Example: EVM: 0x1234...abcd (Supports X Layer, Ethereum, Polygon and 16 EVM chains). Solana address on a separate line: Solana: 5xYZ.... Do NOT enumerate every EVM chain individually.

</MUST>

<SHOULD>

• send / contract-call are atomic: unsigned → sign → broadcast in one command.
• If --from is omitted, the CLI uses the currently selected account's address.
• History output: direction = send / receive; assetChange[] = net asset changes (useful for swaps).
• When recommending EVM chains, include X Layer alongside Ethereum, BNB Chain, Polygon, Arbitrum One, Base. (One EVM 0x address works across all of them; Solana / Bitcoin use different formats.)

</SHOULD>

<NEVER>

• Never show raw accountId — show accountName. accountId is for CLI calls only.
• Do NOT mix address formats across chain types
• Never display mnemonic phrases, seed phrases, or private keys in the conversation — wallet export must always be completed on the Web portal.

</NEVER>

FAQ

For Gas Station FAQ (what is it, how it works, supported tokens/chains, open/close flow): read references/gas-station-faq.md.

Q: The agent cannot autonomously sign and execute transactions — it says local signing is required or asks the user to sign manually. How does signing work?

A: OKX Agentic Wallet uses TEE (Trusted Execution Environment) for transaction signing. The private key is generated and stored inside a server-side secure enclave — it never leaves the TEE.

Shared Chain Name Support

This file is shared across all onchainos skills.

The CLI accepts human-readable chain names and resolves them automatically.

Wallet address creation (7 chains)

The following 7 chains support wallet address creation (i.e., you can generate a wallet address on these chains):

Note: The wallet supports interacting with 17+ chains beyond this list (e.g., Polygon, Avalanche, Optimism).

Run onchainos wallet chains for the full list of supported chains.

Gas Station supported chains and tokens (Solana only)

Authoritative matrix for Gas Station. Use this when the Agent needs chain display name, native token symbol, or the set of stablecoins accepted.

Always derive the per-tx token set from the response's `gasStationTokenList` — it's backend-authoritative. The table above is for reference only (FAQ answers, unsupported-chain detection).

Shared Pre-flight Checks

This file is shared across all onchainos skills. Follow these steps, in order, before the first onchainos command each session. Do not echo routine command output to the user; give a brief status update only when installing, updating, or handling a failure.

1. Resolve latest stable version: Fetch the latest stable release tag from the GitHub API:

   curl -sSL "https://api.github.com/repos/okx/onchainos-skills/releases/latest"

Extract the tag_name field (e.g., v1.0.5) into LATEST_TAG. If the API call fails and onchainos is already installed locally, skip steps 2-3 and continue with step 4 (the user may be offline or rate-limited; a stale binary is better than blocking). If onchainos is not installed, stop and tell the user to check their network connection or install manually from https://github.com/okx/onchainos-skills.

2. Install or update: If onchainos is not found, or if the cache at ~/.onchainos/last_check ($env:USERPROFILE\.onchainos\last_check on Windows) is older than 12 hours:

• Download the installer and its checksum file from the latest release tag:
• macOS/Linux:

curl -sSL "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.sh" -o /tmp/onchainos-install.sh curl -sSL "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" -o /tmp/installer-checksums.txt

• Windows:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.ps1" -OutFile "$env:TEMP\onchainos-install.ps1" Invoke-WebRequest -Uri "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" -OutFile "$env:TEMP\installer-checksums.txt"

• Verify the installer's SHA256 against installer-checksums.txt. On mismatch, stop and warn — the installer may have been tampered with.
• Execute: sh /tmp/onchainos-install.sh (or & "$env:TEMP\onchainos-install.ps1" on Windows).

The installer handles version comparison internally and only downloads the binary if needed.

• On other failures, point to https://github.com/okx/onchainos-skills.

3. Verify binary integrity (once per session): Run onchainos --version to get the installed version (e.g., 1.0.5 or 2.0.0-beta.0). Construct the installed tag as v<version>. Download checksums.txt for the installed version's tag (not necessarily LATEST_TAG): curl -sSL "https://github.com/okx/onchainos-skills/releases/download/v<version>/checksums.txt" -o /tmp/onchainos-checksums.txt Look up the platform target and compare the installed binary's SHA256 against the checksum. On mismatch, reinstall (step 2) and re-verify. If still mismatched, stop and warn.

• Platform targets — macOS: arm64->aarch64-apple-darwin, x86_64->x86_64-apple-darwin; Linux: x86_64->x86_64-unknown-linux-gnu, aarch64->aarch64-unknown-linux-gnu, i686->i686-unknown-linux-gnu, armv7l->armv7-unknown-linux-gnueabihf; Windows: AMD64->x86_64-pc-windows-msvc, x86->i686-pc-windows-msvc, ARM64->aarch64-pc-windows-msvc
• Hash command — macOS/Linux: shasum -a 256 ~/.local/bin/onchainos; Windows: (Get-FileHash "$env:USERPROFILE\.local\bin\onchainos.exe" -Algorithm SHA256).Hash.ToLower()

4. Version drift check — REQUIRED, run even if steps 1-3 were skipped.

• Run onchainos --version → CLI version (e.g., 2.2.9)
• Read version field from the active skill's YAML frontmatter (e.g., version: "2.0.0" at the top of SKILL.md)
• If CLI version > skill version → warn the user and offer to refresh skills:

"⚠️ Skill outdated (skill vX.Y.Z < CLI vA.B.C). Run `onchainos upgrade` to refresh both the CLI and any locally cloned skill checkouts (`~/.codex/onchainos-skills`, `~/.openclaw/onchainos-skills`, `~/.cursor/onchainos-skills`, `~/.opencode/onchainos-skills`). For skills installed via a plugin manager (Claude Code `/plugin`, npm, Cursor marketplace), update through that manager instead — `onchainos upgrade` will skip those paths and print guidance."

• After the user re-runs the skill (or confirms they've updated), re-read SKILL.md so subsequent steps use the fresh content.
• Continue to the user's command.

5. Do NOT auto-reinstall on command failures. Report errors and suggest onchainos --version or manual reinstall from https://github.com/okx/onchainos-skills. 6. Rate limit errors. If a command hits rate limits, the shared API key may be throttled. Suggest creating a personal key at the OKX Developer Portal. If the user creates a .env file, remind them to add .env to .gitignore.

Onchain OS — Agentic Wallet CLI Reference

Complete parameter tables, return field schemas, and usage examples for all wallet commands (A-G).

---

A. Account Commands (6 commands)

A1. onchainos wallet login [email]

Start the login flow. With email: sends OTP; without email: silent AK login.

onchainos wallet login [email] [--locale <locale>]

Return fields (email OTP — returns empty on success):

{ "ok": true, "data": {} }

Return fields (silent login):

A2. onchainos wallet verify <otp>

Verify the OTP code received via email to complete login.

onchainos wallet verify <otp>

Return fields:

Never expose sensitive fields (tokens, keys, certificates) to the user.

A3. onchainos wallet add

Add a new wallet account under the logged-in user.

onchainos wallet add

Parameters: None.

Note: Adding a wallet automatically switches to the new account. No need to run wallet switch manually.

Return fields:

A4. onchainos wallet switch <account_id>

Switch the active wallet account.

onchainos wallet switch <account_id>

Success response: {"ok": true, "data": {}}

A5. onchainos wallet status

Show current login status and active account.

onchainos wallet status

Parameters: None.

Return fields:

Policy fields (inside policy)

A6. onchainos wallet logout

Logout and clear all stored credentials.

onchainos wallet logout

Parameters: None.

Success response: {"ok": true, "data": {}}

A7. onchainos wallet chains

List all chains supported by the wallet, including chain names, IDs, and capabilities.

onchainos wallet chains

Parameters: None.

Return fields (per chain in array):

Usage: Use showName for user-facing display. Use realChainIndex for --chain parameters in wallet commands.

A8. onchainos wallet qrcode --address <addr>

Render a Unicode-block QR code for the given address (or any string), encoded verbatim. No URI scheme is added — the QR payload is exactly the value passed via --address.

onchainos wallet qrcode --address 0x1234...abcd

Parameters:

Output: Plain Unicode-block art on stdout (no JSON wrapper). Render verbatim in a monospace block to preserve scanning fidelity.

---

B. Balance Commands

B1. onchainos wallet balance

Query the authenticated wallet's token balances. Behavior varies by flags.

onchainos wallet balance [--all] [--chain <chain>] [--token-address <addr>] [--force]

---

Scenario 1: No flags — active account balance (default)

Returns the active account's EVM/SOL addresses, all-chain token list, and total USD value.

---

Scenario 2: `--all` — batch balance for all accounts

Returns totalValueUsd plus a details map of per-account balance cache entries.

---

Scenario 3: `--chain <chain>` (no `--token-address`) — chain-filtered balances

Returns token balances for the active account on the specified chain.

---

Scenario 4: `--chain <chain> --token-address <addr>` — specific token balance

Returns balance data for a single token. No totalValueUsd at top level.

---

B — Input / Output Examples

User says: "Show all my accounts' assets"

onchainos wallet balance --all
# -> Display:
#   ◆ All Accounts · Balance                           Total $5,230.00
#
#     Account 1                                          $3,565.74
#     Account 2                                          $1,664.26

---

User says: "Show my balance"

onchainos wallet balance
# -> Display:
#   ◆ Wallet 1 · Balance                               Total $1,565.74
#
#     XLayer (AA)                                          $1,336.00
#     Ethereum                                               $229.74
#
#     No tokens on: Base · Arbitrum One · Solana · ...

---

User says: "Check my balance for token 0x3883ec... on Ethereum"

onchainos wallet balance --chain 1 --token-address "0x3883ec817f2a080cb035b0a38337171586e507be"
# -> Display:
#   ◆ Wallet 1 · Token Detail
#
#     XYZ (Ethereum)    1,500.00    $750.00

---

C. Portfolio Commands

Portfolio / balance commands (portfolio chains, portfolio total-value, portfolio all-balances, portfolio token-balances)

are handled by the okx-wallet-portfolio skill. See that skill's cli-reference for full documentation.

Wallet PnL / DEX-history commands live under market portfolio-* and are owned by okx-dex-market.

---

D. Send Command

D1. onchainos wallet send

Send native tokens or contract tokens (ERC-20 / SPL) from the Agentic Wallet.

onchainos wallet send \
  --readable-amount <amount> \
  --recipient <address> \
  --chain <chain> \
  [--from <address>] \
  [--contract-token <address>] \
  [--force] \
  [--gas-token-address <address>] \
  [--relayer-id <id>] \
  [--enable-gas-station]

Return fields (normal):

Return fields (Gas Station auto-path on Solana — silent Scene B / Scene D):

Confirming response (Gas Station Scene A or Scene C — exit code 2):

When Gas Station needs user input, the CLI returns a Confirming response with the available token list in the next field. The message distinguishes the two subcases:

• Scene A — gasStationFirstTimePrompt=true (first-time enable, render the Scene A verbatim copy with token-list)
• Scene C — hash empty + gasStationFirstTimePrompt=false (default token insufficient, render the Scene C verbatim copy)

See references/gas-station.md for the verbatim user-facing copy and dispatch logic.

Return fields (Gas Station all-insufficient — Scene E):

Return fields (Gas Station pending-blocking):

Return fields (not routed through Gas Station):

Same as regular wallet send output (txHash / orderId). gasStationUsed=false. Covers: native SOL transfer, Jito Bundle transaction, single-tx > 100,000 U, chain ≠ Solana, GS disabled + SOL sufficient.

---

D-GS. Gas Station Management Commands (Solana)

Solana Gas Station does NOT require any on-chain account setup. Enable / disable / change-default operate purely on the backend DB flag. The first transaction the user signs after consenting in Scene A is just a regular Gas Station send — there is no separate "setup" or "upgrade" step.

D-GS1. onchainos wallet gas-station update-default-token

Update the default gas payment token for Gas Station on Solana.

onchainos wallet gas-station update-default-token \
  --chain solana \
  --gas-token-address <spl_mint>

D-GS2. onchainos wallet gas-station enable

Turn Gas Station back on for Solana. Internal: DB flag flip only. There is no on-chain action on Solana — re-enabling is instant. See gas-station.md User-Facing Reply Templates for the user-facing wording.

onchainos wallet gas-station enable \
  --chain solana

D-GS3. onchainos wallet gas-station disable

Turn Gas Station off for Solana; the chain reverts to paying gas with SOL. Internal: DB flag flip only, no on-chain action. The default_gas_token_address is preserved so re-enabling later restores the previous default. See gas-station.md User-Facing Reply Templates for the user-facing wording.

onchainos wallet gas-station disable \
  --chain solana

D-GS4. onchainos wallet gas-station status (read-only probe)

Read-only Gas Station readiness probe on Solana. Used by third-party plugin pre-flight — the agent runs this before invoking a plugin's on-chain command (e.g. kamino-plugin supply --confirm ...) to decide whether GS is ready or needs first-time consent. Never broadcasts. Safe to call repeatedly.

onchainos wallet gas-station status \
  --chain solana \
  [--from <solana_address>]

Response (example):

{
  "ok": true,
  "data": {
    "chainId": "501",
    "chainName": "solana",
    "fromAddress": "CYXWm...",
    "gasStationEnabled": false,
    "gasStationDefaultToken": null,
    "recommendation": "ENABLE_GAS_STATION",
    "hasPendingTx": false,
    "insufficientAll": false,
    "tokenList": [
      { "symbol": "USDT", "feeTokenAddress": "<mint>", "relayerId": "1",
        "balance": "120.0", "serviceCharge": "0.8", "sufficient": true }
    ]
  }
}

recommendation enum (Solana-specific — no PENDING_UPGRADE, no REENABLE_GAS_STATION separation; re-enable is just a normal enable):

---

E. History Command (2 modes)

Routing:

• If any of --tx-hash / --order-id / --uop-hash is provided → Detail mode → /priapi/v5/wallet/agentic/order/detail (precise single record)
• Otherwise → List mode → /priapi/v5/wallet/agentic/order/list (browse paged list)

E1. List Mode (browse paged list)

Browse the transaction order list for the current or specified account. Use when the user wants to see recent transactions without knowing a specific identifier.

onchainos wallet history \
  [--account-id <id>] \
  [--chain <chain>] \
  [--begin <ms_timestamp>] \
  [--end <ms_timestamp>] \
  [--page-num <cursor>] \
  [--limit <n>]

Note: --order-id / --tx-hash / --uop-hash are not accepted in list mode — providing any of them routes to detail mode automatically.

Return fields:

List mode example response:

{
  "ok": true,
  "data": [
    {
      "cursor": "next_page_token",
      "orderList": [
        {
          "txHash": "0xabc123...",
          "txStatus": "1",
          "txTime": "1700000000000",
          "txCreateTime": "1700000000000",
          "from": "0xSender...",
          "to": "0xRecipient...",
          "direction": "send",
          "chainSymbol": "ETH",
          "coinSymbol": "ETH",
          "coinAmount": "0.01",
          "serviceCharge": "0.0005",
          "confirmedCount": "12",
          "hideTxType": "0",
          "repeatTxType": "",
          "assetChange": [
            {
              "coinSymbol": "ETH",
              "coinAmount": "0.01",
              "direction": "out"
            }
          ]
        }
      ]
    }
  ]
}

E2. Detail Mode (single order lookup)

Look up a specific transaction by any of: --order-id, --tx-hash, or --uop-hash. Triggered whenever any of those flags is present.

Preferred for Gas Station: right after a GS broadcast, the user has the orderId but txHash is returned asynchronously by the relayer — use --order-id to poll status without waiting for the hash.

# Query by orderId (recommended right after broadcast)
onchainos wallet history \
  --chain <chain> \
  --order-id <id> \
  [--account-id <id>]

# Query by txHash (once relayer returns hash / for non-GS transactions)
onchainos wallet history \
  --chain <chain> \
  --tx-hash <hash> \
  [--address <addr>] \
  [--account-id <id>]

# Query by user-operation hash
onchainos wallet history \
  --chain <chain> \
  --uop-hash <hash> \
  [--account-id <id>]

Return fields (detail mode):

Detail mode example response:

{
  "ok": true,
  "data": [
    {
      "txHash": "0xabc123...",
      "txTime": "1700000000000",
      "txStatus": "1",
      "failReason": "",
      "direction": "send",
      "repeatTxType": "",
      "from": "0xSender...",
      "to": "0xRecipient...",
      "chainSymbol": "ETH",
      "chainIndex": "1",
      "coinSymbol": "ETH",
      "coinAmount": "0.01",
      "serviceCharge": "0.0005",
      "confirmedCount": "12",
      "explorerUrl": "https://etherscan.io/tx/0xabc123...",
      "hideTxType": "0",
      "input": [
        { "name": "ETH", "amount": "0.01", "direction": "in" }
      ],
      "output": [
        { "name": "ETH", "amount": "0.01", "direction": "out" }
      ]
    }
  ]
}

Transaction Status Values

---

F. Contract Call Command

F1. onchainos wallet contract-call

Call a smart contract on an EVM chain or Solana program with TEE signing and automatic broadcasting.

onchainos wallet contract-call \
  --to <contract_address> \
  --chain <chain> \
  [--amt <amount>] \
  [--input-data <hex_calldata>] \
  [--unsigned-tx <base58_tx>] \
  [--gas-limit <number>] \
  [--from <address>] \
  [--aa-dex-token-addr <address>] \
  [--aa-dex-token-amount <amount>] \
  [--mev-protection] \
  [--jito-unsigned-tx <jito_base58_tx>] \
  [--biz-type <biz_type>] \
  [--strategy <strategy>] \
  [--force]

Either --input-data (EVM) or --unsigned-tx (Solana) must be provided. The CLI will fail if neither is present.

Return fields:

---

G. Sign Message Command

G1. onchainos wallet sign-message

Sign a message using the TEE-backed session key. Supports personalSign (EIP-191, EVM + Solana) and EIP-712 typed structured data (EVM only).

onchainos wallet sign-message \
  --chain <chain> \
  --message <message> \
  [--type <type>] \
  --from <address> \
  [--force]

Note: Using --type eip712 with --chain 501 (Solana) will return an error. EIP-712 is only supported on EVM chains.

Return fields (EVM chains):

Return fields (Solana, chain 501):

G — Input / Output Examples

User says: "Sign this message on Ethereum: Hello World"

onchainos wallet sign-message --chain 1 --from 0xYourAddress --message "Hello World"
# -> personalSign (EVM). message.value is hex-encoded.
#   Signature: 0xabcdef1234567890...

---

User says: "Sign this message on Solana"

onchainos wallet sign-message --chain 501 --from SoLYourAddress --message "Hello World"
# -> personalSign (Solana). message.value is base58-encoded.
#   Signature: 3xB7mK9v... (base58)
#   PublicKey: SoLYourAddress

---

User says: "Sign this EIP-712 typed data on Ethereum"

onchainos wallet sign-message --chain 1 --from 0xYourAddress --type eip712 --message '{"types":{"EIP712Domain":[{"name":"name","type":"string"}],"Mail":[{"name":"contents","type":"string"}]},"primaryType":"Mail","domain":{"name":"Example"},"message":{"contents":"Hello"}}'
# -> eip712 (EVM only). Solana is NOT supported for eip712.
#   Signature: 0x1234abcd5678ef90...

Gas Station — Edge Cases (Solana)

Load on demand: read this when one of the triggers below fires. Render any user-facing template per the <output-discipline> rule in gas-station.md.

<edge-cases-rule> Handle these edge cases explicitly — do NOT fall through to generic error handling. Render any template below per <output-discipline>. </edge-cases-rule>

Edge Case 1 — Relayer single-tx cap exceeded (100,000 U)

Trigger: backend detects single-tx value > 100,000 USD equivalent. Backend silently falls back to normal flow (gasStationUsed=false); CLI will NOT emit a GS Confirming. Agent must NOT proactively mention Gas Station. Only when the user directly asks whether stablecoins can pay gas for this transaction — respond with the verbatim template below.

<edge-tx-cap-copy> User-facing template (render per <output-discipline>):

This transaction exceeds the Gas Station per-transaction cap (100,000 U), so Gas cannot be paid with a stablecoin. Top up the native token and retry the full transfer, or split it into smaller transactions.

Do NOT expose internal terms ("Relayer cap", "TTL", etc.). </edge-tx-cap-copy>

Edge Case 2 — Jito Bundler is a HARD BLOCK

Trigger: user wants to use Jito Bundle for this transaction (e.g., --jito-unsigned-tx is supplied, or user states intent to use Jito Bundler). Gas Station does NOT support Jito Bundler transactions on Solana. This is a hard block — even if SOL is insufficient and stablecoin is available, the Agent must offer the two alternatives below; do NOT silently route to Gas Station.

<edge-jito-copy> User-facing template (render per <output-discipline>):

Sorry, Gas Station does not support Jito Bundler transactions.

You can continue either way:

- Use Jito Bundle: switch the network fee to the native token (SOL); the Bundle transaction can be sent normally.
- Use stablecoin Gas: switch to a normal transaction (no Jito Bundle).

Apply this template whenever the user explicitly asks for Jito Bundle + stablecoin gas, OR whenever the Agent detects both intents (e.g., MEV-protected swap on Solana with --jito-unsigned-tx and Gas Station Confirming was about to fire). Never claim Gas Station can be combined with Jito Bundler. </edge-jito-copy>

Edge Case 3 — User asks for txHash before Relayer returns it

Trigger: the user asks for the tx hash or recent tx detail, but the most recent Gas Station broadcast's txHash is still empty (the Relayer hasn't published the on-chain hash yet). The orderId is known; the hash is not.

<edge-async-hash-copy> User-facing template (first response) (render per <output-discipline>):

The transaction is being submitted on-chain. Please check again shortly.

Follow-up template if the user asks why other transactions return a hash immediately:

This one is paid via Gas Station, so the hash comes back slightly later than for normal transactions.

Do NOT fabricate a txHash. Do NOT show onchainos wallet history ... or any raw CLI command. Do NOT explain the Relayer/async mechanism beyond the one sentence above. </edge-async-hash-copy>

Edge Case 4 — Pending Gas Station tx is blocking

Trigger: hasPendingTx=true in the latest response (CLI scene: "gs_pending_tx"). A previous Gas Station tx is still processing.

User-facing message:

A previous Gas Station transaction is still processing — you can't start a new one yet. Wait for the previous one to finish and retry, or top up SOL and use the native token instead.
(To check the previous one, tell me: **check order {prev_orderId}**)

Do NOT auto-retry. Do NOT mention "Relayer" / internal mechanisms.

Edge Case 5 — Order status query (user types "check order xxx")

Trigger: user replies with any wording meaning "check order {orderId}" or "is that last transaction done?" — in any language.

Agent runs wallet history --chain solana --order-id {orderId} internally (NOT shown to user) and renders one of:

Outcome A — completed (on-chain success, txHash returned):

✅ Order {orderId} completed.

- txHash: {txHash}
- Status: success
- Chain: Solana
- {networkFeeLabel}: {network_fee_line}

{networkFeeLabel} is already provided by the CLI in the order detail response — render it verbatim. The CLI computes the label as either Network fee or Network fee and Rent fee based on whether the Solana Relayer also covered the recipient's SPL token-account rent (~0.002 SOL, folded into {network_fee_line}). Translate the label to the user's language per the global locale rule; never hard-code translations.

Do NOT add a separate line for the rent — it's signalled by the label string only. Do NOT render the raw feeContainCreateAccount field (it is not in the CLI output any more; the label supersedes it).

{network_fee_line} rendering rule (take the first one that fits):

1. If `serviceChargeSymbol` is present (the CLI emits it from the backend's feeName; serviceChargeFeeTokenAddress may be absent in history responses, do NOT treat it as required): {serviceCharge_readable} {serviceChargeSymbol} (≈ ${serviceChargeUsd}, paid via Gas Station) Example: 0.004565 USDC (≈ $0.0046, paid via Gas Station). {serviceCharge_readable} = serviceCharge (raw integer string) divided by 10 ^ serviceChargeDecimal (also emitted by CLI when present). Do NOT print the raw integer; do NOT skip the symbol; do NOT print field names like serviceChargeUsd literally inside the parenthetical. 2. If only `serviceChargeUsd` is present, no symbol (older history responses): ≈ ${serviceChargeUsd} (paid via Gas Station) Example: ≈ $0.001717 (paid via Gas Station). 3. If even `serviceChargeUsd` is empty / 0: paid via Gas Station (amount not returned)

Do not dig through broadcast logs to backfill the symbol — those logs are Agent-internal and not visible from the user's perspective. Filling in the symbol is the CLI's responsibility (emit serviceChargeSymbol from feeName).

Outcome B — still processing:

Order {orderId} is still being processed by the Relayer. Please check again shortly — tell me **check order {orderId}** and I'll fetch the latest status.

Outcome C — failed / timed out (typically 10-minute Relayer TTL):

⚠️ Order {orderId} did not complete.

The transaction was broadcast via Gas Station, but the Relayer did not finalize it on-chain within 10 minutes; it has been marked as failed.

Your funds are untouched — the stablecoin Gas fee was NOT deducted, and the {amount} {tokenSymbol} you tried to send is still in your account.

You can retry now, or top up SOL and pay Gas with the native token instead.

Never fabricate txHash. Never show wallet history as a command to the user.

Edge Case 6 — Native SOL transfer (Gas Station does not apply)

Trigger: user sends native SOL. Backend returns gasStationUsed=false regardless of balance. Gas Station only supports SPL token transfers and contract interactions on Solana.

If user asks why, respond: "Gas Station only applies to SPL token transfers and contract interactions. Native SOL transfers do not go through Gas Station."

Edge Case 7 — Transaction history display rules

When listing or detailing a Gas Station transaction in wallet history:

• Show user intent only — display the user's intended transfer (e.g., "100 USDC → CYXWm..."). Do NOT display the Relayer's fee-payer address.
• Network fee — display the actual token used by Gas Station (e.g., 0.8 USDC), not SOL.
• From address — display the user's address, not the Relayer's.

---

Failure & Backend-Bug Handling

Diagnosis content, not user-facing templates. Backend errors and bugs surfaced during the two-phase wallet send / wallet contract-call flow, plus management-command API errors. The flow, scene dispatch, and product copy live in gas-station.md; the edge-case templates above cover the expected branches; this section covers what neither does.

>

Scene dispatch reminder — read the CLI scene discriminator and dispatch via the gas-station.md "Outcome → render map". Do NOT re-derive the scene from raw backend booleans (gasStationUsed / hasPendingTx / insufficientAll / hash).

Phase 2 failures (after the user picked a token / CLI filled params)

Broadcast & history bugs (should-not-happen)

Broadcast is asynchronous (orderId returned, txHash eventual). For the normal async-hash / Relayer-timeout / order-status / history-display copy, use Edge Case 3 / 5 / 7 above and the Universal Gas Station Success Reply in gas-station.md. Treat the following as backend bugs if observed:

Management command failures

Gas Station — FAQ (Solana)

Load on demand: read this when the user asks a Gas Station FAQ-style question (what is it / how it works / fees / supported networks-tokens / which scenarios don't trigger / why a tiny amount of SOL was received in the transaction). All answers are user-facing reply templates — render per the <output-discipline> rule in gas-station.md. Never expose internal mechanism terms.

<faq-scope> "Gas Station" always means the OKX Agentic Wallet feature shipped by this CLI + skill (Solana variant). When the user asks any FAQ-style question:

• DO use the verbatim templates below.

</faq-scope>

<faq-no-extras> Output the template alone. Nothing before, nothing after.

• If the template doesn't already contain the fact you want to add, the answer is: don't add it. The PRD copy is intentionally curated; extra context dilutes it.

Do NOT layer the "never call Gas Station free" rule onto FAQ answers. That rule governs successful broadcast replies (where a serviceCharge is present in the response) and does NOT mean every FAQ answer must add a service-charge caveat. Transaction-time fee disclosure happens at transaction time, not at FAQ time.

The only allowed deviation is translating the template into the user's language at output time while keeping the structure and every sentence. </faq-no-extras>

Q: What is Gas Station?

Gas Station aggregates third-party services,
  automatically comparing rates and picking the cheapest one to pay Gas for you.
  You can pay with USDT, USDC, or USDG —
  no need to hold SOL or any other native token.
  ──────────────────────────────
  Supported network and tokens: Solana (USDT, USDC, USDG)
  ──────────────────────────────

Q: How does Gas Station work under the hood?

[Solana] Gas Station needs no account upgrade or setup.
A third-party service pays the network fee on your behalf,
and the fee is automatically deducted from the stablecoin you choose.

Q: Are there extra fees for enabling Gas Station?

[Solana] No. Gas Station on Solana requires no account upgrade;
you can pay Gas with a stablecoin on the very first use.

Q: Does each network need to be upgraded before use?

No. Solana has no setup step;
once Gas Station is enabled it can be used directly.

Q: Which tokens can be used to pay Gas?

USDC, USDT, USDG. By default the token with the highest balance is used;
when balances tie, the order is USDT > USDC > USDG.
You can also pin a specific token as the default Gas token.

Q: Which networks are supported?

Solana only, for now.

Q: Which scenarios do NOT trigger Gas Station?

- Native SOL transfers (Gas Station only covers SPL token transfers and contract interactions).
- Transactions sent via Jito Bundle.
- A single transaction value above 100,000 U.
- A previous Gas Station transaction is still being processed.

Q: Why did I receive a small amount of SOL from this transaction?

Render gate — this template is scoped to Gas Station rent-settlement transactions only. Do NOT render on the keyword alone. Before rendering:

1. Resolve the candidate tx — use the txHash from context if the user gave one; otherwise run onchainos wallet history --chain solana and pick the recent SOL-inflow record(s) the user is asking about. 2. Fetch the detail — onchainos wallet history --chain solana --tx-hash <hash> (or --order-id <id>). 3. Require both markers on that detail:

• serviceChargeSymbol ∈ {USDT, USDC, USDG} (Gas Station settled the fee in stablecoin)
• networkFeeLabel == "Network fee and Rent fee" (rent was involved in this tx)

Markers present → render the template below verbatim.

Markers absent → do NOT render this template. The SOL inflow is unrelated to Gas Station rent. Explain from the actual tx data:

• Real swap (e.g., USDC → SOL in the asset change) — describe it as a normal swap result.
• Dusting (1 lamport from an unknown address, txHash often null) — Solana network noise, not user-driven, ignorable.

Do not invent a Gas Station explanation when the markers don't match.

[Solana] This transaction was settled via Gas Station and involves an account rent (rent):
- Within the same transaction, the Relayer first sends a small amount of SOL to cover the account rent for this transaction.
- Within the same transaction, you repay the Relayer in the stablecoin you selected (covering both the rent and the network fee).
- The small amount of SOL you ended up receiving is the leftover after the rent was paid.

Gas Station — Detailed Reference (Solana)

Gas Station enables paying gas fees with stablecoins (USDT / USDC / USDG) when the user lacks native SOL. On Solana the Relayer is the native fee payer (signature index 0); the user is the business authority signer (signature index 1). The stablecoin gas fee is collected via an SPL Token Transfer inside the same transaction — no account upgrade, no per-chain setup, no 7702.

Supported gas tokens: USDT, USDC, USDG.

Supported scenarios: all SPL token transfers and contract interactions (swaps, DeFi supply / borrow / redeem / claim, cross-chain bridge initiation, and any other SPL / program interaction). Native SOL transfers do NOT trigger Gas Station.

Scope: Gas Station state (enable flag, default gas token) is scoped to (account, Solana).

---

Read Critical Rules first, then dispatch via the Outcome → render map under Flow. Scene A/B/D/C/E copy, Universal Success Reply, Edge Cases, Management Commands, User Intent Recognition, Plugin Bail Recovery, and FAQ follow in order.

---

Critical Rules

<backend-dispatch> Backend dispatches; Agent reacts. The Agent does NOT manually check SOL balance or decide whether to use Gas Station. The Agent's only job is to:

1. Call wallet send / wallet contract-call as normal. 2. Read the CLI's `scene` discriminator (and gasStationUsed) and dispatch via the Outcome → render map below — do not re-derive the scene from raw backend fields. 3. If a Confirming response is returned, show the matching scene's verbatim product copy and ask the user to pick a token.

Always surface Gas Station when native SOL is insufficient but a supported stablecoin has enough balance to cover transfer + gas fee — for both a fresh transfer attempt and a "why did my transfer fail?" follow-up. This is the single most valuable suggestion the Agent can make:

• On wallet send success-but-insufficient-native: the backend returns a Confirming via Scene A / Scene C; CLI handles it. Present GS as the primary path, not as one of several equivalent options.
• If Gas Station is currently disabled and the user retries, the backend will return gasStationFirstTimePrompt=true again — follow Scene A.
• Whenever a GS transfer is blocked because the default gas token has insufficient balance and the account holds another stablecoin on the same chain: propose switching the gas token before any other fallback. Switching via Scene C is zero-cost — prefer it over "reduce transfer amount" or "top up default token".

</backend-dispatch>

<phase-call-prohibitions>

• NEVER pass `--gas-token-address`, `--relayer-id`, or `--enable-gas-station` on the FIRST call to wallet send / wallet contract-call. These are only for the second-phase call after the user has chosen a token from a Confirming response.
• NEVER fabricate token addresses or relayer IDs — always use the exact values from the Confirming response's next field (which contains the tokenList JSON).
• NEVER proactively push Gas Station as a feature when the user is just browsing or asking unrelated questions.
• NEVER tell the user Gas Station is "free" — there is a service charge paid in the selected stablecoin. Always display the serviceCharge + serviceChargeSymbol when present.
• NEVER expose implementation detail to the user — see "User Intent Recognition" section below for the authoritative output-vocabulary ban list. User-facing text is only about "enable / disable Gas Station" and "which stablecoin to pay Gas".
• NEVER allow Gas Station with Jito Bundler — Jito Bundler transactions are a HARD BLOCK. See "Edge Cases — Jito Bundler".

</phase-call-prohibitions>

<output-discipline> Template rendering & translation fidelity (applies to every Scene / Edge Case / FAQ template in this file — per-Scene blocks reference this rule and do not restate it). All user-facing copy here is product copy: render the template body verbatim, substituting only the bracketed slots. When the user's language is not English, translate at output time while preserving structure and meaning, and:

• Keep every sentence and every fact; never drop a clause (e.g. "now set as the default Gas token", "you can change the default at any time").
• Never substitute a chain-specific noun: render "Solana" as-is — never replace it with "ETH / BNB / the native token" or any other chain's token. This is the Solana flow.
• No leading setup line ("Sure, let me…") and no trailing notes / tips / follow-up questions beyond what the template contains.

</output-discipline>

---

Flow (integrated into wallet send / wallet contract-call)

Gas Station is not a separate command — the backend decides per-request whether to dispatch it inside the wallet send / wallet contract-call response. When dispatched, the flow uses the standard Confirming Response pattern (exit code 2) for first-time activation / token-switch cases (Scene A / C), and the silent auto-path when a default token is already pinned (Scene B / D).

The CLI tags each response with a machine-readable scene discriminator; dispatch via the Outcome → render map below. On a Confirming, render the matching Scene and ask the user to pick a token.

Token priority (for ordering the token list shown to the user, and for backend auto-selection): by balance descending; on ties, USDT > USDC > USDG.

Outcome → render map

The CLI returns a machine-readable `scene` discriminator — on confirming responses and on the gs_pending_tx / gs_insufficient_all success states. Map `scene` directly to the fixed copy below; do NOT re-derive the scene from raw backend fields, and do NOT author copy yourself. On a Confirming, the response next field carries the exact re-run command for after the user consents.

Edge cases the CLI does NOT tag with a scene (Jito hard-block, tx-cap exceeded, async-hash, native-SOL) are Agent-detected — see Edge Cases.

---

Scene A — Not enabled yet, native SOL insufficient, has sufficient stablecoin

User has not enabled Gas Station; backend returns gasStationFirstTimePrompt=true + gasStationTokenList (with at least one sufficient=true entry; if none, route is Scene E instead).

<scene-a-product-copy> User-facing template (Scene A). Render per the top-level <output-discipline> rule (verbatim, substitute bracketed slots only). The body below is the source of truth.

Your SOL balance is not enough to pay Gas. Two ways to proceed:

1. Top up SOL and pay with the native token.
2. Enable "Gas Station" and pay Gas directly with a stablecoin.

About Gas Station: Gas Station aggregates third-party services, automatically compares rates and picks the cheapest one to cover Gas on your behalf. It accepts USDT, USDC, or USDG — you do not need to hold Solana. Learn more: https://web3.okx.com/learn/wallet-gas-station

- Once enabled, whenever the native token is insufficient, the system will automatically pay Gas with the stablecoin — no manual confirmation needed.
- By default the token with the highest balance is used; you can also pin a specific token as the default for every transaction. Tokens supported on this chain: USDT, USDC, USDG.

Confirm enabling Gas Station and paying this transaction's Gas with stablecoin?

Never modify the template body. Never drop the academy link. Never drop the two bullets. Never drop the "Tokens supported on this chain" line. Never reduce the prompt to a bare "yes/no?" without the education paragraph. (Translation fidelity — including the "you do not need to hold Solana" wording — is governed by the top-level "Template rendering & translation fidelity" rule in Critical Rules.) </scene-a-product-copy>

Consent — the user picks a stablecoin (or declines). On a pick → follow the response next (re-run with that token's --gas-token-address + --relayer-id; if the user confirmed without naming one, use the highest-balance sufficient token). On decline → do NOT re-run; tell them to top up SOL at {fromAddr} and terminate. Ambiguous wording or a token not in the list → re-prompt once, never guess.

Post-success flow (Scene A — MANDATORY two-step finalization)

<scene-a-post-success> After the Phase-2 wallet send / wallet contract-call succeeds in Scene A (broadcast OK, orderId returned), the Agent MUST run the following two steps in order, on every Scene A trigger — not just the literal first-ever activation. Users may have previously disabled GS; do NOT skip Step 1 on that basis.

Step 1 — Pin the used token as the chain's default gas token.

Resolve {chosen_token_address} from the broadcast response (serviceChargeFeeTokenAddress; if absent, use the --gas-token-address the Agent passed in Phase 2). Then call exactly once:

onchainos wallet gas-station update-default-token --chain solana --gas-token-address {chosen_token_address}

This call is silent — do not surface its output, do not narrate it. Treat any non-zero exit as a soft failure and continue to Step 2.

Step 2 — Echo the success reply. Render this template per the top-level "Template rendering & translation fidelity" rule (verbatim, every sentence kept — in particular do not drop "now set as the default Gas token" or "You can change the default Gas token at any time"):

Gas Station enabled. This transaction will pay Gas with {chosen_token}, and {chosen_token} is now set as the default Gas token. Whenever the native token is insufficient from now on, {chosen_token} will be used automatically — no further confirmation needed. You can change the default Gas token at any time.

{chosen_token} = the stablecoin symbol (USDT / USDC / USDG) actually used in this transaction. All occurrences refer to the same token.

Then append the Universal Gas Station Success Reply (network fee + orderId + check-order prompt — see "Universal Gas Station Success Reply" section below). </scene-a-post-success>

---

Scene B / D — Silent auto-path

Backend returns gasStationUsed=true + autoSelectedToken=true + hash non-empty. CLI silently completes Phase 2 (sign + broadcast). Two triggers fall into this path:

• Scene B: a defaultGasTokenAddress is set and that token is sufficient — backend reuses it.
• Scene D: no default is set, but exactly one stablecoin is sufficient — backend auto-selects it (priority: balance desc, tie-break USDT > USDC > USDG). PRD specifies "do not prompt the user" here; complete the transaction silently without asking about default-pinning.

Agent user-facing reply: no Gas Station prompt. Just the Universal Gas Station Success Reply (network fee + orderId + check-order prompt). For Scene D, add a one-line note that the auto-selected token was used.

---

Scene C — Already enabled, default token insufficient

Backend returns gasStationUsed=true + hash empty + gasStationFirstTimePrompt=false + insufficientAll=false, with gasStationTokenList showing the default token as sufficient=false and at least one alternative as sufficient=true. CLI returns Confirming.

<scene-c-product-copy> User-facing template (Scene C). Render per <output-discipline>; substitute slots only.

The default Gas token {prev_token} has insufficient balance (need ${serviceChargeUsd}, current balance ${prev_balance_usd}).
The following stablecoins in your account have enough balance to pay this transaction's Gas:

- {alt_token_1} (balance ${alt_balance_1_usd})
- {alt_token_2} (balance ${alt_balance_2_usd})

How would you like to proceed?
1. Change the default Gas token to {alt_token_X} and use it for this transaction (this chain will default to {alt_token_X} going forward).
2. Use {alt_token_X} for this transaction only; keep the default as {prev_token}.
3. Top up {prev_token} and continue using it.

Slot fills:

• {prev_token} = symbol of the token at defaultGasTokenAddress
• {serviceChargeUsd} = required gas in USD; {prev_balance_usd} = current balance of default token in USD
• {alt_token_N} + {alt_balance_N_usd} = each sufficient=true entry in gasStationTokenList other than the default (omit the default; include all sufficient alternatives in token-priority order)
• {alt_token_X} placeholders in choices 1/2 = if exactly one alternative is sufficient, hard-code its symbol; if multiple, render as <your-pick> and let the user name the token in their reply.

Always include all three choice lines. Always include the "Top up {prev_token}" fallback. Do NOT prepend a setup line ("Sure, let me check…"). Do NOT append any follow-up question — choices 1 / 2 / 3 ARE the prompt. </scene-c-product-copy>

User response parsing

Post-success echo templates (Scene C) — render per <output-discipline>

<scene-c-post-success> After the broadcast succeeds, use one of the two templates per <output-discipline>:

Scene C — keep default unchanged

Done — this transaction will pay Gas with {chosen_token}. The default token remains {prev_token}, unchanged.

Scene C — replace default

Done — this transaction will pay Gas with {chosen_token}, and the default Gas token is now {chosen_token}.

Follow this echo with the Universal Gas Station Success Reply for network fee + orderId. </scene-c-post-success>

---

Scene E — All stablecoins insufficient

Backend returns gasStationUsed=true + insufficientAll=true + all gasStationTokenList entries with sufficient=false + fromAddr. CLI bails (do NOT proceed).

<scene-e-product-copy> User-facing template (Scene E). Render per <output-discipline>; substitute the one slot.

You don't have enough balance to pay Gas. Please top up first:
  Top-up address: {fromAddr}
  Accepted tokens: SOL, USDT, USDC

Slot fills: {fromAddr} = user's Solana address from the response.

Do NOT proceed with the original transaction. Do NOT propose Gas Station — none of the stablecoins are sufficient. </scene-e-product-copy>

---

Universal Gas Station Success Reply (applies to ALL commands)

Whenever any transaction is paid via Gas Station on Solana — regardless of which command triggered it (wallet send, wallet contract-call, swap, bridge, any DeFi plugin) — the Agent's user-facing reply MUST include the four elements below. Detecting that Gas Station was used: the response contains gasStationUsed=true or a non-empty serviceCharge + serviceChargeSymbol pair (or the preceding CLI invocation carried --enable-gas-station / --gas-token-address).

<universal-success-reply> After any successful Gas Station broadcast, the reply MUST contain all four elements:

1. Gas Station acknowledgment — state plainly that this transaction's gas was paid via Gas Station with a stablecoin, not with SOL. Never imply the transaction was "free". 2. Service charge (stablecoin amount + USD equivalent) — show both the raw amount + symbol ({serviceCharge} {serviceChargeSymbol}) and the USD equivalent. Example: Network fee: 0.8 USDC (≈ $0.80, paid via Gas Station). 3. orderId — copy verbatim from the broadcast response. Never omit it, never truncate it. 4. Natural-language follow-up prompt — an exact sentence the user can type back in this chat to get the final status. Template: You can tell me: **check order {orderId}** to check the status. Translate to the user's language at output time, but keep the literal check order {orderId} idiom unchanged so the Agent can recognize the user's reply later.

`networkFeeLabel` field handling (hard rule, applies to every GS-related render — success reply / order detail / history list / etc.):

• When the CLI output (broadcast response, wallet history, order detail) contains a networkFeeLabel string (either Network fee or Network fee and Rent fee), that string IS the label of the network-fee row — render exactly ONE row using it as the row title. Example: Network fee and Rent fee: 0.157385 USDC (≈ $0.16, paid via Gas Station). Translate the label to the user's language per the global locale rule.
• Do NOT render networkFeeLabel as a separate row (e.g. a second "fee description" row).
• Do NOT add a default Gas fee / Network fee title alongside it — networkFeeLabel replaces it.
• When networkFeeLabel is absent in the CLI output, fall back to the default label Network fee.

When `txHash` is empty (Relayer returns hash asynchronously — almost always empty on first response): additionally state that the transaction has been submitted and the on-chain hash will be returned asynchronously by the Relayer, ask the user to check again shortly.

NEVER in this reply:

• Do NOT show raw CLI commands (onchainos wallet history ..., etc.) — the user must not be sent to a terminal.
• Do NOT fabricate a txHash when it's empty — only show it once returned.
• Do NOT call Gas Station "free" or hide the service charge.

</universal-success-reply>

Example reply

The same four-element structure applies regardless of which command triggered the Gas Station broadcast (wallet send, wallet contract-call, swap, bridge, any DeFi plugin) — only the leading action line changes (e.g. Sent 100 USDC to CYXWm..., Deposited 0.01 USDT into Kamino.):

Sent 100 USDC to CYXWm...

- Network fee: 0.8 USDC (≈ $0.80, paid via Gas Station)
- orderId: ord_ghi789rst
- txHash: submitted, on-chain hash will be returned asynchronously by the Relayer — check again shortly.

You can tell me: **check order ord_ghi789rst** to check the status.

Checking the order later

When the user replies with any wording meaning "check order {orderId}" or "what's the status of my last transaction" (in any language), the Agent runs wallet history --chain solana --order-id <orderId> internally (NOT shown to user) and relays:

• Completed: final txHash, on-chain status, final gas fee (may differ slightly from estimate).
• Still pending: tell the user it's still processing and to ask again shortly.
• Failed / timed out: explain "funds are intact" (GS broadcast is atomic — failure means stablecoin was not deducted), propose retry or native-gas fallback.

---

Edge Cases

Load `references/gas-station-edge.md` when one of these triggers fires; render its templates per <output-discipline>. (gs_pending_tx / gs_insufficient_all also arrive as a CLI scene — dispatch via the Outcome → render map.)

---

Management Commands

For command syntax and parameters (gas-station enable / disable / update-default-token, all --chain solana), see references/cli-reference.md → "D-GS. Gas Station Management Commands". This section only owns the user-facing reply wording below.

User-Facing Reply Templates (Management Commands)

Translate to the user's language at output time; the semantic content must not drift.

Before running `wallet gas-station disable` (confirmation prompt)

"Once disabled, transactions on Solana will pay Gas with SOL again. You can re-enable any time. If you only want to switch the Gas-payment token, use 'change default Gas token' instead of disabling. Confirm disabling?"

After any management command succeeds (enable / disable / update-default-token)

Render data.message verbatim (the CLI fills the success copy, incl. the token symbol for update-default-token). Translate per the global locale rule.

---

User Intent Recognition

Users may express Gas Station-related needs in various ways and in any language. The Agent should recognize the semantic intent and respond using the sanctioned vocabulary (templates in this file). Per the global locale rule in SKILL.md, translate to the user's language at output time.

<output-vocabulary> Agent output vocabulary (authoritative): refer to the feature only as "Gas Station" and to the choice only as "which stablecoin to pay gas".

Never surface in user-facing replies:

• Internal field names: gasStationFirstTimePrompt, gasStationUsed, autoSelectedToken, hasPendingTx, insufficientAll, signType, multiSignerTx, unsignedInfo, Phase 1 / Phase 2, DB flag.
• Error codes: any numeric code.
• Debug references: debug flags, log file paths, audit log paths.

Users may input any equivalent phrasing in any language — recognize the intent, but respond using only the sanctioned vocabulary. </output-vocabulary>

---

Plugin Bail Recovery

Third-party plugins like kamino-plugin, raydium-plugin, etc., invoke onchainos wallet contract-call as a subprocess. When the CLI emits a Confirming response (exit code 2, "confirming": true in stdout) for Scene A / Scene C, the plugin's subprocess wrapper typically treats non-zero exit as a failure and bails out of its own flow. The Agent can catch this, resolve the Gas Station setup, and re-invoke the same plugin command — the plugin will re-organize its calldata from scratch and this time CLI will hit the auto path.

When does this pattern trigger

The Agent detects a plugin bail with a structured Confirming in stdout:

Error: <plugin step> failed
Caused by: onchainos exited with status 2: stderr=... stdout={"confirming": true, "scene": "...", "message": "...", "next": "..."}

Markers:

• Exit code 2 (non-zero, subprocess marked as failure)
• stdout contains a JSON with "confirming": true

If these match → a recoverable Gas Station Confirming, not a real failure.

Recovery

Read the scene field from the stdout JSON and dispatch via the Outcome → render map above (render that scene's copy, get consent where required, run any management command it calls for — e.g. update-default-token on a Scene C replace-default pick), then re-invoke the same plugin command verbatim. The plugin re-builds its calldata and this time the CLI hits the auto path. gs_insufficient_all / gs_pending_tx → do NOT retry.

<plugin-recovery-rules>

• Always parse the Confirming JSON structure (exit code 2 + "confirming": true in stdout) before deciding it's recoverable. Real failures return different structures.
• Always ask user consent for Scene A and Scene C token-selection — CLI refuses to decide these silently on purpose.
• Do NOT retry Scene E (insufficientAll) or Edge Case 4 (hasPendingTx) — these require external action.
• Re-invoke the same plugin command verbatim after recovery. Do not reconstruct or replicate the plugin's internal calldata by hand — the bail is pre-broadcast, so re-running is idempotent.

</plugin-recovery-rules>

---

FAQ

Load `references/gas-station-faq.md` when the user asks a Gas Station FAQ — what it is / how it works / fees / supported networks-tokens / which scenarios don't trigger. Answers are verbatim user-facing templates; render per <output-discipline>.

MEV Protection (contract-call only)

Load when: the user requests MEV protection, or before a high-value / DEX-swap wallet contract-call. MEV protection is a contract-call flag only — wallet send does not support it.

The contract-call command supports MEV (Maximal Extractable Value) protection via the --mev-protection flag. When enabled, the broadcast API passes isMEV: true in extraData to route the transaction through MEV-protected channels, preventing front-running, sandwich attacks, and other MEV exploitation.

⚠️ Solana MEV Protection: On Solana, enabling --mev-protection also requires the --jito-unsigned-tx parameter. Without it, the command will fail. This parameter provides the Jito bundle unsigned transaction data needed for Solana MEV-protected routing.

🚨 Never substitute `--unsigned-tx` for `--jito-unsigned-tx` — they are completely different parameters. If Jito bundle data is unavailable, stop and ask the user: proceed without MEV protection, or cancel.

Supported Chains

When to Enable

• High-value transfers or swaps where front-running risk is significant
• DEX swap transactions executed via contract-call
• When the user explicitly requests MEV protection

Usage

# EVM contract call with MEV protection (Ethereum/BSC/Base)
onchainos wallet contract-call --to 0xDef... --chain 1 --input-data 0x... --mev-protection

# Solana contract call with MEV protection (requires --jito-unsigned-tx)
onchainos wallet contract-call --to <program_id> --chain 501 --unsigned-tx <base58_tx> --mev-protection --jito-unsigned-tx <jito_base58_tx>

Third-Party Plugin Pre-flight (Solana)

Load before dispatching a third-party Solana DeFi plugin command that performs an on-chain write.

Third-party Solana DeFi plugins (e.g. kamino-plugin, raydium-plugin) call onchainos wallet contract-call --force internally. Pre-flight Gas Station status on Solana before invoking the plugin's write command.

Gas Station is Solana-only: the Relayer is the native fee payer, and gas is debited via an SPL stablecoin transfer inside the same multi-signer transaction.

Pre-flight checklist

Before a plugin command that performs an on-chain write (--confirm / execute / --broadcast):

1. Resolve <from> from the plugin invocation. 2. Run:

   onchainos wallet gas-station status --chain solana [--from <solana_address>]

3. Branch on data.recommendation:

Skip pre-flight when

• The plugin invocation is dry-run / simulation.
• The plugin command is read-only (e.g. kamino-plugin positions, health-factor, reserves, quickstart).
• status already returned READY for this (solana, from) tuple in the current conversation.

Reactive recovery (plugin already failed)

When a plugin returns a vague error, follow references/gas-station.md → "Plugin Bail Recovery" (authoritative). If the plugin swallowed stdout so no Confirming JSON is visible, run onchainos wallet gas-station status --chain solana [--from <addr>] and branch per the Pre-flight checklist above. Exit-code quick-reference:

Exit codes (seen through a plugin)

Portal Actions — Policy Settings & Wallet Export

Load when: new user login (isNew: true), after wallet add, the user asks about Policy / spending limits / whitelist, or the user asks to export wallet / mnemonic / migrate.

Policy configuration and wallet export must be completed by the user on the Web portal. The Agent only detects the scenario, explains the risk, gives the jump link, and outputs the verbatim template below. The Agent must never display any mnemonic phrase or private key content in the conversation.

Templates

IMPORTANT: Print the matching template verbatim (translated to the user's language). The link and trailing navigation sentence are chosen by loginType (from wallet status, or the login / verify response). If loginType is unknown, run onchainos wallet status first; treat any unrecognized value as email.

Template: Wallet Export

Wallet export must be completed on the Web portal. Please note: once the export is complete, your current wallet will be permanently unbound from your email, and the Agent will no longer be able to operate this wallet. The system will automatically create a new empty wallet for your account. Before exporting, please transfer your assets to a safe address and stop any running strategies. Go to Wallet Export → {export_url}

>

{export_hint}

Template: Policy Settings

You can set per-transaction and daily limits for trades and transfers, as well as a transfer whitelist, to prevent excessive operations or transfers to unauthorized addresses. Go to Policy Setting → {policy_url}

>

{policy_hint}

Available Policy Rules

Policy only includes the following rules. Do NOT invent or mention any rules beyond this list (e.g., no "transaction count limit", no "gas limit", no "token blacklist"):

Trigger flows

The following are trigger conditions — when any is met, the Agent MUST output the corresponding guidance. Do not skip or omit.

New user login (isNew: true)

Handled in Authentication step 5 (SKILL.md) — output the Policy Settings template followed by the Wallet Export template (above).

New account via wallet add

After a successful wallet add, MUST output the Policy Settings template (above), prefixed with a short line such as "New account created.".

User asks about Policy

e.g., "How do I set a spending limit?", "What's my daily limit?", "How to configure whitelist?"

• Run onchainos wallet status and check the policy field.
• If any flag is true, first display the current settings (limits, used amounts).
• Then output the Policy Settings template (above).

User asks about wallet export

e.g., "How do I export my mnemonic?", "I want to migrate my wallet", "How do I import my wallet into a hardware wallet?"

Required sequence — follow exactly, no steps may be skipped or reordered:

Step 1. Confirm the user is logged in (so accountId is available locally). onchainos wallet status will surface it.

Step 2. Call onchainos competition user-status (no --activity-id). The command uses the active session's accountId automatically — no wallet args needed.

Step 3. Inspect results:

• If any entry has joinStatus=1 → output the warning below and stop. Do NOT output export instructions. Wait for explicit user confirmation before proceeding to Step 4.

Your wallet is registered for an Agentic Wallet trading competition. Exporting the wallet will forfeit your eligibility for this competition. Please confirm whether you want to proceed with the export.

• If no entry has joinStatus=1 → proceed directly to Step 4.

Step 4. Only after Step 2 and Step 3 complete, output the Wallet Export template (above).

Wallet Troubleshooting

Load this file when a wallet operation fails or an edge case is encountered.

Edge Cases

Send

• Insufficient balance: Check balance first. Warn if too low (include gas estimate for EVM).
• Wrong chain for token: --contract-token must exist on the specified chain.

History

• No transactions: Display "No transactions found" — not an error.
• Detail mode without chain: CLI requires --chain with --tx-hash. Ask user which chain.
• Detail mode `--address`: optional — the backend matches by --tx-hash / --order-id / --uop-hash. Pass the current account's address only as a hint.
• Empty cursor: No more pages.

Contract Call

• Missing input-data and unsigned-tx: CLI requires exactly one. Command will fail if neither is provided.
• Invalid calldata: Malformed hex causes API error. Help re-encode.
• Simulation failure: Show executeErrorMsg, do NOT broadcast.
• Insufficient gas: Suggest --gas-limit for higher limit.

Common (all sections)

• Region restriction (error code 50125 or 80001): Do NOT show raw error code. Display: "Service is not available in your region. Please switch to a supported region and try again."
• Not logged in (not logged in error): Session expired or wallet store missing. Tell user to run wallet login + wallet verify.
• Confirming response (exit code 2, error code 81362): Not an error — backend requires user confirmation. Display the message and follow instructions in next. Re-run with --force (or with Gas Station params) per the scenario.