# 信息捕手·FOMO Monitor

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

你可以拉全部已收录 KOL，看他们的钱包、持仓和盈亏。

**实时成交不要轮询钱包或名单。** 名单是快照；成交带用 WebSocket 订阅，成交一发生就会推过来。

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

---

## 鉴权

名单接口公开。查看某个 KOL 的持仓详情、历史成交、以及实时订阅，需要 Token，且开通 **FOMO监控**。

开通请联系小助理微信：`coecvyy`

请求时任选一种方式带上 Token：

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

没有 Token 或 Token 无效 → `401`。没有 FOMO监控权限 → `403`。

登录后可打开控制台，查看近 7 天该 Token 的 REST / WebSocket 调用记录。

---

## 你能做什么

1. **拉全部 KOL**

公开，无需 Token。每人含钱包地址、净盈亏、仓位、交易量、关注数、FOMO 主页。

2. **看某个 KOL 的钱包**

需要 Token。能看到当前持仓、已平仓、统计。这是当前画像，不是成交推送。

3. **盯实时成交**

需要 Token，用 WebSocket。可订全部 KOL，或只订若干 handle；可按金额、方向、标的过滤。同一 Token 同时只连一条；再连会顶掉旧的，断线用同一 Token 重连即可。

---

## GET `/v1/traders`（公开）

全部 KOL。查询参数 `q` 可按 handle / 名称搜。

| 字段 | 含义 |
|---|---|
| `handle` | 交易员标识，详情和订阅都用它 |
| `display_name` | 展示名 |
| `followers` | 关注数 |
| `profile_url` | FOMO 主页 |
| `address` | 链上钱包地址 |
| `volume` | 统计窗口内成交额（USD） |
| `fills` | 成交笔数 |
| `buys` / `sells` | 买 / 卖笔数 |
| `last_ts` | 最近一笔成交的 Unix 秒 |
| `realized_pnl` | 已实现盈亏（USD） |
| `unrealized_pnl` | 未实现盈亏（USD） |
| `net_pnl` | 净盈亏 = 已实现 + 未实现 |
| `win_rate` | 胜率，0–1 |
| `state` | `printing` 在赚钱 / `draining` 在回吐 / `flat` 空仓或横盘 |
| `active` | 近期是否还在交易 |
| `open_bags` | 当前持仓标的个数 |
| `open_cost` | 开仓成本合计（USD） |
| `open_value` | 当前持仓市值（USD） |
| `closed_trades` | 已平仓笔数 |
| `best_trade` / `worst_trade` | 最好 / 最差一笔盈亏 |

```bash
curl https://fomo.xxbs.club/v1/traders
curl https://fomo.xxbs.club/v1/traders?q=unipcs
```

---

## GET `/v1/traders/{handle}`（需要 Token）

该 KOL 当前钱包。用来算成本线、持仓占比、是否还拿着某个标的。不要用它代替实时成交。

### 顶层

| 字段 | 含义 |
|---|---|
| `handle` | 交易员标识 |
| `display_name` | 展示名 |
| `followers` | 关注数 |
| `profile_url` | FOMO 主页 |
| `joined` | 收录时间（文本） |
| `streak` | 连续交易相关计数 |
| `num_trades` | 成交笔数 |
| `volume_usd` | 成交额 |
| `address` | 主链钱包 |
| `solana_address` | Solana 地址（若有） |
| `stats` | 汇总统计，见下表 |
| `bags` | 当前持仓数组 |
| `history` | 已平仓数组 |
| `curve` | 盈亏曲线 `[{ts, pnl}]`，`ts` 为 Unix 秒 |

### `stats`

| 字段 | 含义 |
|---|---|
| `window` | 统计窗口 |
| `closed_trades` | 已平仓笔数 |
| `win_rate` | 胜率，0–1 |
| `realized_pnl` | 已实现盈亏 |
| `unrealized_pnl` | 未实现盈亏 |
| `net_pnl` | 净盈亏 |
| `best_trade` / `worst_trade` | 最好 / 最差一笔 |
| `avg_hold_seconds` | 平均持仓秒数 |
| `profit_factor` | 盈亏比 |
| `open_bags` | 当前持仓个数 |

### `bags[]` 当前持仓

| 字段 | 含义 |
|---|---|
| `token` | 代币合约 |
| `symbol` / `name` | 代码 / 名称 |
| `is_stock` | 是否股票类标的 |
| `amount` | 持有数量 |
| `cost_usd` | 成本（USD） |
| `avg_price` | 均价 |
| `opened_ts` | 开仓时间 Unix 秒 |
| `last_buy_ts` | 最近买入 Unix 秒 |
| `mark` | 现价 |
| `liquidity` | 池子流动性 |
| `change24` | 24h 涨跌 |
| `pair_url` | 交易对链接 |
| `value` | 当前市值 |
| `priced` | 是否能定价 |
| `pnl` / `pnl_pct` | 浮盈（USD / 比例） |
| `age_seconds` | 已持有秒数 |

### `history[]` 已平仓

| 字段 | 含义 |
|---|---|
| `token` / `symbol` | 标的 |
| `opened_ts` / `closed_ts` | 开仓 / 平仓 Unix 秒 |
| `cost_sold` | 卖出对应成本 |
| `proceeds_usd` | 卖出所得 |
| `pnl_usd` / `pnl_pct` | 已实现盈亏 |
| `buys` / `sells` | 买 / 卖笔数 |
| `hold_seconds` | 持仓时长 |

```bash
curl -H "Authorization: Bearer $TOKEN" https://fomo.xxbs.club/v1/traders/picadura
```

---

## GET `/v1/traders/{handle}/fills`（需要 Token）

该 KOL 最近成交，从新到旧。适合进实时流之前补一段历史。

| 参数 | 说明 |
|---|---|
| `limit` | 默认 50，最大 500 |
| `side` | `buy` 或 `sell` |
| `min_usd` | 成交额下限，可丢掉试水小单 |
| `since_id` | 只要比这个 `id` 更新的 |

成交字段（HTTP 与 WS 相同）：

| 字段 | 含义 |
|---|---|
| `id` | 成交序号，越大越新，用来去重 |
| `ts` | 成交时间 Unix 秒 |
| `tx` | 交易哈希 |
| `side` | `buy` 买入 / `sell` 卖出 |
| `usd` | 成交额（USD） |
| `amount` | 成交数量 |
| `price` | 成交价 |
| `new_position` | 是否新开仓（1/true 表示新开） |
| `is_stock` | 是否股票类标的 |
| `block` | 区块高度 |
| `priced` | 是否完成定价 |
| `quote_token` | 计价代币 |
| `two_sided` | 是否双边成交 |
| `funding` | 资金相关标记 |
| `payer` | 付款地址 |
| `handle` | 交易员 |
| `display_name` | 展示名 |
| `followers` | 当时关注数 |
| `wallet` | 下单钱包 |
| `token` | 代币合约 |
| `symbol` / `name` | 代码 / 名称 |
| `mark` | 现价 |
| `liquidity` | 流动性 |
| `pair_url` | 交易对链接 |
| `mcap` | 市值 |
| `buys24` / `sells24` | 24h 买 / 卖 |
| `pair_created_at` | 池子创建时间 Unix 秒 |
| `flags` | 标签数组，如 honeypot 等 |

---

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

浏览器：

```
wss://fomo.xxbs.club/v1/ws?token=sk-...&all=1
```

| 你想订什么 | 怎么写 |
|---|---|
| 全部 KOL | `all=1` 或 `handles=*` |
| 指定几人 | `handles=picadura,unipcs` |
| 只要买单 | `side=buy` |
| 只要大单 | `usd_gte=3000` |
| 只要新开仓 | `new_position=1` |
| 只要某些票 | `symbol=CATGPT,DOOM` |

连上后先收到 `{"type":"subscribed",...}`，之后每笔匹配成交是 `{"type":"fill","data":{...}}`。`data` 字段与上表成交字段相同。

也可以连上再改过滤，不用断开：

```json
{"op":"subscribe","all":true,"filters":{"side":{"eq":"buy"},"usd":{"gte":3000}}}
{"op":"ping"}
```

`ping` 会回 `{"type":"pong"}`。

字段过滤：`eq` 等于，`ne` 不等于，`in` 属于列表，`gte`/`lte`/`gt`/`lt` 数值比较，`contains` 包含，`exists` 字段是否有值。

---

## GET `/v1/usage`（需要 Token）

该 Token 近 7 天的调用记录：REST 路径、状态码、耗时；WebSocket 的打开 / 关闭。过期记录会删除。

---

## 用法示例

聪明钱扎堆、主力砸盘、喂给 Agent，都应听 WS，而不是反复打 `/v1/traders/{handle}`。

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

BASE = "https://fomo.xxbs.club"
TOKEN = "sk-..."
h = {"Authorization": f"Bearer {TOKEN}"}

# 1) 公开名单：钱包、盈亏、主页
kols = requests.get(f"{BASE}/v1/traders", timeout=30).json()["traders"]

# 2) 某个 KOL 当前仓位（画像，不是成交流）
wallet = requests.get(f"{BASE}/v1/traders/picadura", headers=h, timeout=30).json()

# 3) 实时成交：全部 KOL、过滤掉小单
ws_url = f"wss://fomo.xxbs.club/v1/ws?token={TOKEN}&all=1&usd_gte=1000"
with connect(ws_url) as ws:
    print(ws.recv())
    for _ in range(20):
        print(ws.recv())
```

把 `skills.md` 丢给模型时，让它：用名单拿地址和主页；用详情看仓位；用 WS 做提醒（例如 N 个高胜率地址短时间内同向建仓，或单笔卖出超过持仓约 30%）。

---

## 出错时

| HTTP | 含义 |
|---|---|
| 400 | 过滤条件不合法 |
| 401 | 带上有效 Token |
| 403 | 该 Token 还没有 FOMO监控，联系微信 `coecvyy` |
| 404 | 没有这个 handle |

本接口只读公开链上已索引的成交，不能下单。