birdeye-api

Files (6)

• SKILL.md
• birdeye_endpoints.md · references/
• error_handling.md · references/
• token_overview_fields.md · references/
• fetch_ohlcv.py · scripts/
• token_screener.py · scripts/

SKILL.md (first lines)

# Birdeye API — Solana Market Data

Birdeye aggregates market data across all Solana DEXes (and 13 other chains). Prices, OHLCV candles, trade history, token metadata, security info, and wallet analytics. Primary data source for Solana token research and historical analysis.

**Note**: For real-time trading systems, use Yellowstone gRPC (see `yellowstone-grpc` skill). Birdeye is best for historical data, research, and analysis workflows.

## Quick Start

### 1. Get an API Key

Sign up at [birdeye.so](https://birdeye.so) — free tier: 30K compute units/month, 1 req/sec.

```bash
export BIRDEYE_API_KEY="your-api-key"
```

### 2. Install Dependencies

```bash
uv pip install httpx pandas python-dotenv
```

### 3. First Request

```python
import httpx, os

API_KEY = os.environ["BIRDEYE_API_KEY"]
headers = {"X-API-KEY": API_KEY, "x-chain": "solana", "accept": "application/json"}

# Get SOL price
resp = httpx.get(
    "https://public-api.birdeye.so/defi/price",
    headers=headers,
    params={"address": "So11111111111111111111111111111111111111112"},
)
price = resp.json()["data"]["value"]
print(f"SOL: ${price}")
```

## Core Endpoints

All endpoints use base URL `https://public-api.birdeye.so` with `X-API-KEY` and `x-chain` headers.

### Token Price

```python
# Single token price (10 CU)
GET /defi/price?address=TOKEN_MINT

# Multiple token prices (variable CU)
POST /defi/multi_price
Body: {"addresses": ["MINT1", "MINT2", "MINT3"]}

# Price at specific timestamp (10 CU)
GET /defi/historical_price_unix?address=TOKEN_MINT&unixtime=1700000000

# Historical price series (60 CU)
GET /defi/history_price?address=TOKEN_MINT&address_type=token&type=15m&time_from=T1&time_to=T2
```

### OHLCV Candles

The primary endpoint for backtesting data.

```python
# Token OHLCV (40 CU, max 1000 candles per request)
GET /defi/ohlcv?address=TOKEN_MINT&type=15m&time_from=T1&time_to=T2
```

**Timeframes**: `1m, 3m, 5m, 15m, 30m, 1H, 2H, 4H, 6H, 8H, 12H, 1D, 3D, 1W, 1M`

Response:
```json
{
  "data": {
    "items": [
      {"o": 23.5, "h": 24.1, "l": 23.2, "c": 23.8, "v": 1234567.89, "unixTime": 1692175200, "type": "15m"}
    ]
  },
  "success": true
}
```

**Pagination for long history**: Max 1000 candles per request. At 15m intervals, 1000 candles ≈ 10.4 days. Slide `time_from`/`time_to` windows for longer history.

```python
# Pair OHLCV (40 CU)
GET /defi/ohlcv/pair?address=PAIR_ADDRESS&type=1H&time_from=T1&time_to=T2
```

### Token Overview

Comprehensive metadata + market data in one call.

```python
# Token overview (30 CU)
GET /defi/token_overview?address=TOKEN_MINT
```

Returns: `name`, `symbol`, `decimals`, `logoURI`, `liquidity`, `price`, `mc` (market cap), `supply`, price changes (30m/1h/2h/4h/6h/8h/12h/24h), trade counts, buy/sell volumes, unique wallets, and social links.

See `references/birdeye_endpoints.md` for full field listing.

### Token Security

Pre-trade safety check — essential before entering any new token.

```python
# Token security (50 CU)
GET /defi/token_security?address=TOKEN_MINT
```

Returns:
- `creatorAddress`, `ownerAddress` — who controls the token
- `top10HolderPercent` — concentration risk
- `mutableMetadata` — can metadata be changed?
- `freezeable`, `freezeAuthority` — can tokens be frozen?
- `transferFeeEnable` — Token-2022 transfer fees?

From Serennity007/awesome-stock-quant-skills, MIT.

More from Serennity007/awesome-stock-quant-skills