API reference · Profiles

Retrieve a profile

GEThttps://fomodata.dev/v1/profiles/{ref}

Scopes:profiles:readRate class:heavyFlag:PROFILES_API_ENABLED

Resolve a Fomo identity by handle (@milo), FomoData id (fp_…) or Fomo user id.

Resolution order: FomoData's index first; for live keys an unknown handle is looked up once through the authorized upstream (misses are cached for 10 minutes). Only public profile metadata is returned — never PnL, balances or private account data.

Live keys read real Fomo data FomoData ingested from its authorized upstream; test keys read clearly-labelled sandbox data (livemode: false, source: "sandbox"). Objects carry updated_at / source_updated_at. When cached data is served because the upstream could not be reached, the object has stale: true.

Example request

curl 'https://fomodata.dev/v1/profiles/@milo' \
  -H "Authorization: Bearer $FOMODATA_API_KEY"

Try it in the playground

Parameters

Path parameters

refstringrequired: @milo, milo, a FomoData id (fp_…) or a Fomo user id.

Response

200 The profile

application/jsonProfile

objectenumrequired"profile"
idstringrequired
handlestringrequired
display_namestring | nullrequired
avatar_urlstring (uri) | nullrequired
profile_urlstring (uri) | nullrequired
biostring | nullrequired
verifiedboolean | nullrequired
sourceenumrequiredWhere the data came from. sandbox = clearly-labelled test fixtures."fomo""sandbox"
livemodebooleanrequired
created_atstring (date-time) | nullrequiredAccount creation time upstream, when known.
first_seen_atstring (date-time)requiredWhen FomoData first observed this profile.
updated_atstring (date-time)required
source_updated_atstring (date-time) | nullrequired
staleboolean
walletobjectOnly present when the Wallets API is enabled and the association is public/authorized.+ 2 child attributes
- addressstringrequired
- networkstringrequired

200 · exampleJSON

{
  "object": "profile",
  "id": "fp_4KZq8mXw2T0aN6rB1cYd9E",
  "handle": "@milo",
  "display_name": "Milo",
  "avatar_url": "https://example.com",
  "profile_url": "https://fomo.family/profile/milo",
  "bio": "string",
  "verified": true,
  "source": "fomo",
  "livemode": true,
  "created_at": "2026-10-07T10:04:12.000Z",
  "first_seen_at": "2026-10-07T10:04:12.000Z",
  "updated_at": "2026-10-07T10:04:12.000Z",
  "source_updated_at": "2026-10-07T10:04:12.000Z",
  "stale": true,
  "wallet": {
    "address": "string",
    "network": "evm"
  }
}

Errors

Status	When
`401`	Missing, invalid, revoked or expired API key
`403`	Insufficient scope, live access not approved, or history limit
`404`	Not found (or feature disabled)
`422`	Validation failed
`429`	Rate limit or quota exceeded
`503`	Upstream unavailable

All errors use the standard envelope. See error codes for every code value.

← All endpoints openapi.json