OKX DEX Token Info CLI
5 commands for token search, metadata, detailed pricing, rankings, and holder distribution.
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.
Confirm installed: Run which onchainos. If not found, install it:
curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh
If the install script fails, ask the user to install manually following the instructions at: https://github.com/okx/onchainos-skills
Check for updates: Read ~/.onchainos/last_check and compare it with the current timestamp:
cached_ts=$(cat ~/.onchainos/last_check 2>/dev/null || true)
now=$(date +%s)
If any onchainos command fails with an unexpected error during this
session, try reinstalling before giving up:
curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh
Create a .env file in the project root to override the default API credentials (optional — skip this for quick start):
OKX_API_KEY= # or OKX_ACCESS_KEY
OKX_SECRET_KEY=
OKX_PASSPHRASE=
Skill Routing
- For real-time prices / K-lines / trade history → use
okx-dex-market
- For swap execution → use
okx-dex-swap
- For transaction broadcasting → use
okx-onchain-gateway
- For wallet balances / portfolio → use
okx-wallet-portfolio
- For meme token safety (dev reputation, rug pull, bundlers, similar tokens by same dev) → use
okx-dex-market
- For smart money / whale / KOL signals → use
okx-dex-market
Quickstart
# Search token
onchainos token search xETH --chains "ethereum,solana"
# Get detailed price info
onchainos token price-info 0xe7b000003a45145decf8a28fc755ad5ec5ea025a --chain xlayer
# What's trending on Solana by volume?
onchainos token trending --chains solana --sort-by 5 --time-frame 4
# Check holder distribution
onchainos token holders 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain xlayer
Chain Name Support
The CLI accepts human-readable chain names (e.g., ethereum, solana, xlayer) 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 |
Command Index
| # |
Command |
Description |
| 1 |
onchainos token search <query> |
Search for tokens by name, symbol, or address |
| 2 |
onchainos token info <address> |
Get token basic info (name, symbol, decimals, logo) |
| 3 |
onchainos token price-info <address> |
Get detailed price info (price, market cap, liquidity, volume, 24h change) |
| 4 |
onchainos token trending |
Get trending / top tokens |
| 5 |
onchainos token holders <address> |
Get token holder distribution (top 20) |
Boundary: token vs market skill
| Need |
Use this skill (okx-dex-token) |
Use okx-dex-market instead |
| Search token by name/symbol |
onchainos token search |
- |
| Token metadata (decimals, logo) |
onchainos token info |
- |
| Price + market cap + liquidity + multi-timeframe change |
onchainos token price-info |
- |
| Token ranking (trending) |
onchainos token trending |
- |
| Holder distribution |
onchainos token holders |
- |
| Raw real-time price (single value) |
- |
onchainos market price |
| K-line / candlestick chart |
- |
onchainos market kline |
| Trade history (buy/sell log) |
- |
onchainos market trades |
| Index price (multi-source aggregate) |
- |
onchainos market index |
| Meme token dev reputation / rug pull |
- |
onchainos market memepump-token-dev-info |
| Bundle/sniper detection |
- |
onchainos market memepump-token-bundle-info |
| Similar tokens by same creator |
- |
onchainos market memepump-similar-tokens |
Rule of thumb: okx-dex-token = token discovery & enriched analytics (search, trending, holders, market cap). okx-dex-market = raw price feeds, charts, smart money signals & meme pump scanning (including dev reputation, rug pull checks, bundler analysis).
Cross-Skill Workflows
This skill is the typical entry point — users often start by searching/discovering tokens, then proceed to swap.
Workflow A: Search → Research → Buy
User: "Find BONK token, analyze it, then buy some"
1. okx-dex-token onchainos token search BONK --chains solana → get tokenContractAddress, chain, price
↓ tokenContractAddress
2. okx-dex-token onchainos token price-info <address> --chain solana → market cap, liquidity, volume24H, priceChange24H
3. okx-dex-token onchainos token holders <address> --chain solana → top 20 holders distribution
4. okx-dex-market onchainos market kline <address> --chain solana --bar 1H → hourly price chart
↓ user decides to buy
5. okx-dex-swap onchainos swap quote --from ... --to <address> --amount ... --chain solana
6. okx-dex-swap onchainos swap swap --from ... --to <address> --amount ... --chain solana --wallet <addr>
Data handoff:
tokenContractAddress from step 1 → reused in all subsequent stepschain from step 1 → reused in all subsequent stepsdecimal from step 1 or onchainos token info → needed for minimal unit conversion in swap
Workflow B: Discover Trending → Investigate → Trade
User: "What's trending on Solana?"
1. okx-dex-token onchainos token trending --chains solana --sort-by 5 --time-frame 4 → top tokens by 24h volume
↓ user picks a token
2. okx-dex-token onchainos token price-info <address> --chain solana → detailed analytics
3. okx-dex-token onchainos token holders <address> --chain solana → check if whale-dominated
4. okx-dex-market onchainos market kline <address> --chain solana → K-line for visual trend
↓ user decides to trade
5. okx-dex-swap onchainos swap swap --from ... --to ... --amount ... --chain solana --wallet <addr>
Workflow C: Token Verification Before Swap
Before swapping an unknown token, always verify:
1. okx-dex-token onchainos token search <name> → find token
2. Check communityRecognized:
- true → proceed with normal caution
- false → warn user about risk
3. okx-dex-token onchainos token price-info <address> → check liquidity:
- liquidity < $10K → warn about high slippage risk
- liquidity < $1K → strongly discourage trade
4. okx-dex-swap onchainos swap quote ... → check isHoneyPot and taxRate
5. If all checks pass → proceed to swap
Operation Flow
Step 1: Identify Intent
- Search for a token →
onchainos token search
- Get token metadata →
onchainos token info
- Get price + market cap + liquidity →
onchainos token price-info
- View rankings →
onchainos token trending
- View holder distribution →
onchainos token holders
Step 2: Collect Parameters
- Missing chain → recommend XLayer (
--chain xlayer, low gas, fast confirmation) as the default, then ask which chain the user prefers
- Only have token name, no address → use
onchainos token search first
- For search,
--chains defaults to "1,501" (Ethereum + Solana)
- For trending,
--sort-by defaults to 5 (volume), --time-frame defaults to 4 (24h)
Step 3: Call and Display
- Search results: show name, symbol, chain, price, 24h change
- Indicate
communityRecognized status for trust signaling
- Price info: show market cap, liquidity, and volume together
Step 4: Suggest Next Steps
After displaying results, suggest 2-3 relevant follow-up actions based on the command just executed:
| Just called |
Suggest |
token search |
1. View detailed analytics (market cap, liquidity) → onchainos token price-info (this skill) 2. View price chart → okx-dex-market 3. Buy/swap this token → okx-dex-swap |
token info |
1. View price and market data → onchainos token price-info (this skill) 2. Check holder distribution → onchainos token holders (this skill) |
token price-info |
1. View K-line chart → okx-dex-market 2. Check holder distribution → onchainos token holders (this skill) 3. Buy/swap this token → okx-dex-swap |
token trending |
1. View details for a specific token → onchainos token price-info (this skill) 2. View price chart → okx-dex-market 3. Buy a trending token → okx-dex-swap |
token holders |
1. View price trend → okx-dex-market 2. Buy/swap this token → okx-dex-swap |
Present conversationally, e.g.: "Would you like to see the price chart or check the holder distribution?" — never expose skill names or endpoint paths to the user.
CLI Command Reference
1. onchainos token search
Search for tokens by name, symbol, or contract address.
onchainos token search <query> [--chains <chains>]
| Param |
Required |
Default |
Description |
<query> |
Yes |
- |
Keyword: token name, symbol, or contract address (positional) |
--chains |
No |
"1,501" |
Chain names or IDs, comma-separated (e.g., "ethereum,solana" or "196,501") |
Return fields:
| Field |
Type |
Description |
tokenContractAddress |
String |
Token contract address |
tokenSymbol |
String |
Token symbol (e.g., "ETH") |
tokenName |
String |
Token full name |
tokenLogoUrl |
String |
Token logo image URL |
chainIndex |
String |
Chain identifier |
decimal |
String |
Token decimals (e.g., "18") |
price |
String |
Current price in USD |
change |
String |
24-hour price change percentage |
marketCap |
String |
Market capitalization in USD |
liquidity |
String |
Liquidity in USD |
holders |
String |
Number of token holders |
explorerUrl |
String |
Block explorer URL for the token |
tagList.communityRecognized |
Boolean |
true = listed on Top 10 CEX or community verified |
2. onchainos token info
Get token basic info (name, symbol, decimals, logo).
onchainos token info <address> [--chain <chain>]
| Param |
Required |
Default |
Description |
<address> |
Yes |
- |
Token contract address (positional) |
--chain |
No |
ethereum |
Chain name |
Return fields:
| Field |
Type |
Description |
tokenName |
String |
Token full name |
tokenSymbol |
String |
Token symbol (e.g., "ETH") |
tokenLogoUrl |
String |
Token logo image URL |
decimal |
String |
Token decimals (e.g., "18") |
tokenContractAddress |
String |
Token contract address |
tagList.communityRecognized |
Boolean |
true = listed on Top 10 CEX or community verified |
3. onchainos token price-info
Get detailed price info including market cap, liquidity, volume, and multi-timeframe price changes.
onchainos token price-info <address> [--chain <chain>]
| Param |
Required |
Default |
Description |
<address> |
Yes |
- |
Token contract address (positional) |
--chain |
No |
ethereum |
Chain name |
Return fields:
| Field |
Type |
Description |
price |
String |
Current price in USD |
time |
String |
Timestamp (Unix milliseconds) |
marketCap |
String |
Market capitalization in USD |
liquidity |
String |
Total liquidity in USD |
circSupply |
String |
Circulating supply |
holders |
String |
Number of token holders |
tradeNum |
String |
24-hour trade count |
priceChange5M |
String |
Price change percentage — last 5 minutes |
priceChange1H |
String |
Price change percentage — last 1 hour |
priceChange4H |
String |
Price change percentage — last 4 hours |
priceChange24H |
String |
Price change percentage — last 24 hours |
volume5M |
String |
Trading volume (USD) — last 5 minutes |
volume1H |
String |
Trading volume (USD) — last 1 hour |
volume4H |
String |
Trading volume (USD) — last 4 hours |
volume24H |
String |
Trading volume (USD) — last 24 hours |
txs5M |
String |
Transaction count — last 5 minutes |
txs1H |
String |
Transaction count — last 1 hour |
txs4H |
String |
Transaction count — last 4 hours |
txs24H |
String |
Transaction count — last 24 hours |
maxPrice |
String |
24-hour highest price |
minPrice |
String |
24-hour lowest price |
4. onchainos token trending
Get trending / top tokens by various criteria.
onchainos token trending [--chains <chains>] [--sort-by <sort>] [--time-frame <frame>]
| Param |
Required |
Default |
Description |
--chains |
No |
"1,501" |
Chain names or IDs, comma-separated |
--sort-by |
No |
"5" |
Sort: 2=price change, 5=volume, 6=market cap |
--time-frame |
No |
"4" |
Window: 1=5min, 2=1h, 3=4h, 4=24h |
Return fields:
| Field |
Type |
Description |
tokenSymbol |
String |
Token symbol |
tokenContractAddress |
String |
Token contract address |
tokenLogoUrl |
String |
Token logo image URL |
chainIndex |
String |
Chain identifier |
price |
String |
Current price in USD |
change |
String |
Price change percentage (for selected time frame) |
volume |
String |
Trading volume in USD (for selected time frame) |
marketCap |
String |
Market capitalization in USD |
liquidity |
String |
Total liquidity in USD |
holders |
String |
Number of token holders |
uniqueTraders |
String |
Number of unique traders (for selected time frame) |
txsBuy |
String |
Buy transaction count (for selected time frame) |
txsSell |
String |
Sell transaction count (for selected time frame) |
txs |
String |
Total transaction count (for selected time frame) |
firstTradeTime |
String |
First trade timestamp (Unix milliseconds) |
5. onchainos token holders
Get token holder distribution (top 20).
onchainos token holders <address> [--chain <chain>]
| Param |
Required |
Default |
Description |
<address> |
Yes |
- |
Token contract address (positional) |
--chain |
No |
ethereum |
Chain name |
Return fields (top 20 holders):
| Field |
Type |
Description |
data[].holdAmount |
String |
Token amount held |
data[].holderWalletAddress |
String |
Holder wallet address |
Input / Output Examples
User says: "Search for xETH token on XLayer"
onchainos token search xETH --chains xlayer
# → Display:
# xETH (0xe7b0...) - XLayer
# Price: $X,XXX.XX | 24h: +X% | Market Cap: $XXM | Liquidity: $XXM
# Community Recognized: Yes
User says: "What's trending on Solana by volume?"
onchainos token trending --chains solana --sort-by 5 --time-frame 4
# → Display top tokens sorted by 24h volume:
# #1 SOL - Vol: $1.2B | Change: +3.5% | MC: $80B
# #2 BONK - Vol: $450M | Change: +12.8% | MC: $1.5B
# ...
User says: "Who are the top holders of this token?"
onchainos token holders 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain xlayer
# → Display top 20 holders with amounts and addresses
Edge Cases
- Token not found: suggest verifying the contract address (symbols can collide)
- Same symbol on multiple chains: show all matches with chain names
- Unverified token:
communityRecognized = false — warn user about risk
- Too many results: name/symbol search caps at 100 — suggest using exact contract address
- Network error: retry once
- Region restriction (error code 50125 or 80001): do NOT show the raw error code to the user. Instead, display a friendly message:
⚠️ Service is not available in your region. Please switch to a supported region and try again.
Amount Display Rules
- Use appropriate precision: 2 decimals for high-value, significant digits for low-value
- Market cap / liquidity in shorthand ($1.2B, $45M)
- 24h change with sign and color hint (+X% / -X%)
Global Notes
- Use contract address as primary identity — symbols can collide across tokens
communityRecognized = true means listed on Top 10 CEX or community verified- The CLI resolves chain names automatically (e.g.,
ethereum → 1, solana → 501)
- EVM addresses must be all lowercase
- The CLI handles authentication internally via environment variables — see Prerequisites step 4 for default values
1---2name: okx-dex-token-23description: This skill should be used when the user asks to 'find a token', 'search for a token', 'look up PEPE', 'what's trending', 'top tokens', 'trending tokens on Solana', 'token rankings', 'who holds this token', 'holder distribution', 'token market cap', 'token liquidity', 'research a token', 'tell me about this token', 'token info', or mentions searching for tokens, discovering trending tokens, viewing rankings, checking holder distribution, or analyzing market cap and liquidity. Covers token search, metadata, market cap, liquidity, volume, trending rankings, and holder analysis across XLayer, Solana, Ethereum, Base, BSC, Arbitrum, Polygon, and 20+ other chains. Do NOT use when the user says only a generic word like 'tokens' without a specific token name or action. For price charts, K-line, trades, or signals use okx-dex-market. For meme token safety, dev reputation, rug pulls, or bundle/sniper detection use okx-dex-market.4license: Apache-2.05---67# OKX DEX Token Info CLI895 commands for token search, metadata, detailed pricing, rankings, and holder distribution.1011## Pre-flight Checks1213Every 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.14151. **Confirm installed**: Run `which onchainos`. If not found, install it:16 ```bash17 curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh18 ```19 If the install script fails, ask the user to install manually following the instructions at: https://github.com/okx/onchainos-skills20212. **Check for updates**: Read `~/.onchainos/last_check` and compare it with the current timestamp:22 ```bash23 cached_ts=$(cat ~/.onchainos/last_check 2>/dev/null || true)24 now=$(date +%s)25 ```26 - If `cached_ts` is non-empty and `(now - cached_ts) < 43200` (12 hours), skip the update and proceed.27 - Otherwise (file missing or older than 12 hours), run the installer to check for updates:28 ```bash29 curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh30 ```31 If a newer version is installed, tell the user and suggest updating their onchainos skills from https://github.com/okx/onchainos-skills to get the latest features.323. If any `onchainos` command fails with an unexpected error during this33 session, try reinstalling before giving up:34 ```bash35 curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh36 ```374. Create a `.env` file in the project root to override the default API credentials (optional — skip this for quick start):38 ```39 OKX_API_KEY= # or OKX_ACCESS_KEY40 OKX_SECRET_KEY=41 OKX_PASSPHRASE=42 ```4344## Skill Routing4546- For real-time prices / K-lines / trade history → use `okx-dex-market`47- For swap execution → use `okx-dex-swap`48- For transaction broadcasting → use `okx-onchain-gateway`49- For wallet balances / portfolio → use `okx-wallet-portfolio`50- For meme token safety (dev reputation, rug pull, bundlers, similar tokens by same dev) → use `okx-dex-market`51- For smart money / whale / KOL signals → use `okx-dex-market`5253## Quickstart5455```bash56# Search token57onchainos token search xETH --chains "ethereum,solana"5859# Get detailed price info60onchainos token price-info 0xe7b000003a45145decf8a28fc755ad5ec5ea025a --chain xlayer6162# What's trending on Solana by volume?63onchainos token trending --chains solana --sort-by 5 --time-frame 46465# Check holder distribution66onchainos token holders 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain xlayer67```6869## Chain Name Support7071The CLI accepts human-readable chain names (e.g., `ethereum`, `solana`, `xlayer`) and resolves them automatically.7273| Chain | Name | chainIndex |74|---|---|---|75| XLayer | `xlayer` | `196` |76| Solana | `solana` | `501` |77| Ethereum | `ethereum` | `1` |78| Base | `base` | `8453` |79| BSC | `bsc` | `56` |80| Arbitrum | `arbitrum` | `42161` |8182## Command Index8384| # | Command | Description |85|---|---|---|86| 1 | `onchainos token search <query>` | Search for tokens by name, symbol, or address |87| 2 | `onchainos token info <address>` | Get token basic info (name, symbol, decimals, logo) |88| 3 | `onchainos token price-info <address>` | Get detailed price info (price, market cap, liquidity, volume, 24h change) |89| 4 | `onchainos token trending` | Get trending / top tokens |90| 5 | `onchainos token holders <address>` | Get token holder distribution (top 20) |9192## Boundary: token vs market skill9394| Need | Use this skill (`okx-dex-token`) | Use `okx-dex-market` instead |95|---|---|---|96| Search token by name/symbol | `onchainos token search` | - |97| Token metadata (decimals, logo) | `onchainos token info` | - |98| Price + market cap + liquidity + multi-timeframe change | `onchainos token price-info` | - |99| Token ranking (trending) | `onchainos token trending` | - |100| Holder distribution | `onchainos token holders` | - |101| Raw real-time price (single value) | - | `onchainos market price` |102| K-line / candlestick chart | - | `onchainos market kline` |103| Trade history (buy/sell log) | - | `onchainos market trades` |104| Index price (multi-source aggregate) | - | `onchainos market index` |105| Meme token dev reputation / rug pull | - | `onchainos market memepump-token-dev-info` |106| Bundle/sniper detection | - | `onchainos market memepump-token-bundle-info` |107| Similar tokens by same creator | - | `onchainos market memepump-similar-tokens` |108109**Rule of thumb**: `okx-dex-token` = token discovery & enriched analytics (search, trending, holders, market cap). `okx-dex-market` = raw price feeds, charts, smart money signals & meme pump scanning (including dev reputation, rug pull checks, bundler analysis).110111## Cross-Skill Workflows112113This skill is the typical **entry point** — users often start by searching/discovering tokens, then proceed to swap.114115### Workflow A: Search → Research → Buy116117> User: "Find BONK token, analyze it, then buy some"118119```1201. okx-dex-token onchainos token search BONK --chains solana → get tokenContractAddress, chain, price121 ↓ tokenContractAddress1222. okx-dex-token onchainos token price-info <address> --chain solana → market cap, liquidity, volume24H, priceChange24H1233. okx-dex-token onchainos token holders <address> --chain solana → top 20 holders distribution1244. okx-dex-market onchainos market kline <address> --chain solana --bar 1H → hourly price chart125 ↓ user decides to buy1265. okx-dex-swap onchainos swap quote --from ... --to <address> --amount ... --chain solana1276. okx-dex-swap onchainos swap swap --from ... --to <address> --amount ... --chain solana --wallet <addr>128```129130**Data handoff**:131- `tokenContractAddress` from step 1 → reused in all subsequent steps132- `chain` from step 1 → reused in all subsequent steps133- `decimal` from step 1 or `onchainos token info` → needed for minimal unit conversion in swap134135### Workflow B: Discover Trending → Investigate → Trade136137> User: "What's trending on Solana?"138139```1401. okx-dex-token onchainos token trending --chains solana --sort-by 5 --time-frame 4 → top tokens by 24h volume141 ↓ user picks a token1422. okx-dex-token onchainos token price-info <address> --chain solana → detailed analytics1433. okx-dex-token onchainos token holders <address> --chain solana → check if whale-dominated1444. okx-dex-market onchainos market kline <address> --chain solana → K-line for visual trend145 ↓ user decides to trade1465. okx-dex-swap onchainos swap swap --from ... --to ... --amount ... --chain solana --wallet <addr>147```148149### Workflow C: Token Verification Before Swap150151Before swapping an unknown token, always verify:152153```1541. okx-dex-token onchainos token search <name> → find token1552. Check communityRecognized:156 - true → proceed with normal caution157 - false → warn user about risk1583. okx-dex-token onchainos token price-info <address> → check liquidity:159 - liquidity < $10K → warn about high slippage risk160 - liquidity < $1K → strongly discourage trade1614. okx-dex-swap onchainos swap quote ... → check isHoneyPot and taxRate1625. If all checks pass → proceed to swap163```164165## Operation Flow166167### Step 1: Identify Intent168169- Search for a token → `onchainos token search`170- Get token metadata → `onchainos token info`171- Get price + market cap + liquidity → `onchainos token price-info`172- View rankings → `onchainos token trending`173- View holder distribution → `onchainos token holders`174175### Step 2: Collect Parameters176177- Missing chain → recommend XLayer (`--chain xlayer`, low gas, fast confirmation) as the default, then ask which chain the user prefers178- Only have token name, no address → use `onchainos token search` first179- For search, `--chains` defaults to `"1,501"` (Ethereum + Solana)180- For trending, `--sort-by` defaults to `5` (volume), `--time-frame` defaults to `4` (24h)181182### Step 3: Call and Display183184- Search results: show name, symbol, chain, price, 24h change185- Indicate `communityRecognized` status for trust signaling186- Price info: show market cap, liquidity, and volume together187188### Step 4: Suggest Next Steps189190After displaying results, suggest 2-3 relevant follow-up actions based on the command just executed:191192| Just called | Suggest |193|---|---|194| `token search` | 1. View detailed analytics (market cap, liquidity) → `onchainos token price-info` (this skill) 2. View price chart → `okx-dex-market` 3. Buy/swap this token → `okx-dex-swap` |195| `token info` | 1. View price and market data → `onchainos token price-info` (this skill) 2. Check holder distribution → `onchainos token holders` (this skill) |196| `token price-info` | 1. View K-line chart → `okx-dex-market` 2. Check holder distribution → `onchainos token holders` (this skill) 3. Buy/swap this token → `okx-dex-swap` |197| `token trending` | 1. View details for a specific token → `onchainos token price-info` (this skill) 2. View price chart → `okx-dex-market` 3. Buy a trending token → `okx-dex-swap` |198| `token holders` | 1. View price trend → `okx-dex-market` 2. Buy/swap this token → `okx-dex-swap` |199200Present conversationally, e.g.: "Would you like to see the price chart or check the holder distribution?" — never expose skill names or endpoint paths to the user.201202## CLI Command Reference203204### 1. onchainos token search205206Search for tokens by name, symbol, or contract address.207208```bash209onchainos token search <query> [--chains <chains>]210```211212| Param | Required | Default | Description |213|---|---|---|---|214| `<query>` | Yes | - | Keyword: token name, symbol, or contract address (positional) |215| `--chains` | No | `"1,501"` | Chain names or IDs, comma-separated (e.g., `"ethereum,solana"` or `"196,501"`) |216217**Return fields**:218219| Field | Type | Description |220|---|---|---|221| `tokenContractAddress` | String | Token contract address |222| `tokenSymbol` | String | Token symbol (e.g., `"ETH"`) |223| `tokenName` | String | Token full name |224| `tokenLogoUrl` | String | Token logo image URL |225| `chainIndex` | String | Chain identifier |226| `decimal` | String | Token decimals (e.g., `"18"`) |227| `price` | String | Current price in USD |228| `change` | String | 24-hour price change percentage |229| `marketCap` | String | Market capitalization in USD |230| `liquidity` | String | Liquidity in USD |231| `holders` | String | Number of token holders |232| `explorerUrl` | String | Block explorer URL for the token |233| `tagList.communityRecognized` | Boolean | `true` = listed on Top 10 CEX or community verified |234235### 2. onchainos token info236237Get token basic info (name, symbol, decimals, logo).238239```bash240onchainos token info <address> [--chain <chain>]241```242243| Param | Required | Default | Description |244|---|---|---|---|245| `<address>` | Yes | - | Token contract address (positional) |246| `--chain` | No | `ethereum` | Chain name |247248**Return fields**:249250| Field | Type | Description |251|---|---|---|252| `tokenName` | String | Token full name |253| `tokenSymbol` | String | Token symbol (e.g., `"ETH"`) |254| `tokenLogoUrl` | String | Token logo image URL |255| `decimal` | String | Token decimals (e.g., `"18"`) |256| `tokenContractAddress` | String | Token contract address |257| `tagList.communityRecognized` | Boolean | `true` = listed on Top 10 CEX or community verified |258259### 3. onchainos token price-info260261Get detailed price info including market cap, liquidity, volume, and multi-timeframe price changes.262263```bash264onchainos token price-info <address> [--chain <chain>]265```266267| Param | Required | Default | Description |268|---|---|---|---|269| `<address>` | Yes | - | Token contract address (positional) |270| `--chain` | No | `ethereum` | Chain name |271272**Return fields**:273274| Field | Type | Description |275|---|---|---|276| `price` | String | Current price in USD |277| `time` | String | Timestamp (Unix milliseconds) |278| `marketCap` | String | Market capitalization in USD |279| `liquidity` | String | Total liquidity in USD |280| `circSupply` | String | Circulating supply |281| `holders` | String | Number of token holders |282| `tradeNum` | String | 24-hour trade count |283| `priceChange5M` | String | Price change percentage — last 5 minutes |284| `priceChange1H` | String | Price change percentage — last 1 hour |285| `priceChange4H` | String | Price change percentage — last 4 hours |286| `priceChange24H` | String | Price change percentage — last 24 hours |287| `volume5M` | String | Trading volume (USD) — last 5 minutes |288| `volume1H` | String | Trading volume (USD) — last 1 hour |289| `volume4H` | String | Trading volume (USD) — last 4 hours |290| `volume24H` | String | Trading volume (USD) — last 24 hours |291| `txs5M` | String | Transaction count — last 5 minutes |292| `txs1H` | String | Transaction count — last 1 hour |293| `txs4H` | String | Transaction count — last 4 hours |294| `txs24H` | String | Transaction count — last 24 hours |295| `maxPrice` | String | 24-hour highest price |296| `minPrice` | String | 24-hour lowest price |297298### 4. onchainos token trending299300Get trending / top tokens by various criteria.301302```bash303onchainos token trending [--chains <chains>] [--sort-by <sort>] [--time-frame <frame>]304```305306| Param | Required | Default | Description |307|---|---|---|---|308| `--chains` | No | `"1,501"` | Chain names or IDs, comma-separated |309| `--sort-by` | No | `"5"` | Sort: `2`=price change, `5`=volume, `6`=market cap |310| `--time-frame` | No | `"4"` | Window: `1`=5min, `2`=1h, `3`=4h, `4`=24h |311312**Return fields**:313314| Field | Type | Description |315|---|---|---|316| `tokenSymbol` | String | Token symbol |317| `tokenContractAddress` | String | Token contract address |318| `tokenLogoUrl` | String | Token logo image URL |319| `chainIndex` | String | Chain identifier |320| `price` | String | Current price in USD |321| `change` | String | Price change percentage (for selected time frame) |322| `volume` | String | Trading volume in USD (for selected time frame) |323| `marketCap` | String | Market capitalization in USD |324| `liquidity` | String | Total liquidity in USD |325| `holders` | String | Number of token holders |326| `uniqueTraders` | String | Number of unique traders (for selected time frame) |327| `txsBuy` | String | Buy transaction count (for selected time frame) |328| `txsSell` | String | Sell transaction count (for selected time frame) |329| `txs` | String | Total transaction count (for selected time frame) |330| `firstTradeTime` | String | First trade timestamp (Unix milliseconds) |331332### 5. onchainos token holders333334Get token holder distribution (top 20).335336```bash337onchainos token holders <address> [--chain <chain>]338```339340| Param | Required | Default | Description |341|---|---|---|---|342| `<address>` | Yes | - | Token contract address (positional) |343| `--chain` | No | `ethereum` | Chain name |344345**Return fields** (top 20 holders):346347| Field | Type | Description |348|---|---|---|349| `data[].holdAmount` | String | Token amount held |350| `data[].holderWalletAddress` | String | Holder wallet address |351352## Input / Output Examples353354**User says:** "Search for xETH token on XLayer"355356```bash357onchainos token search xETH --chains xlayer358# → Display:359# xETH (0xe7b0...) - XLayer360# Price: $X,XXX.XX | 24h: +X% | Market Cap: $XXM | Liquidity: $XXM361# Community Recognized: Yes362```363364**User says:** "What's trending on Solana by volume?"365366```bash367onchainos token trending --chains solana --sort-by 5 --time-frame 4368# → Display top tokens sorted by 24h volume:369# #1 SOL - Vol: $1.2B | Change: +3.5% | MC: $80B370# #2 BONK - Vol: $450M | Change: +12.8% | MC: $1.5B371# ...372```373374**User says:** "Who are the top holders of this token?"375376```bash377onchainos token holders 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain xlayer378# → Display top 20 holders with amounts and addresses379```380381## Edge Cases382383- **Token not found**: suggest verifying the contract address (symbols can collide)384- **Same symbol on multiple chains**: show all matches with chain names385- **Unverified token**: `communityRecognized = false` — warn user about risk386- **Too many results**: name/symbol search caps at 100 — suggest using exact contract address387- **Network error**: retry once388- **Region restriction (error code 50125 or 80001)**: do NOT show the raw error code to the user. Instead, display a friendly message: `⚠️ Service is not available in your region. Please switch to a supported region and try again.`389390## Amount Display Rules391392- Use appropriate precision: 2 decimals for high-value, significant digits for low-value393- Market cap / liquidity in shorthand ($1.2B, $45M)394- 24h change with sign and color hint (+X% / -X%)395396## Global Notes397398- Use contract address as **primary identity** — symbols can collide across tokens399- `communityRecognized = true` means listed on Top 10 CEX or community verified400- The CLI resolves chain names automatically (e.g., `ethereum` → `1`, `solana` → `501`)401- EVM addresses must be **all lowercase**402- The CLI handles authentication internally via environment variables — see Prerequisites step 4 for default values
yejiming