birdeye

Birdeye 数据技能

Birdeye 是 Solana AI Agent 的主要实时市场数据层，可直接索引链上状态，覆盖 800 万多个代币和 500 多个 AMM 池，数据新鲜度不到 10 秒。

概述

当用户询问以下内容时使用此技能：

• 代币价格、图表或基本面数据（市值、交易量、流动性、持有者数量）
• 新代币或热门代币（发现、Meme 代币、新上市代币）
• 代币或交易对的链上交易历史
• 谁在买入／卖出某个代币（顶级交易者、涨幅榜）
• 钱包投资组合、净资产或盈亏跟踪
• 代币安全／跑路风险检查
• 实时价格或巨鲸提醒流（WebSocket）
• 无需 API 密钥即可按请求付费（x402／Agent 原生支付）

说明

1. 检查 MCP：如果环境中提供了 birdeye-mcp 工具，请直接使用。
2. 身份验证：有两种模式：
   • API 密钥（默认）：基本 URL 为 https://public-api.birdeye.so，从 BIRDEYE_API_KEY 读取密钥。
   • x402 按请求付费（无需 API 密钥）：基本 URL 为 https://public-api.birdeye.so/x402，每次调用使用 USDC 付费。当 Agent 有 Solana 钱包但没有 API 密钥时使用。参见 resources/x402.md。
3. 每个 REST 请求都必须包含以下请求头：

   X-API-KEY: <key>
   x-chain: solana           ← do NOT put chain in the URL for REST calls
   Accept: application/json
   User-Agent: <anything>    ← defensive — some older HTTP clients hit 403 without one
   

4. 使用此决策表选择合适的端点：

用户意图	端点
代币价格（当前）	GET /defi/price?address=
代币价格（多个）	GET /defi/multi_price?list_address=a,b,c
图表／OHLCV 蜡烛图	GET /defi/v3/ohlcv?address=&type=1H&time_from=<unix>&time_to=<unix>
代币基本面数据（市值、交易量、持有者）	GET /defi/token_overview?address=
代币元数据（名称、符号、徽标）	GET /defi/v3/token/meta-data/single?address=
跑路／蜜罐检查	GET /defi/token_security?address=
新上市代币	GET /defi/v2/tokens/new_listing?limit=20
热门代币	GET /defi/token_trending?sort_by=rank&sort_type=asc&limit=20
Meme 代币	GET /defi/v3/token/meme/list?sort_by=liquidity&sort_type=desc&limit=20 ← 同时传入 sort_by 和 sort_type
搜索代币或交易对	GET /defi/v3/search?keyword=&chain=solana&target=token&sort_by=liquidity&sort_type=desc
代币的流动性池	GET /defi/v2/markets?address=&time_frame=24h&sort_by=liquidity&sort_type=desc
交易对统计数据	GET /defi/v3/pair/overview/single?address=<PAIR>
代币交易历史	GET /defi/v3/token/txs?address=&tx_type=swap&limit=50
代币顶级交易者	GET /defi/v2/tokens/top_traders?address=&time_frame=24h&sort_by=volume&sort_type=desc
链上最佳交易者	GET /trader/gainers-losers?type=today&sort_by=PnL&sort_type=desc
代币持有者列表	GET /defi/v3/token/holder?address=&limit=100
持有者集中度	GET /holder/v1/distribution?token_address= ← 注意：参数为 token_address
钱包余额／净资产	GET /wallet/v2/current-net-worth?wallet=&sort_type=desc ← sort_type 为必填项
钱包盈亏	GET /wallet/v2/pnl/summary?wallet= ← 仅限 PRO 级别
钱包交易历史	GET /v1/wallet/tx_list?wallet=&limit=50
实时价格流	WebSocket SUBSCRIBE_PRICE ← Business 级别及以上
巨鲸提醒	WebSocket SUBSCRIBE_LARGE_TRADE_TXS ← Business 级别及以上

5. 按层级设置的速率限制（按账户）：Standard 为 1 rps · Lite/Starter 为 15 rps · Premium 为 50 rps（1000 rpm）· Business 为 100 rps（1500 rpm）。Wallet API group（/v1/wallet/token_list、/v1/wallet/token_balance、/v1/wallet/tx_list、/v1/wallet/list_supported_chain、/v1/wallet/simulate 及其多链变体）根据 Birdeye 文档，限制更严格，为 30 rpm — 实际限制可能因套餐而异，因此遇到 429 时应采用退避策略，而不要假定存在固定上限。V2 钱包端点（/wallet/v2/*）遵循按账户设置的层级限制。Token List Scroll：每个账户每 30 s 调用 1 次。
6. WebSocket（Business 层级及以上）：wss://public-api.birdeye.so/socket/{chain}?x-api-key=KEY — chain 位于 URL 路径中，而非请求头中。必须设置 Origin: ws://public-api.birdeye.so 请求头，并将 echo-protocol 作为子协议参数传递（new WebSocket(url, 'echo-protocol', { headers: { Origin: ... } })）— 不要将其作为原始 Sec-WebSocket-Protocol 请求头传递。
7. 需要端点的完整参数列表？ → 阅读 resources/api-reference.md
8. 不知道该使用哪个端点？ → 阅读 resources/intent-index.md（关键词 → 端点）
9. 需要分页方式（offset / cursor / 基于时间）？ → 阅读 resources/pagination.md
10. 需要了解各端点支持的链？ → 阅读 resources/supported-networks.md
11. 需要配置 WebSocket？ → 阅读 resources/websocket.md
12. 需要 x402 按请求付费？ → 阅读 resources/x402.md，然后使用 examples/x402/pay-per-request.ts
13. 需要可运行的代码示例？ → 阅读 examples/ 中对应的文件（见下方的技能结构）

示例

import BirdeyeClient from './templates/birdeye-client';
const client = BirdeyeClient.create('solana'); // reads BIRDEYE_API_KEY

代币概览

用户：“[Token] 的市值和流动性是多少？”

const data = await client.token.getOverview(address);
// data.price, data.marketCap, data.fdv, data.liquidity, data.v24hUSD, data.holder
// data.priceChange1hPercent, data.priceChange24hPercent
// NOTE: 24h volume field is `v24hUSD` (USD) / `v24h` (token units) — NOT `volume24h`

OHLCV 图表

用户：“显示 SOL 的 1h 图表”

const now = Math.floor(Date.now() / 1000);
const data = await client.price.getOHLCV(WSOL, '1H', now - 86400, now);
// data.items[].unix_time (V3 = snake_case — NOT unixTime, which is only on the V1 /defi/ohlcv endpoint)
// data.items[].o .h .l .c .v  +  data.items[].v_usd (V3 only)
// NOTE: time_from and time_to are required — omitting them causes empty response

钱包盈亏（PRO）

用户：“分析钱包 X 的盈亏”

const data = await client.wallet.getPnL(walletAddress);
// data.summary.pnl.realized_profit_usd
// data.summary.counts.win_rate, .total_trade
// data.summary.cashflow_usd.total_invested
// ⚠️ PRO tier only — returns 403 on Standard/Lite

代币安全检查

用户：“这个代币安全吗？[address]”

const data = await client.token.getSecurity(address);
// data.creatorPercentage > 0.20 → high rug risk
// data.freezeable || data.freezeAuthority → freeze risk (tokens can be frozen)
// data.transferFeeEnable === true → transfer tax on every move
// data.top10HolderPercent > 0.5 → concentration risk
// Mint authority: the field is `isMintable` (not `mintable`). Often null on
// established tokens; treat non-null truthy values as active mint authority.

钱包投资组合

用户：“显示钱包 X 的投资组合”

const data = await client.wallet.getNetWorth(wallet);

// ⚠️ ACTUAL FIELD NAMES (snake_case, not camelCase):
//   data.total_value  → string  (NOT totalUsd)
//   item.amount       → number  (token balance — NOT balance)
//   item.value        → string  (USD value — NOT valueUsd) — coerce: Number(item.value)
//   item.price        → number  (NOT priceUsd)

const total = Number(data.total_value ?? 0);   // total_value, not totalUsd
console.log(`Total: $${total.toFixed(2)}`);

for (const item of data.items ?? []) {
    const bal = item.amount;                    // amount is already a number
    const val = Number(item.value ?? 0);        // value is a string — coerce
    const pct = total > 0 ? ((val / total) * 100).toFixed(1) : '0.0';
    console.log(`${item.symbol}: ${bal.toFixed(4)} = $${val.toFixed(2)} (${pct}%)`);
}

钱包交易历史

用户：“显示钱包 X 最近的兑换记录”

const data = await client.wallet.getTxHistory(wallet, 50);

// ⚠️ RESPONSE WRAPPER is keyed by chain — NOT `{ items: [...] }`:
//   data.solana  → array of Solana txs (use `data.ethereum` on Ethereum, etc.)

// ⚠️ FIELD SHAPES on /v1/wallet/tx_list:
//   tx.blockTime  → ISO string "2026-04-13T06:10:38+00:00"  (NOT a unix number)
//   tx.from / to  → plain wallet address string              (NOT objects with .symbol)
//   token info    → tx.balanceChange[].symbol / .amount

const txs = data.solana ?? [];
for (const tx of txs) {
    // Parse time correctly — blockTime is ISO string, NOT unix
    const when = new Date(tx.blockTime).getTime();           // ✅
    // const when = tx.blockTime * 1000;                     // ❌ NaN

    // Token symbols come from balanceChange[], not from/to
    const received = tx.balanceChange
        .filter((b) => b.amount > 0)
        .map((b) => `+${b.amount.toFixed(4)} ${b.symbol}`)
        .join(', ');
    console.log(new Date(when).toISOString(), received);
}

指南

• 务必使用 /wallet/v2/current-net-worth 返回的正确字段名——API 返回 data.total_value（字符串）、item.amount（数字）、item.value（字符串）、item.price（数字）。使用驼峰命名别名（totalUsd、balance、valueUsd）会返回 undefined。
• 务必在进行算术运算前，使用 Number() 转换 item.value 和 data.total_value——它们是字符串。item.amount 已经是数字。
• 务必使用 new Date(tx.blockTime) 解析 /v1/wallet/tx_list 中的 tx.blockTime——它是 ISO 字符串，不是 Unix 时间戳。使用 tx.blockTime * 1000 会产生 NaN。
• 务必从 tx.balanceChange[].symbol 读取代币符号——tx.from 和 tx.to 是普通钱包地址字符串，不是带有 .symbol 的对象。
• 务必为 REST 调用设置 x-chain: solana 标头（只有 WebSocket 才在 URL 路径中指定链）。
• 务必使用 /defi/multi_price 批量查询价格——切勿循环调用 /defi/price。
• 务必在 /holder/v1/distribution 中使用 token_address=（而非 address=）。
• 切勿向 /trader/gainers-losers 传入 type=gainers 或 type=losers——这会导致 400 错误。请使用 type=today、type=yesterday 或 type=1W。
• 切勿在 /defi/v2/markets、/defi/v3/search、/trader/gainers-losers 中省略 sort_by/sort_type——这些端点要求提供这两个参数。
• 务必同时向 /defi/v3/token/meme/list 传入 sort_by 和 sort_type——官方文档将两者都标记为必填。常见的有效 sort_by 值：liquidity、volume_24h_usd、market_cap、fdv、recent_listing_time、volume_24h_change_percent、progress_percent、holder、price_change_24h_percent、trade_24h_count。完整枚举请参阅官方文档。
• 切勿将 v24hUSD 或 volume24h 用作 /defi/v3/token/list 的 sort_by 值——有效值为：liquidity、fdv、market_cap、holder。
• 切勿频繁调用 Wallet V1 分组端点（投资组合、交易列表、代币余额）——文档规定上限为 每分钟 30 次；具体执行情况可能因套餐而异，因此请控制调用频率，并在遇到 429 时采用退避策略。
• 切勿在同一账户下每 30 秒调用 /defi/v3/token/list/scroll 超过一次——此端点的速率限制特别低。
• 切勿在 Agent 响应中暴露 X-API-KEY。
• 切勿在未确认套餐等级的情况下调用仅限 PRO 的端点（/wallet/v2/pnl/*、/smart-money/*）。

常见错误

403 Forbidden

原因：某些 HTTP 客户端很少会因缺少或被标记为机器人而导致 User-Agent 出错，或者端点要求更高的套餐等级。 解决方法：稳妥起见，设置任意 User-Agent。对于受 PRO 套餐限制的端点（/wallet/v2/pnl/*、部分 Smart Money 端点），请在 bds.birdeye.so 升级套餐。

401 Unauthorized

原因：缺少或无效的 X-API-KEY。 解决方法：从 process.env.BIRDEYE_API_KEY 加载。

404 Not Found

原因：指定链上不存在该代币。 解决方法：验证地址和 x-chain 标头值。

429 Too Many Requests

原因：超出速率限制。每个账户的限制因套餐等级而异：Standard 为每秒 1 次，Lite/Starter 为每秒 15 次，Premium 为每秒 50 次（每分钟 1000 次），Business 为每秒 100 次（每分钟 1500 次）。Wallet API 组（V1 钱包端点）的文档规定上限为 每分钟 30 次——具体行为可能因套餐而异。 解决方法：采用指数退避（1 秒 → 2 秒 → 4 秒 → 8 秒 → 最长 16 秒）。对于钱包端点，初始调用间隔至少为 2 秒，遇到 429 时进一步延长间隔。

/holder/v1/distribution 返回 400

原因：传入了 address=，而不是 token_address=。 解决方法：使用 ?token_address=<address>。

技能结构

birdeye/
├── SKILL.md                              # This file — agent instructions & quick reference
├── docs/
│   └── troubleshooting.md               # Common errors, root causes, and fixes
├── resources/
│   ├── api-reference.md                 # Complete endpoint table with all params
│   ├── error-handling.md                # HTTP codes, retry pattern, rate limit table
│   ├── intent-index.md                  # Keyword → endpoint fast lookup for agents
│   ├── pagination.md                    # Offset, scroll, time-based, cursor patterns
│   ├── supported-networks.md            # x-chain values and per-endpoint chain support
│   └── websocket.md                     # WebSocket connection, channels, heartbeat
├── examples/
│   ├── holder-data/
│   │   └── holder-distribution.ts       # Top holders + concentration analysis
│   ├── market-data/
│   │   ├── meme-tokens.ts               # Meme leaderboard + security enrichment
│   │   ├── new-listings.ts              # New token listings
│   │   ├── ohlcv-chart.ts               # OHLCV candle data
│   │   └── trending-tokens.ts           # Trending tokens by rank
│   ├── pair-data/
│   │   └── pair-overview.ts             # Pair/pool stats
│   ├── price-ohlcv/
│   │   └── price-and-ohlcv.ts          # Price + chart in one flow
│   ├── token-data/
│   │   ├── token-overview.ts            # Full token fundamentals
│   │   └── token-security.ts            # Rug / honeypot check
│   ├── trader-intelligence/
│   │   ├── gainers-losers.ts            # Top on-chain traders by P&L
│   │   ├── smart-money.ts               # Smart money accumulation/distribution (PRO)
│   │   └── top-traders.ts               # Top traders per token
│   ├── transactions/
│   │   └── token-trades.ts              # Token trade history
│   ├── wallet-intelligence/
│   │   ├── wallet-pnl.ts                # Wallet P&L analysis (PRO)
│   │   ├── wallet-portfolio.ts          # Net worth + token balances
│   │   └── wallet-tx-history.ts         # Transaction history with swap detection
│   ├── websocket/
│   │   ├── live-price-stream.ts         # Real-time price via SUBSCRIBE_PRICE
│   │   └── whale-alert.ts               # Whale trades via SUBSCRIBE_LARGE_TRADE_TXS
│   └── x402/
│       └── pay-per-request.ts           # Pay-per-request with USDC (no API key)
└── templates/
    └── birdeye-client.ts                # Production-ready TypeScript client with sub-clients

外部文档（供人类阅读）

• Birdeye API 参考
• Birdeye x402 文档
• 按套餐等级划分的数据可访问性
• Birdeye 开发者门户（API 密钥）