Tokens with the same symbol on different chains are different tokens (e.g., USDT-ETH ≠ USDT-BSC ≠ USDT-SOL), with different contract addresses, liquidity pools, and markets.
2. Swap Compatibility Rule
Two tokens can be swapped only if:
Both tokens are on the same chain
Or one is the native token and the other is a contract token on the same chain
Cross-chain Swap is not supported.
3. Token Resolution Workflow
All endpoints requiring token details must first get parameters through the following workflow:
User Input → token-search → token-info → Target Endpoint
Never hardcode or guess token addresses, chainId, or decimal places.
4. Native Token Address Handling (Important)
This is how different endpoints handle native token addresses:
contract field returned by token-info
chainId
Chain
contract value
2001
Solana
So11111111111111111111111111111111111111111
2002
BSC
"" (empty)
2003
Ethereum
"" (empty)
2004
Arbitrum
"" (empty)
2007
Base
"" (empty)
tokenAddress field returned by address-balance
Native tokens on all chains return "" (empty string).
tokenAddress parameter for swap-quote endpoint
Chain
Input Method
API Return Value
Solana
Must use So11111111111111111111111111111111111111111
Kept as is
EVM Chains (ETH/BSC/ARB/Base)
Pass "" empty string
Converted to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
Key Conclusions:
When swapping native tokens on EVM chains, pass empty string "" for tokenAddress
When swapping native tokens on Solana, must pass So11111111111111111111111111111111111111111 for tokenAddress
5. Address Balance Query
chainId is a required parameter. If the user does not specify a chain, must query all supported chains (2001-2004, 2007).
Common Token Address Reference
Native Tokens
Chain
Token
Address
Solana
SOL
So11111111111111111111111111111111111111111
EVM Chains General
Native Coin
0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
Common Contract Tokens (Testnet)
Chain
Token
Address
Solana
USDC
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Solana
USDT
Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
BSC
USDT
0x55d398326f99059ff775485246999027b3197955
BSC
USDC
0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d
Arbitrum
USDC
0xaf88d065e77c8cc2239327c5edb3a432268e5831
Base
USDC
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
API Details
token-search
Fuzzy search tokens by name or symbol.
Request:
{
"keyword": "TRUMP",
"chainId": 2002
}
Parameter
Type
Required
Description
keyword
string
Yes
Search keyword, matches token symbol and name
chainId
integer
No
Platform internal chain ID (2001=Solana, 2002=BSC, 2003=Ethereum, etc.)
Response Key Fields:
tokenId: Platform internal token ID (required by downstream endpoints)
chainId: Platform internal chain ID
contract: Token contract address
symbol: Token symbol
tokenDecimal: Token decimal places
isDeposit/isWithdraw: Whether deposit/withdrawal is supported
token-info
Get complete token details by platform internal token ID.
Prerequisite: First get tokenId from token-search.
Request:
{
"tokenId": "224987722"
}
Parameter
Type
Required
Description
tokenId
string
Yes
Internal token ID (from token-search)
Response Key Fields:
tokenId: Platform internal token ID
chainId: Platform internal chain ID
contract: Token contract address
tokenDecimal: Token decimal places
isNativeToken: Whether it's a native token (1=yes)
type: Token type (e.g., spl-token)
name: Token name
symbol: Token symbol
tokenIcon: Token icon URL
isWithdraw: Whether withdrawal is supported (1=yes)
Token contract address filter. Pass null to query all tokens under the address (filtered by chainId). Pass a specific token address to filter for that token only.
addressChainPairs[].chainId
string
Yes
Platform internal chain ID (as string, e.g., "2001")
tradeType
integer
No
Trade type filter: 0=all, 1=send, 2=receive, 3=trade
limit
string
No
Max transactions per date group (e.g., "50")
Important Notes:
When tokenAddress is null, the API returns transactions for all tokens associated with the address on the specified chain.
The API returns up to the most recent 6 months of data by default. There is no parameter to specify a custom date range.
chainId is required for each address-chain pair. If the user does not specify a chain, the agent must enumerate all supported chains (2001–2004, 2007) and query each one separately.
Source token contract address (see native token address handling rules)
tokenOutAddress
string
Yes
Target token contract address
tokenInId
string
Yes
Source token platform internal ID
tokenOutId
string
Yes
Target token platform internal ID
amountIn
number
Yes
Swap amount (defaults to 100 if not specified by user)
tokenInDecimals
integer
Yes
Source token decimal places
tokenOutDecimals
integer
Yes
Target token decimal places
slippage
number
Yes
Slippage tolerance (e.g., 0.1 = 10%)
fromChainId
integer
Yes
Source chain platform internal chain ID
toChainId
integer
Yes
Target chain platform internal chain ID (must be same as fromChainId)
Response Key Fields:
amountIn: Input amount
amountOut: Expected output amount
tokenInPrice: Source token price (USD)
tokenOutPrice: Target token price (USD)
fee: Transaction fee
Note: If the swap-quote API returns an error, the possible reasons are: (1) the token pair or chain is not supported / no liquidity found, or (2) the API is rate-limited. In case of rate limiting, recommend the user to try again after 5 minutes.
batch-price
Batch query token prices.
Note:
For native tokens (e.g., SOL, BNB, ETH, ARB, BASE), use chain IDs (e.g., 2001, 2002, 2003, 2004, 2007) as tokenIds
For contract tokens, use the specific tokenId (obtained via token-search first)
Smart money wallet address (must be provided by user)
Response — Top-level Fields:
Field
Description
walletAddress
Wallet address
walletBalance
Total wallet balance (USD)
walletSolBalance
SOL balance
follow
Whether current user follows this address
walletRemark
Wallet remark/tag
marketDistribution
Market distribution data
Response — Address Analysis Fields (profitInfo):
Field
Description
profitInfo.profit7d
7-day profit
profitInfo.profitRate7d
7-day profit rate
profitInfo.winRate7d
7-day win rate
profitInfo.tradeInfo
Trade info summary
profitInfo.topProfit
Top profit details
profitInfo.profitRateDistribution
Profit rate distribution
profitInfo.profitTrend7d
7-day profit trend array
Response — Holdings Fields (proportion[]):
Field
Description
tokenAddress
Token contract address
tokenName
Token name
tokenIcon
Token icon URL
tokenId
Platform internal token ID
chainId
Platform internal chain ID
quantity
Holding quantity
balance
Holding value (USD)
price
Current price
holdingPercentage
Holding percentage
priceChangeRate
Price change rate
Response — Transaction History Fields (tradeHistory[]):
Field
Description
tokenAddress
Token contract address
tokenSymbol
Token symbol
tokenIcon
Token icon
tokenId
Platform internal token ID
chainId
Platform internal chain ID
tradeDirection
BUY or SELL
tradeTime
Trade timestamp
quantity
Trade quantity
totalUSD
Trade amount (USD)
price
Execution price
txHash
Transaction hash
profit
Trade profit
About Tokens with Same Name
When the user-specified token is ambiguous and there are multiple tokens with exactly matching names, you must ask the user to confirm which token. Clearly state each token's chain name and token type.
Other Rules
Token Price Query: Query hot-ranking and batch-price endpoints sequentially. Use the first result that returns an exact match (symbol or name,chainId(if valid),tokenId(if valid) matches exactly). If neither returns an exact match, inform the user that the token price is not currently available.
Must verify chainId matches before calling swap-quote
If user does not specify swap amount, default amountIn = 100
K-line data only supports Solana tokens
Response data only includes platform-managed tokens and addresses
