birdeye
Complete Birdeye API integration for real-time DeFi data across Solana and 15 other chains. Use for token prices, OHLCV charts, market discovery, on-chain trader intelligence, holder analysis, wallet portfolio & P&L, and WebSocket streams for live prices and whale alerts.
Install / Use
npx skills add internet-court/internet-court-skill --skill birdeyeInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of birdeye
birdeye scores 96/100 on our quality scale, 195th of 4,698 Development & Engineering skills we index (top 5%).
Its SKILL.md is 15 KB long, well organised into 19 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
With 7,124 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated 21 days ago, so birdeye is actively maintained.
- Our last check on 2026-11-15 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-28. Automated pattern scan on 2026-09-28. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
birdeye compared with similar skills
All 4 of these similar skills score higher than birdeye; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| birdeye (this skill)by internet-court | 96 | 7.1k | 21d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install birdeye?
- Run
npx skills add internet-court/internet-court-skill --skill birdeye. The install tabs above show the steps for each supported agent. - Which AI agents does birdeye work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is birdeye safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is birdeye still maintained?
- The repository was last updated 21 days ago, so birdeye is actively maintained.
Skill content
View source on GitHubname: birdeye description: Complete Birdeye API integration for real-time DeFi data across Solana and 15 other chains. Use for token prices, OHLCV charts, market discovery, on-chain trader intelligence, holder analysis, wallet portfolio & P&L, and WebSocket streams for live prices and whale alerts.
Birdeye Data Skill
Birdeye is the primary real-time market-data layer for Solana AI agents — natively indexed against on-chain state across 8M+ tokens and 500+ AMM pools with sub-10s freshness.
Overview
Use this skill when users ask about:
- Token prices, charts, or fundamentals (mc, volume, liquidity, holder count)
- New or trending tokens (discovery, meme tokens, new listings)
- On-chain transaction history for a token or pair
- Who's buying/selling a token (top traders, gainers)
- Wallet portfolios, net worth, or P&L tracking
- Token security/rug risk checks
- Real-time price or whale alert streams (WebSocket)
- Pay-per-request without an API key (x402 / agent-native payments)
Instructions
- Check for MCP: If
birdeye-mcptools are available in the environment, use them directly. - Auth: Two modes:
- API key (default): Base URL
https://public-api.birdeye.so, load key fromBIRDEYE_API_KEY. - x402 pay-per-request (no API key): Base URL
https://public-api.birdeye.so/x402, pay USDC per call. Use when agent has a Solana wallet but no API key. Seeresources/x402.md.
- API key (default): Base URL
- Required headers on every REST request:
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 - Pick the right endpoint using this decision table:
| User intent | Endpoint |
|---|---|
| Token price (current) | GET /defi/price?address= |
| Token price (multiple) | GET /defi/multi_price?list_address=a,b,c |
| Chart / OHLCV candles | GET /defi/v3/ohlcv?address=&type=1H&time_from=<unix>&time_to=<unix> |
| Token fundamentals (mc, vol, holders) | GET /defi/token_overview?address= |
| Token metadata (name, symbol, logo) | GET /defi/v3/token/meta-data/single?address= |
| Rug / honeypot check | GET /defi/token_security?address= |
| New listings | GET /defi/v2/tokens/new_listing?limit=20 |
| Trending tokens | GET /defi/token_trending?sort_by=rank&sort_type=asc&limit=20 |
| Meme tokens | GET /defi/v3/token/meme/list?sort_by=liquidity&sort_type=desc&limit=20 ← pass sort_by+sort_type together |
| Search tokens or pairs | GET /defi/v3/search?keyword=&chain=solana&target=token&sort_by=liquidity&sort_type=desc |
| Liquidity pools for a token | GET /defi/v2/markets?address=&time_frame=24h&sort_by=liquidity&sort_type=desc |
| Pair stats | GET /defi/v3/pair/overview/single?address=<PAIR> |
| Token trade history | GET /defi/v3/token/txs?address=&tx_type=swap&limit=50 |
| Top traders for a token | GET /defi/v2/tokens/top_traders?address=&time_frame=24h&sort_by=volume&sort_type=desc |
| Best on-chain traders | GET /trader/gainers-losers?type=today&sort_by=PnL&sort_type=desc |
| Token holder list | GET /defi/v3/token/holder?address=&limit=100 |
| Holder concentration | GET /holder/v1/distribution?token_address= ← note: token_address param |
| Wallet balance / net worth | GET /wallet/v2/current-net-worth?wallet=&sort_type=desc ← sort_type required |
| Wallet P&L | GET /wallet/v2/pnl/summary?wallet= ← PRO tier only |
| Wallet transaction history | GET /v1/wallet/tx_list?wallet=&limit=50 |
| Real-time price stream | WebSocket SUBSCRIBE_PRICE ← Business tier+ |
| Whale alerts | WebSocket SUBSCRIBE_LARGE_TRADE_TXS ← Business tier+ |
- Rate limits by tier (per-account): Standard 1 rps · Lite/Starter 15 rps · Premium 50 rps (1000 rpm) · Business 100 rps (1500 rpm). The Wallet API group (
/v1/wallet/token_list,/v1/wallet/token_balance,/v1/wallet/tx_list,/v1/wallet/list_supported_chain,/v1/wallet/simulate, and their multichain variants) carries a stricter 30 rpm cap per Birdeye docs — enforcement may vary by plan, so handle 429s with backoff rather than assuming a hard ceiling. V2 wallet endpoints (/wallet/v2/*) follow the per-account tier limit. Token List Scroll: 1 call / 30 s per account. - WebSocket (Business tier+):
wss://public-api.birdeye.so/socket/{chain}?x-api-key=KEY— chain in URL path, NOT header. RequiredOrigin: ws://public-api.birdeye.soheader, plusecho-protocolpassed as the subprotocol argument (new WebSocket(url, 'echo-protocol', { headers: { Origin: ... } })) — not as a rawSec-WebSocket-Protocolheader. - Need full param list for an endpoint? → Read
resources/api-reference.md - Don't know which endpoint to use? → Read
resources/intent-index.md(keyword → endpoint) - Need pagination (offset / cursor / time-based)? → Read
resources/pagination.md - Need chain support per endpoint? → Read
resources/supported-networks.md - Need WebSocket setup? → Read
resources/websocket.md - Need x402 pay-per-request? → Read
resources/x402.md, then useexamples/x402/pay-per-request.ts - Need a working code example? → Read the matching file in
examples/(see Skill Structure below)
Examples
import BirdeyeClient from './templates/birdeye-client';
const client = BirdeyeClient.create('solana'); // reads BIRDEYE_API_KEY
Token Overview
User: "What's the market cap and liquidity of [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 Chart
User: "Show me the 1h chart for SOL"
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
Wallet P&L (PRO)
User: "Analyze profit/loss for wallet 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
Token Security Check
User: "Is this token safe? [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.
Wallet Portfolio
User: "Show portfolio for wallet 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}%)`);
}
Wallet Transaction History
User: "Show recent swaps for wallet 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);
}
Guidelines
- DO use correct field names from
/wallet/v2/current-net-worth— API returnsdata.total_value(string),item.amount(number),item.value(string),item.price(number). Using camelCase aliases (totalUsd,balance,valueUsd) returnsundefined. - DO coerce
item.valueanddata.total_valuewithNumber()before arithmetic — they are strings.item.amountis already a number. - DO parse
tx.blockTimefrom/v1/wallet/tx_listwithnew Date(tx.blockTime)— it is an ISO string, not a unix timestamp. Usingtx.blockTime * 1000producesNaN. - DO read token symbols from
tx.balanceChange[].symbol—tx.fromandtx.toare plain wallet address strings, not objects with.symbol. - DO set
x-chain: solanaheader for REST calls (chain goes in the URL path only for WebSocket). - DO use
/defi/multi_pricefor batch price checks — never loop/defi/price. - DO use
token_address=(notaddress=) for/holder/v1/distribution. - DON'T pass
type=gainersortype=losersto/trader/gainers-losers— they cause 400. Usetype=today,type=yesterday, ortype=1W. - DON'T omit
sort_by/sort_typefrom/defi/v2/markets,/defi/v3/search,/trader/gainers-losers— required on these endpoints. - DO pass
sort_byandsort_typetogether to/defi/v3/token/meme/list— official docs mark both required. Common validsort_byvalues:liquidity,volume_24h_usd,market_cap,fdv,recent_listing_time,volume_24h_change_percent,progress_percent,holder,price_change_24h_percent,trade_24h_count. See the official docs for the full enum. - DON'T use
v24hUSDorvolume24hassort_byfor/defi/v3/token/list— valid values:liquidity,fdv,market_cap,holder. - DON'T pound Wallet V1 group endpoints (portfolio, tx list, token balance) — docs cite a 30 rpm cap; enforcement may vary by plan, so pace calls and handle 429 with backoff.
- DON'T call
/defi/v3/token/list/scrollmore than once per 30 seconds per account — it has a uniquely low rate limit. - DON'T expose
X-API-KEYin agent responses. - DON'T call PRO-only endpoints (
/wallet/v2/pnl/*,/smart-money/*) without confirming tier.
Common Errors
403 Forbidden
Cause: Rarely, a missing or bot-flagged User-Agent on certain HTTP clients, OR endpoint requires a higher plan tier.
Fix: Set any User-Agent defensively. For PRO-gated endpoints (/wallet/v2/pnl/*, some Smart Money), upgrade your plan at bds.birdeye.so.
401 Unauthorized
Cause: Missing or invalid X-API-KEY.
Fix: Load from process.env.BIRDEYE_API_KEY.
404 Not Found
Cause: Token doesn't exist on the specified chain.
Fix: Verify address and x-chain header value.
429 Too Many Requests
Cause: Rate limit exceeded. Per-account limit
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
