> ## 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. # One pump.fun wallet's realized and unrealized profit > Profit and trading activity across the whole wallet, on the same formula as GET /v2/user/handle/{handle}/pnl. - `24h`, `7d`, `30d` and `all` each carry `realizedPnlUsd`, `unrealizedPnlUsd` and `totalPnlUsd`. `all` covers every trade since 1 January 2025. - `unrealized`: profit on what the wallet holds now. It leaves out spam, pools under $10,000 of liquidity and positions larger than their pool. - `pumpBoard`: the standing pump.fun itself shows on its PnL boards, for reference. - The first call for a wallet reads it live, up to 8 seconds. A window that does not finish in time comes back `pending` and is ready on the next call. - Only a `ready` answer is charged the hit price; every other answer is charged the miss price. - **404** when the wallet has no pump.fun user. **Price:** 500 CU per call. ## OpenAPI ````yaml https://api.fomoscan.sh/openapi.json get /v2/pump/user/wallet/{wallet}/pnl openapi: 3.1.0 info: title: FomoScan Identity API version: 1.1.0 description: >- Resolve a FOMO trader handle to their on-chain wallet addresses, and any wallet back to the traders behind it. Every returned address is a verified match. ## Authentication Send your API key as `Authorization: Bearer fsk_live_…` (or the `X-Api-Key` header). Enter it under Authentication at the top of this page to call any endpoint live. ```bash curl -s -H "Authorization: Bearer $KEY" \ "https://api.fomoscan.sh/v2/user/handle/tradername" ``` ## Response format 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. ## Billing - A lookup that finds nothing is still charged, at the miss price stated on the endpoint. - `GET /v2/me` is free and reports your remaining units. - Errors that are our fault or your client’s (`401`, `403`, `429`, `5xx`) are not billed. - When the allowance is spent, calls return `402 QUOTA_EXCEEDED` until the counter resets. ## Free keys A free key reveals wallets for the sample set below and nobody else. Sample lookups cost no credits. Outside the set, a wallet lookup, or a handle or id lookup whose answer carries a wallet, returns `403 SAMPLE_SET_ONLY`. Profiles without a wallet and misses answer as they do for any key. A self-serve free key cannot open the WebSocket. - Handles: `frankdegods`, `unipcs`, `pointfarmcap`, `orangie`, `theveeman` - Wallets: `498g1rVnFcnjBjpfw1xyqA1WvgQXUU8RWuELjxkjAayQ`, `0x696d1265c8fc4f14797abebfae3c43ebfa9d8e28`, `2heJbC32Tpfcb3nbUb5ER61K11FGZVfVGtVnDm6LDogF`, `Beqv6dzTcjV2eodo8RRXCiCcnSYrS1vkQKhfqwHXqeit`, `83b2LMf12aLec92kur3duRA8VvUkLaXUtML31aCcZNCM`, `F5hkYsi8JxjyA2JHN5CA7MbnnhWubkXB2ZQB7Gkaxqs6` ## 404 NOT_FOUND A lookup that finds nothing answers `404` with the code `NOT_FOUND`. On a handle or id lookup it means we hold no user under that handle or id. On a wallet lookup it means we hold no verified link from that address to a trader. 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`. ## Errors Every error uses one shape: `{ "error": { "code": "…", "message": "…" } }`. | HTTP | Code | Meaning | |---|---|---| | 400 | `VALIDATION_ERROR` | A malformed handle, address or query parameter. | | 400 | `BAD_REQUEST` | The request cannot be served as sent. | | 401 | `UNAUTHORIZED` | Missing or invalid API key. | | 402 | `QUOTA_EXCEEDED` | Out of credits. | | 402 | `REVEAL_LIMIT_REACHED` | The key’s reveal limit is reached. | | 403 | `FORBIDDEN` | The key may not perform this action. | | 403 | `FORBIDDEN_SCOPE` | The key is not provisioned for this endpoint. | | 403 | `FREE_TIER_DISABLED` | The key has no allowance. | | 403 | `SAMPLE_SET_ONLY` | A free key asked for a wallet outside the sample set. | | 403 | `WEBSOCKET_PLAN_REQUIRED` | The key’s plan has no WebSocket. It is included from Growth ($899), and legacy plans keep it. | | 404 | `NOT_FOUND` | No answer for the handle, id or wallet you asked about, or no such route. See the section above. | | 409 | `CONFLICT` | The request conflicts with one already accepted. | | 429 | `RATE_LIMITED` | Per-minute limit exceeded. Retry after `retryAfter` seconds. | | 500 | `INTERNAL_ERROR` | Our fault. Retry. If it persists, contact support with the path and the time. | | 503 | `OVERLOADED` | We are shedding load. Retry. | | 503 | `B2B_DISABLED` | The API is switched off on this deployment. | | 504 | `TIMEOUT` | The answer did not arrive in time. Retry. | A `429` also carries `retryAfter`, in seconds. ## Rate limits Each key has one per-minute request limit across every endpoint, readable from `GET /v2/me` as `ratePerMinute`. A per-IP burst ceiling sits behind it. Exceeding either returns `429 RATE_LIMITED`. ## Pricing Paid plans reach every REST endpoint. Plans differ in credits, request rate, wallet reveals and the WebSocket. Credits and CU are the same unit. | Plan | Free | Starter | Builder | Growth | Scale | Enterprise | | --- | --- | --- | --- | --- | --- | --- | | Price per month | $0 | $99 | $299 | $899 | $2,499 | Set in the contract | | Credits | 25,000 once, for 30 days | 1,000,000 a month | 5,000,000 a month | 20,000,000 a month | 75,000,000 a month | Set in the contract | | Requests per minute | 60 | 150 | 300 | 600 | 1,200 | Set in the contract | | Wallet reveals per month | Sample set only | 150 | 500 | 1,500 | 4,000 | No cap | | Price per 30,000-credit reveal | $0 on the sample set | $2.97 | $1.79 | $1.35 | $1.00 | Set in the contract | | WebSocket | No | No | No | Included | Included | Included | Keys on legacy plans keep the WebSocket access they already have. ### Wallet reveals A wallet reveal is an answer that returns a verified wallet. Each reveal counts against the plan’s wallet reveals for the month. It costs the credits of the endpoint that returned it: | Reveal endpoint | Credits per reveal | | --- | --- | | `GET /v2/user/handle/{handle}` | 100 | | `GET /v2/user/wallet/{address}` | 30,000 | | `GET /v2/user/id/{id}` | 100 | | `POST /v2/user/handle/{handle}/resolve` | 30,000 | | `GET /v2/user/handle/{handle}/pnl` | 30,000 | | `POST /v2/user/handles/pnl` | 30,000 per handle revealed | The price per 30,000-credit reveal in the plan table is what 30,000 credits cost on the plan. It applies to `GET /v2/user/wallet/{address}`, `POST /v2/user/handle/{handle}/resolve`, `GET /v2/user/handle/{handle}/pnl`, `POST /v2/user/handles/pnl`. A reveal on another endpoint costs that endpoint’s credits. ### Credit cost per endpoint | Endpoint | Credits | | --- | --- | | `GET /v2/user/handle/{handle}` | 100 CU on a hit, 200 CU on a 404. | | `GET /v2/user/wallet/{address}` | 30,000 CU on a hit, 200 CU on a 404. | | `GET /v2/user/id/{id}` | 100 CU on a hit, 200 CU on a 404. | | `POST /v2/user/handle/{handle}/resolve` | 30,000 CU on a hit, 200 CU on a 202 or a 404. A paused lookup (202 with reason unavailable and retryable false) is not charged. | | `GET /v2/user/handle/{handle}/pnl` | 30,000 CU on a hit, 200 CU on any answer that is not ready, and on a 404. | | `POST /v2/user/handles/pnl` | 30,000 CU per entry answered ready, 200 CU per entry not ready and per handle in `missing`. | | `GET /v2/thesis` | 200 CU per 20 requested rows (`limit`, up to 100). An empty page costs the same as a full one. | | `GET /v2/thesis/token/{tokenAddress}` | 200 CU per 20 requested rows (`limit`, up to 100). An empty page costs the same as a full one. | | `GET /v2/thesis/user/{id}` | 200 CU per 20 requested rows (`limit`, up to 100). An empty page costs the same as a full one. | | `GET /v2/thesis/user/{id}/token/{tokenAddress}` | 200 CU per 20 requested rows (`limit`, up to 100). An empty page costs the same as a full one. | | `GET /v2/me` | Free. | | `GET /v2/pump/user/wallet/{wallet}` | 10 CU per call. | | `GET /v2/pump/thesis` | 10 CU per call. | | `GET /v2/pump/thesis/token/{mint}` | 10 CU per call. | | `GET /v2/pump/thesis/wallet/{wallet}` | 10 CU per call. | | `GET /v2/pump/leaderboard/traders` | 10 CU per call. | | `GET /v2/pump/user/wallet/{wallet}/pnl` | 500 CU per call. | | `GET /v2/ws` | 20,000 CU per minute held open. | | `GET /v2/ws/pump` | 20,000 CU per minute held open. | ### Credit packs A pack adds credits on top of a plan. Pack credits do not expire, and they are spent after the plan’s monthly credits run out. | Pack | Price | | --- | --- | | 250,000 credits | $29 | | 1,000,000 credits | $115 | | 5,000,000 credits | $349 | | 20,000,000 credits | $1,049 | | 75,000,000 credits | $2,899 | ### Payment Plans are paid by card, and Apple Pay counts as a card. Credit packs are paid in crypto only, with no surcharge. ## Chains Wallet lookups take a Solana address or an EVM address. A verified EVM address is the same address on every EVM chain. Theses carry their token’s chain in `tokenNetwork`. This table shows the value the API returns for each chain we serve. Some chains arrive as a short name and some as a numeric chain id. Match on the exact value in the table. | Chain | `tokenNetwork` | | --- | --- | | Solana | `sol` | | Base | `base` | | BNB Chain | `bsc` | | Robinhood Chain | `robinhood` | | Ethereum | `eth` | | Arc | `5042` | | Monad | `143` | A thesis on a chain outside this table arrives as a short name or a numeric chain id. ## Breaking changes A breaking change removes or renames an endpoint, a field or an error code, or changes what a field means. We announce each one at least 3 days before it ships. The notice goes out on the changelog, on the Telegram announcements channel (https://t.me/scanfomo) and on every other channel we run. New fields can appear without notice. Ignore fields you do not recognise. contact: name: FomoScan url: https://fomoscan.sh email: fomoscan-support@proton.me servers: - url: https://api.fomoscan.sh description: Production security: [] tags: - name: Identities description: Resolve handles ↔ wallets. - name: Thesis Feed description: >- Trader "thesis" posts, newest first, by token, by author, or both. Ask with no `before` for the newest page. Clients MUST dedupe on `id`. - name: WebSocket description: >- The streaming surface. Everything above is a request you make; this is a connection you hold. It delivers the same thesis objects `Thesis Feed` returns. - name: Pump description: >- pump.fun lookups: a user by wallet, the global callout feed or one coin's or wallet's wall, and the PnL leaderboard. On pump.fun the wallet IS the account, so a wallet lookup here is a stored read, not a resolution. - name: Account description: 'Your key: entitlements and usage.' paths: /v2/pump/user/wallet/{wallet}/pnl: get: tags: - Pump summary: One pump.fun wallet's realized and unrealized profit description: >- Profit and trading activity across the whole wallet, on the same formula as GET /v2/user/handle/{handle}/pnl. - `24h`, `7d`, `30d` and `all` each carry `realizedPnlUsd`, `unrealizedPnlUsd` and `totalPnlUsd`. `all` covers every trade since 1 January 2025. - `unrealized`: profit on what the wallet holds now. It leaves out spam, pools under $10,000 of liquidity and positions larger than their pool. - `pumpBoard`: the standing pump.fun itself shows on its PnL boards, for reference. - The first call for a wallet reads it live, up to 8 seconds. A window that does not finish in time comes back `pending` and is ready on the next call. - Only a `ready` answer is charged the hit price; every other answer is charged the miss price. - **404** when the wallet has no pump.fun user. **Price:** 500 CU per call. parameters: - schema: type: string minLength: 1 maxLength: 128 in: path name: wallet required: true description: pump.fun wallet (Solana address). responses: '200': description: Default Response content: application/json: schema: type: object required: - wallet - username - status - retryAfterSeconds - updatedAt - windows - unrealized - pumpBoard properties: wallet: type: string username: type: - 'null' - string status: type: string enum: - ready - pending - failed - unavailable description: >- `ready`: figures are served; each window carries its own status. `pending`: nothing could be read within the wait; ask again after retryAfterSeconds. `failed`: the last reading failed and nothing is held yet. `unavailable`: whole-wallet reading is switched off or out of capacity. Only `ready` is charged the hit price. retryAfterSeconds: type: - 'null' - integer description: Set only when status is pending or failed. updatedAt: type: - 'null' - integer description: >- Epoch ms of the oldest figure served. Null unless status is ready. windows: type: object required: - 24h - 7d - 30d - all description: >- One formula on every window: realized profit on average cost plus the unrealized profit of positions last traded in the window. 24h, 7d and 30d are UTC calendar days ending today. properties: 24h: type: object required: - realizedPnlUsd - unrealizedPnlUsd - totalPnlUsd - returnPct - volumeUsd - buyVolumeUsd - sellVolumeUsd - trades - buys - sells - tokensTraded - winningTokens - status - updatedAt properties: realizedPnlUsd: type: - 'null' - number description: >- Realized profit in the window across the whole wallet, every venue, USD: what sells received minus the average cost of the tokens sold. On all, every trade since 1 January 2025. Null while pending, and when the figure is one no real wallet reaches or a realized profit larger than sellVolumeUsd. unrealizedPnlUsd: type: - 'null' - number description: >- What the tokens held now are worth minus what they cost, USD, for the positions last traded in the window. On all, every position counted in unrealized. Null until the positions have been read. totalPnlUsd: type: - 'null' - number description: >- realizedPnlUsd plus unrealizedPnlUsd, USD. Null when either part is null. returnPct: type: - 'null' - number description: >- Realized profit as a percentage of what the sold tokens cost. volumeUsd: type: - 'null' - number description: Bought plus sold in the window, USD. buyVolumeUsd: type: - 'null' - number description: Paid on buys in the window, USD. sellVolumeUsd: type: - 'null' - number description: Received on sells in the window, USD. trades: type: - 'null' - integer description: Trades in the window. buys: type: - 'null' - integer sells: type: - 'null' - integer tokensTraded: type: - 'null' - integer description: Distinct tokens bought or sold in the window. winningTokens: type: - 'null' - integer description: >- Tokens that closed the window with positive realized profit. status: type: string enum: - ready - pending description: >- `ready`: the figures are filled. `pending`: this window is still being read for the first time; its figures are null and a call a few seconds later carries them. updatedAt: type: - 'null' - integer description: >- Epoch ms when this window's figures were read. Null while pending. 7d: type: object required: - realizedPnlUsd - unrealizedPnlUsd - totalPnlUsd - returnPct - volumeUsd - buyVolumeUsd - sellVolumeUsd - trades - buys - sells - tokensTraded - winningTokens - status - updatedAt properties: realizedPnlUsd: type: - 'null' - number description: >- Realized profit in the window across the whole wallet, every venue, USD: what sells received minus the average cost of the tokens sold. On all, every trade since 1 January 2025. Null while pending, and when the figure is one no real wallet reaches or a realized profit larger than sellVolumeUsd. unrealizedPnlUsd: type: - 'null' - number description: >- What the tokens held now are worth minus what they cost, USD, for the positions last traded in the window. On all, every position counted in unrealized. Null until the positions have been read. totalPnlUsd: type: - 'null' - number description: >- realizedPnlUsd plus unrealizedPnlUsd, USD. Null when either part is null. returnPct: type: - 'null' - number description: >- Realized profit as a percentage of what the sold tokens cost. volumeUsd: type: - 'null' - number description: Bought plus sold in the window, USD. buyVolumeUsd: type: - 'null' - number description: Paid on buys in the window, USD. sellVolumeUsd: type: - 'null' - number description: Received on sells in the window, USD. trades: type: - 'null' - integer description: Trades in the window. buys: type: - 'null' - integer sells: type: - 'null' - integer tokensTraded: type: - 'null' - integer description: Distinct tokens bought or sold in the window. winningTokens: type: - 'null' - integer description: >- Tokens that closed the window with positive realized profit. status: type: string enum: - ready - pending description: >- `ready`: the figures are filled. `pending`: this window is still being read for the first time; its figures are null and a call a few seconds later carries them. updatedAt: type: - 'null' - integer description: >- Epoch ms when this window's figures were read. Null while pending. 30d: type: object required: - realizedPnlUsd - unrealizedPnlUsd - totalPnlUsd - returnPct - volumeUsd - buyVolumeUsd - sellVolumeUsd - trades - buys - sells - tokensTraded - winningTokens - status - updatedAt properties: realizedPnlUsd: type: - 'null' - number description: >- Realized profit in the window across the whole wallet, every venue, USD: what sells received minus the average cost of the tokens sold. On all, every trade since 1 January 2025. Null while pending, and when the figure is one no real wallet reaches or a realized profit larger than sellVolumeUsd. unrealizedPnlUsd: type: - 'null' - number description: >- What the tokens held now are worth minus what they cost, USD, for the positions last traded in the window. On all, every position counted in unrealized. Null until the positions have been read. totalPnlUsd: type: - 'null' - number description: >- realizedPnlUsd plus unrealizedPnlUsd, USD. Null when either part is null. returnPct: type: - 'null' - number description: >- Realized profit as a percentage of what the sold tokens cost. volumeUsd: type: - 'null' - number description: Bought plus sold in the window, USD. buyVolumeUsd: type: - 'null' - number description: Paid on buys in the window, USD. sellVolumeUsd: type: - 'null' - number description: Received on sells in the window, USD. trades: type: - 'null' - integer description: Trades in the window. buys: type: - 'null' - integer sells: type: - 'null' - integer tokensTraded: type: - 'null' - integer description: Distinct tokens bought or sold in the window. winningTokens: type: - 'null' - integer description: >- Tokens that closed the window with positive realized profit. status: type: string enum: - ready - pending description: >- `ready`: the figures are filled. `pending`: this window is still being read for the first time; its figures are null and a call a few seconds later carries them. updatedAt: type: - 'null' - integer description: >- Epoch ms when this window's figures were read. Null while pending. all: type: object required: - realizedPnlUsd - unrealizedPnlUsd - totalPnlUsd - returnPct - volumeUsd - buyVolumeUsd - sellVolumeUsd - trades - buys - sells - tokensTraded - winningTokens - status - updatedAt properties: realizedPnlUsd: type: - 'null' - number description: >- Realized profit in the window across the whole wallet, every venue, USD: what sells received minus the average cost of the tokens sold. On all, every trade since 1 January 2025. Null while pending, and when the figure is one no real wallet reaches or a realized profit larger than sellVolumeUsd. unrealizedPnlUsd: type: - 'null' - number description: >- What the tokens held now are worth minus what they cost, USD, for the positions last traded in the window. On all, every position counted in unrealized. Null until the positions have been read. totalPnlUsd: type: - 'null' - number description: >- realizedPnlUsd plus unrealizedPnlUsd, USD. Null when either part is null. returnPct: type: - 'null' - number description: >- Realized profit as a percentage of what the sold tokens cost. volumeUsd: type: - 'null' - number description: Bought plus sold in the window, USD. buyVolumeUsd: type: - 'null' - number description: Paid on buys in the window, USD. sellVolumeUsd: type: - 'null' - number description: Received on sells in the window, USD. trades: type: - 'null' - integer description: Trades in the window. buys: type: - 'null' - integer sells: type: - 'null' - integer tokensTraded: type: - 'null' - integer description: Distinct tokens bought or sold in the window. winningTokens: type: - 'null' - integer description: >- Tokens that closed the window with positive realized profit. status: type: string enum: - ready - pending description: >- `ready`: the figures are filled. `pending`: this window is still being read for the first time; its figures are null and a call a few seconds later carries them. updatedAt: type: - 'null' - integer description: >- Epoch ms when this window's figures were read. Null while pending. unrealized: type: - 'null' - object required: - unrealizedPnlUsd - holdingsUsd - positions - excludedPositions - status - updatedAt properties: unrealizedPnlUsd: type: number description: >- What the tokens held now are worth minus what they cost, USD. A token held without any buy, such as a transfer in or an airdrop, has no cost to measure against and is left out. holdingsUsd: type: number description: Current value of the positions counted, USD. positions: type: integer description: Open positions counted. excludedPositions: type: integer description: >- Open positions left out: flagged as spam, a pool under $10,000 of liquidity, or a position worth more than its pool holds, since none of those can be sold at the quoted price; and a token held without any buy, which has no cost. status: type: string enum: - ready description: Always `ready` when present. updatedAt: type: integer description: Epoch ms when the positions were read. description: >- Profit on what the wallet holds now. It has no window. Null until the positions have been read at least once. pumpBoard: type: object required: - daily - weekly - monthly description: >- The wallet's standing on the latest pump.fun PnL boards, as pump.fun shows it, for reference. pump.fun computes these itself and they need not match the windows above. Null for a board the wallet is not on. properties: daily: type: - 'null' - object required: - rank - pnlUsd - realizedPnlUsd - unrealizedPnlUsd - asOf properties: rank: type: integer pnlUsd: type: - 'null' - number realizedPnlUsd: type: - 'null' - number unrealizedPnlUsd: type: - 'null' - number asOf: type: integer description: Epoch ms of the board this standing is from. weekly: type: - 'null' - object required: - rank - pnlUsd - realizedPnlUsd - unrealizedPnlUsd - asOf properties: rank: type: integer pnlUsd: type: - 'null' - number realizedPnlUsd: type: - 'null' - number unrealizedPnlUsd: type: - 'null' - number asOf: type: integer description: Epoch ms of the board this standing is from. monthly: type: - 'null' - object required: - rank - pnlUsd - realizedPnlUsd - unrealizedPnlUsd - asOf properties: rank: type: integer pnlUsd: type: - 'null' - number realizedPnlUsd: type: - 'null' - number unrealizedPnlUsd: type: - 'null' - number asOf: type: integer description: Epoch ms of the board this standing is from. '404': description: Default Response content: application/json: schema: $ref: '#/components/schemas/def-0' security: - b2bApiKey: [] components: schemas: def-0: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable, lower-snake-case error code. enum: - BAD_REQUEST - B2B_DISABLED - CONFLICT - FORBIDDEN - FORBIDDEN_SCOPE - FREE_TIER_DISABLED - INTERNAL_ERROR - NOT_FOUND - OVERLOADED - QUOTA_EXCEEDED - RATE_LIMITED - REVEAL_LIMIT_REACHED - SAMPLE_SET_ONLY - TIMEOUT - UNAUTHORIZED - VALIDATION_ERROR - WEBSOCKET_PLAN_REQUIRED message: type: string retryAfter: type: integer description: Seconds; only on RATE_LIMITED. addUrl: type: string description: Hint URL, present on some NOT_FOUND responses. title: ErrorBody securitySchemes: b2bApiKey: type: http scheme: bearer description: >- B2B API key (`fsk_live_…` / `fsk_test_…`), issued by FomoScan. Also accepted via `X-Api-Key`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.