Use this skill when the user provides a specific wallet address and wants to check its balance, token holdings, portfolio value, or DeFi positions. Typical triggers: 'check balance of 0xAbc...', 'show tokens in this address', 'what tokens does 0xAbc hold', 'portfolio value of this address', address portfolio value, multi-chain balance lookup for a given address. Supports XLayer, Solana, Ethereum, Base, BSC, Arbitrum, Polygon, and 20+ other chains. Do NOT use when the user asks about their own wallet without providing an address (e.g., 'check my wallet balance', 'show my assets', '查看我的余额') — use okx-agentic-wallet instead, which queries the logged-in wallet. Do NOT use for PnL analysis, DEX history, realized/unrealized profit — use okx-dex-market. Do NOT use for signal tracking — use okx-dex-signal. Do NOT use for meme scanning — use okx-dex-trenches. Do NOT use for programming questions about balance APIs or integration.
4 commands for supported chains, wallet total value, all token balances, and specific token balances.
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:
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.txtInvoke-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"installer-checksums.txt. On mismatch, stop and warn — the installer may have been tampered with.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.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.
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-msvcshasum -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.
okx-dex-marketokx-dex-marketokx-dex-tokenokx-dex-signalokx-dex-trenchesokx-dex-swapokx-onchain-gateway# Get supported chains for balance queries
onchainos portfolio chains
# Get total asset value on XLayer and Solana
onchainos portfolio total-value --address 0xYourWallet --chains "xlayer,solana"
# Get all token balances
onchainos portfolio all-balances --address 0xYourWallet --chains "xlayer,solana,ethereum"
# Check specific tokens (native OKB + USDC on XLayer)
onchainos portfolio token-balances --address 0xYourWallet --tokens "196:,196:0x74b7f16337b8972027f6196a17a631ac6de26d22"
The CLI accepts human-readable chain names and resolves them automatically.
| Chain | Name | chainIndex |
|---|---|---|
| XLayer | xlayer | 196 |
| Solana | solana | 501 |
| Ethereum | ethereum | 1 |
| Base | base | 8453 |
| BSC | bsc | 56 |
| Arbitrum | arbitrum | 42161 |
Address format note: EVM addresses (0x...) work across Ethereum/BSC/Polygon/Arbitrum/Base etc. Solana addresses (Base58) and Bitcoin addresses (UTXO) have different formats. Do NOT mix formats across chain types.
| # | Command | Description |
|---|---|---|
| 1 | onchainos portfolio chains | Get supported chains for balance queries |
| 2 | onchainos portfolio total-value --address <address> --chains <chains> | Get total asset value for a wallet (both params required) |
| 3 | onchainos portfolio all-balances --address <address> --chains <chains> | Get all token balances for a wallet (both params required) |
| 4 | onchainos portfolio token-balances --address ... --tokens ... | Get specific token balances |
This skill is often used before swap (to verify sufficient balance) or as portfolio entry point.
User: "Swap 1 SOL for BONK"
1. okx-dex-token onchainos token search --query BONK --chains solana → get tokenContractAddress
↓ tokenContractAddress
2. okx-wallet-portfolio onchainos portfolio all-balances --address <addr> --chains solana
→ verify SOL balance >= 1
↓ balance field (UI units) → convert to minimal units for swap
3. okx-dex-swap onchainos swap quote --from 11111111111111111111111111111111 --to <BONK_address> --amount 1000000000 --chain solana
4. okx-dex-swap onchainos swap execute --from ... --to <BONK_address> --amount 1000000000 --chain solana --wallet <addr>
Data handoff:
tokenContractAddress from token search → feeds into swap --from / --tobalance from portfolio is UI units; swap needs minimal units → multiply by 10^decimalUser: "Show my portfolio"
1. okx-wallet-portfolio onchainos portfolio total-value --address <addr> --chains "xlayer,solana,ethereum"
→ total USD value
2. okx-wallet-portfolio onchainos portfolio all-balances --address <addr> --chains "xlayer,solana,ethereum"
→ per-token breakdown
↓ top holdings by USD value
2b. (okx-dex-market) onchainos market portfolio-overview --address <addr> --chain ethereum -> PnL summary and win rate
3. okx-dex-token onchainos token price-info --address <address> --chain <chain> → enrich with 24h change, market cap
4. okx-dex-market onchainos market kline --address <address> --chain <chain> → price charts for tokens of interest
1. okx-wallet-portfolio onchainos portfolio all-balances --address <addr> --chains "xlayer,solana,ethereum"
→ list all holdings
↓ tokenContractAddress + chainIndex for each
2. okx-dex-token onchainos token price-info --address <address> --chain <chain> → get priceChange24H per token
3. Filter by negative change → user confirms which to sell
4. okx-dex-swap onchainos swap quote --from <token_addr> --to <native_addr> --amount ... --chain <chain> → get quote
5. okx-dex-swap onchainos swap execute --from <token_addr> --to <native_addr> --amount ... --chain <chain> --wallet <addr>
Key conversion: balance (UI units) × 10^decimal = amount (minimal units) for swap.
onchainos portfolio total-valueonchainos portfolio all-balancesonchainos portfolio token-balancesonchainos portfolio chains firstokx-dex-market (onchainos market portfolio-overview/portfolio-dex-history/portfolio-recent-pnl/portfolio-token-pnl)--chains xlayer, low gas, fast confirmation) as the default, then ask which chain the user prefers. Common set: "xlayer,solana,ethereum,base,bsc"--exclude-risk 0 (only works on ETH/BSC/SOL/BASE)0x1234...abcd — use tokenContractAddress from the response). Always include the contract address so the user can verify the token identity.x, w, st, r, m) may have incorrect symbol or price metadata from the balance API. After displaying balances, add a note:
⚠️ Token metadata (symbol and price) is sourced from the OKX balance API and may be inaccurate for wrapped or bridged tokens. Always verify the contract address and cross-check prices for high-value holdings.
After displaying results, suggest 2-3 relevant follow-up actions:
| Just completed | Suggest |
|---|---|
portfolio total-value | 1. View token-level breakdown → onchainos portfolio all-balances (this skill) 2. Check price trend for top holdings → okx-dex-market |
portfolio all-balances | 1. View detailed analytics for a token → okx-dex-token 2. Swap a token → okx-dex-swap 3. View PnL analysis → okx-dex-market (onchainos market portfolio-overview) |
portfolio token-balances | 1. View full portfolio across all tokens → onchainos portfolio all-balances (this skill) 2. Swap this token → okx-dex-swap |
Present conversationally, e.g.: "Would you like to see the price chart for your top holding, or swap any of these tokens?" — never expose skill names or endpoint paths to the user.
For detailed parameter tables, return field schemas, and usage examples for all 4 commands, consult:
references/cli-reference.md — Full CLI command reference with params, return fields, and examplesTo search for specific command details: grep -n "onchainos portfolio <command>" references/cli-reference.md
$0.00, not an erroronchainos portfolio chains first to confirm--exclude-risk not working: only supported on ETH/BSC/SOL/BASE--asset-type 2 to query DeFi holdings separately0x…) and Solana/UTXO addresses have incompatible formats. Passing an EVM address with a Solana chain (or vice versa) causes the entire request to fail with an API error — no partial results are returned. Always make separate requests: one call for EVM chains using the EVM address, a separate call for Solana using the Solana address⚠️ Service is not available in your region. Please switch to a supported region and try again.1.5 ETH), never base units (1500000000000000000)$1.2M)0x1234...abcd). For native tokens with empty tokenContractAddress, display (native).x, w, st, r, or m (common wrapped/bridged prefixes) or if the token name contains "BTC" / "ETH" but the reported price is far below BTC/ETH market price, add an inline ⚠️ price unverified flag next to the USD value and suggest running onchainos token price-info for that token.--chains supports up to 50 chain IDs (comma-separated, names or numeric)--asset-type: 0=all 1=tokens only 2=DeFi only (only for total-value)--exclude-risk only works on ETH(1)/BSC(56)/SOL(501)/BASE(8453)token-balances supports max 20 token entriesethereum → 1, solana → 501)