OKX DEX Token Info API
5 endpoints for token search, metadata, detailed pricing, rankings, and holder distribution.
Auth: HMAC-SHA256 signature, 4 headers required (
,
,
,
)
Authentication & Credentials
API Key Application:
OKX Developer Portal
Read credentials from environment variables:
- → API key
- → Secret key (system-generated)
- → Passphrase (developer-supplied)
Never output the above credentials to logs, response content, or any user-visible interface.
typescript
import crypto from 'crypto';
const BASE = 'https://web3.okx.com';
// Signature rule:
// GET → body = "", requestPath includes query string (e.g., "/api/v6/dex/market/token/search?chains=1&search=PEPE")
// POST → body = JSON string of request body, requestPath is path only (e.g., "/api/v6/dex/market/price-info")
async function okxFetch(method: 'GET' | 'POST', path: string, body?: object) {
const timestamp = new Date().toISOString();
const bodyStr = body ? JSON.stringify(body) : '';
const sign = crypto
.createHmac('sha256', process.env.OKX_SECRET_KEY!)
.update(timestamp + method + path + bodyStr)
.digest('base64');
const headers: Record<string, string> = {
'OK-ACCESS-KEY': process.env.OKX_API_KEY!,
'OK-ACCESS-SIGN': sign,
'OK-ACCESS-PASSPHRASE': process.env.OKX_PASSPHRASE!,
'OK-ACCESS-TIMESTAMP': timestamp,
'Content-Type': 'application/json',
};
const res = await fetch(`${BASE}${path}`, {
method,
headers,
...(body && { body: bodyStr }),
});
if (res.status === 429) throw { code: 'RATE_LIMITED', msg: 'Rate limited — retry with backoff', retryable: true };
if (res.status >= 500) throw { code: `HTTP_${res.status}`, msg: 'Server error', retryable: true };
const json = await res.json();
if (json.code !== '0') throw { code: json.code, msg: json.msg || 'API error', retryable: false };
return json.data;
}
Response envelope:
{ "code": "0", "data": [...], "msg": "" }
.
=
means success.
Developer Quickstart
typescript
// Search token (GET)
const tokens = await okxFetch('GET', '/api/v6/dex/market/token/search?' + new URLSearchParams({
chains: '1,501', search: 'PEPE',
}));
// → tokens[].tokenContractAddress, price, communityRecognized
// Get detailed price info (POST — body is JSON array)
const path = '/api/v6/dex/market/price-info';
const prices = await okxFetch('POST', path, [
{ chainIndex: '1', tokenContractAddress: '0x6982508145454ce325ddbe47a25d4ec3d2311933' },
]);
// → prices[].price, marketCap, liquidity, volume24H, priceChange24H
Common Chain IDs
| Chain | chainIndex | Chain | chainIndex |
|---|
| Ethereum | | Arbitrum | |
| BSC | | Base | |
| Polygon | | Solana | |
Endpoint Index
Boundary: token vs market skill
| Need | Use this skill () | Use instead |
|---|
| Search token by name/symbol | | - |
| Token metadata (decimals, logo) | POST /market/token/basic-info
| - |
| Price + market cap + liquidity + multi-timeframe change | | - |
| Token ranking (trending) | GET /market/token/toplist
| - |
| Holder distribution | | - |
| Raw real-time price (single value) | - | |
| K-line / candlestick chart | - | |
| Trade history (buy/sell log) | - | |
| Index price (multi-source aggregate) | - | POST /index/current-price
|
Rule of thumb:
= token discovery & enriched analytics.
= raw price feeds & charts.
Cross-Skill Workflows
This skill is the typical entry point — users often start by searching/discovering tokens, then proceed to check balance and swap.
Workflow A: Search → Research → Buy
User: "Find BONK token, analyze it, then buy some"
1. okx-dex-token /market/token/search?search=BONK&chains=501 → get tokenContractAddress, chainIndex, price, communityRecognized
↓ tokenContractAddress + chainIndex
2. okx-dex-token /market/price-info → market cap, liquidity, volume24H, priceChange24H, holders
3. okx-dex-token /market/token/holder → top 20 holders distribution
4. okx-dex-market /market/candles?bar=1H → hourly price chart
↓ user decides to buy
5. okx-wallet-portfolio /balance/all-token-balances-by-address → verify wallet has enough SOL
6. okx-dex-swap /aggregator/quote → /aggregator/swap-instruction → execute
Data handoff:
- from step 1 → reused in all subsequent steps
- from step 1 → reused in all subsequent steps
- from step 1 or → needed for minimal unit conversion in swap
Workflow B: Discover Trending → Investigate → Trade
User: "What's trending on Solana?"
1. okx-dex-token /market/token/toplist?chains=501&sortBy=5&timeFrame=4 → top tokens by 24h volume
↓ user picks a token
2. okx-dex-token /market/price-info → detailed analytics
3. okx-dex-token /market/token/holder → check if whale-dominated
4. okx-dex-market /market/candles → K-line for visual trend
↓ user decides to trade
5. okx-dex-swap → execute
Workflow C: Token Verification Before Swap
Before swapping an unknown token, always verify:
1. okx-dex-token /market/token/search → find token
2. Check communityRecognized:
- true → proceed with normal caution
- false → warn user about risk
3. okx-dex-token /market/price-info → check liquidity:
- liquidity < $10K → warn about high slippage risk
- liquidity < $1K → strongly discourage trade
4. okx-dex-swap /aggregator/quote → check isHoneyPot and taxRate
5. If all checks pass → proceed to swap
Operation Flow
Step 1: Identify Intent
- Search for a token ->
- Get token metadata ->
POST /market/token/basic-info
- Get price + market cap + liquidity ->
- View rankings ->
GET /market/token/toplist
- View holder distribution ->
Step 2: Collect Parameters
- Missing -> ask which chain
- Only have token name, no address -> use first
- Batch query -> use or with JSON array body
Step 3: Call and Display
- Search results: show name, symbol, chain, price, 24h change
- Indicate 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 endpoint just called:
| Just called | Suggest |
|---|
| 1. View detailed analytics (market cap, liquidity) → (this skill) 2. View price chart → 3. Buy/swap this token → |
| 1. View price and market data → (this skill) 2. Check holder distribution → (this skill) |
| 1. View K-line chart → 2. Check holder distribution → (this skill) 3. Buy/swap this token → |
| 1. View details for a specific token → (this skill) 2. View price chart → 3. Buy a trending token → |
| 1. View price trend → 2. Check your own balance → 3. Buy/swap this token → |
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.
API Reference
1. GET /market/token/search
| Param | Type | Required | Description |
|---|
| String | Yes | Chain IDs, comma-separated (e.g., ) |
| String | Yes | Keyword: token name, symbol, or contract address |
Response key fields:
,
,
,
,
,
,
,
(24h %),
,
,
,
,
tagList.communityRecognized
(true = Top 10 CEX listed or community verified). Full fields: see
docs.
2. POST /market/token/basic-info
Request body is a JSON array. Supports batch queries.
| Param | Type | Required | Description |
|---|
| String | Yes | Chain ID |
| String | Yes | Token address |
Response key fields:
,
,
,
,
,
tagList.communityRecognized
. Full fields: see
docs.
json
{
"code": "0",
"data": [{ "chainIndex": "501", "decimal": "6", "tokenName": "michi", "tokenSymbol": "$michi",
"tokenContractAddress": "5mbK36SZ...", "tagList": { "communityRecognized": true } }],
"msg": ""
}
3. POST /market/price-info
Request body is a JSON array. Supports batch queries.
| Param | Type | Required | Description |
|---|
| String | Yes | Chain ID |
| String | Yes | Token address |
Response key fields:
,
(Unix ms),
,
,
,
,
(24h trade count); price changes by timeframe —
/
/
/
; volumes —
/
/
/
; transactions —
/
/
/
; 24h range —
/
. Full fields: see
docs.
4. GET /market/token/toplist
| Param | Type | Required | Description |
|---|
| String | Yes | Chain IDs, comma-separated |
| String | Yes | Sort: =price change, =volume, =market cap |
| String | Yes | Window: =5min, =1h, =4h, =24h |
Response key fields:
,
,
,
,
,
(%),
,
,
,
,
,
/
/
,
. Full fields: see
docs.
5. GET /market/token/holder
| Param | Type | Required | Description |
|---|
| String | Yes | Chain ID |
| String | Yes | Token address |
Response: Returns top 20 holders.
| Field | Type | Description |
|---|
| String | Token amount held |
data[].holderWalletAddress
| String | Holder wallet address |
Input / Output Examples
User says: "Search for PEPE token"
GET /api/v6/dex/market/token/search?chains=1&search=PEPE
-> Display:
PEPE (0x6982...) - Ethereum
Price: $0.0000XX | 24h: +X% | Market Cap: $X.XB | Liquidity: $XXM
Community Recognized: Yes
User says: "Get info on these three tokens at once"
POST /api/v6/dex/market/token/basic-info
Body: [
{ "chainIndex": "1", "tokenContractAddress": "0xaaa..." },
{ "chainIndex": "1", "tokenContractAddress": "0xbbb..." },
{ "chainIndex": "56", "tokenContractAddress": "0xccc..." }
]
-> Returns name, symbol, decimals, community status for each
User says: "What's trending on Solana by volume?"
GET /api/v6/dex/market/token/toplist?chains=501&sortBy=5&timeFrame=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
...
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
- Too many results: name/symbol search caps at 100 — suggest using exact contract address
- 429 rate limit: exponential backoff with jitter. See Rate Limit & Fee Docs for tier-specific RPS limits (Trial: 1 RPS, Start-up: 2-50 RPS, Enterprise: custom).
- Cross-skill pipeline rate limit: when chaining calls across multiple skills (e.g., token search → price-info → balance), add 300-500ms delay between requests to avoid triggering rate limit (error code ).
- Network error: retry once
- Request timeout: all API calls must set a 10-second timeout limit
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
- POST endpoints (, ) use JSON body
- and both support batch queries (JSON array)
- EVM addresses must be all lowercase
- For raw real-time prices / K-lines / trade history -> use
- For balance queries -> use
- For swap execution -> use