BitMart Web3 Wallet AI Skills#

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

Supported Chains#

chainIdChainNative Coin Symbol2001SolanaSOL2002BSC (BNB Smart Chain)BNB2003EthereumETH2004ArbitrumETH2007BaseETH

API Overview#

• 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

EndpointPathDescriptiontoken-search/web3/chain-web3-base-data-maintainer/v1/token/searchFuzzy search tokens by name or symbolchain-detail/web3/chain-web3-base-data-maintainer/v1/chain/by-chainIdQuery chain details by platform chain IDtoken-info/web3/chain-web3-base-data-maintainer/v1/token/query/by/token-idGet token details by platform token IDkline/web3/chain-web3-market/v1/api/market/kline/historyToken K-line data (Solana only)hot-ranking/web3/chain-web3-market/v1/api/market/trending/hotHot token trending rankingxstock-ranking/web3/chain-web3-market/v1/api/market/rank/xstocksUS stock mapped token rankingsmart-money-rank/web3/chain-web3-smart-money/v1/api/smart-money/listSmart money 7-day P&L rankingsmart-money-info/web3/chain-web3-smart-money/v1/api/smart-money/infoSmart money address analysis, holdings and transaction historyaddress-balance/web3/chain-web3-assetmanager/v1/eoa/balance/listAddress token balance listaddress-recent/web3/chain-web3-data-platform/evm/v2/transaction/address-recentAddress recent transactions (grouped by date)swap-quote/web3/chain-web3-price/api/v1/token/price/swap-quoteToken Swap quote (quote only)batch-price/web3/chain-web3-price/api/v1/token/price/batchBatch 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:

text

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

chainIdChaincontract value2001SolanaSo111111111111111111111111111111111111111112002BSC"" (empty)2003Ethereum"" (empty)2004Arbitrum"" (empty)2007Base"" (empty)

tokenAddress field returned by address-balance

Native tokens on all chains return "" (empty string).

tokenAddress parameter for swap-quote endpoint

ChainInput MethodAPI Return ValueSolanaMust use So11111111111111111111111111111111111111111Kept as isEVM Chains (ETH/BSC/ARB/Base)Pass "" empty stringConverted 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#

ChainTokenAddressSolanaSOLSo11111111111111111111111111111111111111111EVM Chains GeneralNative Coin0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Common Contract Tokens (Testnet)#

ChainTokenAddressSolanaUSDCEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1vSolanaUSDTEs9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYBBSCUSDT0x55d398326f99059ff775485246999027b3197955BSCUSDC0x8ac76a51cc950d9822d68b83fe1ad97b32cd580dArbitrumUSDC0xaf88d065e77c8cc2239327c5edb3a432268e5831BaseUSDC0x833589fcd6edb6e08f4c7c32d4f71b54bda02913

---

API Details#

token-search#

Fuzzy search tokens by name or symbol.

Request:

json

{
    "keyword": "TRUMP",
    "chainId": 2002
}

ParameterTypeRequiredDescriptionkeywordstringYesSearch keyword, matches token symbol and namechainIdintegerNoPlatform 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:

json

{
    "tokenId": "224987722"
}

ParameterTypeRequiredDescriptiontokenIdstringYesInternal 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:

json

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

ParameterTypeRequiredDescriptionaddressstringYesWallet addresschainIdintegerYesPlatform internal chain ID (must iterate 2001-2004, 2007 for complete info)pageIndexintegerNoPage number, starting from 0pageSizeintegerNoPage 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:

json

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

ParameterTypeRequiredDescriptionaddressChainPairsarrayYesArray of address-chain pairs to queryaddressChainPairs[].addressstringYesWallet addressaddressChainPairs[].tokenAddressstring | nullNoToken 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[].chainIdstringYesPlatform internal chain ID (as string, e.g., "2001")tradeTypeintegerNoTrade type filter: 0=all, 1=send, 2=receive, 3=tradelimitstringNoMax 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:

FieldDescriptiondateDate string (YYYY-MM-DD)transactionListArray of transactions for this date

Response — Transaction Fields (transactionList[]):

FieldDescriptionblockNumberBlock numberchainIdPlatform internal chain IDtxHashTransaction hashtransactionType"send", "receive", or "trade"txTimeTransaction timestamp (milliseconds)fromArray of sender entriestoArray of receiver entriestxStatus"success" or "fail"txFeeTransaction feetxFeeUsdTransaction fee (USD)amountUsdTransaction amount (USD)confirmBlockNumberConfirmation block numberorderIdOrder ID

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

FieldDescriptionaddressWallet addressamountToken amountamountUsdAmount (USD)assetToken asset object (null if not applicable)

Response — Asset Fields (asset):

FieldDescriptionsymbolToken symboltokenAddressToken contract addresstokenIconToken icon URLchainIconChain 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:

json

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

ParameterTypeRequiredDescriptiontokenInAddressstringYesSource token contract address (see native token address handling rules)tokenOutAddressstringYesTarget token contract addresstokenInIdstringYesSource token platform internal IDtokenOutIdstringYesTarget token platform internal IDamountInnumberYesSwap amount (defaults to 100 if not specified by user)tokenInDecimalsintegerYesSource token decimal placestokenOutDecimalsintegerYesTarget token decimal placesslippagenumberYesSlippage tolerance (e.g., 0.1 = 10%)fromChainIdintegerYesSource chain platform internal chain IDtoChainIdintegerYesTarget 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:

json

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

ParameterTypeRequiredDescriptiontokenIdsarrayYesPlatform internal chain ID array (2001=Solana, 2002=BSC, 2003=Ethereum, 2004=Arbitrum, 2007=Base)latestOnlybooleanNoWhether 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:

tokenIdchainIdToken SymbolToken Name20012001SOLSolana20022002BNBBNB20032003ETHEthereum20042004ARBArbitrum20072007BASEBase

---

chain-detail#

Query chain details by platform internal chain ID.

Request:

json

{
    "chainId": 2001
}

ParameterTypeRequiredDescriptionchainIdintegerYesPlatform internal chain ID

Response Contains Fields:

FieldDescriptionchainIdPlatform internal chain IDnetworkChainIdIndustry standard blockchain network chain ID (e.g., 501=Solana, 56=BSC, 1=Ethereum)chainSeriesChain series (e.g., SVM, EVM)chainNameFull chain nameshortNameChain short name (e.g., SOL)exploreUrlBlock explorer URLtxUrlTransaction explorer URLaddressUrlAddress explorer URLdepositConfirmationsRequired deposit confirmationswithdrawConfirmationsRequired withdrawal confirmationsstatusChain status

---

kline#

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

Request:

json

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

ParameterTypeRequiredDescriptionintervalstringYesCandlestick period: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 1dtokenAddressstringYesToken contract addressstartTimestringYesStart timestamp (seconds)endTimestringYesEnd timestamp (seconds)

---

hot-ranking / xstock-ranking#

Get hot token / US stock mapped token ranking.

Request:

json

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

ParameterTypeRequiredDescriptionqueryFieldsarrayNoQuery field filtertimezonestringYesTime window: 1=1min, 2=5min, 3=1hour, 4=4hours, 5=24hours

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

FieldDescriptiontokenIdPlatform internal token IDtokenSymbolToken symboltokenNameToken nametokenAddressToken contract addresstokenIconUrlToken icon URLchainIdPlatform internal chain IDpriceCurrent price (USD)priceChangePrice change ratepriceChange24h24-hour price change ratemarketcapMarket capvolumeTrading volumeliquidityLiquidityholdersNumber of holder addressesbuyBuy countsellSell countrankRank positioncreateAtToken creation timecheckAudit/check statussourceData sourcepricesHistorical price points array

---

smart-money-rank#

Get smart money 7-day P&L ranking.

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

Request:

json

{
    "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
    }
}

ParameterTypeRequiredDescriptioncurrentintegerNoPage number, default 1sizeintegerNoPage size, max 100orderBystringNoSort field: profit7d, winRate7d, profitRate7d, tradeCount, totalTradeAmount, lastTradeTimeorderstringNoSort direction: desc / ascfilters.profitMinnumberNoMinimum 7-day profit amountfilters.profitMaxnumberNoMaximum 7-day profit amountfilters.profitRateMinnumberNoMinimum 7-day profit rate (%)filters.profitRateMaxnumberNoMaximum 7-day profit rate (%)filters.winRateMinnumberNoMinimum 7-day win rate (%)filters.winRateMaxnumberNoMaximum 7-day win rate (%)filters.tradeCountMinintegerNoMinimum trade countfilters.tradeCountMaxintegerNoMaximum trade countfilters.totalTradeAmountMinnumberNoMinimum total trade amount (USD)filters.totalTradeAmountMaxnumberNoMaximum total trade amount (USD)

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

FieldDescriptionwalletAddressSmart money wallet addressrankRank positionprofit7d7-day profit amountprofitRate7d7-day profit rate (%)winRate7d7-day win rate (%)tradeCountTotal trade countbuyCountBuy countsellCountSell counttotalTradeAmountTotal trade amount (USD)avgBuyAmountAverage buy amountlastTradeTimeLast trade timestamplatestTradeTokenLatest trade token addresslatestTradeTokenNameLatest trade token nameprofitTrend7d7-day profit trend array (dailyProfit, dailyProfitRate per day)bestProfitTokenBest profit token array (address, name, profitRate, profit)chainIdPlatform internal chain IDfollowWhether current user follows this addresswalletRemarkWallet remark/tagupdateTimeLast update timecreateTimeRecord creation timenotifyWhether notifications are enabled

---

smart-money-info#

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

Limitation: walletAddress must be provided by the user.

Request:

json

{
    "walletAddress": "As7HjL7dzzvbRbaD3WCun47robib2kmAKRXMvjHkSMB5"
}

ParameterTypeRequiredDescriptionwalletAddressstringYesSmart money wallet address (must be provided by user)

Response — Top-level Fields:

FieldDescriptionwalletAddressWallet addresswalletBalanceTotal wallet balance (USD)walletSolBalanceSOL balancefollowWhether current user follows this addresswalletRemarkWallet remark/tagmarketDistributionMarket distribution data

Response — Address Analysis Fields (profitInfo):

FieldDescriptionprofitInfo.profit7d7-day profitprofitInfo.profitRate7d7-day profit rateprofitInfo.winRate7d7-day win rateprofitInfo.tradeInfoTrade info summaryprofitInfo.topProfitTop profit detailsprofitInfo.profitRateDistributionProfit rate distributionprofitInfo.profitTrend7d7-day profit trend array

Response — Holdings Fields (proportion[]):

FieldDescriptiontokenAddressToken contract addresstokenNameToken nametokenIconToken icon URLtokenIdPlatform internal token IDchainIdPlatform internal chain IDquantityHolding quantitybalanceHolding value (USD)priceCurrent priceholdingPercentageHolding percentagepriceChangeRatePrice change rate

Response — Transaction History Fields (tradeHistory[]):

FieldDescriptiontokenAddressToken contract addresstokenSymbolToken symboltokenIconToken icontokenIdPlatform internal token IDchainIdPlatform internal chain IDtradeDirectionBUY or SELLtradeTimeTrade timestampquantityTrade quantitytotalUSDTrade amount (USD)priceExecution pricetxHashTransaction hashprofitTrade 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