# Info Hunter · FOMO Monitor v2

Base URL: `https://fomo.xxbs.club`

Tracks buys, sells and theses from 1,200+ KOLs on fomo across Solana, BSC, Ethereum, Base, Robinhood Chain and Arc, plus site-wide consensus and newly verified tokens. Use REST to backfill history and WebSocket for live data. Do not poll.

This file is the agent spec: `https://fomo.xxbs.club/en/skills.md` (中文：`https://fomo.xxbs.club/skills.md`)

---

## Migrating from v1

- `/v1/traders`, `/v1/traders/{handle}`, `/v1/traders/{handle}/fills`, `/v1/ws` and `/v1/alerts/*` keep their paths and fill field names (`id` `ts` `side` `usd` `token` `symbol` `handle` `new_position` ...).
- New fields: `chain`, `position` (`first` first buy / `add` adding / `reenter` buying again after closing) and `tx_url`.
- Removed: wallet holdings `bags`, closed positions `history` and PnL `curve` (returned as empty arrays); `is_stock` is always 0; `flags` is usually empty.
- The roster grew from 147 Robinhood Chain traders to 1,000+ KOLs on many chains; some old handles are no longer tracked.
- `id` is this site's sequence number and does not continue v1's. Resume after a disconnect with the latest `id` you received (called `seq` in v2).
- For theses, consensus, verified tokens and other new events, use `/v2/events` and `/v2/ws`.

---

## Authentication

The KOL roster is public (basic fields only). Stats, events, live subscriptions and alerts need a token with **FOMO Monitor** enabled. To get one, message us on Telegram: `@CryptoDoge2025` (https://t.me/CryptoDoge2025)

| Where | Example |
|---|---|
| Header | `Authorization: Bearer sk-...` |
| Header | `X-API-Key: sk-...` |
| Query | `?token=sk-...` (use this for browser WebSockets) |

Missing or invalid token → `401`; no FOMO Monitor access → `403`; too fast → `429`.

Each token gets about 5 requests per second with bursts of 30. Use the WebSocket for live data instead of polling REST in a loop.

---

## Event object

`/v2/events`, `/v2/ws` and `/v2/kols/{handle}` return the same event object. Fields without a value are omitted.

| Field | Meaning |
|---|---|
| `seq` | Site sequence number, larger is newer. Fetch increments with `since=<seq>` |
| `kind` | Event type, see below |
| `ts` | Event time in **milliseconds** |
| `handle` / `name` / `avatar` | The KOL. Site-wide signals such as consensus, movers and verified tokens have no `handle` |
| `followers` | Follower count |
| `chain` | `solana` `bsc` `eth` `base` `robinhood` `arc` |
| `symbol` / `ca` | Token symbol / contract address |
| `side` | `buy` / `sell` |
| `usd` | Amount in USD. For consensus, the combined amount |
| `amount` / `price` / `mcap` | Quantity / fill price / market cap |
| `position` | `first` first buy / `add` adding / `reenter` buying again after closing |
| `closed` | This fill closed the position |
| `tx` / `tx_url` | Transaction hash / explorer link |
| `text` / `text_zh` | Thesis text / Chinese translation |
| `pnl` | The author's unrealised PnL on the position when posting a thesis `{usd, pct}` |
| `cash_usd` | The author's stablecoin balance at the time |
| `clan` | Clan `{name, icon}` |
| `group` | Multi-KOL signal: `{people, window_min, net_usd, total_usd, dir, name, members:[{handle, label, avatar, usd}]}` |
| `swap` | Swap `{from, to}` |
| `token` | Token info `{holders, vol24h, created_ts}` |
| `updated` | Last update time (ms). The same `seq` may be pushed again once more details are filled in |

### `kind`

| Value | Meaning |
|---|---|
| `buy` / `sell` | Buy / sell |
| `swap` | Swap from one token to another |
| `thesis` | Thesis (a written take) |
| `consensus` | Site-wide consensus: several KOLs bought the same token within a short window |
| `mover` | Token price mover |
| `clan` | Clan members acting together |
| `verified` | fomo officially verified a new token |
| `cash` | Cash movement |

Retention: trades and theses about 48 hours; consensus, verified tokens and other signals about 7 days.

---

## GET `/v2/kols`

All KOLs. `q` searches handle and name.

Without a token: `handle` `name` `avatar` `profile_url` `chains` `clan` `tracked`.

With a token you also get `followers`, `last_ts` (ms) and `stats` (last 48 hours: `buys` `sells` `theses` `buy_usd` `sell_usd` `net_usd` `tokens` `first_buys`).

## GET `/v2/kols/{handle}` (token required)

KOL profile plus the latest 100 `events`.

## GET `/v2/events` (token required)

| Parameter | Description |
|---|---|
| `kinds` | Comma separated, e.g. `buy,sell,consensus` |
| `handles` | Comma separated |
| `scope` | `watch` your watchlist / `subs` KOLs in your alert rules |
| `chains` | Comma separated |
| `side` | `buy` / `sell` |
| `min_usd` | Minimum amount |
| `symbol` / `ca` | A specific token |
| `since` | Only `seq` greater than this (returned oldest first) |
| `before` | Only `seq` lower than this (pagination) |
| `limit` | Default 50, max 500 |

```bash
curl -H "Authorization: Bearer $TOKEN" "https://fomo.xxbs.club/v2/events?kinds=buy&chains=solana&min_usd=3000&limit=20"
```

## Watchlist

| Endpoint | Purpose |
|---|---|
| `GET /v2/watchlist` | Current watchlist |
| `PUT /v2/watchlist` | Replace it, body `{"handles":["a","b"]}`, up to 300 |
| `POST /v2/watchlist/{handle}` | Add one |
| `DELETE /v2/watchlist/{handle}` | Remove one |
| `GET /v2/subscriptions` | KOLs that appear in your alert rules |

---

## WebSocket `GET /v2/ws` (token required)

```
wss://fomo.xxbs.club/v2/ws?token=sk-...&kinds=buy,sell,consensus&min_usd=1000
```

| Option | Syntax |
|---|---|
| All KOLs | `all=1` (default) |
| Specific KOLs | `handles=frankdegods,dipwheeler` |
| Watchlist / subscriptions | `scope=watch` / `scope=subs` |
| Kinds | `kinds=buy,sell,thesis` |
| Side / amount | `side=buy`, `min_usd=3000` |
| Chains | `chain=solana,bsc` |
| First buys only | `position=first` |

You first receive `{"type":"subscribed"}`, then each message is `{"type":"event","new":true,"data":{event object}}`. `new=false` means an earlier `seq` was updated with more details; overwrite it by `seq`.

Change the subscription without reconnecting:

```json
{"op":"subscribe","kinds":["buy"],"handles":["frankdegods"],"filters":{"usd":{"gte":3000},"chain":{"in":["solana"]}}}
{"op":"ping"}
```

`filters` accepts the fields `chain` `symbol` `ca` `usd` `position` `closed` `mcap` `followers` `people` with the operators `eq` `ne` `in` `gte` `lte` `gt` `lt` `contains` `exists`. Each token keeps one connection; a new connection replaces the old one (close code `4000`).

## WebSocket `GET /v1/ws` (compatible)

Same parameters as v1 (`all` `handles` `side` `usd_gte` `new_position` ...). Pushes only trades by default, as `{"type":"fill","data":{v1 fill fields}}`. Add `kinds=` to mix in other events in the `/v2/ws` format.

---

## v1-compatible endpoints

| Endpoint | Description |
|---|---|
| `GET /v1/traders` | Roster. With a token, includes `buys` `sells` `fills` `volume` `net_flow` `last_ts` (seconds) `chains` |
| `GET /v1/traders/{handle}` | Profile plus `recent_fills`; `bags` `history` `curve` are empty |
| `GET /v1/traders/{handle}/fills` | Recent trades, parameters `limit` `side` `min_usd` `since_id` |
| `GET /v1/usage` | This token's calls over the last 7 days |
| `GET /v1/auth` | Validates the token, includes `admin` |
| `GET /v1/health` | Health check |

---

## Feishu (Lark) alerts `/v1/alerts/*` (token required)

You can also configure these on the `/en/alerts` page.

| Endpoint | Purpose |
|---|---|
| `GET/POST /v1/alerts/channels` | Feishu channels (up to 5 per token) |
| `PATCH/DELETE /v1/alerts/channels/{id}` | Rename or change the webhook; deleting a channel deletes its rules |
| `POST /v1/alerts/channels/{id}/test` | Sends a `[test]` card |
| `GET/POST /v1/alerts/rules` | Rules (up to 20 per token) |
| `PATCH/DELETE /v1/alerts/rules/{id}` | Edit or delete |
| `GET /v1/alerts/deliveries` | Deliveries over the last 7 days |

Rule fields:

| Field | Description |
|---|---|
| `name` / `channel_id` / `enabled` | Name / channel / enabled |
| `kinds` | Default `["buy","sell"]`. Can add `thesis` `swap` `consensus` `mover` `clan` `verified` |
| `handles` | Needed for trades, theses and swaps, up to 300. Site-wide signals such as consensus are not filtered by KOL |
| `chains` | Empty = all |
| `side` | `buy` / `sell` / empty |
| `usd_gte` | Minimum amount, default 1000. Ignored for theses and verified tokens |
| `new_position` | Only first buys |
| `min_people` | Minimum KOLs for consensus / mover / clan |
| `note` | System migration note (read only), cleared once KOLs or kinds are edited |

---

## Example

```python
import json
from websockets.sync.client import connect

TOKEN = "sk-..."
url = f"wss://fomo.xxbs.club/v2/ws?token={TOKEN}&kinds=buy,consensus&min_usd=3000"
with connect(url) as ws:
    print(ws.recv())
    while True:
        msg = json.loads(ws.recv())
        if msg.get("type") != "event" or not msg.get("new"):
            continue
        ev = msg["data"]
        if ev["kind"] == "consensus":
            print("consensus", ev["symbol"], ev["group"]["people"], "KOLs", ev["usd"])
        elif ev.get("position") == "first":
            print(ev["handle"], "first buy", ev["symbol"], ev["chain"], ev["usd"])
```

---

## Errors

| HTTP | Meaning |
|---|---|
| 400 | Invalid parameter |
| 401 | Send a valid token |
| 403 | This token does not have FOMO Monitor yet; message Telegram `@CryptoDoge2025` |
| 404 | Unknown handle |
| 429 | Too fast; slow down or switch to the WebSocket |

Read-only data. No trading.