Data

Profiles

Resolve Fomo identities by handle or id.

A profile is a Fomo identity normalized into a stable schema with a FomoData id (fp_…). FomoData keeps only public profile metadata, never emails, private messages, balances, PnL or session data. The raw upstream response is never exposed.

The profile object

object"profile": Always profile.
idstring: Stable FomoData id, e.g. fp_4KZq8mXw2T0aN6rB1cYd9E. Derived from the upstream identity, so it never changes.
handlestring: The Fomo handle with a leading @.
display_namestring | null: Public display name.
avatar_urlstring | null: Public avatar image URL.
profile_urlstring | null: Public Fomo profile link, used for attribution.
biostring | null: Public bio, when available.
verifiedboolean | null: Upstream verification badge, when known.
source"fomo" | "sandbox": Where the data came from. sandbox means clearly labelled test fixtures.
livemodeboolean: true for live data, false for sandbox data.
created_attimestamp | null: Account creation time upstream, when known.
first_seen_attimestamp: When FomoData first observed this profile.
updated_attimestamp: When FomoData last wrote this record.
source_updated_attimestamp | null: When the upstream last confirmed it.
staleboolean: Present and true only when cached data is served because the upstream was unreachable.
walletobjectComing soon: Public wallet association, { address, network }. Only present when the Wallets API is enabled and the association is public and authorized.

Retrieve a profile

Resolve a profile by handle (@milo or milo, case-insensitive) or by FomoData id (fp_…).

GET/v1/profiles/{ref}profiles:read

const profile =
  await fomo.profiles.get("@sbx_milo");

With a live key, use a real handle: fomo.profiles.get("@milo"). Unknown live handles may trigger a one-off authorized upstream lookup; known profiles are served from FomoData's store and cache.

Look up a profile

Look up by exactly one query parameter. Useful when you stored a FomoData id or the upstream Fomo user id.

Despite the collection-style path this is a lookup: the response is a single Profile object, not a list (404 PROFILE_NOT_FOUND when nothing matches). In the SDK, fomo.profiles.list({ handle }) and its alias fomo.profiles.lookup(…) both resolve to one Profile.

GET/v1/profilesprofiles:read

Query parameters

idstring: FomoData profile id, e.g. fp_123.
handlestring: Fomo handle, with or without @.
fomo_user_idstring: The upstream Fomo user id.

curl 'https://fomodata.dev/v1/profiles?id=fp_4KZq8mXw2T0aN6rB1cYd9E' \
  -H "Authorization: Bearer $FOMODATA_API_KEY"

Freshness

Profiles are cached. updated_at tells you when FomoData last wrote the record and source_updated_at when the upstream last confirmed it. If the upstream is unreachable and FomoData serves a cached copy, the object includes "stale": true. A profile.updated event fires when public metadata changes on resync; subscribe via streams or webhooks.

Errors

Status	Code	When
404	PROFILE_NOT_FOUND	No profile matches the handle or id.
422	INVALID_HANDLE	The handle isn't a valid Fomo handle.
503	UPSTREAM_UNAVAILABLE	A lookup needed the upstream and it was unavailable, with no cached copy.

Privacy

FomoData never exposes emails, private messages, auth tokens, session data, balances, PnL or private account metadata. Wallet associations stay off until they're confirmed public and authorized (WALLETS_API_ENABLED). See data sources.