Bitmart Wallet AI

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: