BitMart Web3 Wallet AI Skills

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

Supported Chains

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

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

tokenAddress field returned by address-balance

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

tokenAddress parameter for swap-quote endpoint

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

Common Contract Tokens (Testnet)

API Details

token-search

Fuzzy search tokens by name or symbol.

Request:

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

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

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
}

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

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:

Response — Transaction Fields (transactionList[]):

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

Response — Asset Fields (asset):

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
}

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
}

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:

chain-detail

Query chain details by platform internal chain ID.

Request:

{
    "chainId": 2001
}

Response Contains Fields:

kline

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

Request:

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

hot-ranking / xstock-ranking

Get hot token / US stock mapped token ranking.

Request:

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

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

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

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

smart-money-info

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

Limitation: walletAddress must be provided by the user.

Request:

{
    "walletAddress": "As7HjL7dzzvbRbaD3WCun47robib2kmAKRXMvjHkSMB5"
}

Response — Top-level Fields:

Response — Address Analysis Fields (profitInfo):

Response — Holdings Fields (proportion[]):

Response — Transaction History Fields (tradeHistory[]):

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