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/pagination.md
View on GitHub# Pagination Guide
Birdeye uses four pagination patterns depending on the endpoint.
---
## Pattern 1: offset / limit (most common)
Used by: token list, holder list, trade history, balance changes, smart money list, etc.
**Request params**: `offset` (default: 0), `limit` (endpoint-specific max)
**Response signals**: `data.total` (total count) or `data.hasNext` (boolean)
```typescript
async function paginate<T>(
fetchPage: (offset: number, limit: number) => Promise<{ items: T[]; total?: number; hasNext?: boolean }>,
limit = 50
): Promise<T[]> {
const all: T[] = [];
let offset = 0;
while (true) {
const page = await fetchPage(offset, limit);
all.push(...page.items);
const done = page.hasNext === false
|| (page.total !== undefined && all.length >= page.total)
|| page.items.length < limit;
if (done) break;
offset += limit;
}
return all;
}
```
### Per-endpoint max limits
| Endpoint | Max `limit` | Notes |
|---|---|---|
| `/defi/v3/token/list` | 50 | Default: 20 |
| `/defi/v3/token/txs` | 50 | — |
| `/defi/v3/token/holder` | 100 | — |
| `/defi/v3/search` | 20 | Hard cap |
| `/smart-money/v1/token/list` | 100 | — |
| `/defi/v2/tokens/new_listing` | — | No documented cap |
| `/wallet/v2/current-net-worth` | 100 | Token list in portfolio |
| `/v1/wallet/tx_list` | 100 | Pagination: `before` (tx hash cursor, Solana only) |
---
## Pattern 2: scroll_id (full dataset iteration)
Used by: `/defi/v3/token/list/scroll` **only**
⚠️ Costs 500 CU per call — only use when you need the full token universe.
```typescript
async function scrollAllTokens(apiKey: string): Promise<any[]> {
const headers = { 'X-API-KEY': apiKey, 'x-chain': 'solana', 'accept': 'application/json' };
const all: any[] = [];
let scrollId: string | undefined;
while (true) {
// Valid sort_by for /defi/v3/token/list/scroll: liquidity | fdv | market_cap | holder
const params = new URLSearchParams({ sort_by: 'liquidity', sort_type: 'desc', limit: '50' });
if (scrollId) params.set('scroll_id', scrollId);
const res = await fetch(`https://public-api.birdeye.so/defi/v3/token/list/scroll?${params}`, { headers });
const json = await res.json() as any;
const tokens = json.data?.tokens ?? [];
all.push(...tokens);
if (!json.data?.hasNext || tokens.length === 0) break;
scrollId = json.data.scroll_id;
}
return all;
}
```
---
## Pattern 3: time-based pagination
Used by: `/defi/v3/token/txs`, `/defi/txs/token/seek_by_time`, `/trader/txs/seek_by_time`
Use `before_time` / `after_time` (Unix seconds) to window queries.
(Note: `/v1/wallet/tx_list` is NOT time-based — it uses a `before` tx-hash cursor, shown separately below.)
```typescript
async function fetchAllTrades(
apiKey: string,
tokenAddress: string,
startTime: number,
endTime: number
): Promise<any[]> {
const headers = { 'X-API-KEY': apiKey, 'x-chain': 'solana', 'accept': 'application/json' };
const all: any[] = [];
let before = endTime;
while (true) {
const url = `https://public-api.birdeye.so/defi/v3/token/txs` +
`?address=${tokenAddress}&before_time=${before}&after_time=${startTime}&limit=50`;
const res = await fetch(url, { headers });
const json = await res.json() as any;
const items = json.data?.items ?? [];
all.push(...items);
if (!json.data?.hasNext || items.length === 0) break;
// /defi/v3/token/txs returns snake_case: use `block_unix_time`, not `blockUnixTime`.
before = items[items.length - 1].block_unix_time - 1;
}
return all;
}
```
---
## Pattern 4: tx-hash cursor (`/v1/wallet/tx_list`)
`/v1/wallet/tx_list` paginates with a `before` param — the transaction hash of
the last item from the previous page. Solana-only per official docs.
```typescript
async function fetchAllWalletTxs(apiKey: string, wallet: string): Promise<any[]> {
const headers = { 'X-API-KEY': apiKey, 'x-chain': 'solana', 'accept': 'application/json' };
const all: any[] = [];
let before: string | undefined;
while (true) {
const params = new URLSearchParams({ wallet, limit: '100' });
if (before) params.set('before', before);
const res = await fetch(`https://public-api.birdeye.so/v1/wallet/tx_list?${params}`, { headers });
const json = await res.json() as any;
const txs = json.data?.solana ?? []; // response is chain-keyed
all.push(...txs);
if (txs.length < 100) break;
before = txs[txs.length - 1].txHash;
}
return all;
}
```
---
## Pattern 5: cursor (rare)
Some newer/beta endpoints may use cursor-based pagination. Check response for a `cursor` field and pass it back in the next request's `cursor` param.
---
## Summary
| Pattern | Endpoints | Key params |
|---|---|---|
| offset/limit | Most list endpoints | `offset`, `limit` → check `hasNext` or `total` |
| scroll_id | `/defi/v3/token/list/scroll` | `scroll_id` from response (500 CU/call) |
| time-based | `/defi/v3/token/txs`, `/defi/txs/*/seek_by_time`, `/trader/txs/seek_by_time` | `before_time`, `after_time`, `limit` |
| tx-hash cursor | `/v1/wallet/tx_list` | `before` (prev page's last `txHash`) — Solana only |
| cursor | Some beta endpoints | `cursor` from response |
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: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |