Help us improve
Share bugs, ideas, or general feedback.
From onchainos-skills
Performs OKX Agentic Wallet operations: auth, balance, transfers, contract calls, history, and Gas Station management on Solana.
npx claudepluginhub okx/onchainos-skills --plugin onchainos-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/onchainos-skills:okx-agentic-walletThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Wallet operations: authentication, balance, token transfers, transaction history, and smart contract calls.
Executes on-chain DEX swaps, wallet portfolio queries, gas estimation, and transaction broadcasting on EVM/Solana chains via OKX Web3 API. Use for token swaps, balance checks, or tx broadcast on Ethereum, Solana, Base, BSC, Arbitrum, Polygon, etc.
Interact with a local AgentLayer wallet runtime: check balances, transfer tokens, swap, DeFi operations, or x402 payments. Prefers wallet tools over shell commands and previews writes before execution.
Crypto wallet API + CLI for AI agents: wallet analysis (portfolio, positions, history, PnL), on-chain trading (swap, bridge, send), off-chain signing (EIP-191, EIP-712), wallet management, and agent tokens with policies for autonomous trading.
Share bugs, ideas, or general feedback.
Wallet operations: authentication, balance, token transfers, transaction history, and smart contract calls.
This document uses tagged blocks to indicate rule severity. In case of conflict, higher priority wins:
<NEVER> — Absolute prohibition. Violation may cause irreversible fund loss. Never bypass.<MUST> — Mandatory step. Skipping breaks functionality or safety.<SHOULD> — Best practice. Follow when possible; deviation acceptable with reason.--chain Resolution--chain accepts both numeric chain ID (e.g. 1, 501, 196) and human-readable names (e.g. ethereum, solana, xlayer).
bsc, "以太坊" → ethereum). The CLI accepts common human names / aliases (eth, bsc, sol, arb, base, xlayer, op, avax, …) and any numeric chain ID; the authoritative supported set is in _shared/chain-support.md (or run onchainos wallet chains).--chain."unsupported chain: ...", the name was not in the CLI mapping. Ask the user to confirm, and run onchainos wallet chains to show the full supported list.If no confident match: do NOT guess — ask the user. Display chain names as human-readable (e.g. "Ethereum", "BNB Chain"), never IDs.
Example flow:
# User says: "Show my balance on Ethereum"
→ onchainos wallet balance --chain ethereum
# Also valid: onchainos wallet balance --chain 1
Error handling:
# User says: "Show my balance on Fantom"
→ onchainos wallet balance --chain fantom
# If CLI returns "unsupported chain: fantom":
# → Ask user: "The chain 'Fantom' was not recognized. Its chain ID is 250 — would you like me to try with that?"
# → Or run `onchainos wallet chains` to check if the chain is supported
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.
CLI Reference: For full parameter tables, return field schemas, and usage examples, see cli-reference.md.
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, active account, and policy settings | No |
| A6 | onchainos wallet logout | Logout and clear all stored credentials | No |
| A7 | onchainos wallet chains | List all supported chains with names and IDs | No |
| A8 | onchainos wallet addresses [--chain <chain>] | Show wallet addresses grouped by chain category (X Layer, EVM, Solana) | No |
| A9 | onchainos wallet qrcode --address <addr> | Render a Unicode-block QR code for the given address (encoded verbatim) | No |
| # | 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 <chain> | Current account — all tokens on a specific chain | Yes |
| B3 | onchainos wallet balance --chain <chain> --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 |
| # | Command | Description | Auth Required |
|---|---|---|---|
| D1 | onchainos wallet send | Send native or contract tokens. Validates recipient format; simulation failure → show executeErrorMsg, do NOT broadcast. | Yes |
| D2 | onchainos wallet contract-call | Call a smart contract with custom calldata. Run onchainos security tx-scan first. | Yes |
The --force flag MUST ONLY be added when ALL of the following conditions are met:
--force once."confirming": true).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.
Pay gas with stablecoins (USDT / USDC / USDG) on Solana when SOL is insufficient. The backend dispatches Gas Station inside wallet send / wallet contract-call responses — when dispatched for a first-time activation or a token switch, the Agent must confirm with the user via the Scene A / C Confirming flow before the second-phase call; when a default token is already pinned, the CLI completes silently via the auto-path. No account upgrade, no per-chain setup — Solana Relayer is the native fee payer (signature index 0); user signs as the authority (signature index 1); gas is debited via an SPL transfer inside the same multi-signer transaction (signType=multiSignerTx).
| # | Command | Description | Auth Required |
|---|---|---|---|
| D-GS1 | onchainos wallet gas-station update-default-token --chain solana | Change the default gas payment token on Solana | Yes |
| D-GS2 | onchainos wallet gas-station enable --chain solana | Turn Gas Station on for Solana | Yes |
| D-GS3 | onchainos wallet gas-station disable --chain solana | Turn Gas Station off for Solana; the chain reverts to paying gas with SOL | Yes |
| D-GS4 | onchainos wallet gas-station status --chain solana | Read-only Gas Station readiness check on Solana. Used by third-party plugin pre-flight: agent runs this before invoking a plugin's on-chain command, branches on the returned recommendation (READY / ENABLE_GAS_STATION / INSUFFICIENT_ALL / HAS_PENDING_TX). Never broadcasts. | Yes |
**Load `references/gas-station.md`** when any of these happen: - `wallet send` / `wallet contract-call` response has `gasStationUsed=true`, or returns a Confirming response with a `gasStationTokenList` - User mentions: Gas Station / stablecoin gas / enable or disable Gas Station / change default gas token / what is Gas Station / how does it work / Jito Bundler compatibility / supported tokens / fees (in any language — recognize semantically)For user-facing reply wording (pre-confirmation prompts and success messages for enable / disable / update-default-token), use the sanctioned templates in
references/gas-station.md→ "User-Facing Reply Templates (Management Commands)".
gas-station.md is the core (dispatch model, Outcome → render map, Scene A / C / E copy, success reply). Two sibling references load on demand:
references/gas-station-faq.md — when the user asks a Gas Station FAQ.references/gas-station-edge.md — when an edge case fires (tx cap, Jito hard-block, async hash, pending tx, order-status query, native-SOL, history display).The skill always uses the verbatim product copy in these files. Never paraphrase those templates.
**"Gas Station" in this skill's context always refers to OKX Agentic Wallet's Gas Station feature on Solana** — a specific product shipped by this CLI + skill. It is **NOT** a general web3 category like "paymaster services" or "meta-transaction relayers". When the user asks any question about Gas Station (what is it / how does it work / which tokens / is there a fee / ...), the Agent MUST:references/gas-station-faq.md. Translate to the user's language; do NOT paraphrase the content.| # | 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 <chain> --address <addr> | Look up a specific transaction by hash | Yes |
| # | Command | Description | Auth Required |
|---|---|---|---|
| F1 | onchainos wallet sign-message --chain <chain> --from <addr> --message <msg> | personalSign (EIP-191). Supports EVM and Solana. Default mode. Supports --force to bypass confirmation prompts. | Yes |
| F2 | onchainos wallet sign-message --chain <chain> --from <addr> --type eip712 --message <json> | EIP-712 typed structured data. EVM only. Supports --force to bypass confirmation prompts. | Yes |
Some commands return confirming (exit code 2) when backend requires user confirmation (e.g., high-risk tx).
{
"confirming": true,
"message": "The human-readable prompt to show the user.",
"next": "Instructions for what the agent should do after user confirms."
}
message field to the user and ask for confirmation.next field (typically re-running the same command with --force flag appended).# 1. Run command without --force
onchainos wallet send --readable-amount "0.1" --recipient "0xAbc..." --chain 1
# → exit code 2, confirming: true → show message to user
# 2. User confirms → re-run with --force
onchainos wallet send --readable-amount "0.1" --recipient "0xAbc..." --chain 1 --force
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:
gas-station status recommendation branch, and skip conditions live in references/plugin-preflight.md.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".IMPORTANT: Several sections below instruct the Agent to output the Wallet Export template or the Policy Settings template. When triggered, 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.
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}
loginType | {export_url} | {export_hint} |
|---|---|---|
email | https://web3.okx.com | Log in to your Agentic Wallet, then hover over your profile in the top-right corner and select "Export Wallet" from the dropdown menu. |
ak | https://web3.okx.com/onchainos/dev-portal | Log in the Developer Portal using a plugin wallet or the OKX Wallet App that manages your API Key, and click Agentic Wallet → Wallet Export. |
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}
loginType | {policy_url} | {policy_hint} |
|---|---|---|
email | https://web3.okx.com/portfolio/agentic-wallet-policy | Log in to your Agentic Wallet, then hover over your profile in the top-right corner and select "Policy Setting" from the dropdown menu. |
ak | https://web3.okx.com/onchainos/dev-portal | Log in with the EOA wallet that created the Agentic Wallet and open the OKX Web3 Dev platform, and click on the Agentic Wallet - Policy Setting in the upper right corner to set security rules. |
For commands requiring auth (sections B, D, E), check login state:
onchainos wallet status. Read data.loggedIn from the response. If loggedIn: true, proceed.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
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>. Infer--localefrom conversation context and pass it in underscore form: Chinese (简体/繁体) →zh_CN, English →en_US, any other language passes through under its own code (e.g.ja_JP,ko_KR,fr_FR). If you cannot confidently determine the user's language, omit--locale— do not forceen_US. The CLI normalizes the value and drops anything unrecognizable; login still proceeds either way.
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
onchainos wallet login directly (the CLI picks up OKX_API_KEY / OKX_SECRET_KEY / OKX_PASSPHRASE from env).wallet login invocation returns a confirming: true response with exit code 2:
message.contains("not the account you used last time") (substring match on the verbatim discriminator, NOT the leading ⚠️ emoji) → this is the login-diff gate. The CLI message body already names the scenario and includes any masked identifiers; render it to the user verbatim (translated if needed; the discriminator substring stays English-only and verbatim — never translate, paraphrase, or modify it). Collect Yes/No:
--force appended (onchainos wallet login <email> --locale <locale> --force, or the AK equivalent with --force).confirming response → handle per its own discriminator.onchainos wallet balance.wallet verify or wallet login response contains "isNew": true, output the Policy Settings template followed by the Wallet Export template (load references/portal-actions.md). If "isNew": false, skip this step.After successful login: a wallet account is created automatically — never call
wallet addunless the user is already logged in and explicitly requests an additional account.
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-protectionalso requires the--jito-unsigned-txparameter. Without it, the command will fail. This parameter provides the Jito bundle unsigned transaction data needed for Solana MEV-protected routing.
🚨 Never substitute
--unsigned-txfor--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.
| Chain | MEV Protection | Additional Requirements |
|---|---|---|
| Ethereum | Yes | — |
| BSC | Yes | — |
| Base | Yes | — |
| Solana | Yes | Must also pass --jito-unsigned-tx |
| Other chains | Not supported | — |
contract-call# 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>
1.5 ETH), never base units (1500000000000000000)$1.2M, $340K)0x1234...abcd). For native tokens with empty tokenContractAddress, display (native).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.executeResult is false → show executeErrorMsg, do NOT broadcast.accessToken, refreshToken, apiKey, secretKey, passphrase, sessionKey, sessionCert, teeId, encryptedSessionSk, signingKey, raw tx data. Only show: email, accountId, accountName, isNew, addressList, txHash.0x-prefixed, 42 chars. Solana: Base58, 32-44 chars. Validate before sending.block > warn > empty (safe). Top-level action = highest priority from riskItemDetail.type(uint256).max or 2^256-1 or any equivalent "infinite" value.setApprovalForAll(operator, true) — this grants full control over all tokens of that type.Policy configuration must be completed by the user on the Web portal. The Agent only detects the scenario, provides guidance, and gives the jump link.
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"):
| Rule | Description | Field (from wallet status) |
|---|---|---|
| Per-transaction limit | Max USD amount per single transaction or transfer | singleTxLimit / singleTxFlag |
| Daily transfer limit | Max USD amount for transfers per day (resets at UTC 0:00) | dailyTransferTxLimit / dailyTransferTxFlag / dailyTransferTxUsed |
| Daily trade limit | Max USD amount for trades (swaps) per day (resets at UTC 0:00) | dailyTradeTxLimit / dailyTradeTxFlag / dailyTradeTxUsed |
| Transfer whitelist | Only allow transfers to pre-approved addresses | Configured on Web portal only |
The following three subsections are trigger conditions — when any condition is met, the Agent MUST output the corresponding guidance. Do not skip or omit.
isNew: true)Handled in Authentication step 5
wallet addAfter a successful wallet add, MUST output the Policy Settings template (see "User-Facing Message Templates"), prefixed with a short line such as "New account created.".
e.g., "How do I set a spending limit?", "What's my daily limit?", "How to configure whitelist?"
onchainos wallet status and check the policy field.The Agent must never display any mnemonic phrase or private key content in the conversation. The Agent's role is limited to: recognizing user intent, explaining the risks, and providing the Web portal link.
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:
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.
joinStatus=1 → proceed directly to Step 4.Step 4. Only after Step 2 and Step 3 complete, output the Wallet Export template (see "User-Facing Message Templates").
Load on error:
references/troubleshooting.md
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.