--- name: pumpfomo description: Build with the pumpfomo API (api.pumpfomo.com), the data API for pump.fun and fomo.family. Covers traders, wallets, coins, PnL, leaderboards, callouts and wallet reverse lookups over REST, and live trades over one WebSocket on Solana and 11 EVM chains. Use when writing code that calls pumpfomo, when choosing an endpoint for pump.fun or fomo.family data, when handling its credits, rate limits and errors, or when connecting to wss://api.pumpfomo.com/v1/stream, for example in a trading bot, copy trading tool, wallet tracker, dashboard or alert bot. --- # pumpfomo API pumpfomo serves pump.fun and fomo.family data as REST endpoints and one WebSocket. It is read-only: it never trades, signs or holds funds, so any order a bot places goes through the user's own wallet and code. It is independent, not pump.fun or fomo.family. ## Before writing code 1. Read the key from the environment: `PUMPFOMO_API_KEY`. Never hardcode it, print it, commit it or send it to a browser; call pumpfomo from a server or a script. Keys are made at https://pumpfomo.com/dashboard/keys?ref=ai-docs (the Free plan has 2,500 credits a month). 2. Find the endpoint in the index below, then open its reference file (`reference/.md`) for the parameters, a real example answer and its errors. **Don't guess field names**: `data` keeps pump.fun's and fomo.family's own field names, which mix camelCase and snake_case and differ between endpoints. Write types from the example answer. 3. Check the key with `GET /v1/ping` (free) if a call fails with 401 or 403. ## Calling it - Base URL `https://api.pumpfomo.com`, header `Authorization: Bearer $PUMPFOMO_API_KEY` (or `X-API-Key`). - A key has scopes: `read:pump`, `read:fomo`, `read:wallet`, `stream`. A 403 `scope_missing` means the key lacks the route's scope; the user changes it in the dashboard. - The free plan is one per person: a free account's key gets 403 `free_plan_in_use` from an address another free account's keys called from in the last 24 hours. Use one account's keys, or a paid plan. - Success: `{"data": …, "meta": {"source", "cache", "fetchedAt"}}`. Error: `{"error": {"code", "message", "requestId"}}`. Branch on `code`. - Lists page with a `cursor` parameter: pass the last page's `nextCursor`. Each page costs the page's price. - Batch routes (`POST /v1/pump/coins/batch`, `POST /v1/wallets/batch` and the others in the index) take a list in the body (`mints`, `wallets` or `addresses`; 20 to 100 items, see each) and cost a flat price per call, so prefer them to loops of single calls. ## Credits, limits, retries - Every call costs the credits on its endpoint, most of them 1 or 2, PnL 5, a wallet reveal 500. `X-Credits-Cost` and `X-Credits-Remaining` come back on every paid call; log them. - Errors are free. A 404 miss costs 1. - Wallet reveals (a wallet lookup that finds someone) are capped a month by the plan: Free 10, Starter 300, Builder 1,000, Growth 3,000, Scale 8,000. Past the cap: 402 `reveal_limit_reached`, not charged. Look a wallet up once and keep the answer. - Rate limit per key: Free 2 a second (burst 10), Starter 10, Builder 25, Growth 60, Scale 150. On 429 wait `Retry-After` seconds. Retry 5xx and 503 `upstream_busy` / `upstream_unavailable` with backoff (not charged). Don't retry 400, 401, 402 or 403. - Polling faster than an answer changes spends credits for nothing: `meta.fetchedAt` says how recent an answer is. For live data use the stream. ## A small client TypeScript (Node 18+): ```ts const BASE = "https://api.pumpfomo.com" export class PumpfomoError extends Error { constructor(public status: number, public code: string | undefined, message: string) { super(message) } } export async function pf(path: string, init: RequestInit = {}, tries = 4): Promise { for (let i = 0; ; i++) { const res = await fetch(BASE + path, { ...init, headers: { Authorization: `Bearer ${process.env.PUMPFOMO_API_KEY}`, ...(init.body ? { "Content-Type": "application/json" } : {}), ...init.headers, }, }) if (res.ok) return (await res.json()).data as T const again = res.status === 429 || res.status >= 500 if (!again || i >= tries) { const e = await res.json().catch(() => ({})) throw new PumpfomoError(res.status, e.error?.code, e.error?.message ?? res.statusText) } const wait = Number(res.headers.get("Retry-After")) || 2 ** i await new Promise((r) => setTimeout(r, wait * 1000)) } } // const board = await pf("/v1/fomo/leaderboard/7d") // const coins = await pf("/v1/pump/coins/batch", { method: "POST", body: JSON.stringify({ mints }) }) ``` Python (requests): ```python import os, time, requests BASE = "https://api.pumpfomo.com" s = requests.Session() s.headers["Authorization"] = f"Bearer {os.environ['PUMPFOMO_API_KEY']}" def pf(path, method="GET", tries=4, **kw): for i in range(tries + 1): r = s.request(method, BASE + path, timeout=30, **kw) if r.ok: return r.json()["data"] if (r.status_code != 429 and r.status_code < 500) or i == tries: err = r.json().get("error", {}) if "json" in r.headers.get("content-type", "") else {} raise RuntimeError(f"{r.status_code} {err.get('code')}: {err.get('message', r.text)}") time.sleep(float(r.headers.get("Retry-After") or 2 ** i)) ``` ## The live stream `wss://api.pumpfomo.com/v1/stream` carries every live channel on one connection: `trades` (pump.fun trades, by coin, by wallet, or every trade of $1,000 or more), `traders` (chosen pump.fun and fomo.family traders), `coins` (new pump.fun coins), `callouts` and `fomo` (fomo.family trades, theses and its activity feed). The plan sets the connections open at once: Builder 1, Growth 5, Scale 15; Free and Starter have none (close code 4003). A stream costs 10 credits a minute while it's open (about 432,000 credits for a month around the clock), charged as each minute starts; nothing by the message. Close a connection you don't need. ```ts import WebSocket from "ws" // npm i ws function connect(attempt = 0) { const ws = new WebSocket("wss://api.pumpfomo.com/v1/stream", { headers: { Authorization: `Bearer ${process.env.PUMPFOMO_API_KEY}` }, }) ws.on("open", () => { attempt = 0 ws.send(JSON.stringify({ op: "subscribe", channel: "traders", fomo: ["somehandle"], pump: [""] })) }) ws.on("message", (raw) => { const m = JSON.parse(raw.toString()) if (m.type === "trade" || m.type === "fomo_trade") onTrade(m) else if (m.type === "error") console.warn("stream refused:", m.code, m.message) }) ws.on("close", (code) => { if (code === 4003) return console.error("no free stream on this plan: close another or upgrade") setTimeout(() => connect(attempt + 1), Math.min(30_000, 1000 * 2 ** attempt)) }) } ``` - A new `subscribe` to a channel replaces that channel's filter; other channels stay as they are. Subscribe again after every reconnect. - On subscribe, recent events can come first in one `replay` message; send `"replay": false` to skip them. - Read fast: a client that falls behind is closed with 4008. Do slow work (HTTP calls, database writes) off the message handler. - Expect to reconnect: when the server is updated, open streams are closed with 1012 and it is back within a few seconds. Reconnect with a growing wait, subscribe again, and let the replay fill the gap. Don't reconnect on 4002 or 4003. - `reference/stream.md` has every channel's filters and every message's fields. ## Picking endpoints for common jobs - **Who is behind a wallet:** `GET /v1/wallets/{address}` (a wallet reveal, 500 credits), or `POST /v1/wallets/batch` for up to 100. - **A pump.fun trader:** profile `GET /v1/pump/users/{id}`, PnL `GET /v1/pump/users/{wallet}/pnl`, positions `…/portfolio`, trades `…/trades`, callouts `…/callouts` and `…/callout-stats`. - **A fomo.family trader:** `GET /v1/fomo/users/{handle}`, rank and PnL `…/rank`, trades `…/trades`, holdings `…/balances`, PnL curve `…/pnl-chart`. - **Traders worth following:** `GET /v1/pump/leaderboard`, `GET /v1/fomo/leaderboard/{window}`, `GET /v1/fomo/leaderboard/clans/{window}`, then vet each one with PnL, trades and callout stats before trusting a rank. - **A coin:** `GET /v1/pump/coins/{mint}`, candles `…/candles`, trades `…/trades`, holders and traders `…/traders`, live stats `…/live`; many coins at once with `POST /v1/pump/coins/batch` or `POST /v1/pump/coins/market-activity/batch`. - **Copy trading:** pick traders from the leaderboards, follow them on the stream's `traders` channel, filter each trade (size, market cap, the token's warnings at `GET /v1/fomo/tokens/{chain}/{address}/warnings`), and execute with the user's own wallet. Run on paper first. Nothing here is financial advice; memecoins are extremely volatile. When code places real trades, make it log what it would do before it does it, cap the size, and leave the keys to the user. ## Every endpoint The parameters, a real example answer and the errors of each are in the reference file named in its heading. Online, every page is also at `https://pumpfomo.com/docs/.md`, and the index is at https://pumpfomo.com/llms.txt. ### General (reference/general.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/ping` | 0 | Checks an API key and says which key, account and scopes it speaks for. | ### Wallets (reference/wallets.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/wallets/{address}` | 500 | Reverse lookup: the fomo.family and pump.fun people behind a wallet. | | `POST /v1/wallets/batch` | 250 per wallet answered, each a wallet reveal (capped a month by the plan); 50 when none is | Reverse lookup for up to 100 wallets in one call. | ### pump.fun users (reference/pump-users.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/pump/users/{id}` | 1 | A pump.fun profile by wallet or user id: name, avatar, bio, follower counts, wallets. | | `GET /v1/pump/users/{id}/trades` | 2 | A pump.fun trader's trades and/or transfers, newest first, 100 a page. | | `GET /v1/pump/users/{id}/following` | 2 | The pump.fun accounts a user follows (up to 1,000). | | `GET /v1/pump/users/{id}/followers` | 2 | The pump.fun accounts following a user, roughly the most followed first (up to 1,999). | | `GET /v1/pump/users/{id}/followers/count` | 1 | How many pump.fun accounts follow a user. | | `GET /v1/pump/users/{id}/activity` | 2 | A user's coin launches and creator-fee claims, newest first, 20 a page. | | `GET /v1/pump/users/{wallet}/pnl` | 5 | A wallet's realized and unrealized PnL over a period, in SOL and USD, with holdings. | | `GET /v1/pump/users/{wallet}/pnl/chart` | 5 | A wallet's equity curve over a period. | | `GET /v1/pump/users/{wallet}/pnl/{mint}` | 1 | Cost basis, realized and unrealized PnL and fees paid by a wallet in one coin. | | `GET /v1/pump/users/{wallet}/positions` | 2 | A wallet's position in each of up to 50 coins. | | `GET /v1/pump/users/{wallet}/portfolio` | 2 | Every position of a wallet — open, closed or all — by PnL or size, 100 a page. | | `GET /v1/pump/users/{wallet}/balance` | 1 | A wallet's total value and PnL across every chain pump.fun knows. | | `GET /v1/pump/users/{wallet}/balances` | 2 | Every token a wallet holds on every chain, with price, value and PnL, 200 a page. | | `GET /v1/pump/users/{wallet}/created-coins` | 2 | The coins a wallet launched on pump.fun, 50 a page. | | `GET /v1/pump/users/{wallet}/fees` | 2 | Creator fees a wallet earned, day by day, over 7, 30, 90 days or all time. | | `GET /v1/pump/users/{wallet}/fees/shares` | 1 | The coins whose creator fees a wallet has a share of, with earned, claimed and unclaimed totals. | | `GET /v1/pump/users/{wallet}/trader-stats` | 1 | Volume, trade count and biggest trade over 1, 7 and 30 days and all time, by platform. | | `GET /v1/pump/users/{wallet}/streak` | 1 | A wallet's current and longest daily trading streak, with day-by-day history. | | `GET /v1/pump/search/users` | 1 | pump.fun users by name or wallet (top 20, labelled wallets included). | | `GET /v1/pump/resolve` | 1 | Says whether an address is a pump.fun user, a coin or neither, with the match. | ### pump.fun coins (reference/pump-coins.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/pump/coins/{mint}` | 1 | One coin: name, symbol, images, socials, creator, supply, price and market cap. | | `GET /v1/pump/coins/{mint}/holders/count` | 1 | How many wallets hold a coin. | | `GET /v1/pump/coins/{mint}/traders` | 2 | The pump.fun users with a position in a coin, 50 at a time, by size, recency, rank or closed PnL. | | `GET /v1/pump/coins/{mint}/top-traders` | 2 | PnL-leaderboard traders who traded a coin, and their trades in it. | | `GET /v1/pump/coins/{mint}/ath` | 1 | A coin's all-time-high market cap in USD. | | `GET /v1/pump/coins/{mint}/candles` | 2 | OHLCV candles in USD, from 1-second to 1-day bars, up to 500. | | `GET /v1/pump/coins/{mint}/sparkline` | 1 | A small price line for lists: at most 120 points. | | `GET /v1/pump/coins/{mint}/trades` | 2 | Every trade in a coin, newest first, 100 a page, with buy/sell aggregates. | | `GET /v1/pump/coins/{mint}/live` | 1 | Live stats of a coin: snipers, KOLs who traded, buys and sells, fees and tips, curve progress. | | `GET /v1/pump/coins/{mint}/market-activity` | 1 | Trades, volume, buyers, sellers and price change over 5m, 1h, 6h and 24h. | | `GET /v1/pump/coins` | 1 | pump.fun coins by newest, last trade or market cap, 60 a page (NSFW excluded). | | `GET /v1/pump/search/coins` | 1 | pump.fun coins by name, symbol or address (top 50, NSFW excluded). | ### pump.fun boards (reference/pump-boards.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/pump/boards/{board}` | 1 | pump.fun's movers or trending board (up to 150 coins), on chosen chains. | | `GET /v1/pump/leaderboard` | 1 | pump.fun's top 100 traders by PnL, daily, weekly or monthly. | | `GET /v1/pump/leaderboard/streaks` | 1 | The wallets with the longest current daily trading streaks. | | `GET /v1/pump/leaderboard/positions` | 2 | The best single positions behind the PnL leaderboard. | | `GET /v1/pump/leaderboard/payouts` | 1 | Who pump.fun paid the most USDC to in the last day, 50 a page. | | `GET /v1/pump/competitions` | 1 | pump.fun trading competitions: upcoming, live and past, with prizes and winners. | | `GET /v1/pump/competitions/{id}` | 1 | One competition with its live leaderboard. | | `GET /v1/pump/competitions/{id}/entries/{entry}` | 1 | A competition entry's 10 best tokens and each member's PnL in them. | | `GET /v1/pump/sol-price` | 0 | pump.fun's SOL/USD price. | ### pump.fun callouts (reference/pump-callouts.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/pump/users/{wallet}/callouts` | 2 | A pump.fun trader's callouts, newest first (100): thesis, call market cap, multiple, and how followers did. | | `GET /v1/pump/users/{wallet}/callout-stats` | 2 | How a trader's callouts did: hit rates, multiples, and the PnL of those who followed them. | | `GET /v1/pump/callouts/{id}` | 1 | One pump.fun callout with its author. | | `GET /v1/pump/callouts/{id}/replies` | 1 | The replies under a callout (up to 200), or only the author's own updates. | ### pump.fun batch (reference/pump-batch.md) | Endpoint | Credits | What | |---|---|---| | `POST /v1/pump/users/batch` | 5 | pump.fun profiles of up to 50 wallets; only matched wallets come back. | | `POST /v1/pump/wallets/overview` | 5 | Total value, SOL balance and first-trade time of up to 20 wallets. | | `POST /v1/pump/coins/batch` | 5 | Full coin records of up to 50 mints. | | `POST /v1/pump/users/{wallet}/pnl/coins` | 5 | One wallet's PnL in each of up to 50 coins. | | `POST /v1/pump/creators/fees/chart` | 5 | Creator fees earned by up to 20 creator wallets over time. | | `POST /v1/pump/coins/ath/batch` | 3 | All-time-high market cap of up to 60 coins. | | `POST /v1/pump/coins/market-activity/batch` | 3 | Trades, volume, traders and price change over 5m, 1h, 6h and 24h of up to 50 coins. | | `POST /v1/pump/coins/{mint}/holders/pnl` | 5 | Each of up to 50 wallets' PnL in one Solana coin. | | `POST /v1/pump/coins/{mint}/trades/by-wallets` | 5 | The trades of up to 50 wallets in one coin. | ### fomo.family users (reference/fomo-users.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/fomo/users/{handle}` | 2 | A fomo.family trader by handle: wallets, bio, counts, volume, clan. | | `GET /v1/fomo/users/{handle}/balances` | 2 | What a fomo.family trader holds now, with market data and PnL per token. | | `GET /v1/fomo/users/{handle}/positions` | 2 | A fomo.family trader's swaps, newest first. | | `GET /v1/fomo/users/{handle}/trades` | 2 | A trader's positions, open and closed, with the wallet each was traded from and any thesis. | | `GET /v1/fomo/users/{handle}/following` | 2 | The fomo.family traders a user follows, with their 24h PnL. | | `GET /v1/fomo/users/{handle}/followers` | 2 | A fomo.family trader's followers (first page), with their 24h PnL. | | `GET /v1/fomo/users/{handle}/rank` | 2 | A trader's leaderboard rank and PnL, all time and over 24h, 7d and 30d. | | `GET /v1/fomo/users/{handle}/pnl-chart` | 5 | A trader's PnL and equity curve over 1, 7 or 30 days. | | `GET /v1/fomo/users/{handle}/spotlight` | 2 | A trader's best trades and best theses. | | `GET /v1/fomo/search` | 2 | fomo.family traders by name or handle. | ### fomo.family tokens (reference/fomo-tokens.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/fomo/tokens/{chain}/{address}/holders` | 2 | The fomo.family traders holding a token, with value, PnL and thesis. | | `GET /v1/fomo/tokens/{chain}/{address}/devs` | 2 | What the token's developer wallets hold. | | `GET /v1/fomo/tokens/{chain}/{address}/stats` | 2 | Buys, sells, volumes and unique traders over 5m, 1h, 4h and 24h; holders and top-10 share. | | `GET /v1/fomo/tokens/{chain}/{address}/warnings` | 2 | fomo.family's risk warnings for a token, and whether buying or selling is disabled. | | `GET /v1/fomo/tokens/{chain}/{address}/candles` | 2 | OHLCV candles from fomo.family's market data, 1-minute to 1-week bars, up to 2,000. | | `GET /v1/fomo/tokens/{chain}/{address}/theses` | 2 | fomo.family traders' theses on a token, 100 a page, optionally only from positions above a size. | | `GET /v1/fomo/tokens/{chain}/{address}/trades` | 2 | The buys and sells of fomo.family users in one token, newest first. | | `GET /v1/fomo/tokens/batch` | 5 | Market data for up to 50 tokens on any of fomo.family's chains. | | `GET /v1/fomo/search/tokens` | 2 | Tokens by name or symbol, or one token by address. | ### fomo.family boards (reference/fomo-boards.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/fomo/leaderboard/{window}` | 1 | fomo.family's top traders by PnL over 24h, 7d, 30d or all time. | | `GET /v1/fomo/tokens/trending` | 1 | The tokens trending on fomo.family now. | | `GET /v1/fomo/tokens/most-held` | 1 | The tokens most fomo.family traders hold. | ### fomo.family clans (reference/fomo-clans.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/fomo/leaderboard/clans/{window}` | 1 | fomo.family's top 50 clans by PnL over 24h, 7d, 30d or all time. | | `GET /v1/fomo/clans/search` | 2 | fomo.family clans by name. | | `GET /v1/fomo/clans/{id}` | 2 | One clan: profile, rank and PnL for a window, top tokens and members. | | `GET /v1/fomo/clans/{id}/holdings` | 2 | What a clan's members hold together, 20 tokens a page. | ### fomo.family feed and trades (reference/fomo-feed.md) | Endpoint | Credits | What | |---|---|---| | `GET /v1/fomo/feed` | 2 | fomo.family's global activity feed: large buys and sells, theses, listings, milestones, 50 a page. | | `GET /v1/fomo/trades/{id}` | 2 | One fomo.family position with its swaps, transfers and thesis. | | `GET /v1/fomo/trades/{id}/comments` | 2 | The thesis and comments on a fomo.family position. | ### Account (reference/account.md) | Endpoint | Credits | What | |---|---|---| | `POST /v1/auth/wallet/challenge` | 0 | Starts a wallet sign-in: returns the message to sign. | | `POST /v1/auth/wallet/verify` | 0 | Finishes a wallet sign-in with the signature; returns a session token. | | `POST /v1/auth/telegram` | 0 | Starts a Telegram sign-in: a bot link to open and a secret to poll with. | | `GET /v1/auth/telegram/{id}` | 0 | Polls a Telegram sign-in; returns the session once the bot confirms. | | `POST /v1/auth/logout` | 0 | Ends the current session (204). | | `GET /v1/account` | 0 | The signed-in account. | | `GET /v1/account/keys` | 0 | The account's API keys (hints only, never the secret). | | `POST /v1/account/keys` | 0 | Makes a key; the secret (field "key") is shown once. | | `PATCH /v1/account/keys/{id}` | 0 | Changes a key's name, scopes, allowed IPs or expiry. | | `DELETE /v1/account/keys/{id}` | 0 | Revokes a key at once (204). | | `POST /v1/account/keys/{id}/rotate` | 0 | Makes a replacement key; the old one keeps working for a grace period. | | `GET /v1/account/wallets` | 0 | The account's USDC deposit addresses (Solana and EVM), made on first ask. | | `GET /v1/account/balance` | 0 | USD balance, live plan and pack credits, and the current subscription and plan. | | `GET /v1/account/deposits` | 0 | The account's last 100 deposits. | | `GET /v1/account/usage` | 0 | Calls and credits by day (and by hour for the last 48 hours), by endpoint and by key, up to a minute behind. | | `GET /v1/account/requests` | 0 | The last 200 calls made with the account's keys, newest first, kept a week: status, error code and message, credits charged, latency, key and request id (the X-Request-Id of the answer). | | `POST /v1/account/subscribe` | 0 | Buys or changes the plan from the USDC balance (needs an Idempotency-Key header). | | `POST /v1/account/packs` | 0 | Buys credits that never expire from the USDC balance (needs an Idempotency-Key header). | | `GET /v1/plans` | 0 | The public plans (price, credits, rate, streams, keys) and credit packs. |