> ## Documentation Index > Fetch the complete documentation index at: https://docs.fomoscan.sh/llms.txt > Use this file to discover all available pages before exploring further. # Read the PnL of up to 100 wallets > The PnL of up to 100 wallets in one call. `items` follows the order of `wallets`, one item per distinct wallet. - Each item holds the wallet's `wal_` id, `found`, and the document `GET /v3/wallets/{family}/{address}/pnl` returns, or `null` when we never saw the wallet. - Each item costs what `GET /v3/wallets/{family}/{address}/pnl` costs for its answer: the hit price when `ready`, the miss price otherwise and when not found. No reveal. - The whole batch is refused with 402 before any read unless the key holds the hit price for every item. - An unknown wallet is an item with `found: false`. This operation never answers 404. ## Price **Per item**: 500 credits and one reveal for each item whose `status` is `ready`, 200 credits for every other item. Before any work the whole batch is refused when the balance holds less than 200 credits per item (402 `QUOTA_EXCEEDED`), or the key has fewer reveals left this month than items, whatever their status turns out to be. | Answer | Credits | Reveals | | --- | --- | --- | | Each item whose `status` is `ready`. | 500 | 0 | | Each item with another `status`, or a wallet we never saw. | 200 | 0 | | 100 wallets, 60 of them `ready`. | 38,000 | 0 | ## Limits - 120 requests per minute from one address on this operation, beside the per-minute limit of the key. - A key with less than 200 credits left gets 402 `QUOTA_EXCEEDED` before any work. ## OpenAPI ````yaml https://api.fomoscan.sh/v3/openapi.json post /v3/wallets/pnl openapi: 3.1.0 info: title: fomoscan API version: 3.0.0 description: >- Coming from v2 (`https://api.fomoscan.sh/v2`)? The section Moving from v2, at the end of this introduction, maps each v2 route to its v3 operation and price and lists what changed. Social graph, post and wallet data for trading products, in one shape for every platform. Every price is in credit units. ## Objects Every object is an envelope: ```json { "kind": "trader", "id": "tdr_01jbst8pvcfp79y0938nkrkayd", "canonical": { … }, "sources": { "": { "profile": { … } } } } ``` | Field | Meaning | | --- | --- | | `kind` | `trader`, `wallet`, `post`, `trade`, `token`, `group`. The only field to switch on. Skip kinds you do not know. | | `id` | Our id of the object. Store it; see Ids. | | `canonical` | Fields that mean the same on every platform. | | `sources` | Capability blocks keyed by platform. A block has the same shape on every platform that provides it and carries its own `observedAt`. | What `sources` tells you: | On the wire | Meaning | | --- | --- | | `sources.` absent | The object has no side on that platform. | | `sources..` absent | The platform cannot provide the block (`GET /v3/capabilities` lists which can), or we hold no reading of it yet. | | A block field is `null` | The platform left it empty at `observedAt`, or never fills it (`unfilled` in the capability table). | | `{ "status": "unavailable", "retryable": true }` in place of a block | We could not read the block for this call. The rest of the object is current. | PnL, boards, rankings, follow lists, the key and the capability table are documents about a subject. A document holds envelopes wherever a subject appears. ## Ids | Kind | Id | | --- | --- | | `trader` | `tdr_` and 26 lowercase base32 characters | | `wallet` | `wal__
`, family `svm` or `evm` | | `post` | `pst_` and 26 lowercase base32 characters | | `trade` | `trd_` and 26 lowercase base32 characters | | `token` | `tok__
` | | `group` | `grp_` and 26 lowercase base32 characters | - A malformed id or a wrong prefix answers 400 `INVALID_ARGUMENT` before any read. - A platform's own ids never appear in a response. Find a trader once, by handle (`GET /v3/traders/lookup`) or by wallet (`GET /v3/wallets/{family}/{address}`), then keep our id. - An id merged into another trader answers 200 with the trader that absorbed it, whose `canonical.mergedFrom` lists the old id. - List cursors start with `c_`, stream cursors with `s_`. Neither works in the place of the other. ## Money and time - Money and token quantities are `Amount` objects, never JSON numbers. `{ "value": "12345678", "decimals": 6, "currency": "USD" }` is 12.345678 USD. - `value` is an integer in base units, as a string, and negative below zero. Read it with a decimal or big integer type: a float loses digits. - `currency` is `USD`, or the token id of a token quantity (`tok_solana_`). - `priceAsOf` is present when we converted a value with a price, and holds the time of that price. - Ratios (`returnPct`, `multiple`) and counts are JSON numbers. - Times in bodies are RFC3339 in UTC with milliseconds. A time in a query parameter (`at`) is RFC3339 with `Z` or an offset. ## Paging A list answers one page: ```json { "items": [ … ], "hasMore": true, "nextCursor": "c_…" } ``` - Send `nextCursor` back as `cursor` for the next page. Stop when `hasMore` is `false`. - A cursor is opaque and belongs to the query that produced it. Sent with other parameters, it answers 400 `INVALID_ARGUMENT`. - `limit` defaults to 50, at most 200. Post feeds, follow lists and trade lists default to 20, at most 100. - A page boundary inside a tie of the order neither drops nor repeats a row. - The entries of one board or ranking arrive whole, without paging. ## Errors Every error answers the same body: ```json { "error": { "type": "invalid_request", "code": "NOT_FOUND", "message": "Trader not found.", "requestId": "req_…" } } ``` | HTTP | `type` | `code` | When | | --- | --- | --- | --- | | 400 | `invalid_request` | `INVALID_ARGUMENT` | A parameter, id, cursor or body is malformed, or the operation does not take it. | | 401 | `authentication` | `UNAUTHENTICATED` | No key, or the key is unknown, revoked or expired. | | 402 | `quota` | `QUOTA_EXCEEDED` | The credit balance cannot pay for the call. | | 402 | `quota` | `REVEAL_LIMIT_REACHED` | The answer needs a reveal and the key has used every reveal this month. | | 403 | `permission` | `PERMISSION_DENIED` | The key may not make the call: it has no REST scope, its plan is switched off, or a free key asked for a reveal. | | 403 | `permission` | `PLAN_REQUIRED` | The plan of the key does not include the stream. REST calls never answer it. | | 404 | `invalid_request` | `NOT_FOUND` | The subject of the call does not exist, or no route has this method and path. | | 429 | `rate_limit` | `RATE_LIMITED` | Too many requests from the key or the address. Wait `Retry-After` seconds. | | 500 | `internal` | `INTERNAL` | The call failed on our side. Retry with backoff, and quote `requestId` if it repeats. | | 503 | `overloaded` | `OVERLOADED` | The API holds too many requests at once. Wait `Retry-After` seconds. | - Act on `code`. `message` is for people and can change. - 429 and 503 carry `Retry-After` in seconds. - A query parameter the operation does not list answers 400. ## Requests - Send the key in `Authorization: Bearer ` or in `X-Api-Key: `. A key in the query string does not count. - Every response carries `X-Request-Id`, the id of the request in our logs. Quote it when you write to us. - Every response carries `Cache-Control: private, no-store`. - A request body is JSON sent with `Content-Type: application/json`. A body with another content type, or with none, answers 400. - `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` report the per-minute window of the key. A key without a limit gets none of them. ## Compatibility - Inside v3 every change is additive: a new optional field, kind, platform key or block. Skip what you do not know. - Removing, renaming or retyping a field needs a new major version. ## Servers REST calls go to `https://api.fomoscan.sh`. The stream lives on its own host; see the WebSocket section. ## Credits and reveals - A call that answers takes the credits of the table below from the key's monthly balance; a `free` operation takes none. `GET /v3/me` shows the balance. - A refusal (400, 401, 402, 403, 429, 503) costs nothing. A 404 costs what the operation's Price table says. - A reveal is one unit of the key's monthly reveal allowance. Operations that show who owns a wallet or what a person earned take them, as the Reveals column says. - A metered key that cannot pay for an answer gets 402 `QUOTA_EXCEEDED` in its place. It is never charged past its balance. - Each operation lists its prices in full under Price. | Operation | Credits | Reveals | | --- | --- | --- | | `GET /v3/traders/{traderId}` | 100 hit, 200 miss | none | | `GET /v3/traders/lookup` | 100 hit, 200 miss | none | | `GET /v3/wallets/{family}/{address}` | 30,000 hit, 200 miss, 10 flat | one per hit | | `GET /v3/traders/{traderId}/wallets` | 100 hit, 200 miss | one when the page lists a wallet | | `GET /v3/traders/{traderId}/pnl` | 30,000 hit, 200 miss | one per hit | | `POST /v3/traders/pnl` | 30,000 per `ready` item, 200 per other item | one per `ready` item | | `GET /v3/posts` | 200 per started 20 rows of `limit`; 10 flat with `platform=pump` | none | | `GET /v3/tokens/{network}/{address}/posts` | 200 per started 20 rows of `limit`; 10 flat with `platform=pump` | none | | `GET /v3/traders/{traderId}/posts` | 200 per started 20 rows of `limit`; 10 flat with `platform=pump` | none | | `GET /v3/tokens/{network}/{address}` | 100 hit, 100 miss | none | | `GET /v3/leaderboards` | free | none | | `GET /v3/leaderboards/{platform}/{board}` | 500 hit, 200 miss, 10 flat | none | | `GET /v3/rankings` | free | none | | `GET /v3/rankings/{key}` | 500 hit, 200 miss | none | | `GET /v3/me` | free | none | | `GET /v3/capabilities` | free | none | | `GET /v3` (WebSocket) | 20,000 per started minute per connection | none | | `GET /v3/traders/{traderId}/followers` | 200 per started 20 rows of `limit` | none | | `GET /v3/traders/{traderId}/following` | 200 per started 20 rows of `limit` | none | | `GET /v3/trades` | 200 per started 20 rows of `limit`, plus 100 per trader shown | one per trader shown | | `GET /v3/traders/{traderId}/trades` | 200 per started 20 rows of `limit`, plus 100 per trader shown | one per trader shown | | `GET /v3/wallets/{family}/{address}/trades` | 200 per started 20 rows of `limit` | none | | `GET /v3/wallets/{family}/{address}/pnl` | 500 hit, 200 miss | none | | `POST /v3/wallets/pnl` | 500 per `ready` item, 200 per other item | none | ## Rate limits | Limit | Value | Past it | | --- | --- | --- | | Per key | The key's `ratePerMinute` (`GET /v3/me`), reported in the `RateLimit-*` headers. | 429 `RATE_LIMITED` with `Retry-After`. | | Per address, before the key is checked | 2,400 requests per minute. | 429 `RATE_LIMITED` with `Retry-After`. | | Per address and operation | Requests per minute: 2,000 on most operations; 120 on `POST /v3/traders/pnl`; 120 on `GET /v3/me`; 120 on `POST /v3/wallets/pnl`; 600 on `GET /v3/leaderboards/{platform}/{board}`; 600 on `GET /v3/rankings/{key}`. | 429 `RATE_LIMITED` with `Retry-After`. | | Requests in flight at once on one API instance, across every key | 30 requests. | 503 `OVERLOADED` with `Retry-After: 1`, before the key is checked. | | Requests in flight at once on one API instance, for one key and the keys under it | 15 requests. | 429 `RATE_LIMITED` with `Retry-After: 1`, after the key is checked. | A refused request costs nothing. Retry after the seconds in `Retry-After`. ## Live posts Live posts arrive over one WebSocket on the stream host. The WebSocket section at the end of this page says how to connect, what it costs and how to behave on it. ## Moving from v2 v2 (`https://api.fomoscan.sh/v2`) and v3 take the same key and spend from the same balance. Most v3 operations cost what the v2 route they replace costs; the table under Routes and prices lists both. ### At a glance | | v2 | v3 | | --- | --- | --- | | REST | `https://api.fomoscan.sh/v2/…` | `https://api.fomoscan.sh/v3/…` | | Reference | `https://api.fomoscan.sh/docs`, `https://docs.fomoscan.sh` | `https://api.fomoscan.sh/v3/docs`, `https://api.fomoscan.sh/v3/openapi.json` | | Stream | `wss://api.fomoscan.sh/v2/ws`, `wss://api.fomoscan.sh/v2/ws/pump` | `wss://stream.fomoscan.sh/v3`, one socket for every platform | | Key | `fsk_live_…`, `fsk_test_…` | the same key | | Headers | `Authorization: Bearer ` or `X-Api-Key: ` | the same; a key in the query string does not count | | Answers | flat JSON records, USD as numbers, epoch milliseconds | envelopes and documents, money as integer strings, RFC3339 times | ### Keys, plans and credits - Your v2 key works on v3. A v3 call spends from the monthly credits, top-up and reveal cap a v2 call spends from, so `GET /v2/me` and `GET /v3/me` report one balance. - Scopes are the v2 scopes: `basic` covers REST and the stream, `http:read` REST only and `live:read` the stream only. - The stream takes the plans it takes on v2; the WebSocket section lists them. - A key on a free plan (`pilot` or `explore`) without reveals gets 403 `PERMISSION_DENIED` for every answer that takes a reveal. v2 let such keys reveal a fixed sample of handles and wallets; v3 has no sample set. - A refusal (400, 401, 402, 403, 429, 503) costs nothing. A 404 costs the operation's miss price, as on v2. ### Routes and prices Credits per call. A reveal is one unit of the key's monthly reveal cap. Each v3 operation lists every answer and its price under Price. | v2 | v2 credits | v3 | v3 credits | | --- | --- | --- | --- | | `GET /v2/user/handle/{handle}` | 100 and a reveal when a wallet is returned; 200 not found | `GET /v3/traders/lookup?handle=`, then `GET /v3/traders/{traderId}/wallets` | 100, 200 with no match; then 100, and a reveal when the page lists a wallet | | `GET /v2/user/handle/{handle}/profile` | 100; 200 not found | `GET /v3/traders/lookup?handle=` | 100; 200 with no match | | `GET /v2/user/id/{id}`, `GET /v2/user/id/{id}/profile` | 100; 200 not found | not in v3 yet | | | `GET /v2/user/wallet/{address}`, `GET /v2/pump/user/wallet/{wallet}` | 30,000 and a reveal, 200 not found; the `/v2/pump/` route 10 | `GET /v3/wallets/{family}/{address}` | 30,000 and a reveal; 10 when every owner holds tier `account`; 200 without an owner | | `POST /v2/user/handle/{handle}/resolve` | 30,000 and a reveal; 200 on a 202 or 404 | `GET /v3/traders/{traderId}/wallets`, stored wallets only | 100, and a reveal when the page lists a wallet; 200 for an unknown trader | | `GET /v2/user/handle/{handle}/pnl` | 30,000 and a reveal when `ready`; 200 otherwise | `GET /v3/traders/{traderId}/pnl` | 30,000 and a reveal when `ready`; 200 otherwise | | `POST /v2/user/handles/pnl` | per handle: 30,000 and a reveal when `ready`, 200 otherwise | `POST /v3/traders/pnl` | per id: 30,000 and a reveal when `ready`, 200 otherwise | | `GET /v2/pump/user/wallet/{wallet}/pnl` | 500 when `ready`; 200 otherwise | `GET /v3/wallets/svm/{address}/pnl` | 500 when `ready`; 200 otherwise | | `POST /v2/pump/user/wallets/pnl` | per wallet: 500 when `ready`, 200 otherwise | `POST /v3/wallets/pnl` | per wallet: 500 when `ready`, 200 otherwise | | `GET /v2/user/handle/{handle}/holdings`, `POST /v2/user/handles/holdings` | 2,500; 1,250 per handle; allow-listed keys only | allow-listed keys only; v3 keeps its own list | 2,500; 1,250 per trader | | `GET /v2/pump/user/wallet/{wallet}/holdings`, `POST /v2/pump/user/wallets/holdings` | 500 per wallet; allow-listed keys only | not in v3 yet | | | `GET /v2/thesis` | 200 per started 20 rows of `limit` | `GET /v3/posts` | 200 per started 20 rows of `limit` | | `GET /v2/thesis/token/{tokenAddress}` | 200 per started 20 rows of `limit` | `GET /v3/tokens/{network}/{address}/posts` | 200 per started 20 rows of `limit` | | `GET /v2/thesis/user/{id}`, `GET /v2/thesis/user/{id}/token/{tokenAddress}` | 200 per started 20 rows of `limit` | `GET /v3/traders/{traderId}/posts`, with `token=tok_…` for one token | 200 per started 20 rows of `limit`; 200 for an unknown trader | | `GET /v2/pump/thesis` | 10 for a page of 25 | `GET /v3/posts?platform=pump` | 10 for a page of up to 100 | | `GET /v2/pump/thesis/token/{mint}` | 10 for a page of 25 | `GET /v3/tokens/solana/{address}/posts?platform=pump` | 10 for a page of up to 100 | | `GET /v2/pump/thesis/wallet/{wallet}` | 10 for a page of 25 | `GET /v3/wallets/{family}/{address}` once, then `GET /v3/traders/{traderId}/posts?platform=pump` | the wallet lookup once, then 10 for a page of up to 100 | | `GET /v2/token/{address}` | 100; 200 not found | `GET /v3/tokens/{network}/{address}` | 100; 100 not found | | `GET /v2/leaderboard/traders`, `GET /v2/leaderboard/clans` | 500 | `GET /v3/leaderboards/fomo/traders`, `GET /v3/leaderboards/fomo/clans` | 500; 200 without a capture | | `GET /v2/leaderboard/tokens/most-held`, `GET /v2/leaderboard/tokens/trending`, `GET /v2/leaderboard/tokens/graduated` | 10 | `GET /v3/leaderboards/fomo/tokens_most_held`, `GET /v3/leaderboards/fomo/tokens_trending`, `GET /v3/leaderboards/fomo/tokens_graduated` | 10 | | `GET /v2/pump/leaderboard/traders` | 10 | `GET /v3/leaderboards/pump/traders` | 10 | | `GET /v2/leaderboard/traders-fomoscan` | 500 | `GET /v3/rankings/traders_net_flow_` | 500; 200 without a snapshot | | `GET /v2/me` | free | `GET /v3/me` | free | | `GET /v2/ws`, `GET /v2/ws/pump` | 20,000 per minute per socket | `wss://stream.fomoscan.sh/v3` | 20,000 per started minute per connection | | `POST /v2/user/handle/{handle}/reveal`, `GET /v2/stats/…` | used by the v2 MCP server | not in v3 yet | | | `GET /feed/trades` | not metered | `GET /v3/trades` | 200 per started 20 rows of `limit`, plus 100 and a reveal per trader the page shows | | `GET /feed/trader/{handle}` | not metered | `GET /v3/traders/lookup?handle=`, then `GET /v3/traders/{traderId}`, `GET /v3/traders/{traderId}/wallets` and `GET /v3/traders/{traderId}/trades` | each at its own price | | `GET /get-followers/{handle}`, `GET /get-following/{handle}` | not metered | `GET /v3/traders/{traderId}/followers`, `GET /v3/traders/{traderId}/following` | 200 per started 20 rows of `limit` | | `GET /get-user/{handle}`, `GET /get-user-by-id/{id}`, `GET /search` | not metered | `GET /v3/traders/lookup?handle=` for a whole handle; nothing for an id or a prefix | 100; 200 with no match | New in v3, with no v2 route: - `GET /v3/traders/{traderId}`: 100; 200 for an unknown id. - `GET /v3/leaderboards`: free. - `GET /v3/rankings`: free. - `GET /v3/capabilities`: free. - `GET /v3/traders/{traderId}/trades`: 200 per started 20 rows of `limit`, plus 100 and a reveal per trader the page shows. - `GET /v3/wallets/{family}/{address}/trades`: 200 per started 20 rows of `limit`. ### Ids and lookups - v3 never returns a platform's own id, such as v2's `id` and `authorId`. Every object carries our id, in the forms the Ids section at the top lists. - v3 has no lookup by a v2 `id`. Find each trader once by handle (`GET /v3/traders/lookup`) or by wallet (`GET /v3/wallets/{family}/{address}`), store the `tdr_` id, and call by it from then on: ```bash curl -s -H "Authorization: Bearer $KEY" "https://api.fomoscan.sh/v3/traders/lookup?handle=tradername" curl -s -H "Authorization: Bearer $KEY" "https://api.fomoscan.sh/v3/traders/tdr_01jbst8pvcfp79y0938nkrkayd/wallets" ``` ```json { "items": [ { "kind": "trader", "id": "tdr_01jbst8pvcfp79y0938nkrkayd", "canonical": { … }, "sources": { … } } ], "hasMore": false, "nextCursor": null } ``` - A handle can match traders on several platforms. The lookup lists current handles first, then handles an account held in the last 30 days; `platform=` narrows it to one platform. - A trader merged into another answers 200 with the trader that absorbed it, and `canonical.mergedFrom` lists the old id. Store the id you get back. - Wallet paths name the address family: `/v2/user/wallet/{address}` is `/v3/wallets/svm/{address}` or `/v3/wallets/evm/{address}`. EVM addresses come back lowercase. - Token paths and ids name the network: `/v3/tokens/{network}/{address}`, `tok__
`, with `network` one of `solana`, `ethereum`, `base`, `bsc`, `arbitrum`, `optimism`, `polygon`, `robinhood`, `hyperevm`, `monad`, `arc`, `xlayer`, `ink` or `hyperliquid`. v2 inferred the chain from the address. ### Answers - Every object is an envelope (`kind`, `id`, `canonical`, `sources`); the Objects section at the top explains it. PnL, boards, rankings and the key are documents that hold envelopes. - Money: v2 sent USD as JSON numbers (`"netUsd": 1430.12`). v3 sends an `Amount`: `{ "value": "1430120000", "decimals": 6, "currency": "USD" }`. Read `value` as a big integer or decimal and shift it by `decimals`; a float loses digits. Token prices carry 18 decimals. - Time: v2 sent and took epoch milliseconds (`fomoCreatedAt`, `updatedAt`, `capturedAt`, `?at=`). v3 sends RFC3339 in UTC with milliseconds (`2026-11-02T09:30:00.000Z`) and takes RFC3339 in `at`; epoch milliseconds in `at` answer 400. - Nulls: v2 used `null` for a missing value. v3 tells four cases apart: no `sources.` key (no side on that platform), no block (the platform cannot provide it, or we hold no reading), a `null` field (empty when observed), and `{ "status": "unavailable", "retryable": true }` in place of a block (we could not read it for this call). - Paging: v2 pages took `before=` and answered `count`, `hasMore`, `nextBefore`. v3 lists answer `{ "items", "hasMore", "nextCursor" }`; send `nextCursor` back as `cursor`. A cursor works only with the parameters that produced it. Post feeds keep `limit` from 1 to 100, 20 by default. - v2 ignored a query parameter it did not know. v3 answers 400 `INVALID_ARGUMENT`. `HEAD` answers 404. ### Errors v2: `{ "error": { "code", "message", "retryAfter" } }`. v3: `{ "error": { "type", "code", "message", "requestId" } }`, with `X-Request-Id` on every response and `Retry-After` on 429 and 503. | v2 | v3 | | --- | --- | | 400 `VALIDATION_ERROR` | `INVALID_ARGUMENT` | | 401 `UNAUTHORIZED` | `UNAUTHENTICATED` | | 402 `QUOTA_EXCEEDED`, `REVEAL_LIMIT_REACHED` | the same codes | | 403 `FORBIDDEN_SCOPE`, `FREE_TIER_DISABLED`, `SAMPLE_SET_ONLY`, `FORBIDDEN` | `PERMISSION_DENIED` | | 403 `WEBSOCKET_PLAN_REQUIRED` | `PLAN_REQUIRED` | | 404 `NOT_FOUND` | `NOT_FOUND` | | 429 `RATE_LIMITED`, `retryAfter` in the body | `RATE_LIMITED`, `Retry-After` header | | 500 `INTERNAL_ERROR` | `INTERNAL` | | 503 `OVERLOADED`, `B2B_DISABLED`, `DATA_UNAVAILABLE`; 504 `TIMEOUT` | 503 `OVERLOADED`, `Retry-After` header | | 202 `{ "pending": true }` from resolve | none | ### Fields #### User record - `id` (the platform user id): none. Use the trader `id` (`tdr_`). - `handle`, `name`, `bio`, `profilePicture`: `handle`, `name`, `bio`, `avatarUrl` of the `profile` block in `sources.`. `canonical.display` repeats the newest of them. - `twitter` (a URL): `profile.xHandle`, the handle without `@`. - `followers`, `following`: the `followGraph` block. - `solanaAddress`, `evmAddress`: `GET /v3/traders/{traderId}/wallets`, wallet envelopes with `canonical.family`, `canonical.address` and the `tier` of each owner. - Handle suggestions: a missed lookup answers `suggestions`; `match=closest` answers the closest trader. Prefixes match through suggestions; there is no `/search`. - `walletAvailable`: `canonical.walletAvailable` on `GET /v3/traders/{traderId}` and `GET /v3/traders/lookup`, at no extra price and without a reveal. - `banner`, `isPumpUser`, `groupBadges`: none. - Wallet lookup: v2 answered one user record with the wallet on the other chain. `GET /v3/wallets/{family}/{address}` answers the wallet with every owner and a `tier` each (`proven`, `account`, `partial`, `weak`, `unverified`); `GET /v3/traders/{traderId}` reads an owner. #### PnL - The path takes the `tdr_` id in place of the handle. The batch body takes `traderIds` in place of `handles` and answers `{ "items": [ { "trader", "found", "pnl" } ] }` in request order, in place of `count`, `missing` and `entries`. - `status` `no-wallet` is `no_wallet`. - `wallet`, `evmWallet`: `wallets`, a list of `wal_` ids, filled only when `status` is `ready`. - `handle`, `displayName`, `avatarUrl`, `twitter`, `followers`: none. Read the trader. - In each window: `netUsd` is `realized`, `volumeUsd` is `volume`, `buyVolumeUsd` and `sellVolumeUsd` are `buyVolume` and `sellVolume`, `trades` is `tradeCount`, `updatedAt` is `asOf`, and `rank` is `{ "position", "of", "ranking" }`. `origin` says where the figures come from: `provider` on `24h`, `7d` and `30d`, `computed` on `all`. - `unrealized.unrealizedPnlUsd` and `holdingsUsd` are `unrealized.value` and `holdingsValue`. - Per window, `unrealizedPnlUsd` and `totalPnlUsd` are `unrealized` and `total`; `approximate`, `stale` and `nextUpdateAt` keep their v2 names. - Wallet PnL (`GET /v3/wallets/{family}/{address}/pnl`) lists the paired wallet of the other family in `wallets`; `boards` replaces `pumpBoard`. `POST /v3/wallets/pnl` takes up to 100 wallets. - `all` holds the net flow and rank we compute from our trades. v2 mixed cash flow with whole-wallet figures since 1 January 2025. - `window` (new) narrows `windows` to one key at the same price. #### Posts Theses, callouts and stream items are one kind, `post`: - `thesis`: `canonical.body`. `segments`: `canonical.segments`, each `{ "text", "url" }`. - `tokenAddress` and `tokenNetwork`, callout `coinMint` and `chain`: `canonical.token.id` (`tok__
`). `tokenSymbol`, `coinSymbol`: `canonical.token.symbol`. - `authorId` and `authorHandle`, callout `wallet` and `userName`: `canonical.author.trader` and `canonical.author.handle`. - `fomoCreatedAt`, callout `createdAt`: `canonical.postedAt`. `firstSeenAt` (new) is when we first read the post. - `likeCount`, `likes`: `canonical.likeCount`. `commentCount`, `replyCount`, `viewCount`: the `engagement` block. - `holdingsUsd`, `tokenAmount`, `authorTradeUsd`, `realizedPnlUsd`, `unrealizedPnlUsd`, `pnl`, `closedAt`, callout `position`: the `position` block (`value`, `quantity`, `invested`, `realizedPnl`, `unrealizedPnl`, `totalPnl`, `closed`, `closedAt`). - `calledOutAtMcap`, `multiple`, `maxMultiplier`, `mediaUrl`: the `callPerformance` block (`marketCapAtCall`, `multiple`, `maxMultiple`, `mediaUrl`). - Thesis `priceUsdAtPost` and `marketCapAtPost`: `callPerformance.priceAtCall` and `callPerformance.marketCapAtCall`. - `thesisHash`: none. Key on `id`. #### Tokens - `GET /v2/token/{address}`: `GET /v3/tokens/{network}/{address}`. The `market` block per platform carries `price`, `marketCap`, `liquidity`, `volume24h`, `holders` and `priceChange24h` (percent). A token without platform market data is read live, as on v2, into `canonical.market`. #### Boards and rankings - `/v2/leaderboard/` and `/v2/pump/leaderboard/traders` are `/v3/leaderboards/{platform}/{board}`; `GET /v3/leaderboards` lists every board with its windows. - `window` stays. `period` `daily`, `weekly`, `monthly` is `window` `24h`, `7d`, `30d`. `at` takes RFC3339 in place of epoch milliseconds. - `count` is `entryCount`. An entry is `{ "rank", "subject", "measures" }`: `subject` is the trader, token or group envelope in place of `id`, `handle`, `label` and `avatarUrl`. `measures` holds the figures under snake-case keys, money as amounts: `marketCap` is `market_cap`, `numTrades` is `trade_count`, `memberCount` is `members`. - `/v2/leaderboard/traders-fomoscan?window=&order=` is `/v3/rankings/traders_net_flow_?order=`. Tied traders share a rank, and `order=worst` answers the bottom entries with their own ranks, where v2 numbered them from 1. #### Account - `GET /v3/me` moves `entitlement` and `usage` into `api`: `monthlyUnits`, `additionalUnits`, `unitsUsed`, `unitsRemaining`, `ratePerMinute`, `monthlyReveals`, `revealsUsed`, `revealsRemaining`, `unmetered`. Stream minutes count in `api.unitsUsed`. ### Limits and refusals | | v2 | v3 | | --- | --- | --- | | Per key | `ratePerMinute`, a fixed minute | the same `ratePerMinute` | | Per address, before the key | 2,400 per minute | 2,400 per minute | | Per address and route, per minute | 2,000 by default; 600 on boards; 120 on `/v2/me` and batches; 10 on resolve | 2,000 by default; 120 on `POST /v3/traders/pnl`, `GET /v3/me` and `POST /v3/wallets/pnl`; 600 on `GET /v3/leaderboards/{platform}/{board}` and `GET /v3/rankings/{key}` | | Headers | `x-ratelimit-*` for the route limit | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` for the key | | 429 | `retryAfter` in the body | `Retry-After` header | | Load | 503 `OVERLOADED` | 503 `OVERLOADED` with `Retry-After: 1` past 30 requests in flight on one API instance, before the key is checked | | Requests in flight per key | none | 429 `RATE_LIMITED` with `Retry-After: 1` past 15 requests in flight for one key and its child keys on one API instance | - A 429 or a 503 costs nothing. Retry after the seconds in `Retry-After`. - A reveal that waits more than 2 seconds on the reveal lock of the key answers 429 with `Retry-After: 1`, as on v2. ### Stream | | v2 | v3 | | --- | --- | --- | | URL | `wss://api.fomoscan.sh/v2/ws` (theses), `wss://api.fomoscan.sh/v2/ws/pump` (callouts) | `wss://stream.fomoscan.sh/v3`, every platform on one socket | | Key | `Authorization: Bearer` or `X-Api-Key` on the upgrade | the same; a refusal is an HTTP status: 401, 402, 403 `PERMISSION_DENIED` (scope), 403 `PLAN_REQUIRED`, 429 | | Subscribe | `{ "type": "subscribe", "subscription": { "type": "all" } }` | `{ "type": "subscribe", "topic": "posts" }` | | Tokens | `"subscription": { "type": "tokens", "tokens": ["
"] }`, up to 50 | `"tokens": ["tok_solana_"]`, up to 50 | | Platforms | one socket per feed | `"platforms": [ … ]`, every platform when left out | | Acknowledgement | `replaced`, then `subscription` | one `subscribed` frame that carries `subscription` and `replaced` | | Items | `thesis` with `data`, `pump_callout` with `callout` | `post` with `cursor` and `item`, the envelope `GET /v3/posts` returns | | Errors | `error` with a string | `error` with `{ "type", "code", "message", "requestId" }` | | Replay | none | `"since": "s_…"` replays the last 5 minutes, then `replay_done` | | Heartbeat | ping every 30 s, close 1011 after 90 s of silence | the same | | Subscribe rate | no limit | 10 `subscribe` or `unsubscribe` frames per 60 s | | Price | 20,000 credits per minute, per socket | 20,000 credits per started minute per connection, charged on connect and every 60 s, subscribed or not | ```json {"type":"subscribe","topic":"posts","platforms":["fomo","pump"],"tokens":["tok_solana_"],"since":"s_…"} ``` - Close codes: 1001 we restart; 1008 no credit for the next minute, or the key lost access; 1009 a frame over 64 KB; 1011 no pong, or billing failed twice in a row; 1013 8 MB of frames wait unread, or frames arrive faster than we handle them. - One socket carries every platform, so a client of both v2 sockets pays one minute where v2 charged two. - A v2 frame sent to v3 answers an `INVALID_ARGUMENT` error frame and changes nothing. - v3 sends each post once, when it first becomes visible to us. `postedAt` gives its age. - Reconnect with `since` set to the last `cursor` you handled. The WebSocket section at the end of this page holds every frame, error code and a reconnect recipe. ### Not in v3 yet - Lookup by a v2 `id`: `GET /v2/user/id/{id}`, `GET /v2/user/id/{id}/profile`, and author feeds keyed on that id. - Reads on demand: v2 fetched the theses of a token it had not read during the call. `GET /v3/tokens/{network}/{address}/posts` answers an empty page. - Author name, author avatar and token image on each post (`authorName`, `authorAvatarUrl`, `tokenImageUrl`, callout `profileImage`). Read the author and the token by id. - Percentages and cost basis of the author's position: `percentageRealizedPnl`, `percentageUnrealizedPnl`, callout `pnlPercentage`, `avgEntryPriceUsd`, `avgEntryMcapUsd`, `costBasisAmount`, `amountBought`. - Wallet holdings with cost basis from the buy history: `GET /v2/pump/user/wallet/{wallet}/holdings`, `POST /v2/pump/user/wallets/holdings`. - Live resolve: `POST /v2/user/handle/{handle}/resolve` and its 202. v3 answers from stored data. - The stats and open holdings of the `GET /feed/trader/{handle}` card. - MCP: the v2 MCP server, its `GET /v2/stats/…` reads and `POST /v2/user/handle/{handle}/reveal`. servers: - url: https://api.fomoscan.sh description: The API host security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: Traders - name: Wallets - name: Posts - name: Tokens - name: Leaderboards - name: Rankings - name: Account - name: Trades - name: WebSocket description: >- The live stream: one socket for every platform, platform and token filters, and a replay of the last 5 minutes. paths: /v3/wallets/pnl: post: tags: - Wallets summary: Read the PnL of up to 100 wallets description: >- The PnL of up to 100 wallets in one call. `items` follows the order of `wallets`, one item per distinct wallet. - Each item holds the wallet's `wal_` id, `found`, and the document `GET /v3/wallets/{family}/{address}/pnl` returns, or `null` when we never saw the wallet. - Each item costs what `GET /v3/wallets/{family}/{address}/pnl` costs for its answer: the hit price when `ready`, the miss price otherwise and when not found. No reveal. - The whole batch is refused with 402 before any read unless the key holds the hit price for every item. - An unknown wallet is an item with `found: false`. This operation never answers 404. ## Price **Per item**: 500 credits and one reveal for each item whose `status` is `ready`, 200 credits for every other item. Before any work the whole batch is refused when the balance holds less than 200 credits per item (402 `QUOTA_EXCEEDED`), or the key has fewer reveals left this month than items, whatever their status turns out to be. | Answer | Credits | Reveals | | --- | --- | --- | | Each item whose `status` is `ready`. | 500 | 0 | | Each item with another `status`, or a wallet we never saw. | 200 | 0 | | 100 wallets, 60 of them `ready`. | 38,000 | 0 | ## Limits - 120 requests per minute from one address on this operation, beside the per-minute limit of the key. - A key with less than 200 credits left gets 402 `QUOTA_EXCEEDED` before any work. operationId: bulkWalletPnl parameters: [] requestBody: required: true content: application/json: schema: type: object properties: wallets: minItems: 1 maxItems: 100 type: array items: type: object properties: family: type: string enum: - svm - evm description: >- The address family: `svm` for Solana, `evm` for EVM networks. address: type: string minLength: 1 maxLength: 128 description: >- The wallet address. An EVM address matches in any letter case. required: - family - address additionalProperties: false description: >- 1 to 100 wallets. A wallet repeated, in any letter case for EVM, counts once. window: description: >- One window: `24h`, `7d`, `30d` or `all`. Leave it out for all four. `status` stays the same either way. type: string enum: - 24h - 7d - 30d - all required: - wallets additionalProperties: false responses: '200': description: OK headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/WalletPnlBulk' example: items: - wallet: wal_svm_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM found: true pnl: wallet: wal_svm_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM wallets: - wal_svm_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM - wal_evm_0x52908400098527886e0f7030069857d2e4169ee7 status: ready retryAfterSeconds: null windows: 7d: origin: provider status: ready realized: value: '-312750000' decimals: 6 currency: USD unrealized: value: '1506900000' decimals: 6 currency: USD total: value: '1194150000' decimals: 6 currency: USD unpricedProceeds: null netFlow: null volume: value: '80160000000' decimals: 6 currency: USD buyVolume: value: '41200000000' decimals: 6 currency: USD sellVolume: value: '38960000000' decimals: 6 currency: USD returnPct: -0.79635371 tradeCount: 105 buys: 58 sells: 47 tokensTraded: 19 winningTokens: 8 rank: null asOf: '2026-11-01T08:55:00.000Z' approximate: false unrealized: origin: provider value: value: '2318400000' decimals: 6 currency: USD holdingsValue: value: '11904650000' decimals: 6 currency: USD positions: 9 excludedPositions: 2 asOf: '2026-11-01T08:55:00.000Z' asOf: '2026-11-01T08:55:00.000Z' nextUpdateAt: '2026-11-01T11:55:00.000Z' stale: false boards: - platform: fomo board: traders window: 7d rank: 14 measures: pnl: value: '8421300000' decimals: 6 currency: USD capturedAt: '2026-11-01T08:30:00.000Z' - wallet: wal_svm_11111111111111111111111111111112 found: false pnl: null '400': description: >- `INVALID_ARGUMENT`: a parameter, an id, a cursor or the body is malformed, or the operation does not take it. - `wallets` is empty, holds more than 100 wallets, or holds an address that is not valid for its `family`. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '401': description: >- `UNAUTHENTICATED`: no key, or the key is unknown, revoked or expired. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '402': description: '`QUOTA_EXCEEDED`: the credit balance cannot pay for the call.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '403': description: '`PERMISSION_DENIED`: the key may not make this call.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '429': description: >- `RATE_LIMITED`: too many requests. Retry after the seconds in `Retry-After`. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '500': description: '`INTERNAL`: the call failed on our side.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '503': description: >- `OVERLOADED`: the API holds too many requests at once. Retry after the seconds in `Retry-After`. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' components: headers: X-Request-Id: description: The id of this request, as in our logs. schema: type: string RateLimit-Limit: description: Requests per minute allowed for the key. schema: type: integer minimum: 0 RateLimit-Remaining: description: Requests left in the current minute. schema: type: integer minimum: 0 RateLimit-Reset: description: Seconds until the current minute ends. schema: type: integer minimum: 0 schemas: WalletPnlBulk: type: object properties: items: type: array items: type: object properties: wallet: type: string description: The `wal_` id of the wallet you sent, normalized. found: type: boolean description: '`false` when we never saw this wallet.' pnl: anyOf: - $ref: '#/components/schemas/WalletPnlDocument' - type: 'null' description: The wallet PnL document, or `null` when not found. required: - wallet - found - pnl description: One item per distinct wallet you sent, in your order. required: - items description: The PnL of several wallets, one item per wallet. ErrorBody: type: object properties: error: type: object properties: type: type: string enum: - invalid_request - authentication - quota - permission - rate_limit - internal - overloaded description: The group of the error. Each `code` belongs to one type. code: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - QUOTA_EXCEEDED - REVEAL_LIMIT_REACHED - PERMISSION_DENIED - PLAN_REQUIRED - NOT_FOUND - RATE_LIMITED - INTERNAL - OVERLOADED description: What went wrong, from a closed list. Act on this field. message: type: string description: A sentence for people. It can change; never parse it. requestId: type: string description: >- The id of the request, equal to `X-Request-Id`. Quote it when you write to us. required: - type - code - message - requestId description: The error. required: - error description: The body of every error answer. WalletPnlDocument: type: object properties: wallet: type: string description: The `wal_` id of the wallet asked for. wallets: type: array items: type: string description: >- The `wal_` ids the figures cover, one per address family, Solana first: the wallet asked for and, when a platform keys it to an account of one trader, the wallet of the other family the same trader holds as an account key on that platform. Listed whatever the status. status: type: string enum: - ready - pending - failed - unavailable description: >- `ready`: figures present. `pending`: no reading yet; call again after `retryAfterSeconds`. `failed`: the last read failed; call again after `retryAfterSeconds`. `unavailable`: provider reads are off or this month's provider budget is spent. retryAfterSeconds: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Seconds to wait before you ask again while `status` is `pending` or `failed`; else `null`. windows: type: object properties: 24h: description: The last 24 hours, from our data provider. type: object properties: origin: type: string enum: - computed - provider description: >- `provider`: figures of the whole wallets from our data provider, every venue. `computed`: our figures from the trades and rankings we compute. status: type: string enum: - ready - pending description: >- `ready`: the values hold a reading. `pending`: no reading yet, and every value is `null`. realized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss taken by selling, in USD. `null` when not known. unrealized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss on tokens still held, in USD. On `24h`, `7d` and `30d`: the open positions last traded inside the window, on UTC calendar days (`24h` from 00:00 UTC today, `7d` and `30d` from 00:00 UTC 6 and 29 days before), from the reading of the top `unrealized`, which leaves out the same positions. On `all`: our own figure from the trades we hold, on a wallet. `null` when not known, and on the `all` of a trader. total: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- `realized` plus `unrealized`, in USD: one formula on every window. `null` when either is `null`. unpricedProceeds: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Proceeds of tokens sold beyond the position we saw them buy, in USD. `null` when not known. netFlow: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- USD received from sells minus USD paid for buys, in USD. `null` when not known. volume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: Buy volume plus sell volume, in USD. `null` when not known. buyVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD paid for buys, in USD. `null` when not known. sellVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD received from sells, in USD. `null` when not known. returnPct: description: >- Return in percent, rounded to 8 decimals: 10 means a 10 % gain. `null` when the base is zero or not known. type: - number - 'null' tradeCount: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Trades in the window. `null` when not known. buys: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Buys in the window. `null` when not known. sells: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Sells in the window. `null` when not known. tokensTraded: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Distinct tokens traded in the window. `null` when not known. winningTokens: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Tokens closed at a profit in the window. `null` when not known. rank: anyOf: - type: object properties: position: type: integer minimum: 1 maximum: 9007199254740991 description: >- 1 plus the number of subjects with a higher value. Ties share a position. of: type: integer minimum: 1 maximum: 9007199254740991 description: Subjects in the ranking. ranking: type: string description: The ranking key, for `GET /v3/rankings/{key}`. required: - position - of - ranking - type: 'null' description: >- Where the trader stands in our ranking for this window. Set on a trader's `all`; `null` on the other windows and on a wallet. asOf: anyOf: - $ref: '#/components/schemas/Time' - type: 'null' description: >- When the figures were read or computed. `null` while `pending`. approximate: type: boolean description: >- `true` when our data provider could not read this window and we counted it from per-token totals of the wallets' positions instead: each token's whole realized profit, volume and trade count lands in the window of its last trade, so `24h`, `7d` and `30d` can show more than happened inside them. The next reading of the window replaces these figures. `false` otherwise, while `pending`, and on a computed window. required: - origin - status - realized - unrealized - total - unpricedProceeds - netFlow - volume - buyVolume - sellVolume - returnPct - tradeCount - buys - sells - tokensTraded - winningTokens - rank - asOf - approximate 7d: description: The last 7 days, from our data provider. type: object properties: origin: type: string enum: - computed - provider description: >- `provider`: figures of the whole wallets from our data provider, every venue. `computed`: our figures from the trades and rankings we compute. status: type: string enum: - ready - pending description: >- `ready`: the values hold a reading. `pending`: no reading yet, and every value is `null`. realized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss taken by selling, in USD. `null` when not known. unrealized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss on tokens still held, in USD. On `24h`, `7d` and `30d`: the open positions last traded inside the window, on UTC calendar days (`24h` from 00:00 UTC today, `7d` and `30d` from 00:00 UTC 6 and 29 days before), from the reading of the top `unrealized`, which leaves out the same positions. On `all`: our own figure from the trades we hold, on a wallet. `null` when not known, and on the `all` of a trader. total: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- `realized` plus `unrealized`, in USD: one formula on every window. `null` when either is `null`. unpricedProceeds: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Proceeds of tokens sold beyond the position we saw them buy, in USD. `null` when not known. netFlow: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- USD received from sells minus USD paid for buys, in USD. `null` when not known. volume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: Buy volume plus sell volume, in USD. `null` when not known. buyVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD paid for buys, in USD. `null` when not known. sellVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD received from sells, in USD. `null` when not known. returnPct: description: >- Return in percent, rounded to 8 decimals: 10 means a 10 % gain. `null` when the base is zero or not known. type: - number - 'null' tradeCount: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Trades in the window. `null` when not known. buys: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Buys in the window. `null` when not known. sells: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Sells in the window. `null` when not known. tokensTraded: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Distinct tokens traded in the window. `null` when not known. winningTokens: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Tokens closed at a profit in the window. `null` when not known. rank: anyOf: - type: object properties: position: type: integer minimum: 1 maximum: 9007199254740991 description: >- 1 plus the number of subjects with a higher value. Ties share a position. of: type: integer minimum: 1 maximum: 9007199254740991 description: Subjects in the ranking. ranking: type: string description: The ranking key, for `GET /v3/rankings/{key}`. required: - position - of - ranking - type: 'null' description: >- Where the trader stands in our ranking for this window. Set on a trader's `all`; `null` on the other windows and on a wallet. asOf: anyOf: - $ref: '#/components/schemas/Time' - type: 'null' description: >- When the figures were read or computed. `null` while `pending`. approximate: type: boolean description: >- `true` when our data provider could not read this window and we counted it from per-token totals of the wallets' positions instead: each token's whole realized profit, volume and trade count lands in the window of its last trade, so `24h`, `7d` and `30d` can show more than happened inside them. The next reading of the window replaces these figures. `false` otherwise, while `pending`, and on a computed window. required: - origin - status - realized - unrealized - total - unpricedProceeds - netFlow - volume - buyVolume - sellVolume - returnPct - tradeCount - buys - sells - tokensTraded - winningTokens - rank - asOf - approximate 30d: description: The last 30 days, from our data provider. type: object properties: origin: type: string enum: - computed - provider description: >- `provider`: figures of the whole wallets from our data provider, every venue. `computed`: our figures from the trades and rankings we compute. status: type: string enum: - ready - pending description: >- `ready`: the values hold a reading. `pending`: no reading yet, and every value is `null`. realized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss taken by selling, in USD. `null` when not known. unrealized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss on tokens still held, in USD. On `24h`, `7d` and `30d`: the open positions last traded inside the window, on UTC calendar days (`24h` from 00:00 UTC today, `7d` and `30d` from 00:00 UTC 6 and 29 days before), from the reading of the top `unrealized`, which leaves out the same positions. On `all`: our own figure from the trades we hold, on a wallet. `null` when not known, and on the `all` of a trader. total: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- `realized` plus `unrealized`, in USD: one formula on every window. `null` when either is `null`. unpricedProceeds: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Proceeds of tokens sold beyond the position we saw them buy, in USD. `null` when not known. netFlow: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- USD received from sells minus USD paid for buys, in USD. `null` when not known. volume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: Buy volume plus sell volume, in USD. `null` when not known. buyVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD paid for buys, in USD. `null` when not known. sellVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD received from sells, in USD. `null` when not known. returnPct: description: >- Return in percent, rounded to 8 decimals: 10 means a 10 % gain. `null` when the base is zero or not known. type: - number - 'null' tradeCount: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Trades in the window. `null` when not known. buys: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Buys in the window. `null` when not known. sells: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Sells in the window. `null` when not known. tokensTraded: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Distinct tokens traded in the window. `null` when not known. winningTokens: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Tokens closed at a profit in the window. `null` when not known. rank: anyOf: - type: object properties: position: type: integer minimum: 1 maximum: 9007199254740991 description: >- 1 plus the number of subjects with a higher value. Ties share a position. of: type: integer minimum: 1 maximum: 9007199254740991 description: Subjects in the ranking. ranking: type: string description: The ranking key, for `GET /v3/rankings/{key}`. required: - position - of - ranking - type: 'null' description: >- Where the trader stands in our ranking for this window. Set on a trader's `all`; `null` on the other windows and on a wallet. asOf: anyOf: - $ref: '#/components/schemas/Time' - type: 'null' description: >- When the figures were read or computed. `null` while `pending`. approximate: type: boolean description: >- `true` when our data provider could not read this window and we counted it from per-token totals of the wallets' positions instead: each token's whole realized profit, volume and trade count lands in the window of its last trade, so `24h`, `7d` and `30d` can show more than happened inside them. The next reading of the window replaces these figures. `false` otherwise, while `pending`, and on a computed window. required: - origin - status - realized - unrealized - total - unpricedProceeds - netFlow - volume - buyVolume - sellVolume - returnPct - tradeCount - buys - sells - tokensTraded - winningTokens - rank - asOf - approximate all: description: All time, computed by us. `null` when we hold no figure. anyOf: - type: object properties: origin: type: string enum: - computed - provider description: >- `provider`: figures of the whole wallets from our data provider, every venue. `computed`: our figures from the trades and rankings we compute. status: type: string enum: - ready - pending description: >- `ready`: the values hold a reading. `pending`: no reading yet, and every value is `null`. realized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss taken by selling, in USD. `null` when not known. unrealized: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss on tokens still held, in USD. On `24h`, `7d` and `30d`: the open positions last traded inside the window, on UTC calendar days (`24h` from 00:00 UTC today, `7d` and `30d` from 00:00 UTC 6 and 29 days before), from the reading of the top `unrealized`, which leaves out the same positions. On `all`: our own figure from the trades we hold, on a wallet. `null` when not known, and on the `all` of a trader. total: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- `realized` plus `unrealized`, in USD: one formula on every window. `null` when either is `null`. unpricedProceeds: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Proceeds of tokens sold beyond the position we saw them buy, in USD. `null` when not known. netFlow: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- USD received from sells minus USD paid for buys, in USD. `null` when not known. volume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Buy volume plus sell volume, in USD. `null` when not known. buyVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD paid for buys, in USD. `null` when not known. sellVolume: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: USD received from sells, in USD. `null` when not known. returnPct: description: >- Return in percent, rounded to 8 decimals: 10 means a 10 % gain. `null` when the base is zero or not known. type: - number - 'null' tradeCount: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Trades in the window. `null` when not known. buys: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Buys in the window. `null` when not known. sells: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Sells in the window. `null` when not known. tokensTraded: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Distinct tokens traded in the window. `null` when not known. winningTokens: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Tokens closed at a profit in the window. `null` when not known. rank: anyOf: - type: object properties: position: type: integer minimum: 1 maximum: 9007199254740991 description: >- 1 plus the number of subjects with a higher value. Ties share a position. of: type: integer minimum: 1 maximum: 9007199254740991 description: Subjects in the ranking. ranking: type: string description: The ranking key, for `GET /v3/rankings/{key}`. required: - position - of - ranking - type: 'null' description: >- Where the trader stands in our ranking for this window. Set on a trader's `all`; `null` on the other windows and on a wallet. asOf: anyOf: - $ref: '#/components/schemas/Time' - type: 'null' description: >- When the figures were read or computed. `null` while `pending`. approximate: type: boolean description: >- `true` when our data provider could not read this window and we counted it from per-token totals of the wallets' positions instead: each token's whole realized profit, volume and trade count lands in the window of its last trade, so `24h`, `7d` and `30d` can show more than happened inside them. The next reading of the window replaces these figures. `false` otherwise, while `pending`, and on a computed window. required: - origin - status - realized - unrealized - total - unpricedProceeds - netFlow - volume - buyVolume - sellVolume - returnPct - tradeCount - buys - sells - tokensTraded - winningTokens - rank - asOf - approximate - type: 'null' description: One entry per window. With `window` set, only that key is present. unrealized: anyOf: - type: object properties: origin: type: string const: provider description: 'Always `provider`: our data provider reads it.' value: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- Profit or loss on the tokens still held, in USD. `null` when not known. holdingsValue: anyOf: - $ref: '#/components/schemas/Amount' - type: 'null' description: >- What the held tokens are worth, in USD. `null` when not known. positions: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Positions counted. `null` when not known. excludedPositions: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Positions left out, such as tokens without a price. `null` when not known. asOf: $ref: '#/components/schemas/Time' description: When our data provider read the wallets. required: - origin - value - holdingsValue - positions - excludedPositions - asOf - type: 'null' description: >- Unrealized profit or loss of the wallet, from our data provider. `null` without a reading. asOf: anyOf: - $ref: '#/components/schemas/Time' - type: 'null' description: >- The oldest `asOf` among the ready windows, else the ranking time of `all`, else `null`. nextUpdateAt: anyOf: - $ref: '#/components/schemas/Time' - type: 'null' description: >- When the first figure from our data provider falls due to be read again: its `asOf` plus its refresh interval. The first call after that time reads it again. Earlier than now when `stale` is `true`. `null` unless `status` is `ready`. stale: type: boolean description: >- `true` when at least one figure from our data provider is past its refresh interval and this call could not read it again: the read failed, did not finish within the 8 second wait, or this month's provider budget is spent. A later call can carry newer figures. The computed `all` window does not count. `false` unless `status` is `ready`. boards: type: array items: type: object properties: platform: $ref: '#/components/schemas/Platform' description: The platform that publishes the board. board: type: string description: The board, as `GET /v3/leaderboards` lists it. window: description: >- The window of the board this standing is on. `null` on a board without windows. type: - string - 'null' rank: type: integer minimum: 1 maximum: 9007199254740991 description: The rank the platform gives the account on that capture. measures: type: object propertyNames: type: string enum: - pnl - net_flow - portfolio_value - price - liquidity - roi - volume - trade_count - win_rate - impressions - views - likes - followers - holders - market_cap - members - points - realized_pnl - unrealized_pnl additionalProperties: anyOf: - $ref: '#/components/schemas/Amount' - type: number description: >- Figures of the entry keyed by metric. Money is an `Amount`; ratios and counts are numbers. A metric the source did not store is absent. capturedAt: $ref: '#/components/schemas/Time' description: When we captured the board. required: - platform - board - window - rank - measures - capturedAt description: >- Where the accounts keyed by these wallets stand on the newest capture of each platform board that ranks accounts, as the platform shows it, for reference. The platform computes these itself; they need not match the windows above. Empty when no board lists them. required: - wallet - wallets - status - retryAfterSeconds - windows - unrealized - asOf - nextUpdateAt - stale - boards description: The profit and loss of one wallet, per window. Names no owner. Amount: type: object properties: value: type: string pattern: ^(0|-?[1-9]\d*)$ description: >- An integer in base units, as a string, and negative below zero. Read it with a decimal or big integer type; a float loses digits. decimals: type: integer minimum: 0 maximum: 36 description: >- The power of ten between base units and one whole unit: `value` ÷ 10^`decimals`. currency: type: string minLength: 1 description: >- `USD`, or the token id (`tok__
`) of a token quantity. priceAsOf: $ref: '#/components/schemas/Time' description: >- The time of the price we converted the value with. Absent when no price was used. required: - value - decimals - currency description: >- Money or a token quantity, never a JSON number. `{ "value": "12345678", "decimals": 6, "currency": "USD" }` is 12.345678 USD. Time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}(?:Z))$ description: 'A time in RFC3339, UTC, with milliseconds: `2026-11-01T09:12:44.120Z`.' Platform: type: string enum: - fomo - pump - hyperliquid - markets - polymarket - legend - risex securitySchemes: bearerAuth: type: http scheme: bearer apiKeyHeader: type: apiKey in: header name: X-Api-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.