Base URL: https://api-cloud.bitmart.com
Authentication: No API Key required, send HTTP requests directly
Request Method: POST, JSON body
Response Format: { "success": bool, "code": "string", "message": "string", "data": ... }
Request Limit: 15 requests per second per IP，or you would be rate limited

Endpoint	Path	Description
token-search	`/web3/chain-web3-base-data-maintainer/v1/token/search`	Fuzzy search tokens by name or symbol
chain-detail	`/web3/chain-web3-base-data-maintainer/v1/chain/by-chainId`	Query chain details by platform chain ID
token-info	`/web3/chain-web3-base-data-maintainer/v1/token/query/by/token-id`	Get token details by platform token ID
kline	`/web3/chain-web3-market/v1/api/market/kline/history`	Token K-line data (Solana only)
hot-ranking	`/web3/chain-web3-market/v1/api/market/trending/hot`	Hot token trending ranking
xstock-ranking	`/web3/chain-web3-market/v1/api/market/rank/xstocks`	US stock mapped token ranking
smart-money-rank	`/web3/chain-web3-smart-money/v1/api/smart-money/list`	Smart money 7-day P&L ranking
smart-money-info	`/web3/chain-web3-smart-money/v1/api/smart-money/info`	Smart money address analysis, holdings and transaction history
address-balance	`/web3/chain-web3-assetmanager/v1/eoa/balance/list`	Address token balance list
address-recent	`/web3/chain-web3-data-platform/evm/v2/transaction/address-recent`	Address recent transactions (grouped by date)
swap-quote	`/web3/chain-web3-price/api/v1/token/price/swap-quote`	Token Swap quote (quote only)
batch-price	`/web3/chain-web3-price/api/v1/token/price/batch`	Batch query token prices

Core Rules

1. Token Chain Dependency Rule

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)
isDeposit: Whether deposit is supported (1=yes)
status: Token status
gasLimit: Gas limit
contractOwner: Contract owner address
source: Token source (e.g., pump_dot_fun)
createdAt: Token creation time (ISO 8601)
createTime: Token creation timestamp (milliseconds)

address-balance

Get token balance list for an address.

Limitations:

Only supports platform-managed addresses and EOA wallet addresses
Does not support external addresses or smart contract wallets
Response does not contain symbol or balance_usd

Request:

{
    "address": "0x4396e479fe8270487f301b7c5cc92e8cd59ef91a",
    "chainId": 2002,
    "pageIndex": 0,
    "pageSize": 100
}

Parameter	Type	Required	Description
address	string	Yes	Wallet address
chainId	integer	Yes	Platform internal chain ID (must iterate 2001-2004, 2007 for complete info)
pageIndex	integer	No	Page number, starting from 0
pageSize	integer	No	Page size

address-recent

Get recent transactions for an address, grouped by date.

Limitations:

Only supports platform-managed addresses and EOA wallet addresses
Does not support external addresses or smart contract wallets

Request:

{
    "addressChainPairs": [
        {
            "address": "2h4hhjuWxEo4uyzGAxzWvpdSotAozchjpfyefvVWvi8R",
            "tokenAddress": null,
            "chainId": "2001"
        }
    ],
    "tradeType": 0,
    "limit": "50"
}

Parameter	Type	Required	Description
addressChainPairs	array	Yes	Array of address-chain pairs to query
addressChainPairs[].address	string	Yes	Wallet address
addressChainPairs[].tokenAddress	string \| null	No	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.

Response — Top-level:

Array of date groups, each containing:

Field	Description
date	Date string (YYYY-MM-DD)
transactionList	Array of transactions for this date

Response — Transaction Fields (transactionList[]):

Field	Description
blockNumber	Block number
chainId	Platform internal chain ID
txHash	Transaction hash
transactionType	`"send"`, `"receive"`, or `"trade"`
txTime	Transaction timestamp (milliseconds)
from	Array of sender entries
to	Array of receiver entries
txStatus	`"success"` or `"fail"`
txFee	Transaction fee
txFeeUsd	Transaction fee (USD)
amountUsd	Transaction amount (USD)
confirmBlockNumber	Confirmation block number
orderId	Order ID

Response — Address Entry Fields (from[] / to[]):

Field	Description
address	Wallet address
amount	Token amount
amountUsd	Amount (USD)
asset	Token asset object (null if not applicable)

Response — Asset Fields (asset):

Field	Description
symbol	Token symbol
tokenAddress	Token contract address
tokenIcon	Token icon URL
chainIcon	Chain icon URL

swap-quote

Get token Swap price quote. Quote only, does not execute transaction.

Prerequisite: Get tokenId, contract, tokenDecimal, and chainId for both tokens from the token resolution workflow.

Request:

{
    "tokenInAddress": "",
    "tokenOutAddress": "0x55d398326f99059ff775485246999027b3197955",
    "tokenInId": "2002",
    "tokenOutId": "1169983",
    "amountIn": 1,
    "tokenInDecimals": 18,
    "tokenOutDecimals": 18,
    "slippage": 0.1,
    "fromChainId": 2002,
    "toChainId": 2002
}

Parameter	Type	Required	Description
tokenInAddress	string	Yes	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)

Request:

{
    "tokenIds": [2001, 2002, 2003, 2004, 2007],
    "latestOnly": true
}

Parameter	Type	Required	Description
tokenIds	array	Yes	Platform internal chain ID array (2001=Solana, 2002=BSC, 2003=Ethereum, 2004=Arbitrum, 2007=Base)
latestOnly	boolean	No	Whether to return only latest price, default true

Response Key Fields:

tokenId: Platform internal chain ID
chainId: Platform internal chain ID
baseToken: Base token symbol
quoteToken: Quote token (USD)
price: Price (USD)
priceUsd: Price (USD)
generateTime: Price generation time

Supported Tokens:

tokenId	chainId	Token Symbol	Token Name
2001	2001	SOL	Solana
2002	2002	BNB	BNB
2003	2003	ETH	Ethereum
2004	2004	ARB	Arbitrum
2007	2007	BASE	Base

chain-detail

Query chain details by platform internal chain ID.

Request:

{
    "chainId": 2001
}

Parameter	Type	Required	Description
chainId	integer	Yes	Platform internal chain ID

Response Contains Fields:

Field	Description
chainId	Platform internal chain ID
networkChainId	Industry standard blockchain network chain ID (e.g., 501=Solana, 56=BSC, 1=Ethereum)
chainSeries	Chain series (e.g., SVM, EVM)
chainName	Full chain name
shortName	Chain short name (e.g., SOL)
exploreUrl	Block explorer URL
txUrl	Transaction explorer URL
addressUrl	Address explorer URL
depositConfirmations	Required deposit confirmations
withdrawConfirmations	Required withdrawal confirmations
status	Chain status

kline

Get token historical K-line data. Only supports Solana chain tokens.

Request:

{
    "interval": "5m",
    "tokenAddress": "Cz5YvHHpU1e3dqDQJHVdjVi7VSqvhu21A1GvxcTHMpLM",
    "startTime": "1773307582",
    "endTime": "1773393982"
}

Parameter	Type	Required	Description
interval	string	Yes	Candlestick period: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 1d
tokenAddress	string	Yes	Token contract address
startTime	string	Yes	Start timestamp (seconds)
endTime	string	Yes	End timestamp (seconds)

hot-ranking / xstock-ranking

Get hot token / US stock mapped token ranking.

Request:

{
    "queryFields": [],
    "timezone": "5"
}

Parameter	Type	Required	Description
queryFields	array	No	Query field filter
timezone	string	Yes	Time window: 1=1min, 2=5min, 3=1hour, 4=4hours, 5=24hours

Response (each token in data.list[]):

Field	Description
tokenId	Platform internal token ID
tokenSymbol	Token symbol
tokenName	Token name
tokenAddress	Token contract address
tokenIconUrl	Token icon URL
chainId	Platform internal chain ID
price	Current price (USD)
priceChange	Price change rate
priceChange24h	24-hour price change rate
marketcap	Market cap
volume	Trading volume
liquidity	Liquidity
holders	Number of holder addresses
buy	Buy count
sell	Sell count
rank	Rank position
createAt	Token creation time
check	Audit/check status
source	Data source
prices	Historical price points array

smart-money-rank

Get smart money 7-day P&L ranking.

All parameters are optional. If omitted, returns default ranking.

Request:

{
    "current": 1,
    "size": 20,
    "orderBy": "profit7d",
    "order": "desc",
    "filters": {
        "profitMin": 5,
        "profitMax": 50,
        "profitRateMin": 5,
        "profitRateMax": 50,
        "winRateMin": 50,
        "winRateMax": 100,
        "tradeCountMin": 10,
        "tradeCountMax": 200,
        "totalTradeAmountMin": 1000,
        "totalTradeAmountMax": 100000
    }
}

Parameter	Type	Required	Description
current	integer	No	Page number, default 1
size	integer	No	Page size, max 100
orderBy	string	No	Sort field: profit7d, winRate7d, profitRate7d, tradeCount, totalTradeAmount, lastTradeTime
order	string	No	Sort direction: desc / asc
filters.profitMin	number	No	Minimum 7-day profit amount
filters.profitMax	number	No	Maximum 7-day profit amount
filters.profitRateMin	number	No	Minimum 7-day profit rate (%)
filters.profitRateMax	number	No	Maximum 7-day profit rate (%)
filters.winRateMin	number	No	Minimum 7-day win rate (%)
filters.winRateMax	number	No	Maximum 7-day win rate (%)
filters.tradeCountMin	integer	No	Minimum trade count
filters.tradeCountMax	integer	No	Maximum trade count
filters.totalTradeAmountMin	number	No	Minimum total trade amount (USD)
filters.totalTradeAmountMax	number	No	Maximum total trade amount (USD)

Response (each address in data.records[]):

Field	Description
walletAddress	Smart money wallet address
rank	Rank position
profit7d	7-day profit amount
profitRate7d	7-day profit rate (%)
winRate7d	7-day win rate (%)
tradeCount	Total trade count
buyCount	Buy count
sellCount	Sell count
totalTradeAmount	Total trade amount (USD)
avgBuyAmount	Average buy amount
lastTradeTime	Last trade timestamp
latestTradeToken	Latest trade token address
latestTradeTokenName	Latest trade token name
profitTrend7d	7-day profit trend array (dailyProfit, dailyProfitRate per day)
bestProfitToken	Best profit token array (address, name, profitRate, profit)
chainId	Platform internal chain ID
follow	Whether current user follows this address
walletRemark	Wallet remark/tag
updateTime	Last update time
createTime	Record creation time
notify	Whether notifications are enabled

smart-money-info

Get smart money address analysis, holdings, and transaction history.

Limitation: walletAddress must be provided by the user.

Request:

{
    "walletAddress": "As7HjL7dzzvbRbaD3WCun47robib2kmAKRXMvjHkSMB5"
}

Parameter	Type	Required	Description
walletAddress	string	Yes	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

bitmart-wallet-ai

BitMart Web3 Wallet AI Skills

Supported Chains

API Overview