# 信息捕手·FOMO Monitor v2

基址：`https://fomo.xxbs.club`

监控 fomo 上一千多位博主在 Solana、BSC、Ethereum、Base、Robinhood、Arc 上的买卖和观点，以及全站共识、官方认证代币。历史动态用 REST 补，实时用 WebSocket，不要轮询。

给 Agent 用的说明书就是这一份：`https://fomo.xxbs.club/skills.md`（English: `https://fomo.xxbs.club/en/skills.md`）

---

## 从 v1 迁移

- `/v1/traders`、`/v1/traders/{handle}`、`/v1/traders/{handle}/fills`、`/v1/ws`、`/v1/alerts/*` 路径不变，成交字段名不变（`id` `ts` `side` `usd` `token` `symbol` `handle` `new_position` ...）。
- 新增字段：`chain`（链）、`position`（`first` 首次 / `add` 加仓 / `reenter` 清仓后再买）、`tx_url`。
- 不再提供：钱包持仓 `bags`、已平仓 `history`、盈亏曲线 `curve`（返回空数组）；`is_stock` 恒为 0；`flags` 一般为空。
- 名单从 Robinhood 链 147 人扩到多链 1000+ 人，部分旧 handle 不再收录。
- `id` 是本站序号，与 v1 不连续。断线续传用最新收到的 `id`（v2 叫 `seq`）。
- 想要观点、共识、认证等新事件，用 `/v2/events` 和 `/v2/ws`。

---

## 鉴权

KOL 名单公开（只含基础信息）。统计、动态、实时订阅、提醒需要 Token，且开通 **FOMO监控**。开通请联系小助理微信：`coecvyy`

| 位置 | 示例 |
|---|---|
| Header | `Authorization: Bearer sk-...` |
| Header | `X-API-Key: sk-...` |
| Query | `?token=sk-...`（浏览器 WebSocket 用这个） |

没有 Token 或无效 → `401`；没有权限 → `403`；请求太快 → `429`。

每个 Token 约每秒 5 次、可突发 30 次。实时数据请用 WebSocket，不要循环拉 REST。

---

## 事件对象

`/v2/events`、`/v2/ws`、`/v2/kols/{handle}` 返回同一种事件对象。没有值的字段不出现。

| 字段 | 含义 |
|---|---|
| `seq` | 本站序号，越大越新。增量拉取用 `since=<seq>` |
| `kind` | 事件类型，见下表 |
| `ts` | 事件时间，**毫秒** |
| `handle` / `name` / `avatar` | 博主。共识、异动、认证这类全站信号没有 `handle` |
| `followers` | 粉丝数 |
| `chain` | `solana` `bsc` `eth` `base` `robinhood` `arc` |
| `symbol` / `ca` | 代币符号 / 合约地址 |
| `side` | `buy` / `sell` |
| `usd` | 金额（USD）。共识为合计金额 |
| `amount` / `price` / `mcap` | 数量 / 成交价 / 市值 |
| `position` | `first` 首次建仓 / `add` 加仓 / `reenter` 清仓后再买 |
| `closed` | 这一笔把仓位清空 |
| `tx` / `tx_url` | 交易哈希 / 浏览器链接 |
| `text` / `text_zh` | 观点原文 / 中文翻译 |
| `pnl` | 观点里作者当时的持仓浮盈 `{usd, pct}` |
| `cash_usd` | 作者当时的稳定币余额 |
| `clan` | 战队 `{name, icon}` |
| `group` | 多人信号：`{people, window_min, net_usd, total_usd, dir, name, members:[{handle, label, avatar, usd}]}` |
| `swap` | 换仓 `{from, to}` |
| `token` | 代币信息 `{holders, vol24h, created_ts}` |
| `updated` | 最后更新时间（毫秒）。同一 `seq` 可能会被补全信息后再推一次 |

### `kind`

| 值 | 含义 |
|---|---|
| `buy` / `sell` | 买入 / 卖出 |
| `swap` | 换仓 |
| `thesis` | 观点 |
| `consensus` | 全站共识：短时间内多位博主买同一代币 |
| `mover` | 代币异动 |
| `clan` | 战队共振 |
| `verified` | fomo 官方验证了新代币 |
| `cash` | 资金调动 |

保留：买卖、观点约 48 小时；共识、认证等信号约 7 天。

---

## GET `/v2/kols`

全部博主。`q` 按 handle / 名称搜。

不带 Token：`handle` `name` `avatar` `profile_url` `chains` `clan` `tracked`。

带 Token 额外有：`followers`、`last_ts`（毫秒）、`stats`（近 48 小时：`buys` `sells` `theses` `buy_usd` `sell_usd` `net_usd` `tokens` `first_buys`）。

## GET `/v2/kols/{handle}`（需要 Token）

博主信息 + 最近 100 条动态 `events`。

## GET `/v2/events`（需要 Token）

| 参数 | 说明 |
|---|---|
| `kinds` | 逗号分隔，如 `buy,sell,consensus` |
| `handles` | 逗号分隔 |
| `scope` | `watch` 我的自选 / `subs` 我的提醒规则里的博主 |
| `chains` | 逗号分隔 |
| `side` | `buy` / `sell` |
| `min_usd` | 金额下限 |
| `symbol` / `ca` | 指定代币 |
| `since` | 只要 `seq` 大于它的（从旧到新返回） |
| `before` | 只要 `seq` 小于它的（翻页） |
| `limit` | 默认 50，最大 500 |

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

## 自选

| 接口 | 作用 |
|---|---|
| `GET /v2/watchlist` | 当前自选 |
| `PUT /v2/watchlist` | 整体覆盖，body `{"handles":["a","b"]}`，最多 300 |
| `POST /v2/watchlist/{handle}` | 加一个 |
| `DELETE /v2/watchlist/{handle}` | 删一个 |
| `GET /v2/subscriptions` | 提醒规则里出现过的博主 |

---

## WebSocket `GET /v2/ws`（需要 Token）

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

| 参数 | 写法 |
|---|---|
| 全部博主 | `all=1`（默认） |
| 指定博主 | `handles=frankdegods,dipwheeler` |
| 自选 / 订阅 | `scope=watch` / `scope=subs` |
| 类型 | `kinds=buy,sell,thesis` |
| 方向 / 金额 | `side=buy`、`min_usd=3000` |
| 链 | `chain=solana,bsc` |
| 首次建仓 | `position=first` |

连上先收到 `{"type":"subscribed"}`，之后每条是 `{"type":"event","new":true,"data":{事件对象}}`。`new=false` 表示之前推过的 `seq` 补全了信息，用 `seq` 覆盖即可。

连上后可改订阅，不用断开：

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

`filters` 支持字段 `chain` `symbol` `ca` `usd` `position` `closed` `mcap` `followers` `people`，操作 `eq` `ne` `in` `gte` `lte` `gt` `lt` `contains` `exists`。同一 Token 同时只保留一条连接，新连接会顶掉旧的（关闭码 `4000`）。

## WebSocket `GET /v1/ws`（兼容）

参数与 v1 相同（`all` `handles` `side` `usd_gte` `new_position` ...）。默认只推买卖，消息为 `{"type":"fill","data":{v1 成交字段}}`。加 `kinds=` 可以混入其它事件，格式同 `/v2/ws`。

---

## v1 兼容接口

| 接口 | 说明 |
|---|---|
| `GET /v1/traders` | 名单。带 Token 时含 `buys` `sells` `fills` `volume` `net_flow` `last_ts`（秒）`chains` |
| `GET /v1/traders/{handle}` | 博主信息 + `recent_fills`；`bags` `history` `curve` 为空 |
| `GET /v1/traders/{handle}/fills` | 最近买卖，参数 `limit` `side` `min_usd` `since_id` |
| `GET /v1/usage` | 该 Token 近 7 天调用记录 |
| `GET /v1/auth` | 校验 Token，含 `admin` |
| `GET /v1/health` | 健康检查 |

---

## 飞书提醒 `/v1/alerts/*`（需要 Token）

网页 `/alerts` 也能配置。

| 接口 | 作用 |
|---|---|
| `GET/POST /v1/alerts/channels` | 飞书渠道（每 Token 最多 5 个） |
| `PATCH/DELETE /v1/alerts/channels/{id}` | 改名称或 webhook；删除渠道会删掉它的规则 |
| `POST /v1/alerts/channels/{id}/test` | 发一张 `[test]` 卡片 |
| `GET/POST /v1/alerts/rules` | 规则（每 Token 最多 20 条） |
| `PATCH/DELETE /v1/alerts/rules/{id}` | 改或删 |
| `GET /v1/alerts/deliveries` | 近 7 天投递 |

规则字段：

| 字段 | 说明 |
|---|---|
| `name` / `channel_id` / `enabled` | 名称 / 渠道 / 启用 |
| `kinds` | 默认 `["buy","sell"]`。可加 `thesis` `swap` `consensus` `mover` `clan` `verified` |
| `handles` | 买卖、观点、换仓需要，最多 300 人。共识等全站信号不按博主过滤 |
| `chains` | 空 = 全部 |
| `side` | `buy` / `sell` / 空 |
| `usd_gte` | 金额下限，默认 1000。对观点、认证不生效 |
| `new_position` | 买入只推首次建仓 |
| `min_people` | 共识 / 异动 / 战队最少人数 |
| `note` | 系统迁移说明（只读），编辑博主或类型后清空 |

---

## 用法示例

```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("共识", ev["symbol"], ev["group"]["people"], "人", ev["usd"])
        elif ev.get("position") == "first":
            print(ev["handle"], "首次买入", ev["symbol"], ev["chain"], ev["usd"])
```

---

## 出错时

| HTTP | 含义 |
|---|---|
| 400 | 参数不合法 |
| 401 | 带上有效 Token |
| 403 | 该 Token 还没有 FOMO监控，联系微信 `coecvyy` |
| 404 | 没有这个 handle |
| 429 | 请求太快，降频或改用 WebSocket |

只读数据，不能下单。