internet-court/internet-court-skill / vendored/sendaifun/birdeye
birdeye
VerifiedComplete 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.
resources/websocket.md
View on GitHub# WebSocket Reference
Birdeye WebSocket streams require **Business tier or higher**.
---
## Connection
```
wss://public-api.birdeye.so/socket/{chain}?x-api-key=YOUR_API_KEY
```
Chain goes in the **URL path** — NOT a header, NOT an additional query param.
| Chain | URL |
|---|---|
| Solana | `wss://public-api.birdeye.so/socket/solana?x-api-key=KEY` |
| Ethereum | `wss://public-api.birdeye.so/socket/ethereum?x-api-key=KEY` |
| BSC | `wss://public-api.birdeye.so/socket/bsc?x-api-key=KEY` |
| Base | `wss://public-api.birdeye.so/socket/base?x-api-key=KEY` |
| Arbitrum | `wss://public-api.birdeye.so/socket/arbitrum?x-api-key=KEY` |
| Optimism | `wss://public-api.birdeye.so/socket/optimism?x-api-key=KEY` |
| Polygon | `wss://public-api.birdeye.so/socket/polygon?x-api-key=KEY` |
### Required connection setup
- Subprotocol: `echo-protocol` — pass as the subprotocol argument to `new WebSocket(url, subprotocol, options)`, NOT as a raw `Sec-WebSocket-Protocol` header.
- `Origin: ws://public-api.birdeye.so` header is required.
```typescript
import WebSocket from 'ws';
const ws = new WebSocket(
`wss://public-api.birdeye.so/socket/solana?x-api-key=${API_KEY}`,
'echo-protocol',
{ headers: { Origin: 'ws://public-api.birdeye.so' } }
);
```
---
## Subscription message formats
### Channels WITH `data` wrapper (most channels)
```json
{
"type": "SUBSCRIBE_PRICE",
"data": {
"address": "TOKEN_ADDRESS",
"currency": "usd",
"type": "1H"
}
}
```
Other channels using the `data` wrapper: `SUBSCRIBE_TXS`, `SUBSCRIBE_BASE_QUOTE_PRICE`, `SUBSCRIBE_WALLET_TXS`, `SUBSCRIBE_TOKEN_STATS`, `SUBSCRIBE_MEME`
### Channels WITHOUT `data` wrapper (params at top level)
```json
{ "type": "SUBSCRIBE_LARGE_TRADE_TXS", "min_volume": 10000, "max_volume": 100000 }
{ "type": "SUBSCRIBE_TOKEN_NEW_LISTING", "min_liquidity": 1000 }
{ "type": "SUBSCRIBE_NEW_PAIR", "min_liquidity": 500 }
```
Channels without data wrapper: `SUBSCRIBE_LARGE_TRADE_TXS`, `SUBSCRIBE_TOKEN_NEW_LISTING`, `SUBSCRIBE_NEW_PAIR`
### Unsubscribe
Replace `SUBSCRIBE` with `UNSUBSCRIBE`. No `data` wrapper needed:
```json
{ "type": "UNSUBSCRIBE_PRICE" }
{ "type": "UNSUBSCRIBE_LARGE_TRADE_TXS" }
```
---
## All 9 channels
| Channel | Description | CU/byte | Data wrapper | Chain |
|---|---|---|---|---|
| `SUBSCRIBE_PRICE` | Token OHLCV candle updates | 0.003 | yes | all |
| `SUBSCRIBE_TXS` | Live swap/trade feed | 0.0004 | yes | all |
| `SUBSCRIBE_BASE_QUOTE_PRICE` | Pair price updates | 0.003 | yes | all |
| `SUBSCRIBE_TOKEN_NEW_LISTING` | New token listings | 0.08 | **no** | SOL only |
| `SUBSCRIBE_NEW_PAIR` | New DEX pair creation | 0.05 | **no** | SOL only |
| `SUBSCRIBE_LARGE_TRADE_TXS` | Whale trades above threshold | 0.006 | **no** | all |
| `SUBSCRIBE_WALLET_TXS` | Live wallet activity | 0.004 | yes | all |
| `SUBSCRIBE_TOKEN_STATS` | Token stat updates | 0.005 | yes | all |
| `SUBSCRIBE_MEME` | Meme token stats | varies | yes | SOL only |
### Channel capacity limits
| Channel | Max addresses per sub |
|---|---|
| `SUBSCRIBE_PRICE` | 100 |
| `SUBSCRIBE_TXS` | 100 |
| `SUBSCRIBE_TOKEN_STATS` | 100 |
| `SUBSCRIBE_WALLET_TXS` | 1 address per subscription |
| `SUBSCRIBE_BASE_QUOTE_PRICE` | 1 pair per **connection** |
---
## Heartbeat / keepalive
Birdeye does not send server-side pings — implement client-side keepalive:
```typescript
function keepAlive(ws: WebSocket, intervalMs = 30_000): NodeJS.Timeout {
return setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: 'PING' }));
}
}, intervalMs);
}
```
---
## Auto-reconnect with exponential backoff
```typescript
function createWebSocket(
apiKey: string,
chain: string,
onMessage: (msg: any) => void,
retryDelay = 1000
): WebSocket {
const url = `wss://public-api.birdeye.so/socket/${chain}?x-api-key=${apiKey}`;
const ws = new WebSocket(url, 'echo-protocol', {
headers: { Origin: 'ws://public-api.birdeye.so' },
});
ws.on('message', (raw) => {
try { onMessage(JSON.parse(raw.toString())); } catch {}
});
ws.on('close', (code) => {
const nextDelay = Math.min(retryDelay * 2, 30_000);
console.warn(`WS closed (${code}) — reconnecting in ${retryDelay / 1000}s`);
setTimeout(() => createWebSocket(apiKey, chain, onMessage, nextDelay), retryDelay);
});
ws.on('error', (err) => {
console.error('WS error:', err.message);
ws.close();
});
return ws;
}
```
---
## CU billing
WebSocket CU is charged **per byte received** (not per message). High-traffic channels on Solana (`TOKEN_NEW_LISTING`, `NEW_PAIR`) generate large volumes — use `min_liquidity` filters to reduce noise and cost.
---
## Examples
- `examples/websocket/live-price-stream.ts` — SUBSCRIBE_PRICE with candle output
- `examples/websocket/whale-alert.ts` — SUBSCRIBE_LARGE_TRADE_TXS with Telegram/Discord routing
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |