birdeye

Birdeye データスキル

Birdeye は、Solana AI エージェント向けの主要なリアルタイム市場データレイヤーです。800万以上のトークンと500以上の AMM プールのオンチェーン状態をネイティブにインデックス化し、10秒未満の鮮度でデータを提供します。

概要

次のような質問をユーザーから受けたときに、このスキルを使用します。

• トークン価格、チャート、または基本情報（時価総額、出来高、流動性、保有者数）
• 新規またはトレンドのトークン（発見、ミームトークン、新規上場）
• トークンまたはペアのオンチェーン取引履歴
• トークンを売買している人（上位トレーダー、値上がり銘柄）
• ウォレットのポートフォリオ、純資産、または損益の追跡
• トークンのセキュリティ／ラグリスクの確認
• リアルタイムの価格またはクジラアラートのストリーム（WebSocket）
• API キーを使わないリクエストごとの支払い（x402／エージェントネイティブな決済）

手順

1. MCP を確認する：環境で birdeye-mcp ツールが利用できる場合は、それらを直接使用します。
2. 認証：次の2つのモードがあります。
   • API キー（デフォルト）：ベース URL は https://public-api.birdeye.so です。BIRDEYE_API_KEY からキーを読み込みます。
   • x402 リクエストごとの支払い（API キー不要）：ベース URL は https://public-api.birdeye.so/x402 です。呼び出しごとに USDC で支払います。エージェントが 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
ミームトークン	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 グループ（/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 秒あたり 1 回の呼び出し。
6. WebSocket（Business プラン以上）：wss://public-api.birdeye.so/socket/{chain}?x-api-key=KEY — チェーンは 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 / time-based）が必要ですか？ → 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 の 1 時間足チャートを表示して」

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 が返されます。
• 必ず item.value と data.total_value を算術演算の前に Number() で数値に変換してください。これらは文字列です。item.amount はすでに数値です。
• 必ず /v1/wallet/tx_list の tx.blockTime を new Date(tx.blockTime) で解析してください。これは ISO 文字列であり、UNIX タイムスタンプではありません。tx.blockTime * 1000 を使用すると NaN になります。
• 必ず トークンシンボルを tx.balanceChange[].symbol から読み取ってください。tx.from と tx.to は通常のウォレットアドレス文字列であり、.symbol を持つオブジェクトではありません。
• 必ず REST 呼び出しに x-chain: solana ヘッダーを設定してください（チェーンを URL パスに指定するのは WebSocket の場合のみです）。
• 必ず 一括価格チェックには /defi/multi_price を使用してください。/defi/price を繰り返し呼び出してはいけません。
• 必ず /holder/v1/distribution には address= ではなく token_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 です。列挙値の全一覧は公式ドキュメントを参照してください。
• 禁止：/defi/v3/token/list の sort_by に v24hUSD または volume24h を使用しないでください。有効な値は liquidity、fdv、market_cap、holder です。
• 禁止：Wallet V1 のグループエンドポイント（ポートフォリオ、取引一覧、トークン残高）を大量に呼び出さないでください。ドキュメントでは30 rpmの上限が示されています。適用状況はプランによって異なる場合があるため、呼び出し間隔を空け、429 エラーにはバックオフで対処してください。
• 禁止：アカウントごとに /defi/v3/token/list/scroll を 30 秒間に複数回呼び出さないでください。特にレート制限が低いエンドポイントです。
• 禁止：エージェントの応答で 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 rps、Lite／Starter は 15 rps、Premium は 50 rps（1000 rpm）、Business は 100 rps（1500 rpm）です。Wallet API グループ（V1 のウォレットエンドポイント）には、ドキュメントに記載された30 rpmの上限があります。正確な適用状況はプランによって異なる場合があります。 対処：指数バックオフを使用してください（1s → 2s → 4s → 8s → 最大 16s）。ウォレットエンドポイントでは、まず 2 秒以上の間隔を空け、429 エラーが発生した場合はさらに間隔を広げてください。

/holder/v1/distribution の 400 エラー

原因：token_address= ではなく 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 キー）