Onchain OS Wallet

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

Stack arbitration. three.ws has two wallet stacks. This OKX onchainos stack is for OKX-managed / Agentic Wallet accounts and OKX-specific chains/venues (e.g. X Layer). For a plain three.ws-native send/transfer the user did not route through OKX, defer to the send-usdc skill (the awal / three.ws-native default). Do not sign here for a request that never named OKX.

Pre-flight Checks

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

Before wallet contract-call (custom calldata), run onchainos security tx-scan first.

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.

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.

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>

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:

• 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

FAQ

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

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.