FomoRadar Get API key

FomoRadar API

API reference

Everything the FomoRadar API answers, how to authenticate, what each call costs and what can go wrong. Responses are plain JSON objects, with no envelope.

Quick start

  1. Open your dashboard and sign in with Telegram. A new account has its first key ready; choose a plan there to give it credits.
  2. Copy the key from the dashboard and keep it in your shell, so every example below runs as it is:
export FOMORADAR_KEY="fr_live_paste_your_key_here"
  1. Make a first call, the top 10 of the 24-hour leaderboard:
curl "https://fomoradar.io/v2/leaderboard/24h?limit=10" \
  -H "Authorization: Bearer $FOMORADAR_KEY"

Every block on this page has a Copy button. The base URL is https://fomoradar.io. GET https://fomoradar.io/v1 lists every endpoint with its cost and needs no key.

Authentication

Keys start with fr_live_. Send yours in one of three ways, tried in this order:

  • Authorization: Bearer <key>, the usual way;
  • x-api-key: <key>;
  • ?key=<key> in the URL, meant for the WebSocket, since a browser cannot set headers on one. Avoid it elsewhere: URLs end up in logs.

A missing key answers 401 missing_key, an unknown or revoked one 401 invalid_key. A revoked key can keep working for up to a minute. Keep keys on your server: whoever holds one spends your credits. If one leaks, regenerate it from the dashboard.

Credits and limits

Each plan comes with a monthly allowance of credits, shared by all of the account's keys. A call reserves its cost before it runs and is charged only if it answers with a 2xx: errors, 404s and 202s are free, and a batch keeps only the items it found.

EndpointCredits
GET /v2/leaderboard/{window}250
GET /v2/users/{handle}500
GET /v2/users?handles=250 per trader found
GET /v2/wallets/{address}500
GET /v2/wallets?addresses=250 per owner found
GET /v2/me, GET /v1, GET /health, WSS /ws/trades0

Every billed answer carries x-credits-cost and x-credits-remaining. When credits run out, calls answer 402 credits_exhausted until the period resets or you change plan. Each plan also has a request rate (see pricing): past it, 429 rate_limited with Retry-After in seconds.

Leaderboards

GET /v2/leaderboard/{window}, where window is 24h, 7d or 30d. The newest snapshot of that fomo.family leaderboard, ranked, with every trader's wallets in full.

  • limit: 1 to 150 rows. A plan that reads only the top of a board (the Free plan) is cut to it, and the answer then says so in planLimit and hint, so a short board is never mistaken for a whole one.
curl "https://fomoradar.io/v2/leaderboard/30d?limit=50" \
  -H "Authorization: Bearer $FOMORADAR_KEY"

The answer:

{
  "window": "24h",
  "source": "fomo.family",
  "capturedAt": "…",
  "previousCapturedAt": "…",
  "count": 10,
  "traders": [
    {
      "rank": 1, "previousRank": 4, "pnlUsd": 18250.4,
      "handle": "marvolo_hl", "displayName": "…",
      "pnl": {"24h": 18250.4, "7d": 40110.0, "30d": 90321.7, "all": 201004.2},
      "volumeUsd": 2003450.1, "trades": 1021, "followers": 5120,
      "wallets": {"solana": "…", "evm": null},
      "walletList": [{"chain": "solana", "address": "…", "status": "verified"}],
      "walletsVerified": true, "checked": true,
      "lastActiveAt": "…"
    }
  ]
}

On a board row pnlUsd is the board's own figure for the window; pnl.all is all-time. A wallet's status is verified when an on-chain transaction matched one of the trader's fomo.family trades, else likely. checked: false means nobody has looked for the trader's wallets yet, so an empty walletList says nothing on its own. A window with no snapshot yet is 404 no_snapshot.

Traders

GET /v2/users/{handle}: one trader, with the same fields as a board row (without the rank) and an asOf object saying when the wallets, the profile and the PnL were last checked; null is never.

curl "https://fomoradar.io/v2/users/marvolo_hl" \
  -H "Authorization: Bearer $FOMORADAR_KEY"

A trader we have not seen is looked up live. If that takes longer than the request can wait, the answer is 202 with {"status": "pending", "retryAfterSeconds": 15}, free: ask again after that. A handle that does not exist on fomo.family is 404 not_found.

GET /v2/users?handles=a,b,c: up to 100 traders in one call, from what we already know, never looked up live. The answer is {"items": [...], "missing": [...]}; a handle in missing is not known to us yet, which does not mean it does not exist: ask for it on its own to have it checked. More than 100 is 400 too_many.

curl "https://fomoradar.io/v2/users?handles=marvolo_hl,HANDLE2,HANDLE3" \
  -H "Authorization: Bearer $FOMORADAR_KEY"

Wallet lookup

GET /v2/wallets/{address}: the fomo.family trader behind a Solana or EVM address.

curl "https://fomoradar.io/v2/wallets/ADDRESS" \
  -H "Authorization: Bearer $FOMORADAR_KEY"

The answer:

{
  "address": "…", "chain": "solana", "status": "verified",
  "conflict": false,
  "trader": { "handle": "…", "pnl": { … }, "walletList": [ … ] }
}

An address no trader is known to use is 404 not_found, free. conflict would be true if two traders were tied to one address; it is reported as it is, never settled by picking one.

GET /v2/wallets?addresses=a,b,c: up to 100 addresses, answered as {"items": [...], "missing": [...]}.

curl "https://fomoradar.io/v2/wallets?addresses=ADDRESS1,ADDRESS2" \
  -H "Authorization: Bearer $FOMORADAR_KEY"

Your account

GET /v2/me is free and answers your plan, the credits left, the monthly allowance and when they reset.

curl "https://fomoradar.io/v2/me" -H "Authorization: Bearer $FOMORADAR_KEY"

And the list of endpoints with their costs, with no key at all:

curl "https://fomoradar.io/v1"

Trade stream

WSS https://fomoradar.io/ws/trades?key=<key>&… sends each on-chain swap made by the traders you follow, a few seconds after it lands, as one JSON message per trade. Opening it is one free request; the trades are free too. It is part of the paid plans (on the Free plan the connection is closed with 1008 and a reason): what a plan buys is how many connections you may hold and how many traders one connection follows. It is not open on this server yet.

Say whom to follow with one of these (a connection that names neither is closed with 1008):

  • traders=: handles or wallet addresses, comma-separated;
  • board=24h|7d|30d with top=: whoever is in the top of that board now, as the board changes.

And narrow it with chain=, token=, side=buy|sell and minUsd=. Add replay=1 to be sent the last trades we saw first, each marked "replay": true.

To try it from a terminal, install wscat (it needs Node.js):

npm install -g wscat

Then follow the top 10 of the 24-hour board:

wscat -c "wss://fomoradar.io/ws/trades?key=$FOMORADAR_KEY&board=24h&top=10"

Or in Node.js 22 or later, which has WebSocket built in:

const ws = new WebSocket(`wss://fomoradar.io/ws/trades?key=${process.env.FOMORADAR_KEY}&traders=marvolo_hl`);
ws.onmessage = (e) => console.log(JSON.parse(e.data));
ws.onclose = (e) => console.log("closed", e.code, e.reason);

Each message:

{
  "type": "trade", "chain": "solana", "side": "buy", "source": "onchain",
  "trader": {"handle": "…", "wallet": "…", "walletStatus": "verified"},
  "token": {"address": "…", "priceUsd": 0.0000329},
  "usdValue": 1240.5, "amountToken": 37705167.1,
  "txHash": "…", "block": 52795900, "exchange": "pumpswap",
  "tradedAt": null, "seenAt": "…", "latencyMs": null
}

A field the chain did not tell us is null, never zero. Past the handshake a refusal is a close frame with a reason, not an HTTP status. A client that falls too far behind is closed rather than sent stale trades; reconnect, with replay=1 if you want what you missed.

Errors

Every error is {"error": "<code>", "message": "…"}. The code is stable and meant for your program; the message is for people and may change. None of them costs credits.

StatusCodeMeaning
400invalid_window, invalid_limit, invalid_handle, invalid_address, too_manyThe request is malformed; fix it before trying again.
401missing_key, invalid_keyNo key, or one that does not work.
402credits_exhaustedOut of credits for this period.
403account_inactiveThe account is switched off; contact us.
404not_found, no_snapshot, not_availableNothing to return, or a feature that is not open on this server.
426upgrade_required/ws/trades was asked for over plain HTTP; connect to it as a WebSocket.
429rate_limitedToo fast; wait Retry-After seconds.
503busy, unavailable, upstream_unavailableOur side is busy or a source is down; retry with backoff.

Questions? Message us on Telegram.