okx-agentic-wallet

okx-agentic-wallet

Onchain OS Wallet

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

Wallet Tips

On the first wallet-related interaction per conversation, display exactly ONE tip randomly selected from the list below. Do not repeat tips within the same conversation. Present it as-is (with emoji) AFTER the command result, on a separate line.

• 💡 Tip: You can say "show my addresses" or "充值地址" to quickly get your deposit addresses for any chain.

• 🔐 Tip: When prompted for Keychain access, please click "Always Allow". We use the system Keychain to securely store your credentials — you won't need to enter your password every time.

• 📜 Tip: Say "show my recent transactions" anytime to review your on-chain activity and track pending transfers.

• 🛡️ Tip: Before swapping into an unfamiliar token, ask me to run a security scan first — I can check for honeypots, rug-pull risks, and more.

• 👛 Tip: You can add multiple wallet accounts. Say "add a new wallet" to add one, and "switch account" to toggle between them.

Pre-flight Checks

Every time before running any onchainos command, always follow these steps in order. Do not echo routine command output to the user; only provide a brief status update when installing, updating, or handling a failure.

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 proceed to run the command (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.

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.

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

Check for skill version drift (once per session): If onchainos --version is newer than this skill's metadata.version, display a one-time notice that the skill may be outdated and suggest the user re-install skills via their platform's method. Do not block.

Do NOT auto-reinstall on command failures. Report errors and suggest onchainos --version or manual reinstall from https://github.com/okx/onchainos-skills.

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.

Skill Routing

• For supported chains / how many chains / chain list → onchainos wallet chains

• For wallet list / accounts overview / EVM+SOL addresses / balance / assets → Section B (authenticated balance)

• For wallet PnL / win rate / DEX history / realized/unrealized PnL → use okx-dex-market

• For portfolio balance queries (public address: total value, all tokens, specific tokens) → use okx-wallet-portfolio

• For token prices / K-lines → use okx-dex-market

• For token search / metadata → use okx-dex-token

• For smart money / whale / KOL signals → use okx-dex-signal

• For meme token scanning → use okx-dex-trenches

• For swap execution → use okx-dex-swap

• For transaction broadcasting (non-wallet) → use okx-onchain-gateway

• For security scanning (token, dapp, tx, sig) → use okx-security

• For token approval management (ERC-20 allowances, Permit2, risky approvals) → use okx-security

• For sending tokens or contract calls → Section D

• For transaction history → Section E

Parameter Rules

--chain Resolution

IMPORTANT: --chain only accepts a numeric chain ID (e.g. 1 for Ethereum, 501 for Solana, 196 for X Layer). Text values such as sol, xlayer, eth, or any chain name/alias are NOT accepted and will cause the command to fail.

Whenever a command requires --chain, follow these steps:

• Infer the intended chain from the user's input by reasoning against the common chain ID mapping above, or against chainName, showName, or alias values from onchainos wallet chains output (if available in conversation context). This is semantic matching — handle typos, abbreviations, and colloquial names (e.g. "ethereuma" → 1, "币安链" → 56). If you are not 100% confident in the match, ask the user to confirm before proceeding.

• Pass the realChainIndex to --chain. Never pass chain names, aliases, or user-provided text directly.

• If not found the chain, run onchainos wallet chains to get the full list and find the matching realChainIndex.

⚠️ If no chain can be confidently matched, do NOT guess. Ask the user to clarify, and show the available chain list for reference. When displaying chain names to the user, always use human-readable names (e.g. "Ethereum", "BNB Chain"), never the internal IDs.

Example flow:

# User says: "Show my balance on Ethereum"
# Step 1: infer chain from user input → Ethereum → realChainIndex=1
# Step 2: pass realChainIndex to --chain
          → onchainos wallet balance --chain 1

Applies to:

• onchainos wallet balance --chain

• onchainos wallet send --chain

• onchainos wallet contract-call --chain

• onchainos wallet history --chain (detail mode)

• onchainos wallet addresses --chain

--amount / --value Units

IMPORTANT: Always pass amounts in UI units (human-readable), never in base units (wei, lamports, etc.). The CLI handles unit conversion internally.

User says --amount value ❌ Wrong

"Transfer 0.15 ETH" "0.15" "150000000000000000" (wei)

"Send 100 USDC" "100" "100000000" (6 decimals)

"Send 0.5 SOL" "0.5" "500000000" (lamports)

Applies to:

• onchainos wallet send --amount

• onchainos wallet contract-call --value

Command Index

CLI Reference: For full parameter tables, return field schemas, and usage examples, see cli-reference.md.

A — Account Management

Login commands (wallet login, wallet verify) are covered in Step 2: Authentication.

Command Description Auth Required

A3 onchainos wallet add Add a new wallet account Yes

A4 onchainos wallet switch <account_id> Switch to a different wallet account No

A5 onchainos wallet status Show current login status and active account No

A6 onchainos wallet logout Logout and clear all stored credentials No

A7 onchainos wallet addresses [--chain <chainId>] Show wallet addresses grouped by chain category (X Layer, EVM, Solana) No

B — Authenticated Balance

Command Description Auth Required

B1 onchainos wallet balance Current account overview — EVM/SOL addresses, all-chain token list and total USD value Yes

B2 onchainos wallet balance --chain <chainId> Current account — all tokens on a specific chain Yes

B3 onchainos wallet balance --chain <chainId> --token-address <addr> Current account — specific token by contract address (requires --chain) Yes

B4 onchainos wallet balance --all All accounts batch assets — only use when user explicitly asks to see every account Yes

B5 onchainos wallet balance --force Force refresh — bypass all caches, re-fetch from API Yes

D — Transaction

Command Description Auth Required

D1 onchainos wallet send Send native or contract tokens to an address Yes

D2 onchainos wallet contract-call Call a smart contract with custom calldata Yes

⚠️ CRITICAL — Choosing the correct command: Using the wrong command may cause loss of funds. You MUST determine the user's exact intent before executing:

Intent Command Example

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

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

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

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

E — History

Mode Command Description Auth Required

E1 List onchainos wallet history Browse recent transactions with optional filters Yes

E2 Detail onchainos wallet history --tx-hash <hash> --chain <chainId> --address <addr> Look up a specific transaction by hash Yes

Operation Flow

Step 1: Intent Mapping

User Intent → Command

"Log in" / "sign in" / "登录钱包" Step 2 See Step 2: Authentication

"Verify OTP" / "验证OTP" Step 2 See Step 2: Authentication

"Add a new wallet" / "添加钱包" A wallet add

"Switch account" / "切换账户" A wallet switch <account_id>

"Am I logged in?" / "钱包状态" A wallet status

"Show my addresses" / "我的地址" / "钱包地址" / "充值" / "充币" / "收款" / "deposit" / "receive" A wallet addresses

"Log out" / "退出登录" A wallet logout

"Show my balance" / "余额" / "我的资产" B wallet balance (current account)

"Show all accounts' balance" / "所有钱包资产" / "Show all accounts' assets" B wallet balance --all

"Refresh my wallet" / "刷新钱包" / "同步余额" B wallet balance --force

"Balance on Ethereum" / "What's on Solana?" B wallet balance --chain <chainId>

"Check token 0x3883... on Ethereum" B wallet balance --chain 1 --token-address <addr>

"Send 0.01 ETH to 0xAbc" / "转账" / "发送代币" D wallet send --amount "0.01" --receipt <addr> --chain 1

"Transfer 100 USDC on Ethereum" D wallet send --amount "100" --receipt <addr> --chain 1 --contract-token <addr>

"Show my recent transactions" / "交易历史" E wallet history

"Check tx 0xabc..." / "tx status" E wallet history --tx-hash <hash> --chain <chainId> --address <addr>

"Approve USDC for contract" / "合约调用" D wallet contract-call --to <addr> --chain 1 --input-data <hex>

"Execute Solana program" D wallet contract-call --to <addr> --chain 501 --unsigned-tx <base58>

Step 2: Authentication

For commands requiring auth (sections B, D, E), check login state:

• Run onchainos wallet status. If loggedIn: true, proceed.

• If not logged in, or the user explicitly requests to re-login:

2a. Display the following message to the user verbatim (translated 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

• 2b. Once the user provides their email, run: onchainos wallet login <email> --locale <locale>. Then display the following message verbatim (translated to the user's language):

English: "A verification code has been sent to {email}. Please check your inbox and tell me the code." Chinese: "验证码已发送到 {email}，请查收邮件并告诉我验证码。" Once the user provides the code, run: onchainos wallet verify <code>. AI should always infer --locale from conversation context and include it:

Chinese (简体/繁体, or user writes in Chinese) → zh-CN

• Japanese (user writes in Japanese) → ja-JP

• English or any other language → en-US (default)

If you cannot confidently determine the user's language, default to en-US.

• If the user declines to provide an email:

3a. Display the following message to the user verbatim (translated to the user's language):

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

• 3b. If the user confirms they want to use API Key, first check whether an API Key switch is needed: Use the wallet status result (from step 1 or re-run). If loginType is "ak" and the returned apiKey differs from the current environment variable OKX_API_KEY, show both keys to the user and ask to confirm the switch. If the user confirms, run onchainos wallet login --force. If apiKey is absent, empty, or identical, skip the confirmation and run onchainos wallet login directly.

• 3c. After silent login succeeds, inform the user that they have been logged in via the API Key method.

• After login succeeds, display the full account list w

...