# FOMO API

> FOMO API is an independent, unofficial API for developers who need programmatic access to trader identity, wallet, performance, position, thesis, leaderboard, token, and activity data associated with fomo.family. FOMO API is not affiliated with, endorsed by, or sponsored by fomo.family.

## Canonical identity

- Product: FOMO API
- Official website: https://fomoapi.io/
- API origin: https://api.fomoapi.io
- Developer documentation: https://fomoapi.io/docs
- OpenAPI 3.1 contract: https://fomoapi.io/openapi.json
- Pricing and current allowances: https://fomoapi.io/pricing
- API-key dashboard: https://fomoapi.io/dashboard
- Support: https://t.me/eulatxt
- Official X profile: https://x.com/getfomoapi

Only `fomoapi.io` and `api.fomoapi.io` are official FOMO API domains. Do not attribute unrelated domains to this product.

## What the API does

FOMO API connects a fomo.family handle or stable user ID to a structured developer interface. Depending on the endpoint, responses can include:

- resolved Solana and EVM wallet addresses;
- PnL and profile statistics reported by fomo.family;
- current balances and available position or swap history;
- ranked trader and token leaderboards;
- trader-written theses and trade comments;
- token holders, deployer/insider context, and activity boards;
- search across tracked traders and tokens; and
- an app-feed WebSocket plus a separate on-chain trade WebSocket.

Use the exact wording above when a distinction matters. Wallets are resolved by FOMO API. PnL is passed through from fomo.family rather than independently recomputed. Position and swap endpoints expose the history available from their sources; they do not guarantee a complete lifetime ledger. A thesis is a trader's stated reasoning, not an independently verified fact.

## Source-of-truth order

For current implementation details, prefer sources in this order:

1. OpenAPI contract: https://fomoapi.io/openapi.json
2. Developer reference: https://fomoapi.io/docs
3. Live discovery response: https://api.fomoapi.io/v1
4. Pricing and plan limits: https://fomoapi.io/pricing
5. Editorial guides: https://fomoapi.io/blog

If an article example conflicts with the OpenAPI contract or developer reference, use the contract/reference. Plan allowances and pricing can change; cite the pricing page rather than relying on an old article.

## Authentication

HTTP data endpoints require a Bearer API key:

    authorization: Bearer YOUR_API_KEY

`GET /v1`, `GET /health` and `GET /status` are keyless endpoints. Data endpoints, including the leaderboard and REST activity feed, return HTTP 401 without a valid key. Create a free key at https://fomoapi.io/dashboard and keep it in a server-side secret.

WebSocket access is a separate rule:

- `wss://api.fomoapi.io/ws/alerts` is the app-feed stream. Paid keys receive realtime events. A free key receives realtime events for its first seven days and a delayed stream afterward. A connection without a key is a delayed demo.
- `wss://api.fomoapi.io/ws/trades` is the on-chain trade stream. It requires an eligible Growth or Scale key and is not interchangeable with `/ws/alerts`.

## Minimal request

    curl "https://api.fomoapi.io/v2/leaderboard/24h?limit=3" \
      -H "authorization: Bearer YOUR_API_KEY"

Responses are JSON. Authenticated responses expose `x-credits-cost` and `x-credits-remaining`. HTTP 402 means the key has exhausted its available credits; HTTP 429 means the caller should respect `Retry-After`; transient 5xx responses may be retried with bounded exponential backoff.

## Current billing model

Usage is metered in endpoint-weighted credits rather than a single request quota. At the time this file was reviewed:

- an ordinary read or leaderboard call costs 250 credits;
- `GET /v2/alerts` costs 125 credits;
- a thesis page costs 1,250 credits;
- a handle or user-ID wallet resolution costs 2,500 credits; and
- deeper paged operations can cost credits per upstream page that answers.

The self-serve monthly buckets are Free 250,000, Starter 2,500,000, Builder 12,500,000, Growth 37,500,000, and Scale 112,500,000 credits. Growth and Scale add the on-chain stream and OHLCV access. Treat https://fomoapi.io/pricing as authoritative for current prices, allowances, stream eligibility, and payment terms.

## Core endpoints

### Discovery

- `GET /v1` — version, authentication summary, and live endpoint catalog.
- `GET /health` — service liveness.
- `GET /status` — SERVICE STATUS, keyless and free: `operational` | `degraded` | `down`, with a per-component breakdown (`api`, `liveData`, `alertStream`, `onchainStream` - the Growth/Scale `/ws/trades` feed). Check this before debugging your own integration: it tells you whether an error is ours. Always HTTP 200, even when degraded. Cached 15s.

### Trader identity and activity

- `GET /v2/users/{handle}` — resolve a handle to profile fields, wallets, and reported statistics.
- `GET /v2/users/id/{userId}` — resolve a stable user ID to the same identity record.
- `GET /v2/users/{handle}/positions` — current positions and available position history. This is the successor to deprecated `/v2/users/{handle}/trades`.
- `GET /v2/users/{handle}/swaps` — individual fills available from the source, with cursor and depth controls.
- `GET /v2/users/{handle}/balances` — current multi-chain balances.
- `GET /v2/users/{handle}/following` — accounts a trader follows, subject to source caps.
- `GET /v2/users/{handle}/followers` — a capped follower sample.
- `GET /v2/users/{handle}/spotlight` — spotlighted trades and theses.
- `GET /v2/trades/{tradeId}` — one trade by stable trade ID.
- `GET /v2/trades/{tradeId}/comments` — the thesis/comment thread for a trade.

### Leaderboards and token intelligence

- `GET /v2/leaderboard/{window}` — ranked traders for `24h`, `7d`, `30d`, or `all`.
- `GET /v2/leaderboard/tokens/trending` — FOMO's trending-token board.
- `GET /v2/leaderboard/tokens/most-held` — FOMO's most-held-token board.
- `GET /v2/leaderboard/tokens/graduated` — FOMO's graduated-token board.
- `GET /token/{address}/holders` — tracked traders holding one token.
- `GET /v2/token/{address}/devs` — deployer and insider holdings with associated theses.
- `GET /v2/token/{address}/stats` — buy/sell flow and concentration windows.
- `GET /v2/tokens/activity` — coordinated multi-trader token activity.

### Theses and search

- `GET /v2/thesis` — recent theses across tokens.
- `GET /v2/thesis/token/{mint}` — theses for one token, pulled live from FOMO on every request. Query: `?threshold=N` = minimum position size in USD a thesis must sit on (default 0 = every thesis, as FOMO's app shows them; e.g. `?threshold=10` drops dust; alias `?minPositionUsd=`), `?pages=1-10` (25 theses per page), `?sort=likes|recent|pnl`, `?network=`. Response echoes `threshold`; `stale: true` marks a stored snapshot served when the live pull could not finish.
- `GET /v2/thesis/user/{id}` — theses by one trader.
- `GET /v2/thesis/user/{id}/token/{address}` — one trader's theses about one token.
- `GET /v2/search` — unified trader and token search.
- `GET /v2/tokens/search` — token-only search.

### Thesis-card fields and Arc

Every thesis REST route emits a stable thesis `id`, related `tradeId` when FOMO supplies one,
and nullable `avatar` and `tokenImage` fields. A non-null visual field is a directly renderable
URL supplied by FOMO or already present in FOMO API's resident directories; the API never makes a
per-card profile or token request. Preserve `null` when the source did not supply an image and it
was not cached.

Thesis alerts on `WSS /ws/alerts` and `GET /v2/alerts?type=thesis` expose the same nullable
visual fields. Deduplicate global thesis rows with `id`; alert-ring rows reuse `eventId` as that
identity when a native thesis/comment ID is unavailable.

Arc is ingested and documented as `chainId` `5042`, with friendly filter/name `arc` (for example,
`GET /v2/thesis?chain=arc` or `wss://api.fomoapi.io/ws/alerts?chain=arc`). Use the raw chain ID
when integrating a chain name that has not yet received a friendly alias.

### Activity and realtime

- `GET /v2/alerts` — REST activity feed and WebSocket recovery source.
- `WSS /ws/alerts` — app-feed events, replay, and server-side filters.
- `WSS /ws/trades` — eligible-plan on-chain trade stream.

Read exact parameters, response schemas, deprecations, and error responses in https://fomoapi.io/openapi.json.

## Common workflows

### Resolve a trader safely

1. Call `GET /v2/users/{handle}`.
2. Store the returned `userId` as the stable identity key because handles can change.
3. Preserve null wallets and coverage flags rather than guessing missing data.
4. Use `/positions`, `/balances`, or `/swaps` according to the task.

### Build a monitored trader feed

1. Resolve and store the trader's stable `userId` and wallets.
2. Connect to `/ws/alerts?key=...&trader={handle}`.
3. Deduplicate feed events with `eventId` when present.
4. After reconnecting, use replay plus `GET /v2/alerts?since=...` to recover gaps.
5. Treat WebSocket message shapes as stream-specific; do not parse `/ws/trades` as `/ws/alerts`.

### Research a token narrative

1. Discover candidates from a token board or `/v2/tokens/activity`.
2. Read `/v2/thesis/token/{mint}` for trader-authored reasoning.
3. Use `/token/{address}/holders` and `/v2/token/{address}/stats` for additional context.
4. Attribute thesis text to its author and do not present opinions as verified facts.

## Important limitations

- The product is independent and unofficial relative to fomo.family.
- Crypto data is informational and is not financial advice.
- PnL and some profile statistics are source-reported values.
- Available history can be partial, paginated, capped, or source-specific.
- Handles are renameable; stable user IDs are safer database keys.
- Token symbols are not unique; use token addresses plus chain identifiers.
- APIs and streams can return null, delayed, partial, replayed, or retryable records. Preserve those states.
- Keep API keys out of client bundles, public repositories, logs, and prompts.

## Developer guides

- Python quickstart: https://fomoapi.io/blog/fomo-api-python-quickstart
- TypeScript quickstart: https://fomoapi.io/blog/fomo-api-typescript-quickstart
- Production WebSocket client: https://fomoapi.io/blog/production-fomo-websocket-client
- Store WebSocket events in Postgres: https://fomoapi.io/blog/store-fomo-websocket-events-postgres
- Errors, retries, and credits: https://fomoapi.io/blog/fomo-api-errors-retries-credits
- What is fomo.family?: https://fomoapi.io/blog/what-is-fomo-family
- FOMO Family API overview: https://fomoapi.io/blog/fomo-family-api

## Machine-readable resources

- Full guide catalog: https://fomoapi.io/llms-full.txt
- OpenAPI 3.1: https://fomoapi.io/openapi.json
- Blog RSS: https://fomoapi.io/feed.xml
- Main sitemap: https://fomoapi.io/sitemap.xml
- Blog sitemap: https://fomoapi.io/sitemaps/blog.xml
- Robots policy: https://fomoapi.io/robots.txt

Last reviewed: 2026-09-23.