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"

Every successful response uses the same envelope:

{
  "data": { "...": "the answer" },
  "meta": {
    "asOf": "2026-08-19T10:00:00.000Z",
    "requestId": "3f4c9a52-6a7e-4b1d-8f2e-0c1d2e3f4a5b"
  }
}

• meta.asOf — the freshness marker: the data is best observed as of this time.
• meta.requestId — unique per request. Include it if you contact support.

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 feed. Attach, then send one subscribe frame naming either the firehose 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.

• 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 the polling endpoint on connect and reconcile on id after any reconnect.
• The pong is mandatory: we ping every 30 seconds and close a socket that does not answer by the next one.
• Running out of quota closes the socket with code 1008.

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.
• GET /v2/ws is metered per minute held open rather than per call.
• 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_OBSERVED

A 404 does not mean the handle, wallet or token is unknown to fomo.family. It means FomoScan holds no verified link for it — either no proof has ever been observed, or one was observed but did not meet the verification bar. The correct client behaviour is the same either way: treat it as "no answer today," cache the negative briefly, and retry later. Verification is continuous, so a subject that misses now may resolve next week.

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 may return pending the first time it is asked for. Poll the same endpoint on your normal interval.