bitmart-wallet-ai

What this skill does

# 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
- **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:**
```json
{
    "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:**
```json
{
    "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:**
```json
{
    "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:**
```json
{
    "addressChainPairs": [
        {
            "address": "2h4hhjuWxEo4uyz