Birdeye Feeds

Birdeye is the long-tail and memecoin upstream behind charts, prices, holders, trending tokens, and live trade feeds — accessed over REST and WebSocket through the Price Engine.

What Birdeye gives us

Birdeye is the memecoin and long-tail upstream behind several core surfaces:

Charts — OHLCV candles for assets without a Pyth/Chainlink feed.
Prices and sparklines — batch quotes and time-series for the asset detail screens.
Trending — the gainers/losers, trending, and new-listings rails.
Holder distribution — top holders and concentration metrics on the asset detail screen.
Live trades — the streaming trade feed on the asset detail screen and the chat memecoin agent’s contextual reads.
Token security — audit and honeypot signals.

Birdeye is consumed only by the Price Engine and never by the browser. API keys never leave the server.

REST endpoints

All Birdeye REST traffic goes through BirdeyeRestAdapter. The adapter wraps every call with the circuit-breaker, retry, and 429-aware backoff policies described below.

Endpoint	Purpose
`/defi/token_overview`	Token metadata + price stats
`/defi/multi_price`	Batch price for many addresses
`/defi/ohlcv`	Candles for charts
`/defi/history_price`	Time-series for sparklines
`/defi/v3/token/txs`	Live trade history
`/defi/v3/token/holder`	Holder distribution
`/defi/v2/tokens/top_traders`	Most active traders
`/defi/v2/markets`	Liquidity pools and markets
`/defi/token_security`	Audit / honeypot signals
`/defi/token_creation_info`	Creator address + launch ts
`/defi/token_trending`	Trending list (clamped to top 20)
`/defi/v2/tokens/new_listing`	Recently launched
`/defi/v3/token/list`	Gainers / losers (sorted by 24h)
`/defi/v3/search`	Token search by keyword
`/defi/v3/pair/overview/single`	Pool/pair overview
`/defi/v3/swap/route`	Best swap route
`/defi/v3/token/trade-data/multiple`	Batch volume / change stats

Auth

Transport	Header / Param
REST	`X-API-KEY: <key>` and `x-chain: solana`
WebSocket	`?x-api-key=<key>` in the URL query string

Birdeye’s WS rejects an API key sent as a header; sending it in the query string is required.

WebSocket channels

There are two distinct WS implementations on the server side:

Multi-topic adapter

Used for the broader stream surface. Subscription types:

SUBSCRIBE_PRICE
SUBSCRIBE_TXS
SUBSCRIBE_TOKEN_STATS
SUBSCRIBE_LARGE_TRADE_TXS
SUBSCRIBE_TOKEN_NEW_LISTING
SUBSCRIBE_NEW_PAIR
SUBSCRIBE_MEME

Inbound payloads follow { type: "{TOPIC}_DATA", data: { … } }. The adapter replays active subscriptions on reconnect so resumption is transparent to consumers.

High-throughput stats pool

A dedicated pool of N connections (default 5) for SUBSCRIBE_TOKEN_STATS to bypass single-socket throughput limits. The select block on the subscription is mandatory or Birdeye returns trimmed payloads:

{
  "type": "SUBSCRIBE_TOKEN_STATS",
  "address": "<mint>",
  "select": {
    "price": true,
    "trade_data": {
      "volume": true,
      "trade": true,
      "price_history": true,
      "intervals": ["30m", "1h", "4h", "24h"]
    },
    "fdv": true,
    "marketcap": true,
    "supply": true,
    "last_trade": true,
    "liquidity": true
  }
}

Reconnect, backoff, and circuit breaker

Layer	Policy
REST retry	Exponential backoff `100 * 2^(attempt-1)` ms, capped at 1s, max 3 retries. Honors `Retry-After` on 429.
REST circuit breaker	Trips OPEN on 5×5xx OR 3 timeouts in a rolling 30s window. Half-opens after 60s for one probe.
WS reconnect	Exponential backoff with jitter, default 1s → 30s.
WS auth failure	401/403 surfaces immediately and disables reconnect to prevent key burn.
429 accounting	Does not count toward circuit-breaker failures, to avoid spurious failover.

Failover

The MemecoinRouter prefers Birdeye but falls back to GeckoTerminal when Birdeye is unavailable, the breaker is open, or the requested data shape is missing. Failover is per-call; healthy paths continue to use Birdeye while degraded paths use the fallback.

Long-tail data is best-effort

Memecoin price, holder, and trade-feed data are sourced from Birdeye and a fallback. They are useful for context, not for execution against tight slippage. Trading agents check the Price Engine’s stale flag and refuse execution against a stale read; do the same in any custom integration.

For Developers

Where it lives

REST adapter: services/price-engine/src/adapters/birdeye/rest.ts
WS multi-topic adapter: services/price-engine/src/adapters/birdeye/ws.ts
Stats pool: services/price-engine/src/adapters/birdeye/stats-pool.ts
Router with failover: services/price-engine/src/adapters/memecoin-router.ts

Calling Birdeye from your code

You don’t. Birdeye is upstream-only. Consume the unified Price Engine API (/v1/price, /v1/ohlcv, /v1/stream) and let the router decide whether the data comes from Birdeye, GeckoTerminal, or a Pyth/Chainlink feed.

Safety, limits, failure modes

Trimmed payloads. Missing the WS select block on stats subscriptions returns incomplete frames. Always include it.
Auth burn. A misconfigured key triggers 401/403; the WS adapter disables reconnect to avoid burning the key. Fix the credential, then reconnect manually.
Breaker thrashing. Sustained 5xx storms trip the breaker; the router fails over to GeckoTerminal until Birdeye recovers.
Trending clamp. The trending REST surface is clamped to top 20 to keep UI rails consistent; deeper lists require pagination through other endpoints.