bitmart-wallet-ai

name	bitmart-wallet-ai
description	BitMart Web3 Wallet Skills (12 endpoints): Token Search, Chain Details, Token Info, K-Line Chart, Hot Token Ranking, xStock Ranking, Smart Money P&L Ranking, Smart Money Address Analysis/Holdings/Transaction History, Address Balance, Address Recent Transactions, Swap Quote, Batch Price. All APIs do not require API Key. Use when users ask about token prices, market data, smart money tracking, asset queries, recent transactions, or token swap quotes.
homepage	https://www.bitmart.com
metadata	{"author":"bitmart","version":"2026.3.23","updated":"2026-03-23"}

BitMart Web3 Wallet AI Skills

This document describes the BitMart Web3 Wallet capabilities exposed as AI skills.

Supported Chains

chainId	Chain	Native Coin Symbol
2001	Solana	SOL
2002	BSC (BNB Smart Chain)	BNB
2003	Ethereum	ETH
2004	Arbitrum	ETH
2007	Base	ETH

API Overview

• Base URL: https://api-cloud.bitmart.com
• Authentication: No API Key required, send HTTP requests directly
• Request Method: POST, JSON body
• Required Header: User-Agent: bitmart-skills/wallet/v2026.3.23 (SDK source identifier for analytics)
• 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 chain 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:

• tokenIds accepts two types of identifiers:
  • Native tokens: use the chainId value as the identifier (e.g., 2001 for SOL, 2002 for BNB, 2003 for ETH). This is a special convention — chainId doubles as tokenId for native tokens.
  • Contract tokens: use the platform-internal tokenId obtained from token-search (e.g., "224987722" for a specific token).
• Do not confuse chainId (chain identifier) with tokenId (token identifier) — they happen to share the same value only for native tokens.

Request:

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

Parameter	Type	Required	Description
tokenIds	array	Yes	Array of token identifiers. For native tokens, use the chainId as tokenId (e.g., 2001=SOL, 2002=BNB, 2003=ETH). For contract tokens, use the platform tokenId from token-search.
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

Note: The hot-ranking and xstock-ranking endpoints may ignore the pageSize parameter in the request and return all available results. Do not rely on pageSize to limit the response — always handle variable-length result arrays.

---

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.

---

Error Handling

Response Format

All endpoints return the same response structure:

{
  "success": false,
  "code": "error_code",
  "message": "Human-readable error description",
  "data": null
}

When success is false, check the code and message fields for details.

Common Error Scenarios

Scenario	Typical Response	Action
Invalid/missing parameter	success: false with descriptive message	Check required fields and types
Token not found	Empty data or data: null	Verify tokenId/address via token-search first
Chain not supported	Error in message	Check supported chains (2001-2004, 2007)
Rate limited (>15 req/s)	HTTP 429 or error response	Back off, wait 5 seconds, retry (max 3 times)
Cloudflare interception	HTTP 403/503 with HTML body (not JSON)	This is a Cloudflare WAF block, not an API error. Do not parse as JSON. Check IP reputation (VPN/cloud IPs may be challenged). Wait 30-60 seconds and retry. Do not auto-retry more than 3 times.
Server error	HTTP 500+	Retry once after 2 seconds; if persistent, inform user

Cloudflare Handling

BitMart API is behind Cloudflare CDN. If you receive HTTP 403/503 and the response body contains "Cloudflare", "cf-", or an HTML challenge page (instead of JSON):

1. This is a Cloudflare interception, not a BitMart API error — do not parse as JSON
2. Check if too many requests were sent in a short window
3. Wait 30-60 seconds before retrying
4. Do not auto-retry more than 3 times
5. If persistent, suggest the user check their network environment (VPN, proxy, cloud IP)

Important — Cloudflare Error 1010 (Non-curl clients):

Cloudflare may block requests from HTTP libraries that use default "bot-like" User-Agent strings (e.g., Python-urllib/3.x, Go-http-client/1.1, Java/...). The symptom is HTTP 403 with error code 1010.

This does not affect curl (which sends a recognized User-Agent by default), but will affect:

• Python urllib / urllib3 without custom User-Agent
• Go net/http default client
• Any HTTP library that sends a generic or empty User-Agent

Solution: Always include the User-Agent header in every request (e.g., bitmart-skills/wallet/v2026.3.23). Ensure your HTTP client actually sends this header and does not override it with a default value.

# Python requests — correct
import requests
r = requests.post(url, json=body, headers={"User-Agent": "bitmart-skills/wallet/v2026.3.23"})

# Python urllib — correct
import urllib.request
req = urllib.request.Request(url, data=json.dumps(body).encode(),
    headers={"Content-Type": "application/json", "User-Agent": "bitmart-skills/wallet/v2026.3.23"})
resp = urllib.request.urlopen(req)

---

curl Examples

Public endpoint (token-search)

curl -s -X POST 'https://api-cloud.bitmart.com/web3/chain-web3-base-data-maintainer/v1/token/search' \
  -H "Content-Type: application/json" \
  -H "User-Agent: bitmart-skills/wallet/v2026.3.23" \
  -d '{"keyword":"TRUMP","chainId":2001}'

Public endpoint (batch-price — native tokens)

curl -s -X POST 'https://api-cloud.bitmart.com/web3/chain-web3-price/api/v1/token/price/batch' \
  -H "Content-Type: application/json" \
  -H "User-Agent: bitmart-skills/wallet/v2026.3.23" \
  -d '{"tokenIds":[2001,2002,2003],"latestOnly":true}'

Public endpoint (address-balance)

curl -s -X POST 'https://api-cloud.bitmart.com/web3/chain-web3-assetmanager/v1/eoa/balance/list' \
  -H "Content-Type: application/json" \
  -H "User-Agent: bitmart-skills/wallet/v2026.3.23" \
  -d '{"address":"0x4396e479fe8270487f301b7c5cc92e8cd59ef91a","chainId":2002,"pageIndex":0,"pageSize":100}'

Public endpoint (swap-quote)

curl -s -X POST 'https://api-cloud.bitmart.com/web3/chain-web3-price/api/v1/token/price/swap-quote' \
  -H "Content-Type: application/json" \
  -H "User-Agent: bitmart-skills/wallet/v2026.3.23" \
  -d '{"tokenInAddress":"","tokenOutAddress":"0x55d398326f99059ff775485246999027b3197955","tokenInId":"2002","tokenOutId":"1169983","amountIn":1,"tokenInDecimals":18,"tokenOutDecimals":18,"slippage":0.1,"fromChainId":2002,"toChainId":2002}'

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