fomo.family API reference

A JSON API over HTTPS. Every response is a flat object with no envelope, every timestamp is UTC in RFC 3339, and every amount is in US dollars.

Base URL: https://provadata.com

Your first request

Fetch the 24-hour leaderboard. It costs 100 credits and returns up to 150 traders, each with their wallets and evidence status.

cURL

curl "https://provadata.com/v2/leaderboard/24h?limit=10" \
  -H "Authorization: Bearer $API_KEY"

Authentication

Send your key in the Authorization header as a bearer token. x-api-key: <key> is accepted too.

A key is shown once, when it is issued. We store only its SHA-256 hash, so a lost key cannot be recovered, only replaced. A revoked key stops working within a minute.

To get a key, sign in with your email. We send a one-time code, no password; your first key is created on your first sign-in.

401 · missing or unknown key

{
  "error": "invalid_key",
  "message": "unknown or revoked API key"
}

Credits and headers

Each plan has a monthly credit balance that resets at the end of the period. Before a request runs, its maximum cost is reserved; once it finishes, the real cost is charged and the rest is returned.

Only a 2xx is billed. A 404, a 202 pending and a 503 cost nothing. Batch endpoints charge per item found, so 100 handles of which 12 exist cost 12 × 250 = 3,000 credits.

When the balance cannot cover a request, the API answers 402 credits_exhausted. There are no overage charges.

Every response

x-credits-cost: 500
x-credits-remaining: 1284500

100	leaderboard	per request
500	users/{handle}	per trader
500	wallets/{address}	per wallet
250	batch endpoints	per item found
0	me, health, v1	free

Rate limits

Each account has a token bucket: a sustained rate plus a burst. Going over returns 429 rate_limited with a Retry-After header and retryAfterSeconds in the body. Keyless routes allow 60 requests a minute per IP. Looking up handles that do not exist is limited too: after five 404s in a minute, /v2/users/{handle} returns 429 for the rest of that minute. To check a list of names, use the batch route.

1/s	Free	burst 5
5/s	Starter	burst 20
20/s	Growth	burst 60
50/s	Scale	burst 150

Errors

Every error is {"error": "<code>", "message": "…"}, sometimes with extra fields. The code is stable and meant for your program; the message is for people and may change. Errors marked "retryable": true are safe to retry after Retry-After.

400	invalid_window, invalid_limit, invalid_handle, invalid_address, too_many	Fix the request.
401	missing_key, invalid_key	Check your key.
402	credits_exhausted	Upgrade or wait for the reset.
403	account_inactive	The key is right; the account is not activated yet. See your dashboard.
404	not_found, no_snapshot, not_available	Nothing to return. Free.
429	rate_limited	Slow down.
503	busy, upstream_unavailable, unavailable	Retry shortly. Free.

Nulls and omitted fields

A field we track but do not know for this trader is null, which is never the same as 0. A field we do not provide at all is left out of the response rather than faked. Treat unknown fields as additions: we add fields without a new version, and never change what an existing one means.

GET/v2/leaderboard/{window}

Leaderboard

The newest snapshot of a board, ranked, with each trader’s wallets. previousRank is the rank in the snapshot before, or null for a newcomer.

100 creditsBilled on 200 only

Parameters

windowpath · stringrequired

24h, 7d or 30d.

limitquery · integer

1 to 150. Defaults to 150.

RequestcURL

curl "https://provadata.com/v2/leaderboard/24h?limit=10" \
  -H "Authorization: Bearer $API_KEY"

Response200

{
  "window": "24h",
  "source": "fomo",
  "capturedAt": "2026-09-24T14:00:00Z",
  "previousCapturedAt": "2026-09-24T13:00:00Z",
  "count": 150,
  "traders": [
    {
      "rank": 3,
      "previousRank": 5,
      "pnlUsd": 18402.0,
      "handle": "halvard",
      "walletsVerified": true,
      …the trader fields below
    }
  ]
}

GET/v2/users/{handle}

Retrieve a trader

A trader’s profile, windowed PnL and every wallet linked to them, each with its evidence status. If the trader is not in our wallet map yet, you get a free 202 while we check in the background; retry after retryAfterSeconds.

500 creditsBilled on 200 only

Parameters

handlepath · stringrequired

With or without a leading @. Case-insensitive.

Fields

walletListarray

Every linked wallet. status is verified when an on-chain transaction moved the wallet’s balance in step with the trader’s swap, otherwise likely.

walletsVerifiedboolean

True if at least one wallet is verified.

checkedboolean

False if nobody has searched for this trader’s wallets yet. An empty walletList means “none found” only when this is true.

pnlobject · number | null

USD profit and loss for 24h, 7d, 30d and all.

asOfobject · timestamp | null

When wallets, profile and PnL were last checked. null means never.

RequestcURL

curl "https://provadata.com/v2/users/halvard" \
  -H "Authorization: Bearer $API_KEY"

Response200

{
  "handle": "halvard",
  "userId": "u_8f21c0",
  "displayName": "Halvard",
  "twitter": null,
  "pnlUsd": 148210.7,
  "pnl": { "24h": 18402.0, "7d": -3129.4,
           "30d": 64960.0, "all": 148210.7 },
  "volumeUsd": 4120044.1,
  "trades": 1377,
  "followers": 5402,
  "wallets": { "solana": "7xKq…9fQe", "evm": "0x4a1b…e07c" },
  "walletList": [
    { "chain": "solana", "address": "7xKq…9fQe", "status": "verified" },
    { "chain": "solana", "address": "3mPd…Lw2a", "status": "likely" },
    { "chain": "bnb", "address": "0x4a1b…e07c", "status": "verified" }
  ],
  "walletsVerified": true,
  "checked": true,
  "lastActiveAt": "2026-09-24T13:58:10Z",
  "asOf": {
    "walletsCheckedAt": "2026-09-24T09:12:44Z",
    "profileCheckedAt": "2026-09-24T14:05:00Z",
    "pnlCheckedAt": "2026-09-24T14:05:00Z"
  }
}

Response202 · free

{
  "status": "pending",
  "handle": "newtrader",
  "retryAfterSeconds": 15
}

GET/v2/users?handles=a,b,c

Batch traders

Up to 100 traders in one call, answered from the wallet map only; a batch never starts a background check. Handles we do not have come back in missing; fetch them one by one if you need them.

250 credits per trader found

RequestcURL

curl "https://provadata.com/v2/users?handles=halvard,ghost" \
  -H "Authorization: Bearer $API_KEY"

Response200

{
  "items": [ …traders, as above ],
  "missing": [ "ghost" ]
}

GET/v2/wallets/{address}

Resolve a wallet

The trader who owns a Solana or EVM address, with the evidence status of that link. conflict is true if the address is tied to more than one trader; we report it rather than pick one.

500 creditsBilled on 200 only

RequestcURL

curl "https://provadata.com/v2/wallets/$ADDRESS" \
  -H "Authorization: Bearer $API_KEY"

Response200

{
  "address": "7xKq…9fQe",
  "chain": "solana",
  "status": "verified",
  "conflict": false,
  "trader": { "handle": "halvard", … }
}

GET/v2/wallets?addresses=a,b,c

Batch wallets

Up to 100 addresses in one call. Owners found come back in items, the rest in missing.

250 credits per wallet found

RequestcURL

curl "https://provadata.com/v2/wallets?addresses=$ADDRESS_1,$ADDRESS_2" \
  -H "Authorization: Bearer $API_KEY"

Response200

{
  "items": [ …owners, as above ],
  "missing": [ "9zzz…aaaa" ]
}

GET/v2/me

Account

Your plan, remaining credits, when the period ends and your rate limit. Free.

RequestcURL

curl "https://provadata.com/v2/me" \
  -H "Authorization: Bearer $API_KEY"

Response200

{
  "tier": "starter",
  "creditsRemaining": 1284500,
  "creditsMonthly": 2500000,
  "periodEnd": "2026-10-01T00:00:00Z",
  "planExpiresAt": "2026-10-24T00:00:00Z",
  "rateLimit": { "rps": 5, "burst": 20 },
  "streams": false
}

GET/health · /v1

Health and discovery

/health reports liveness and how many traders are mapped. /v1 lists every endpoint with its price. Both are free and need no key.

cURL

curl https://provadata.com/health