Every endpoint, what it costs, and what it returns.

Authentication

Send your key as a bearer token. X-Api-Key: $KEY is accepted as an alternative. Keys look like fsk_live_… (production) or fsk_test_… (sandbox).

curl -s -H "Authorization: Bearer $KEY" \
  "https://api.fomoscan.sh/v2/user/handle/tradername"

A successful response is the record itself, as flat JSON. There is no wrapper to unwrap. Timestamps on thesis and PnL records are epoch milliseconds.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "handle": "tradername",
  "name": "Trader",
  "bio": null,
  "banner": null,
  "profilePicture": "https://…/a/3e0e…5671.webp",
  "twitter": "https://x.com/tradername",
  "solanaAddress": "So11111111111111111111111111111111111111112",
  "evmAddress": null
}

GET /v2/user/handle/{handle}/pnl reads one trader's profit and loss. You are billed on every call. Three outcomes carry three different meanings:

Live feed

One socket carries the whole thesis feed. Attach, then send one subscribe frame naming either every token or up to 50 token addresses, and change it later without reconnecting. A connection holds one subscription, and a new subscribe replaces whatever you had. pump.fun callouts have their own socket, described below.

• The feed is included from Growth ($899). Growth, Scale and Enterprise keys can connect. Keys on legacy plans keep the access they already have. Self-serve free, Starter and Builder keys are refused during the handshake with 403 WEBSOCKET_PLAN_REQUIRED.
• It authenticates with the same Authorization header, so the key cannot come from a browser — hold the socket in your backend.
• There is no replay. Take a snapshot from GET /v2/thesis/token/{tokenAddress} on connect and reconcile on id after any reconnect.
• The pong is mandatory: we ping every 30 seconds and close, with code 1011, a socket we have not heard from for 90 seconds.
• Running out of quota closes the socket with code 1008.
• A restart on our side closes the socket with code 1001. Reconnect and send your subscribe again.

Pump callouts (live)

New pump.fun callouts, sent to your server as they appear. Most callouts reach you within about a second of being posted on pump.fun. Each one is the same record GET /v2/pump/thesis returns, so your code reads one shape.

1. Connect

Open a WebSocket to this address with your key in the Authorization header, the same header as every other call. A browser cannot set that header, so hold the socket on your server and pass callouts on to your app from there.

wss://api.fomoscan.sh/v2/ws/pump
Authorization: Bearer $KEY

2. Subscribe

You receive nothing until you subscribe. Send one of these messages. all gives you every new callout. tokens narrows it to up to 50 coins. A new subscribe replaces the one before it.

{ "type": "subscribe", "subscription": { "type": "all" } }
{ "type": "subscribe", "subscription": { "type": "tokens", "tokens": ["<coin mint>"] } }

3. Read callouts

Each new callout arrives as one pump_callout message:

{
  "type": "pump_callout",
  "callout": {
    "id": "…",
    "wallet": "<author wallet>",
    "userName": "caller",
    "xUsername": "caller",
    "isVerified": false,
    "coinMint": "<coin mint>",
    "chain": "solana:mainnet",
    "coinSymbol": "COIN",
    "coinName": "Coin",
    "thesis": "Why I am in this coin…",
    "mediaUrl": null,
    "calledOutAtMcap": 48210.5,
    "multiple": 1.8,
    "maxMultiplier": 2.4,
    "createdAt": 1790000000000
  }
}

• id: The callout. Match on it so nothing shows twice.
• wallet: The author. On pump.fun the wallet is the account.
• coinMint: The coin the callout is about.
• thesis: What the author wrote.
• calledOutAtMcap: Market cap in USD when the callout was posted.
• multiple: Price move since the callout, as a multiple.
• createdAt: Post time, in epoch milliseconds.

If the connection drops

• There is no replay. Reconnect, send your subscribe again, then fetch GET /v2/pump/thesis to pick up anything you missed. Match on id so nothing shows twice.
• A restart on our side closes the socket with code 1001. Reconnect at once and subscribe again.
• Answer our pings. Standard WebSocket libraries do this for you. A socket we have not heard from for 90 seconds is closed with code 1011.

Plans and billing

• Included from Growth ($899): Growth, Scale and Enterprise keys can connect. Keys on legacy plans keep the access they already have. Self-serve free, Starter and Builder keys are refused with 403 WEBSOCKET_PLAN_REQUIRED.
• Billed per minute the socket is open, 20,000 CU a minute, from the same credits as your REST calls. Running out of credits closes the socket with code 1008.
• This socket is billed on its own. Holding the thesis feed and the pump feed at once means two sockets and two meters.

Resolving on demand

POST /v2/user/handle/{handle}/resolve asks for a handle's wallet when FomoScan holds nothing for it yet, and waits for the answer. A handle already held comes back immediately.

When the answer is not ready in time you get a 202 instead of an error, with a reason that is one of queued, timeout, unavailable, rate_limited or not_ingested, all worth retrying, or no_preview, which is a property of the account and not worth retrying. Honour retryAfterSeconds rather than tight-looping.

Repeat calls for the same handle join the request you already have rather than starting a second one.

Billing

• Every call costs compute units (CU) from your monthly allowance, at the price listed beside its endpoint above. Plan prices are published at partner.fomoscan.sh (opens in a new tab).
• A miss still costs. A lookup that finds nothing is charged 200 CU.
• A free key reveals wallets for a fixed sample set of accounts and nobody else. The interactive Swagger UI lists them. Those lookups cost nothing. Outside the set, a lookup that would return a wallet answers 403 SAMPLE_SET_ONLY. Profiles without a wallet still answer.
• GET /v2/ws and GET /v2/ws/pump are metered per minute held open rather than per call, from the same credits as your REST calls. Each socket is billed on its own.
• Errors that are FomoScan's fault or your client's fault — 401, 403, 429, 5xx — are never billed.
• Your monthly allowance is a hard cap with no rollover. Once spent, calls return 402 QUOTA_EXCEEDED until the counter resets; topping up lifts that cap immediately. Wallet reveals draw on a separate monthly allowance; past it, reveal calls return 402 REVEAL_LIMIT_REACHED, which top-ups cannot lift. Check remaining units any time with the unbilled GET /v2/me.

{
  "error": { "code": "QUOTA_EXCEEDED", "message": "out of credits - update billing on https://partner.fomoscan.sh" }
}

404 NOT_FOUND

A lookup that finds nothing answers 404 with the code NOT_FOUND. On a handle or id lookup it means FomoScan holds no user under that handle or id. On a wallet lookup it means FomoScan holds no verified link from that address to a trader. It does not mean the subject is unknown to FOMO. Treat it as "no answer today," cache the negative briefly, and ask again later. A user we hold without a verified wallet answers 200 with both addresses null.

Error codes

Every error uses the same shape: { "error": { "code": "...", "message": "..." } }. A 429 additionally carries retryAfter in seconds.

Rate limits

Each key has one per-minute request limit across every endpoint, readable from GET /v2/me as ratePerMinute, set by your plan:

A per-IP burst ceiling sits behind the plan limit as an anti-abuse backstop. Exceeding either returns 429 RATE_LIMITED with a retryAfter.

A thesis page can come back empty the first time a token is asked for. Ask the same endpoint again on your normal interval.