# fomo-mcp

Unofficial API wrapper + MCP server for fomo.family. Same code both ways: import `FomoClient` in your own project, or point your agent at it over MCP.

Not affiliated with fomo.family. Endpoints can change without notice.

## Auth

The app logs in through Privy (Apple / Google OAuth). After one login in a browser you get three tokens:

- `FOMO_ID_TOKEN` — goes on every API call as the Bearer token. Lasts about an hour.
- `FOMO_ACCESS_TOKEN` — Privy API token.
- `FOMO_REFRESH_TOKEN` — long-lived. Keeps the Privy session alive via `POST /api/v1/sessions`.
- `FOMO_CA_ID` — optional, binds requests to the session that minted the tokens.

To grab them: log in at fomo.family, open devtools, look at any request to `prod-api.fomo.family` for the `Authorization: Bearer ...` header (that's the ID token), and the response of `POST https://auth.privy.io/api/v1/oauth/authenticate` for all three.

Only `/oauth/authenticate` mints ID tokens — the refresh endpoint won't give you a new one. When calls start 401ing, log in again and swap in a fresh triple. Note each login method (Apple vs Google) can be a separate account, so use the one tied to your profile.

## Run it

Requires Google Chrome installed. API traffic runs through a headless
Chrome window under the hood — the API edge rejects non-browser clients,
so plain fetch/curl won't work.

```bash
npm install
npm run build

export FOMO_ID_TOKEN=... FOMO_ACCESS_TOKEN=... FOMO_REFRESH_TOKEN=...
node dist/server.js
```

As an MCP server (Claude Code, Claude Desktop, Codex, etc.):

```json
{
  "mcpServers": {
    "fomo": {
      "command": "node",
      "args": ["/path/to/fomo-mcp/dist/server.js"],
      "env": {
        "FOMO_ID_TOKEN": "...",
        "FOMO_ACCESS_TOKEN": "...",
        "FOMO_REFRESH_TOKEN": "..."
      }
    }
  }
}
```

As a library:

```ts
import { FomoClient } from "fomo-mcp"; // src/client.ts
const fomo = new FomoClient(process.env.FOMO_ID_TOKEN!);
const me = await fomo.getUserByHandle("lxfts");
```

Two things learned the hard way: don't send `accept-encoding: gzip` manually (Node fetch handles it, raw clients need to decompress), and don't replay cached `if-none-match` headers or everything comes back 304.

## Tools

Users / profile: `fomo_get_user_by_handle`, `fomo_get_user`, `fomo_get_following_ids`, `fomo_search_users`, `fomo_get_user_swaps`, `fomo_get_user_rank`, `fomo_get_spotlight`, `fomo_get_recommended_users`

Balances: `fomo_get_balances`, `fomo_get_pnl_equity_series`, `fomo_get_snapshot_by_id`

Leaderboards: `fomo_get_leaderboard` (24h / 7d / 30d / all), `fomo_get_clan_leaderboard`

Clans: `fomo_search_clans`, `fomo_get_clan`, `fomo_get_clan_holdings`, `fomo_get_clan_holding_breakdown`, `fomo_get_clan_feed`

Trades: `fomo_get_trades`, `fomo_get_trade`, `fomo_get_trade_comments`

Swaps: `fomo_request_swap_quote` — quotes only. Token ids look like `<mint>:<chainId>` (`1399811149` = Solana, `4663` = EVM), amount in base units. Execution signs and submits on-chain (Jito), deliberately not exposed.

Tokens / market: `fomo_filter_tokens`, `fomo_search_tokens`, `fomo_token_details`, `fomo_token_warnings`, `fomo_verified_tokens`, `fomo_top_holders`, `fomo_dev_holdings`, `fomo_friends_holdings`, `fomo_token_allow_list`, `fomo_ohlcv`

Feed: `fomo_token_feed`, `fomo_token_thesis`, `fomo_token_sorted_thesis`, `fomo_trading_activity`

Watchlist / transfers / meta: `fomo_get_watchlist`, `fomo_add_watchlist`, `fomo_remove_watchlist`, `fomo_transfers_with`, `fomo_supported_transfer_tokens`, `fomo_get_config`

Live updates run over `wss://prod-api.fomo.family/ws` (plain GET upgrades to 101) — not wrapped yet.