# CryptoBro API

Programmatic access to every CryptoBro view. JSON over HTTPS, the same data as
the terminal. Base URL:

```
https://crypto-bro.lol/api
```

All responses are JSON. Every view the sidebar shows is an endpoint.

---

## Authentication

Create an API key in **Account settings** (or the user menu, **API & docs**).
Keys look like `cb_...`, are shown once, and are stored hashed.

Send the key either way:

```
Authorization: Bearer cb_XXXX
# or
X-API-Key: cb_XXXX
```

Keys can optionally be **bound to a single IP address**; a bound key is rejected
from any other address (`403 ip_not_allowed`).

---

## Quickstart

```bash
curl -s "https://crypto-bro.lol/api?action=catalog" \
  -H "Authorization: Bearer cb_XXXX"

curl -s "https://crypto-bro.lol/api?ep=oi_all&baseCoin=BTC" \
  -H "Authorization: Bearer cb_XXXX"

curl -s "https://crypto-bro.lol/api?src=binance_oi_hist&symbol=BTCUSDT&interval=1h" \
  -H "X-API-Key: cb_XXXX"

curl -s "https://crypto-bro.lol/api?liq=hybrid&symbol=BTCUSDT&interval=1h&lookback_hours=336" \
  -H "Authorization: Bearer cb_XXXX"
```

Python:

```python
import requests
r = requests.get("https://crypto-bro.lol/api?ep=oi_all&baseCoin=BTC",
                 headers={"Authorization": "Bearer cb_XXXX"}, timeout=30)
print(r.json()["data"])
```

JavaScript:

```js
const r = await fetch("https://crypto-bro.lol/api?src=binance_oi_hist&symbol=BTCUSDT&interval=1h", {
  headers: { "X-API-Key": "cb_XXXX" }
});
console.log((await r.json()).data);
```

---

## Endpoints

| Route | Method | Purpose |
|---|---|---|
| `/api?action=catalog` | GET | List every view your plan can access. |
| `/api?ep=<key>&...` | GET | Aggregated derivatives endpoint (open interest, funding, liquidations, long/short, order book, indicators). |
| `/api?src=<id>&...` | GET | Direct exchange/public source (Binance, OKX, Bybit). |
| `/api?liq=event\|estimate\|hybrid&...` | GET | Native liquidation heatmap models. |
| `/api?action=api_me` | GET | Your plan limits, usage and keys (session auth). |
| `/api?action=api_plans` | GET | API policy per plan. |
| `/api?action=series_me` | GET | Live Series: your tier, unlocked views, refresh quota. |
| `/api?action=series&asset=SOLUSDT&view=unified[&at=...]` | GET | Live Series frame (quota-limited). |
| `/api?action=series_index&asset=SOLUSDT&view=unified` | GET | Archived frames for the time slider. |
| `/api?action=series_overlays&...` | GET | Chart-ready overlays (maker orders, liquidation heatmap, klines). |
| `/api?action=docs_md` | GET | This document as Markdown. |
| `/api?action=mcp_server` | GET | The CryptoBro MCP server script (Python). |

Data parameters:

| Param | Applies to | Notes |
|---|---|---|
| `symbol` | ep, src, liq | e.g. `BTCUSDT`, `ETHUSDT`, `SOLUSDT` |
| `baseCoin` | ep | e.g. `BTC` |
| `interval` | ep, src, liq | `5m, 15m, 30m, 1h, 2h, 4h, 8h, 24h` |
| `exchange` | ep | `Binance`, `OKX`, `Bybit`, `Gate` |
| `lookback_hours` | liq | window in hours |
| `force=1` | all | bypass server caches |

Response shape:

```json
{ "ok": true, "cached": false, "stale": false, "ts": 1760000000.1,
  "endpoint": "oi_all", "data": [ ... ] }
```

---

## Large maker orders

`GET /api?ep=large_trades&symbol=BTCUSDT&exchange=Binance&productType=SWAP&amount=1000000`

Each row is one large **market** order annotated with its **taker** side (`side` =
`buy`/`sell`) for BTC/ETH/SOL in `SWAP` or `SPOT`, sourced directly from the
Binance and OKX trade archives since 1 January 2026.

Row shape:

```json
{ "exchangeName": "Binance", "baseCoin": "BTC", "side": "sell",
  "price": 81659.6, "tradeTurnover": 1500000.0, "ts": 1792040129000,
  "symbol": "BTCUSDT" }
```

The website view is **date-window based** (a replay slider). Selectors:

| Param | Values |
|---|---|
| `exchange` | `Binance`, `OKX` |
| `productType` | `SWAP`, `SPOT` |
| `amount` | `1000000`, `2000000`, `5000000`, `10000000`, `20000000`, `50000000` |
| `symbol` | `BTCUSDT`, `ETHUSDT`, `SOLUSDT` |
| `bucket` | a replay window id from `?action=large_trades_tm` (or `live`) |

A window returns **every** qualifying order in it. The window/step is tiered:

| Tier | Range | Step |
|---|---|---|
| anonymous | last **14 days** | 1 day |
| signed-in (free) | last **~3 months** | 7 days |
| paid | **full timeframe** | 7 days |

Out-of-tier windows return `403 upgrade_required`.

`size` (`100`, `500`) is an **API-key** pagination control and is never sent by
the website. With an API key you can pass any `amount`, `size`, and an `endTime`
window for backtesting.

---

## Live Series

`series`, `series_index` and `series_overlays` honour your plan's **tier**,
**unlocked views** and **daily refresh quota**. A frame is charged only when it
is newer than any frame you have already unlocked; replaying older frames and
reading the index is free. A view your plan does not unlock returns
`403 forbidden`.

---

## Rate limits and plans

Limits follow your plan. Every response carries:

- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`

When the daily quota or the per-minute rate is exceeded the API returns `429`
with `Retry-After`.

---

## Errors

| Status | error | Meaning |
|---|---|---|
| 401 | `invalid_token` | Missing or unknown key. |
| 403 | `api_not_enabled` | The API is disabled for your plan. |
| 403 | `ip_not_allowed` | The key is bound to a different IP address. |
| 403 | `forbidden` | Your plan is not entitled to that view. |
| 429 | `rate_limited` | Per-minute rate exceeded. |
| 429 | `quota_exceeded` | Daily request quota reached. |
| 400 | `unknown endpoint` | Unknown ep/src/liq key. |

---

## MCP server (for agents)

The MCP server exposes CryptoBro as tools for any Model Context Protocol client:
**opencode**, **Claude Code**, **Hermes**, and others.

Tools: `cryptobro_catalog`, `cryptobro_data`, `cryptobro_series_me`,
`cryptobro_series`, `cryptobro_docs`.

Requires Python 3.9+ (standard library only). Download the script:

```bash
curl -s -o cryptobro_mcp_server.py \
  "https://crypto-bro.lol/api?action=mcp_server"
```

Environment:

- `CRYPTOBRO_API_KEY` (required) your `cb_...` key.
- `CRYPTOBRO_API_URL` (optional) default `https://crypto-bro.lol/api`.

### opencode

Add to `opencode.json` (project) or the global config:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cryptobro": {
      "type": "local",
      "command": ["python3", "/absolute/path/cryptobro_mcp_server.py"],
      "environment": { "CRYPTOBRO_API_KEY": "cb_XXXX" },
      "enabled": true
    }
  }
}
```

### Claude Code

```bash
claude mcp add cryptobro \
  --env CRYPTOBRO_API_KEY=cb_XXXX \
  -- python3 /absolute/path/cryptobro_mcp_server.py
```

Or a project `.mcp.json`:

```json
{
  "mcpServers": {
    "cryptobro": {
      "command": "python3",
      "args": ["/absolute/path/cryptobro_mcp_server.py"],
      "env": { "CRYPTOBRO_API_KEY": "cb_XXXX" }
    }
  }
}
```

### Hermes and other MCP clients

```json
{
  "mcpServers": {
    "cryptobro": {
      "command": "python3",
      "args": ["/absolute/path/cryptobro_mcp_server.py"],
      "env": { "CRYPTOBRO_API_KEY": "cb_XXXX" }
    }
  }
}
```

---

Informational only. Not financial advice.