---
name: fomoscan-api
description: The FomoScan Identity API (fomo handle to wallet, PnL, thesis feeds, leaderboards), its real cost per call, and the hard spend rules and guard script that exist because one loop burned a whole $79 month in 75 calls. Read BEFORE any FomoScan call, any metered/paid API work, and any wallet-identity hunt.
sources: [cowork]
aliases: [fomoscan, fsk, fomo scan api, identity api, partner.fomoscan.sh, api budget rules]
---

# FomoScan API, and the spend rules that govern it

## THE INCIDENT, 19 Sep 2026
Ben bought the Starter plan ($79/mo, 250,000 CU, 150 req/min) to finish the
@apebender wallet hunt. I looped `/v2/user/wallet/{address}` over 72 candidate
addresses plus one leaderboard call. **That consumed 250,000 CU, the entire
month, in about 75 calls, to answer one question.** Measured burn: roughly
**3,000 CU per identity call, about $0.95 a call.** $79 buys about 80 calls.
[stated] Ben: "You just burned $70 for one little thing. I want to use this API
a lot, and I need to make sure this never happens again."

## THE RULES (standing, and they apply to EVERY metered paid API, not just this one)
1. **DRY RUN FIRST, ALWAYS.** Print the estimated CU and the dollar cost of a
   batch before a single credit moves. No estimate, no call.
2. **NEVER LOOP A SINGLE-ITEM ENDPOINT.** If a batch or leaderboard endpoint
   exists, it is the only acceptable route. Hard limit 5 single-item calls.
3. **CACHE IDENTITY FOREVER.** handle/wallet/id mappings are immutable, so they
   are never bought twice. Cache to disk, keyed by endpoint plus params.
4. **HARD CAPS, NOT WARNINGS.** 10,000 CU per run, 25,000 CU per day, refused
   at the call site. An over-large `--spend` is clamped, never honoured.
5. **MEASURE, DO NOT GUESS.** Learn the true price by diffing `/v2/me` around a
   call and persist it. An unmeasured endpoint is priced at the 3,000 CU worst case.
6. **STOP AT LOW BALANCE.** Below 20,000 CU remaining, refuse everything and
   tell Ben to top up. Never discover the wall by hitting it.
7. **LEDGER EVERY CALL** (endpoint, CU, remaining) so the burn is auditable after.
8. **BUDGET BEFORE BREADTH.** State the question, pick the cheapest endpoint that
   answers it, and spend on-chain RPC (free) for anything the API is not uniquely
   needed for. Entry price, hold time and lead time are all free on chain.

## THE GUARD SCRIPT: `fsk.py`
The ONLY sanctioned client. Container copy `/home/claude/fsk.py`, Mac copy
`~/.hypekit/fsk.py`. Key at `~/.secrets/fomoscan`, chmod 600, never echoed.
Encodes all eight rules. CLI: `balance`, `cost`, `ledger`, `plan`, `handle`,
`wallet`, `board`, `pnl`; nothing spends without `--spend <CU>`.
Verified 19 Sep against the failure itself: a replay of the 72-wallet loop now
**stops after 5 calls, max exposure $4.74 instead of $68.**

## ENDPOINT MAP (base `https://api.fomoscan.sh`, `Authorization: Bearer fsk_live_...`)
Spec at `/openapi.json`, human docs at `/docs`. NOTE: `www.fomoscan.sh/api` and
`partner.fomoscan.sh/api` are the Next.js SPA and return 404 HTML; only
`api.fomoscan.sh` is the API. `partner.fomoscan.sh/account` is the billing page.
- `GET /v2/user/handle/{handle}` , `GET /v2/user/wallet/{address}` , `GET /v2/user/id/{id}` , `POST /v2/user/handle/{handle}/resolve` (live)
- `GET /v2/user/handle/{handle}/pnl` , **`POST /v2/user/handles/pnl` (up to 100 traders in ONE call, the cheap route)**
- `GET /v2/leaderboard/traders-fomoscan?window=24h|7d|30d|all&order=best|worst` , **100 traders, one call**, fields: rank, handle, wallet, evmWallet, netUsd, volumeUsd, **trades**, displayName, twitter, followers, **returnPct**
- `GET /v2/leaderboard/traders` , `/clans` , `/tokens/most-held` , `/tokens/trending` , `/tokens/graduated` , `/creators-revshare` , `/affiliates`
- `GET /v2/thesis` , `/thesis/token/{ca}` , `/thesis/user/{id}` , `/thesis/user/{id}/token/{ca}` , all paginated by `before` = previous `nextBefore`
- `GET /v2/ws` live thesis firehose (WebSocket), the hook for an alert bot
- `[Experimental] /v2/pump/*` , pump.fun user by wallet, callouts, PnL leaderboard
- `GET /v2/me` introspects the key (plan, entitlement, unitsUsed, unitsRemaining)

## FINDINGS ALREADY BOUGHT WITH THESE CREDITS (do not pay for them twice)
- `0xc3236a41c10c5ee3590be36cef8ae84d20c64e7e` / Solana
  `Bgcx5SQxdueDvi2bnX1AcTTNjL7fKaiYYWFxggS5y9SG` = fomo handle **onchainrebirth**
  ("🦢"), no linked twitter. This is the wallet I wrongly gave Ben as @apebender;
  it is a copy-trader, see [[apebender-wallet]].
- `0xd67d64afc4e0337613cd31bd76b69e9887b7d26c` = **RareDualJay**
- `0x85d26724d4447a85ec1089b0a572c97f1ad476f3` = **pricedin**
- `0xee1c511d8d9ee0fb88c9eb79ff40b295411184cf` = **CoachPauI**
- **TuttoPassa** exists (matching the "TUTTO PASSA" on apebender's X photo) but is
  NOT him: $1,182 account, 3 followers, 148 trades, 18h40m average hold.
- fomo handle `apebender` does not exist; nor do gab, ape, apebndr, 0xgab, gabx.
  `gabe`, `bender`, `gabo` exist but carry no wallets.
- Board size: **447,139 FOMO accounts** with at least one traded wallet.
- Top of the all-time board: **Visi235**, 60 trades, +$1,102,409, +5,802%.

## THE "RARE, EARLY, HIGH HIT RATE, LONG HOLD" SCREEN Ben asked for
Cheap by construction, about 4 calls / 12,000 CU:
1. `/v2/leaderboard/traders-fomoscan` on `all` and `30d`, `best` and `worst`
   (4 calls, 400 traders). The `worst` boards exclude one-lucky-hit accounts.
2. Filter on fields the board already carries: **low `trades`, high `returnPct`,
   meaningful `netUsd`**. That is exactly Ben's "trades rarely, high hit rate".
3. FREE on chain: entry market cap and holding duration per position, which the
   API does not carry, so never buy it.
4. `/v2/thesis/user/{id}` for their callouts with timestamps, to confirm they
   were early BEFORE they spoke (the signed-lead-time rule in /preferences.md).