# Altcoin Season Index API
> One number that tells you whether crypto capital is rotating into altcoins or huddling in Bitcoin, computed live from Binance daily candles (no key, nothing stored). The market swings between two regimes: in "altcoin season" most alts outperform Bitcoin and money chases the long tail; in "Bitcoin season" alts bleed against BTC and capital flees to the majors. The classic gauge is simple — of the top altcoins, what share has outperformed Bitcoin over the last 90 days? Above ~75% it is altcoin season; below ~25% it is Bitcoin season. The index endpoint returns that index (0-100), the season label, Bitcoin's own return over the window and how many alts out- versus under-performed. The leaderboard endpoint ranks the alts by their excess return versus Bitcoin — who is leading the rotation and who is lagging — each with its own return, BTC's return and the gap. The coins endpoint lists the universe. The altcoin-season / alt-vs-BTC rotation cut — distinct from the market-cap-dominance and global-market APIs (which report BTC's share of total cap, not relative performance), the single-coin momentum and the price APIs. It answers whether it is altseason, not what the market cap is.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/altseason-api/..."
```

## Pricing
- **Free** (Free) — 950 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 23,000 calls/Mo, 6 req/s
- **Pro** ($34/Mo) — 115,000 calls/Mo, 18 req/s
- **Business** ($77/Mo) — 580,000 calls/Mo, 45 req/s

## Endpoints

### Index

#### `GET /v1/index` — Altcoin season index (0-100) with season label and counts

**Parameters:**
- `window` (query, optional, string) — Lookback in days (7-365) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/altseason-api/v1/index?window=90"
```

**Response:**
```json
{
    "data": {
        "note": "The altcoin season index is the share of the top altcoins that outperformed Bitcoin over window_days, on a 0-100 scale. >=75 = altcoin season (rotate into alts); <=25 = bitcoin season (flight to BTC). Default window is the classic 90 days. Not financial advice.",
        "season": "leaning bitcoin",
        "source": "Binance",
        "alts_total": 50,
        "window_days": 90,
        "btc_return_pct": -10.13,
        "altcoin_season_index": 28,
        "alts_outperforming_btc": 14,
        "alts_underperforming_btc": 36
    },
    "meta": {
        "timestamp": "2026-06-12T10:35:21.664Z",
        "request_id": "5bbe792f-db0f-405f-8789-a3a2f02d12bd"
    },
    "status": "ok",
    "message": "Index retrieved successfully",
    "success": true
}
```

### Leaderboard

#### `GET /v1/leaderboard` — Alts ranked by excess return versus Bitcoin

**Parameters:**
- `window` (query, optional, string) — Lookback in days (7-365) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/altseason-api/v1/leaderboard?window=90"
```

**Response:**
```json
{
    "data": {
        "note": "Top altcoins ranked by excess return versus Bitcoin over window_days (return minus BTC's return). Positive excess = beating BTC (leading the rotation); negative = lagging. Use leaders/laggards for the headline movers.",
        "coins": [
            {
                "coin": "INJ",
                "return_pct": 75.31,
                "outperformed_btc": true,
                "excess_vs_btc_pct": 85.44
            },
            {
                "coin": "NEAR",
                "return_pct": 56.93,
                "outperformed_btc": true,
                "excess_vs_btc_pct": 67.06
            },
            {
                "coin": "DYDX",
                "return_pct": 37.59,
                "outperformed_btc": true,
                "excess_vs_btc_pct": 47.73
            },
            {
                "coin": "TON",
                "return_pct": 31.63,
                "outperformed_btc": true,
                "excess_vs_btc_pct": 41.76
            },
            {
                "coin": "XLM",
                "return_pct": 18.72,
                "outperformed_btc": true,
                "excess_vs_btc_pct": 28.85
            },
            {
                "coin": "ATOM",
                "return_pct": 7.2,
                "outperformed_btc": true,
                "excess_vs_btc_pct": 17.33
            },
            {
                "coin": "TRX",
                "return_pct": 6.61,
                "outperformed_btc": true,
            
…(truncated, see openapi.json for full schema)
```

### Coins

#### `GET /v1/coins` — The altcoin universe measured against Bitcoin

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/altseason-api/v1/coins"
```

**Response:**
```json
{
    "data": {
        "note": "The curated top-altcoin universe (Binance USDT pairs, stablecoins excluded) measured against Bitcoin for the season index.",
        "coins": [
            "ETH",
            "SOL",
            "XRP",
            "BNB",
            "DOGE",
            "ADA",
            "TRX",
            "AVAX",
            "LINK",
            "DOT",
            "TON",
            "SHIB",
            "LTC",
            "BCH",
            "NEAR",
            "UNI",
            "APT",
            "ICP",
            "XLM",
            "ETC",
            "FIL",
            "HBAR",
            "ATOM",
            "ARB",
            "OP",
            "INJ",
            "IMX",
            "VET",
            "RENDER",
            "GRT",
            "AAVE",
            "ALGO",
            "SAND",
            "MANA",
            "AXS",
            "THETA",
            "EGLD",
            "FLOW",
            "XTZ",
            "CHZ",
            "SUI",
            "SEI",
            "TIA",
            "STX",
            "RUNE",
            "FTM",
            "GALA",
            "CRV",
            "DYDX",
            "LDO"
        ],
        "count": 50,
        "source": "Binance",
        "benchmark": "BTC"
    },
    "meta": {
        "timestamp": "2026-06-12T10:35:22.792Z",
        "request_id": "1b5fcdb8-ac6c-494c-82b6-d4d21694faae"
    },
    "status": "ok",
    "message": "Coins retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/altseason-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "window is 7-365 days (default 90, the classic horizon). The index is the percent of the alt universe that outperformed BTC. Read fresh per call, nothing cached.",
        "source": "Binance daily klines (BTC + top altcoins), live",
        "service": "altseason-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/coins": "The altcoin universe measured against Bitcoin.",
            "GET /v1/index": "The altcoin season index (0-100) with season label and out/under-performer counts (window=90).",
            "GET /v1/leaderboard": "Alts ranked by excess return versus Bitcoin, with leaders and laggards (window=90)."
        },
        "description": "Altcoin Season Index — whether capital is rotating into altcoins or huddling in Bitcoin, live from Binance (no key, nothing stored). index returns the 0-100 altcoin-season index (share of top alts beating BTC over the window), the season label, BTC's return and the out/under-performer counts. leaderboard ranks the alts by excess return versus Bitcoin. coins lists the universe. The altcoin-season / alt-vs-BTC rotation cut — distinct from the market-cap-dominance and global-market APIs (BTC's share of cap, not relative performance), single-coin momentum and price APIs. It answers whether it is altseason.",
        "universe_size": 50,
        "upstream_status": "ok",
        "altcoin_season_index": 28
    },
    "meta": {
        "timestamp": "2026-06-12T1
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/altseason-api
OpenAPI spec: https://www.oanor.com/api/altseason-api/openapi.json