# Xxyy Trade

> Executes on-chain token trades and queries data on Solana, Ethereum, BSC, and Base via the XXYY Open API.

- Skill: `jimmy-holiday/xxyy-trade` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add jimmy-holiday/xxyy-trade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jimmy-holiday/xxyy-trade/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs, Finance & Business, Crypto & Web3, Trading & Investing
- Tags: Api Key, Base, Bsc, Ethereum, Solana, Swap, Token Trading, Wallet
- Author: Jimmy-Holiday (https://skillmd.com/u/jimmy-holiday)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/jimmy-holiday/xxyy-trade

---


# XXYY Trade

On-chain token trading and data queries on Solana, Ethereum, BSC, and Base via XXYY Open API.

## Prerequisites

Set environment variables before use:
- `XXYY_API_KEY` (required) -- Your XXYY Open API Key (format: `xxyy_ak_xxxx`). Get one at https://www.xxyy.io/apikey
- `XXYY_API_BASE_URL` (optional) -- API base URL, defaults to `https://www.xxyy.io`

## Authentication

All requests require header: `Authorization: Bearer $XXYY_API_KEY`

## Security Notes

> **⚠ READ BEFORE FIRST USE.** This skill executes **real on-chain trades** with real funds. There is **no read-only API key** — the same key signs both data queries and trades. Treat your `XXYY_API_KEY` like a hot wallet private key. The skill will surface a one-time risk acknowledgement on your first trade each session; after that, only trade details are confirmed so trading stays fast.

- **⚠️ API Key = Wallet access** -- Your XXYY API Key can execute real on-chain trades using your wallet balance. If it leaks, anyone can buy/sell tokens with your funds. Never share it, never commit it to version control, never expose it in logs or public channels. If you suspect a leak, regenerate the key immediately at https://xxyy.io.
- **Custodial trading model** -- XXYY is a custodial trading platform. You only provide your wallet address (public key) and API Key. No private keys or wallet signing are needed -- XXYY executes trades on your behalf through their platform.
- **No read-only mode** -- The same API Key is used for both data queries (Feed, Token Query) and trading (Buy, Sell). There is currently no separate read-only key.
- **IP whitelist (recommended)** -- For extra security, configure an IP whitelist for your API Key at https://www.xxyy.io/apikey. Only whitelisted IPs can call the API. Use the `get_ip` tool to check your current outbound IP before setting up the whitelist.

## API Reference

> **STRICT: Only the endpoints listed below exist. Do NOT guess, infer, or construct any URL that is not explicitly documented here. If you need functionality not covered below, tell the user it is not supported.**
>
> Complete endpoint list:
> - `POST /api/trade/open/api/swap` — Buy / Sell
> - `GET  /api/trade/open/api/trade` — Query Trade
> - `GET  /api/trade/open/api/ping` — Ping
> - `POST /api/trade/open/api/feed/{type}` — Feed Scan
> - `GET  /api/trade/open/api/query` — Token Query
> - `GET  /api/trade/open/api/wallets` — List Wallets
> - `GET  /api/trade/open/api/wallet/info` — Wallet Info
> - `GET  /api/trade/open/api/pnl` — PNL Query
> - `GET  /api/trade/open/api/trades` — Trade History
> - `GET  /api/trade/open/api/ip` — Get IP (exempt from IP whitelist)
> - `GET  /api/trade/open/api/kol-buy-list` — KOL Buy List
> - `GET  /api/trade/open/api/tag-holder-buy-list` — Tag Holder Buy List
> - `GET  /api/trade/open/api/label-list` — Label List (tokens with specific labels)
> - `POST /api/trade/open/api/signal-list` — Signal List (AI trending signals)
> - `POST /api/trade/open/api/trending-list` — Trending List (hot tokens by period, SOL/BSC)
> - `POST /api/trade/open/api/{chain}/launch` — Launch Token (create new token)
> - `POST /api/trade/open/api/autoSell/createOrUpdate` — Create/Update Auto-Sell Rules
> - `GET  /api/trade/open/api/autoSell/list` — List Auto-Sell Rules
> - `GET  /api/trade/open/api/autoSell/delete` — Delete Auto-Sell Rules
> - `GET  /api/trade/open/api/autoSell/open` — Toggle Auto-Sell
> - `GET  /api/trade/open/api/holders/{type}` — Token Holder List

### Buy Token
`POST ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/swap`

```json
{
  "chain": "sol",
  "walletAddress": "<user_wallet>",
  "tokenAddress": "<token_contract>",
  "isBuy": true,
  "amount": 0.1,
  "tip": 0.0001,
  "slippage": 20
}
```

#### Buy Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | YES | string | `sol` / `eth` / `bsc` / `base` | Only these 4 values accepted |
| `walletAddress` | YES | string | SOL: Base58 32-44 chars; EVM: 0x+40hex | Wallet address on XXYY platform, must match chain |
| `tokenAddress` | YES | string | Valid contract address | Token contract address to buy |
| `isBuy` | YES | boolean | `true` | Must be true for buy |
| `amount` | YES | number | > 0 | Amount in native currency (SOL/ETH/BNB) |
| `tip` | YES | number | SOL: 0.0001-0.1 (unit: SOL); EVM: 0.1-100 (unit: Gwei) | Priority fee for all chains. If not provided, falls back to priorityFee |
| `slippage` | NO | number | 0-100 | Slippage tolerance %, default 20 |
| `model` | NO | number | 1 or 2 | 1=anti-sandwich (default), 2=fast mode |
| `priorityFee` | NO | number | >= 0 | Solana chain only. Extra priority fee in addition to tip |

### Sell Token
`POST ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/swap`

```json
{
  "chain": "sol",
  "walletAddress": "<user_wallet>",
  "tokenAddress": "<token_contract>",
  "isBuy": false,
  "amount": 50,
  "tip": 0.0001
}
```

#### Sell Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | YES | string | `sol` / `eth` / `bsc` / `base` | Only these 4 values accepted |
| `walletAddress` | YES | string | SOL: Base58 32-44 chars; EVM: 0x+40hex | Wallet address on XXYY platform, must match chain |
| `tokenAddress` | YES | string | Valid contract address | Token contract address to sell |
| `isBuy` | YES | boolean | `false` | Must be false for sell |
| `amount` | YES | number | 1-100 | Sell percentage. Example: 50 = sell 50% of holdings |
| `tip` | YES | number | SOL: 0.0001-0.1 (unit: SOL); EVM: 0.1-100 (unit: Gwei) | Priority fee for all chains. If not provided, falls back to priorityFee |
| `slippage` | NO | number | 0-100 | Slippage tolerance %, default 20 |
| `model` | NO | number | 1 or 2 | 1=anti-sandwich (default), 2=fast mode |
| `priorityFee` | NO | number | >= 0 | Solana chain only. Extra priority fee in addition to tip |

### tip / priorityFee Rules

- `tip` (required) -- Universal priority fee for ALL chains. EVM chains (eth/bsc/base) use tip as the priority fee. If tip is not provided, the API falls back to priorityFee.
  - SOL chain: unit is SOL (1 = 1 SOL, very expensive). Recommended range: 0.0001 - 0.1
  - EVM chains (eth/bsc/base): unit is Gwei. Recommended range: 0.1 - 100
- `priorityFee` (optional) -- Only effective on Solana chain. Solana supports both tip and priorityFee simultaneously.

### Query Trade
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/trade?txId=<tx_id>`

Response fields: txId, status (pending/success/failed), statusDesc, chain, tokenAddress, walletAddress, isBuy, baseAmount, quoteAmount

### Trade History
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/trades?walletAddress=<wallet>&chain=<chain>`

Paginated query of successful trade records for a specific wallet. Only returns completed transactions, sorted by creation time (newest first).

#### Trade History Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `walletAddress` | YES | string | Wallet address | Must belong to current API Key user |
| `chain` | YES | string | `sol` / `eth` / `bsc` / `base` | Chain identifier (required) |
| `tokenAddress` | NO | string | Contract address | Filter by specific token |
| `pageNum` | NO | int | >= 1 | Page number, default 1 |
| `pageSize` | NO | int | 1-20 | Items per page, default 20 |

#### Trade History Response

```json
{
  "code": 200,
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 56,
    "list": [
      {
        "txId": "5xYz...",
        "status": 2,
        "statusDesc": "success",
        "chain": "sol",
        "tokenAddress": "EPjF...",
        "walletAddress": "5xYz...",
        "isBuy": 1,
        "baseAmount": 0.5,
        "quoteAmount": 1000,
        "createTime": "2026-03-18T10:00:00",
        "updateTime": "2026-03-18T10:00:05"
      }
    ]
  }
}
```

Response fields: txId, status (fixed 2=success), statusDesc, chain, tokenAddress, walletAddress, isBuy (1=buy, 0=sell), baseAmount, quoteAmount, createTime, updateTime

### Ping
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/ping`

Returns "pong" if API key is valid.

### Feed (Scan Tokens)
`POST ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/feed/{type}?chain={chain}`

Retrieve Meme token lists: newly launched, almost graduated, or graduated.

#### Path & Query Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `type` | YES | path string | `NEW` / `ALMOST` / `COMPLETED` | NEW = newly launched, ALMOST = almost graduated, COMPLETED = graduated |
| `chain` | NO | query string | `sol` / `eth` / `bsc` / `base` | Default `sol`. All 4 chains supported |

#### Body (Filter Parameters)

All filters are optional. Range parameters use comma-separated string format `"min,max"`. Leave one side empty to set only min or max (e.g. `"100,"` = min 100, `",50"` = max 50).

| Param | Type | Description | Example |
|-------|------|-------------|---------|
| `dex` | string[] | DEX platform filter | See DEX Values by Chain below |
| `quoteTokens` | string[] | Quote token filter | See quoteTokens Values by Chain below |
| `link` | string[] | Social media link filter | `["x","tg","web"]` |
| `keywords` | string[] | Token name/symbol keyword match | `["pepe","doge"]` |
| `ignoreWords` | string[] | Ignore keywords | `["scam"]` |
| `mc` | string | Market cap range (USD) | `"10000,500000"` |
| `liq` | string | Liquidity range (USD) | `"1000,"` |
| `vol` | string | Trading volume range (USD) | `"5000,100000"` |
| `holder` | string | Holder count range | `"50,"` |
| `createTime` | string | Creation time range (minutes from now) | `"1,20"` |
| `tradeCount` | string | Trade count range | `"100,"` |
| `buyCount` | string | Buy count range | `"50,"` |
| `sellCount` | string | Sell count range | `"10,"` |
| `devBuy` | string | Dev buy amount range (native token) | `"0.001,"` |
| `devSell` | string | Dev sell amount range (native token) | `"0.001,"` |
| `devHp` | string | Dev holding % range | `",60"` |
| `topHp` | string | Top10 holding % range | `",60"` |
| `insiderHp` | string | Insider holding % range | `",50"` |
| `bundleHp` | string | Bundle holding % range | `",60"` |
| `newWalletHp` | string | New wallet holding % range | `",30"` |
| `progress` | string | Graduation progress % range (NEW/ALMOST only) | `"1,90"` |
| `snipers` | string | Sniper count range | `",5"` |
| `xnameCount` | string | Twitter rename count range | `",3"` |
| `tagHolder` | string | Watched wallet buy count range | `"1,2"` |
| `kol` | string | KOL buy count range | `"1,2"` |
| `dexPay` | int | DexScreener paid, `1` = filter paid only | `1` |
| `oneLink` | int | At least one social link, `1` = enabled | `1` |
| `live` | int | Currently live streaming, `1` = filter live | `1` |

#### DEX Values by Chain

- **SOL**: `pump`, `pumpmayhem`, `bonk`, `heaven`, `believe`, `daosfun`, `launchlab`, `mdbc`, `jupstudio`, `mdbcbags`, `trends`, `moonshotn`, `boop`, `moon`, `time`
- **BSC**: `four`, `four_agent`, `bnonly`, `flap`

#### quoteTokens Values by Chain

- **SOL**: `sol`, `usdc`, `usd1`
- **BSC**: `bnb`, `usdt`, `usdc`, `usd1`, `aster`, `u`

#### Feed Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "tokenAddress": "...",
        "symbol": "TOKEN",
        "name": "Token Name",
        "createTime": 1773140232851,
        "dexName": "PUMPFUN",
        "launchPlatform": { "name": "PUMPFUN", "progress": "12.89", "completed": false },
        "holders": 3,
        "priceUSD": 0.000003046,
        "marketCapUSD": 3046.80,
        "devHoldPercent": 12.48,
        "hasLink": false,
        "snipers": 0,
        "quoteToken": "sol"
      }
    ]
  },
  "success": true
}
```

Key response fields: `tokenAddress`, `symbol`, `name`, `createTime`, `dexName`, `launchPlatform` (name/progress/completed), `holders`, `priceUSD`, `marketCapUSD`, `devHoldPercent`, `hasLink`, `snipers`, `volume`, `tradeCount`, `buyCount`, `sellCount`, `topHolderPercent`, `insiderHp`, `bundleHp`

### Token Query
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/query?ca={contract_address}&chain={chain}`

Query token details: price, security checks, tax rates, holder distribution, etc.

#### Token Query Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `ca` | YES | string | Contract address | Token contract address |
| `chain` | NO | string | `sol` / `eth` / `bsc` / `base` | Default `sol`. All 4 chains supported |

#### Token Query Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "chainId": "bsc",
    "tokenAddress": "0x...",
    "baseSymbol": "TOKEN",
    "tradeInfo": {
      "marketCapUsd": 15464629.87,
      "price": 0.01546,
      "holder": 7596,
      "hourTradeNum": 20611,
      "hourTradeVolume": 2564705.05
    },
    "pairInfo": {
      "pairAddress": "0x...",
      "pair": "TOKEN - WBNB",
      "liquidateUsd": 581750.57,
      "createTime": 1772182240000
    },
    "securityInfo": {
      "honeyPot": false,
      "openSource": true,
      "noOwner": true,
      "locked": true
    },
    "taxInfo": { "buy": "0", "sell": "0" },
    "linkInfo": { "tg": "", "x": "", "web": "" },
    "dev": { "address": "0x...", "pct": 0.0 },
    "topHolderPct": 25.14,
    "topHolderList": [
      { "address": "0x...", "balance": 98665702.34, "pct": 9.86 }
    ]
  },
  "success": true
}
```

Response groups:
- **tradeInfo**: marketCapUsd, price, holder, hourTradeNum, hourTradeVolume
- **pairInfo**: pairAddress, pair, liquidateUsd, createTime
- **securityInfo**: honeyPot, openSource, noOwner, locked
- **taxInfo**: buy, sell (percentage strings)
- **dev**: address, pct
- **topHolderPct** and **topHolderList**: top 10 holder distribution

### List Wallets
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/wallets`

Query the current user's wallet list (with balances) for a specific chain.

#### Wallets Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | NO | string | `sol` / `eth` / `bsc` / `base` | Default `sol` |
| `pageNum` | NO | int | >= 1 | Page number, default 1 |
| `pageSize` | NO | int | 1-20 | Items per page, default 20 |
| `tokenAddress` | NO | string | Contract address | Returns token holdings per wallet |

#### Wallets Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "totalCount": 3,
    "pageSize": 20,
    "totalPage": 1,
    "currPage": 1,
    "list": [
      {
        "userId": 12345,
        "chain": 1,
        "name": "Wallet-1",
        "address": "5xYz...abc",
        "balance": 1.523456789,
        "topUp": 1,
        "tokenBalance": null,
        "createTime": "2025-01-01 00:00:00",
        "updateTime": "2025-06-01 12:00:00",
        "isImport": false
      }
    ]
  },
  "success": true
}
```

Response fields:
- **totalCount**: Total wallet count
- **list[].chain**: Chain code (1=SOL, 2=BSC, 3=ETH, 6=BASE)
- **list[].name**: Wallet display name
- **list[].address**: Wallet address
- **list[].balance**: Native token balance
- **list[].topUp**: 1=pinned, 0=normal
- **list[].tokenBalance**: Token holdings (only present when `tokenAddress` is provided). Contains `amount`, `decimals`, `uiAmount`, `uiAmountString`
- **list[].isImport**: Whether the wallet was imported

#### Chain Codes

| Code | Chain |
|------|-------|
| 1 | SOL |
| 2 | BSC |
| 3 | ETH |
| 6 | BASE |

### Wallet Info
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/wallet/info`

Query a single wallet's details (native balance + optional token balance).

#### Wallet Info Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `walletAddress` | YES | string | Wallet address | EVM chains are case-insensitive |
| `chain` | NO | string | `sol` / `eth` / `bsc` / `base` | Default `sol` |
| `tokenAddress` | NO | string | Contract address | Returns token holdings for this token |

#### Wallet Info Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "address": "5xY...abc",
    "name": "MyWallet",
    "chain": 1,
    "isImport": false,
    "topUp": 0,
    "balance": 1.234567,
    "tokenBalance": {
      "amount": "1000000",
      "uiAmount": 1.0,
      "decimals": 6
    }
  },
  "success": true
}
```

Response fields:
- **address**: Wallet address
- **name**: Wallet display name
- **chain**: Chain code (1=SOL, 2=BSC, 3=ETH, 6=BASE)
- **balance**: Native token balance
- **topUp**: 1=pinned, 0=normal
- **isImport**: Whether the wallet was imported
- **tokenBalance**: Only present when `tokenAddress` is provided. Contains `amount`, `uiAmount`, `decimals`

### PNL Query
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/pnl?walletAddress=<wallet>&tokenAddress=<token>&chain=<chain>`

Query PNL (profit and loss) data for a specific wallet-token pair. Returns buy/sell totals, current holdings, and profit in both native currency and USD. Covers the last 30 days.

#### PNL Query Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `walletAddress` | YES | string | Wallet address | Must belong to current API Key user |
| `tokenAddress` | YES | string | Contract address | Token contract address |
| `chain` | YES | string | `sol` / `eth` / `bsc` / `base` | Chain identifier (required) |

#### PNL Query Response

```json
{
  "code": 200,
  "data": {
    "wallet": "5xYz...",
    "tokenMint": "EPjF...",
    "balance": 1.5,
    "buy": 2.0,
    "sell": 0.8,
    "hold": 1.2,
    "pnl": 0.5,
    "pnlusd": 75.0,
    "holdTokenNum": 1000,
    "holdTokenPercent": 0.05,
    "lastTradeTime": 1710000000000,
    "meta": {
      "symbol": "TOKEN",
      "dexId": "raydium",
      "pairAddress": "xxx"
    }
  }
}
```

Response fields:
- **wallet**: Wallet address
- **tokenMint**: Token contract address
- **balance**: Native token balance (e.g. SOL)
- **buy**: Total buy amount (native currency)
- **sell**: Total sell amount (native currency)
- **hold**: Current holding value (native currency)
- **pnl**: Profit/loss (native currency)
- **pnlusd**: Profit/loss (USD)
- **holdTokenNum**: Current token holdings quantity
- **holdTokenPercent**: Holdings as percentage of total supply
- **lastTradeTime**: Last trade timestamp (milliseconds)
- **meta.symbol**: Token symbol
- **meta.dexId**: DEX identifier
- **meta.pairAddress**: Trading pair address

### Get IP
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/ip`

Get the current outbound IP address of this server. Use this to check which IP to add to your API Key's whitelist. **This endpoint is exempt from IP whitelist restrictions** — it will work even if your IP is not whitelisted.

No parameters required.

#### Get IP Response

```json
{
  "code": 200,
  "data": {
    "ip": "203.0.113.42"
  },
  "success": true
}
```

Response fields:
- **ip**: Your current outbound IP address

### KOL Buy List
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/kol-buy-list?chain={chain}`

Get KOL (Key Opinion Leader) recent buy list. Shows tokens recently purchased by influential traders.

#### KOL Buy List Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | NO | string | `sol` / `eth` / `bsc` / `base` | Default `sol`. All 4 chains supported |

#### KOL Buy List Response

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "tokenMeta": {
        "symbol": "TOKEN",
        "dexId": "pump",
        "dexIcon": "https://...",
        "imageUrl": "https://...",
        "pairAddress": "PairAddress...",
        "mint": "TokenMintAddress..."
      },
      "priceNative": 0.0000001,
      "priceUsd": 0.0000085,
      "marketCap": 8500.0,
      "priceChange24h": 15.0,
      "walletBuyCnt": 2,
      "lastTradeTime": 1711234567890,
      "holder": 120,
      "volumeNative": 5000.0,
      "volumeUSD": 5000.0,
      "walletBuyItemList": [
        {
          "wallet": "KolWalletAddress...",
          "walletName": "KOL Name",
          "walletBuyAmount": 1.5
        }
      ]
    }
  ]
}
```

Response fields:
- **tokenMeta.symbol**: Token symbol
- **tokenMeta.mint**: Token contract address
- **tokenMeta.dexId**: DEX identifier
- **tokenMeta.pairAddress**: Trading pair address
- **tokenMeta.imageUrl**: Token logo URL
- **priceNative**: Price in native currency
- **priceUsd**: Price in USD
- **marketCap**: Market capitalization in USD
- **priceChange24h**: 24-hour price change percentage
- **walletBuyCnt**: Number of KOL wallets that bought
- **lastTradeTime**: Last trade timestamp (milliseconds)
- **holder**: Number of holders
- **walletBuyItemList[].wallet**: KOL wallet address
- **walletBuyItemList[].walletName**: KOL wallet name
- **walletBuyItemList[].walletBuyAmount**: Buy amount in native currency

### Tag Holder Buy List
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/tag-holder-buy-list?chain={chain}`

Get tag holder (Smart Money, Whale, etc.) recent buy list. Shows tokens recently purchased by tagged wallets.

#### Tag Holder Buy List Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | NO | string | `sol` / `eth` / `bsc` / `base` | Default `sol`. All 4 chains supported |

#### Tag Holder Buy List Response

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "tokenMeta": {
        "symbol": "TOKEN",
        "dexId": "pump",
        "dexIcon": "https://...",
        "imageUrl": "https://...",
        "pairAddress": "PairAddress...",
        "mint": "TokenMintAddress..."
      },
      "priceNative": 0.0000001,
      "priceUsd": 0.0000085,
      "marketCap": 8500.0,
      "priceChange24h": -5.0,
      "walletBuyCnt": 1,
      "lastTradeTime": 1711234567890,
      "holder": 250,
      "volumeNative": 12000.0,
      "volumeUSD": 12000.0,
      "walletBuyItemList": [
        {
          "wallet": "HolderWalletAddress...",
          "walletName": "Smart Money",
          "walletBuyAmount": 2.5
        }
      ]
    }
  ]
}
```

Response fields:
- **tokenMeta.symbol**: Token symbol
- **tokenMeta.mint**: Token contract address
- **tokenMeta.dexId**: DEX identifier
- **tokenMeta.pairAddress**: Trading pair address
- **tokenMeta.imageUrl**: Token logo URL
- **priceNative**: Price in native currency
- **priceUsd**: Price in USD
- **marketCap**: Market capitalization in USD
- **priceChange24h**: 24-hour price change percentage
- **walletBuyCnt**: Number of tagged wallets that bought
- **lastTradeTime**: Last trade timestamp (milliseconds)
- **holder**: Number of holders
- **walletBuyItemList[].wallet**: Holder wallet address
- **walletBuyItemList[].walletName**: Holder wallet name / tag
- **walletBuyItemList[].walletBuyAmount**: Buy amount in native currency

### Label List
`GET ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/label-list?chain={chain}&labelType={labelType}`

Get tokens with specific labels (e.g., AGENT_KOL marked tokens).

#### Label List Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | NO | string | `sol` / `eth` / `bsc` / `base` | Default `sol`. All 4 chains supported |
| `labelType` | NO | string | `AGENT_KOL` | Default `AGENT_KOL`. Currently only AGENT_KOL supported |

#### Label List Response

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "pairAddress": "PairAddress...",
      "dexId": "raydium",
      "dexName": "Raydium",
      "symbol": "TOKEN",
      "name": "Token Name",
      "tokenAddress": "TokenAddress...",
      "imageUrl": "https://...",
      "priceUSD": "0.00123",
      "marketCapUSD": "123456.78",
      "priceChange24H": "15.5",
      "launchFrom": "pump",
      "links": {
        "tg": "https://t.me/...",
        "x": "https://x.com/...",
        "web": "https://..."
      }
    }
  ],
  "success": true
}
```

Response fields:
- **pairAddress**: Trading pair address
- **dexId**: DEX identifier
- **dexName**: DEX name
- **symbol**: Token symbol
- **name**: Token name
- **tokenAddress**: Token contract address
- **imageUrl**: Token logo URL
- **priceUSD**: Current price in USD
- **marketCapUSD**: Market capitalization in USD
- **priceChange24H**: 24-hour price change percentage
- **launchFrom**: Launch platform
- **links**: Social media links (Telegram, X/Twitter, Website)

### Signal List
`POST ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/signal-list?type={type}&chain={chain}`

Get AI trend signal list (e.g., open-ai-trending tokens).

#### Signal List Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `type` | NO | string | `open-ai-trending` | Default `open-ai-trending`. Currently only open-ai-trending supported |
| `chain` | NO | string | `sol` / `eth` / `bsc` / `base` | Default `sol`. All 4 chains supported |

Request body: Empty JSON object `{}`

#### Signal List Response

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "pairAddress": "PairAddress...",
      "dexId": "raydium",
      "dexName": "Raydium",
      "symbol": "TOKEN",
      "name": "Token Name",
      "tokenAddress": "TokenAddress...",
      "imageUrl": "https://...",
      "priceUSD": "0.00456",
      "marketCapUSD": "456789.12",
      "priceChange24H": "-5.2",
      "launchFrom": "pump",
      "links": {
        "tg": "https://t.me/...",
        "x": "https://x.com/...",
        "web": "https://..."
      }
    }
  ],
  "success": true
}
```

Response fields: Same as Label List (see above)

### Trending List
`POST ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/trending-list?chain={chain}`

Get trending/hot token list. Shows the most active tokens within a given time period. Supports SOL and BSC chains.

#### Trending List Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | NO | string | `sol` / `bsc` | Default `sol`. Only SOL and BSC supported |
| `period` | YES | string | `1M` / `5M` / `30M` / `1H` / `6H` / `24H` | Time period for trending. Not all periods available for all internal categories |

Request body:
```json
{ "period": "5M" }
```

#### Trending List Response

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "imageUrl": "https://...",
      "createTime": "1774581395318",
      "symbol": "TOKEN",
      "name": "Token Name",
      "dexId": "pfamm",
      "headerImage": "https://...",
      "pairAddress": "PairAddress...",
      "tokenAddress": "TokenMintAddress...",
      "priceUSD": "0.00005670",
      "priceChange24H": "98.00",
      "launchPlatform": {
        "name": "PUMP",
        "progress": 85,
        "completed": false,
        "launchedPair": null
      },
      "dexName": "Pump AMM",
      "dexIcon": "https://...",
      "marketCapUSD": "56708.41",
      "links": { "tg": "", "x": "https://x.com/...", "web": "" },
      "security": {
        "mintAuthority": { "value": false, "passed": true },
        "freezeAuthority": { "value": false, "passed": true },
        "topHolder": { "value": 18.61, "passed": false },
        "lpBurned": { "value": 100.0, "passed": true }
      },
      "holders": 641,
      "devHoldPercent": "0.0000000000000",
      "smartWallets": { "total": 3, "records": [{ "wallet": "...", "action": "buy", "nativeAmount": "1.5" }] },
      "sourceDexIcon": "https://...",
      "launchFrom": "pump",
      "extendFlags": { "live": false },
      "volume": 142092.91,
      "liquid": 20995.35,
      "buyCount": 2123,
      "sellCount": 1620,
      "auditInfo": {
        "devHp": 0,
        "snipers": 20,
        "insiderHp": 0,
        "newHp": 10.63,
        "bundleHp": 0,
        "dexPaid": true
      }
    }
  ]
}
```

Response fields:
- **imageUrl**: Token logo URL
- **createTime**: Trading pair creation timestamp (milliseconds)
- **symbol**: Token symbol
- **name**: Token name
- **tokenAddress**: Token contract address
- **pairAddress**: Trading pair address
- **priceUSD**: Current price in USD
- **priceChange24H**: 24-hour price change percentage
- **marketCapUSD**: Market capitalization in USD
- **volume**: Trading volume
- **liquid**: Liquidity
- **buyCount**: Buy transaction count
- **sellCount**: Sell transaction count
- **holders**: Number of holders
- **devHoldPercent**: Developer holding percentage
- **dexName**: DEX pool name
- **launchFrom**: Launch platform identifier
- **launchPlatform**: Launch platform details (name, progress, completed, launchedPair)
- **links**: Social media links (tg, x, web)
- **security**: Security info — mintAuthority, freezeAuthority (value=bool, passed=bool), topHolder, lpBurned (value=number, passed=bool)
- **smartWallets**: Smart wallet activity (total count + recent records with wallet/action/nativeAmount)
- **extendFlags.live**: Whether token is currently live streaming
- **auditInfo**: Audit details — devHp (dev holding %), snipers count, insiderHp, newHp (new wallet holding %), bundleHp, dexPaid (DexScreener paid)

### Launch Token
`POST ${XXYY_API_BASE_URL:-https://www.xxyy.io}/api/trade/open/api/{chain}/launch`

Launch (create) a new token. Optionally buy an initial amount of the newly created token.

> **Note**: Chain restriction is lifted at the API level, but the current implementation only ships chain-specific options for `sol` (`solOptions`) and `bsc` (`bscOptions`). Launching on `eth`/`base` will fail downstream until corresponding options are added.

#### Path Parameters

| Param | Required | Type | Valid values | Description |
|-------|----------|------|-------------|-------------|
| `chain` | YES | string | `sol` / `eth` / `bsc` / `base` | See note above |

#### Launch Request Body

| Param | Required | Type | Description |
|-------|----------|------|-------------|
| `walletAddress` | YES | string | Wallet address (must belong to the API Key's account) |
| `name` | YES | string | Token name |
| `symbol` | YES | string | Token symbol |
| `buyAmount` | NO | string | Native token amount for initial buy. "0" = create only. Default: "0" |
| `solOptions` | Sol only | object | Solana chain specific options (see below) |
| `bscOptions` | BSC only | object | BSC chain specific options (see below) |

**buyAmount Limits:**
- SOL: max 100 SOL, min balance = buyAmount + 0.01 SOL
- BSC: max 20 BNB, min balance = buyAmount + 0.015 BNB

#### solOptions (chain=sol)

| Param | Required | Type | Default | Description |
|-------|----------|------|---------|-------------|
| `uri` | YES | string | - | Metadata JSON URI (Metaplex standard, containing name/symbol/description/image) |
| `slippage` | NO | integer | 100 | Slippage in basis points. 100 = 1%. Only effective when buyAmount > 0 |
| `priorityFee` | NO | long | 100000 | Priority fee in lamports |
| `tipFee` | NO | long | 100000 | Tip fee in lamports |
| `model` | NO | integer | 1 | 1 = MEV protection, 2 = fast mode |
| `creator` | NO | string | null | Creator address (base58). Defaults to signing wallet |
| `mayhemMode` | NO | boolean | false | Pump mayhem mode |
| `cashback` | NO | boolean | false | Pump cashback |

> Platform fee (1%) is charged automatically when buyAmount > 0, not configurable.

#### bscOptions (chain=bsc)

| Param | Required | Type | Default | Description |
|-------|----------|------|---------|-------------|
| `desc` | YES | string | - | Token description |
| `image` | YES | string | - | Image URL / base64 / data URI (≤5MB) |
| `label` | NO | string | "Meme" | Category: Meme, AI, Defi, Games, Infra, De-Sci, Social, Depin, Charity, Others |
| `gasPrice` | NO | string | null | Custom gas price (wei). Auto-fetched if not provided |
| `model` | NO | integer | 1 | 1 = MEV protection (bundle), 2 = fast mode |
| `feePlan` | NO | boolean | false | Fee plan toggle |
| `webUrl` | NO | string | "" | Website URL |
| `twitterUrl` | NO | string | "" | Twitter URL |
| `telegramUrl` | NO | string | "" | Telegram URL |
| `launchMode` | NO | string | `legacy` | `legacy` for existing FourMeme launch, `openfour` for OpenFour templates |
| `templateId` | OpenFour | string | - | OpenFour template ID, required when `launchMode=openfour` |
| `openFourParams` | NO | object | null | Schema-native OpenFour params; service fills safe defaults when possible |
| `initParams` | NO | object | null | Advanced: pre-encoded OpenFour module params. Avoid unless you know the schema bytes |
| `antiSniperEnabled` | NO | boolean | null | Optional OpenFour anti-sniper toggle |
| `tokenTaxInfo` | NO | object | null | Legacy BSC token tax configuration (see below); do not mix with OpenFour |

#### tokenTaxInfo (BSC legacy only)

| Param | Required | Type | Description |
|-------|----------|------|-------------|
| `feeRate` | YES | integer | Trading fee rate. Fixed options: 1, 3, 5, 10 (representing 1%-10%) |
| `burnRate` | YES | integer | Burn rate (0-100) |
| `divideRate` | YES | integer | Dividend distribution rate (0-100) |
| `liquidityRate` | YES | integer | Liquidity pool rate (0-100) |
| `recipientRate` | YES | integer | Recipient allocation rate (0-100) |
| `minSharing` | Conditional | long | Min token amount for dividend participation (in ether). Required when divideRate > 0. Format: d × 10^n (n≥5, 1≤d≤9) |
| `recipientAddress` | Conditional | string | Recipient address (0x...). Required when recipientRate > 0 |

**Constraint:** burnRate + divideRate + liquidityRate + recipientRate must equal 100.

#### BSC OpenFour Templates

| Template ID | Name | MCP alias | Notes |
|-------------|------|-----------|-------|
| `1778027615723` | Goplus SkillRoyalty | `skillroyalty` | Tax / royalty template. Fee rates are basis points; `100 = 1%` |
| `1778027615724` | Goplus Creator Incentives | `creator_incentives` | Usually works with service defaults |
| `1778027615725` | Likwid Dex | `likwid_dex` | Usually works with service defaults |
| `1778027615728` | Cubepeg | `cubepeg` | Node service auto-mines `hookSalt`; callers normally do not pass it |

#### openFourParams (BSC OpenFour)

| Param | Template | Type | Description |
|-------|----------|------|-------------|
| `buyFeeRate` | SkillRoyalty | integer | Buy fee in bps. `100 = 1%` |
| `sellFeeRate` | SkillRoyalty | integer | Sell fee in bps. `100 = 1%` |
| `rateFounder` | SkillRoyalty | integer | Founder fee share (0-100) |
| `rateHolder` | SkillRoyalty | integer | Holder fee share (0-100) |
| `rateBurn` | SkillRoyalty | integer | Burn fee share (0-100) |
| `rateLiquidity` | SkillRoyalty | integer | Liquidity fee share (0-100) |
| `minShare` | SkillRoyalty | string | Minimum share threshold; pass as a string to avoid large-number precision loss. Service default is safe for normal launches |
| `founder` | SkillRoyalty | string | Founder EVM address; defaults to the signing wallet when omitted |
| `renderer` | Cubepeg | string | Optional renderer EVM address; zero-address/default is acceptable |
| `hookSalt` | Cubepeg advanced | bytes32 | Optional. Leave empty so Node auto-mines a valid salt |

**OpenFour Notes:**
- REST API payload uses nested `bscOptions.*` fields. MCP `launch_token` uses flat `bsc_*` fields and converts them into the REST payload before calling the API.
- `launchMode` defaults to `legacy` in the REST API. In the MCP tool, `bsc_launchMode` may be omitted; if a supported OpenFour template alias/ID is provided, the tool infers OpenFour automatically.
- Use legacy for existing FourMeme launches and legacy `tokenTaxInfo`; use OpenFour only when the user asks for one of the supported OpenFour templates. Do not mix legacy `tokenTaxInfo` with OpenFour params.
- `buyAmount` becomes the OpenFour initial buy / presale quote in BNB. Use `"0"` for create-only, or e.g. `"0.001"` for create + initial buy.
- Cubepeg `hookSalt` is mined by the Node service when omitted; only pass it for advanced deterministic deployments.
- SkillRoyalty fee rates are bps, not percent. `buyFeeRate=100` and `sellFeeRate=100` mean 1% buy/sell fee. If you override distribution rates, `rateFounder + rateHolder + rateBurn + rateLiquidity` must equal 100.
- `initParams` is an advanced escape hatch for already encoded OpenFour module params. Prefer `openFourParams` for normal integrations.

#### MCP launch_token BSC OpenFour Parameters

These are MCP tool parameters, not raw REST fields. The MCP server maps them into `bscOptions.launchMode`, `bscOptions.templateId`, `bscOptions.openFourParams`, and `bscOptions.initParams`.

| MCP Param | Required | Type | Maps to REST | Description |
|-----------|----------|------|--------------|-------------|
| `bsc_launchMode` | NO | enum | `bscOptions.launchMode` | `legacy` or `openfour`. Can be omitted; OpenFour is inferred when a supported template is provided |
| `bsc_openfourTemplate` | NO | enum | `bscOptions.templateId` | Alias: `skillroyalty`, `creator_incentives`, `likwid_dex`, `cubepeg` |
| `bsc_openfourTemplateId` | OpenFour | string | `bscOptions.templateId` | One of `1778027615723`, `1778027615724`, `1778027615725`, `1778027615728` |
| `bsc_openfour_antiSniperEnabled` | NO | boolean | `bscOptions.antiSniperEnabled` | Optional anti-sniper toggle |
| `bsc_openfour_renderer` | Cubepeg only | string | `openFourParams.renderer` | Optional renderer EVM address |
| `bsc_openfour_hookSalt` | NO | bytes32 | `openFourParams.hookSalt` | Advanced Cubepeg salt. Omit for auto-mining by Node service |
| `bsc_openfour_buyFeeRate` | SkillRoyalty only | integer | `openFourParams.buyFeeRate` | Buy fee in bps; `100 = 1%` |
| `bsc_openfour_sellFeeRate` | SkillRoyalty only | integer | `openFourParams.sellFeeRate` | Sell fee in bps; `100 = 1%` |
| `bsc_openfour_rateFounder` | SkillRoyalty only | integer | `openFourParams.rateFounder` | Founder share (0-100) |
| `bsc_openfour_rateHolder` | SkillRoyalty only | integer | `openFourParams.rateHolder` | Holder share (0-100) |
| `bsc_openfour_rateBurn` | SkillRoyalty only | integer | `openFourParams.rateBurn` | Burn share (0-100) |
| `bsc_openfour_rateLiquidity` | SkillRoyalty only | integer | `openFourParams.rateLiquidity` | Liquidity share (0-100) |
| `bsc_openfour_minShare` | SkillRoyalty only | string | `openFourParams.minShare` | Minimum share threshold; pass as string |
| `bsc_openfour_founder` | SkillRoyalty only | string | `openFourParams.founder` | Founder EVM address; defaults to signing wallet in Node service |
| `bsc_openfourParamsJson` | NO | JSON object string | `bscOptions.openFourParams` | Advanced raw params, merged before typed `bsc_openfour_*` fields |
| `bsc_openfourInitParamsJson` | NO | JSON object string | `bscOptions.initParams` | Advanced encoded module params; avoid unless schema bytes are known |

#### MCP OpenFour launch_token Examples

Cubepeg (`1778027615728`, hookSalt auto-mined):
```json
{
  "chain": "bsc",
  "walletAddress": "<BSC_WALLET>",
  "name": "Cube Token",
  "symbol": "CUBE",
  "buyAmount": "0.001",
  "bsc_desc": "OpenFour Cubepeg token",
  "bsc_image": "https://example.com/image.png",
  "bsc_label": "Meme",
  "bsc_model": 1,
  "bsc_feePlan": false,
  "bsc_launchMode": "openfour",
  "bsc_openfourTemplate": "cubepeg"
}
```

Likwid Dex (`1778027615725`):
```json
{
  "chain": "bsc",
  "walletAddress": "<BSC_WALLET>",
  "name": "Likwid Token",
  "symbol": "LIQ",
  "buyAmount": "0.001",
  "bsc_desc": "OpenFour Likwid Dex token",
  "bsc_image": "https://example.com/image.png",
  "bsc_label": "Meme",
  "bsc_model": 1,
  "bsc_feePlan": false,
  "bsc_launchMode": "openfour",
  "bsc_openfourTemplate": "likwid_de

…(truncated)