bitmart wallet skill

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.

# 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": "2h4hhjuWxEo4uyzG