FOMO leaderboard API: fomo.family top traders as JSON

FOMO (fomo.family) shows its traders a leaderboard in the app. If you want that leaderboard in your own product, as JSON you can poll, that's one call: GET /v1/leaderboard. This post covers the call, every field on a row, and the three things people misread.

The call

curl "https://api.fomo-api.com/v1/leaderboard?window=24h&limit=10"

No key needed for the first 10 rows. window is 24h, 7d or 30d. With a key, send it as Authorization: Bearer <API_KEY>: a free key returns 20 rows, and a paid plan returns the full top 150.

Node.js

const res = await fetch("https://api.fomo-api.com/v1/leaderboard?window=7d&limit=20", {
  headers: { Authorization: `Bearer ${process.env.FOMO_API_KEY}` },
});
const board = await res.json();
console.log(board.source, board.syncedAt);
for (const row of board.data) console.log(row.rank, row.handle, row.pnlUsd);

Python

import os, requests

r = requests.get(
    "https://api.fomo-api.com/v1/leaderboard",
    params={"window": "30d", "limit": 20},
    headers={"Authorization": f"Bearer {os.environ['FOMO_API_KEY']}"},
    timeout=10,
)
board = r.json()
for row in board["data"]:
    print(row["rank"], row["handle"], row["pnlUsd"], row["clan"])

More rows than one page holds? pageInfo.hasMore says there are, and pageInfo.nextCursor goes back in as ?cursor= for the next page.

What's on a row

• rank, handle, displayName, avatarUrl, verified: who the trader is, as FOMO shows them.
• pnlUsd: the trader's PnL for the window. On the default board this is FOMO's own figure, and reportedPnlUsd carries the same value under that name.
• clan (name and icon) and followers: the social side of the app.
• allTimePnlUsd and allTimeRank: lifetime figures, when FOMO publishes them for that trader. Often null.
• fomoLifetimeVolumeUsd, fomoNumTrades, fomoSwapCount: FOMO's lifetime counters, under their own names.
• topHoldings: the trader's three largest open positions by value, with token, network, amount, price and PnL.
• wallets: the trader's trading wallets, where we've linked and verified them. walletLinkPending tells you when we know the trader but haven't linked a wallet yet.

Two boards

The default, board=fomo-parity, serves FOMO's figures exactly as FOMO reports them to its users, labelled source: "fomo". If FOMO's latest figures are more than 2 hours old, the same board falls back to our own computed numbers and says source: "computed". Read source; don't assume it.

board=solana is always ours: realized PnL from FIFO cost basis, computed from on-chain swaps, with coverage on every row. Use it when you need a number you can audit trade by trade. The method is in how we calculate wallet PnL.

Three things people misread

1. FOMO's PnL is mark-to-market. It blends realized and unrealized into one number, so it moves with price even when the trader does nothing. pnlBasis on the response says which kind you're looking at. On FOMO rows, realizedPnlUsd and unrealizedPnlUsd are null: FOMO doesn't split them, and we don't invent a split.
2. Lifetime counters aren't window-scoped. fomoLifetimeVolumeUsd and fomoNumTrades are the same on the 24h, 7d and 30d boards. Don't divide a 24h PnL by them.
3. An empty wallets doesn't mean no wallets. It means we haven't linked one we're willing to publish yet. Check walletLinkPending.

From the leaderboard to a trader's trades

Every row has a traderId. With a key, GET /v1/traders/:traderId/trades returns that trader's last 30 days of trades across their linked wallets. ?source=onchain limits it to trades with a transaction hash you can check on a block explorer.

Get a key in the console (free, no card), or see the full reference in the docs.

Frequently asked questions

Is there an API for the FOMO leaderboard?

Yes. GET https://api.fomo-api.com/v1/leaderboard?window=24h returns the fomo.family trader leaderboard as JSON, with 7d and 30d windows too. It works without a key (10 rows); a free key returns 20 rows and a paid plan the full top 150.

Is this the official FOMO API?

No. Fomo Api is an independent product, not affiliated with FOMO (fomo.family). We publish FOMO's leaderboard figures as FOMO reports them, labelled as such on every response, alongside our own computed analytics.

How fresh is the leaderboard?

Every response carries syncedAt, the time of the capture it was built from. If FOMO's figures are more than 2 hours old, the same board serves our own computed numbers instead and the source field changes from fomo to computed.

Is the PnL realized or unrealized?

FOMO's figure is mark-to-market: realized plus unrealized on open positions, as one number. The response says so in pnlBasis. For realized-only PnL computed from FIFO cost basis, request board=solana.