API reference · Tokens

Retrieve a token

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

Scopes:tokens:readRate class:heavyFlag:TOKENS_API_ENABLED

Normalized token metadata plus thesis counters. For live keys an unknown symbol is looked up once through the authorized upstream's token search.

All counts are derived from theses FomoData ingested from its authorized upstream since first_seen_at (metrics_scope: "ingested") — not Fomo's all-time totals.

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/tokens/$RUN?chain=robinhood' \
  -H "Authorization: Bearer $FOMODATA_API_KEY"

Try it in the playground

Parameters

Path parameters

refstringrequired: Token reference: tk_… id, contract/mint address, chain:address, $RUN or RUN (case-insensitive). A symbol on several chains returns 409 AMBIGUOUS_TOKEN — pass ?chain= or the address.

Query parameters

chainstring: Narrow to one chain, e.g. robinhood, solana, base. Test keys: sandbox.

Response

200 The token

application/jsonToken

objectenumrequired"token"
idstringrequired
symbolstringrequired
namestring | nullrequired
chainstringrequired
chain_idinteger | nullrequired
addressstringrequired
logo_urlstring (uri) | nullrequired
fomo_urlstring (uri) | nullrequired
thesis_countintegerrequiredTheses FomoData has ingested for this token (see metrics_scope).
unique_thesis_authorsintegerrequired
recent_thesis_countintegerrequiredTheses in the last 24 hours.
first_seen_atstring (date-time)required
last_activity_atstring (date-time) | nullrequired
metrics_scopeenumrequiredCounts cover theses FomoData has observed since first_seen_at — not Fomo's all-time totals."ingested"
sourceenumrequiredWhere the data came from. sandbox = clearly-labelled test fixtures."fomo""sandbox"
livemodebooleanrequired
updated_atstring (date-time)required
source_updated_atstring (date-time) | nullrequired
staleboolean

200 · exampleJSON

{
  "object": "token",
  "id": "string",
  "symbol": "$RUN",
  "name": "string",
  "chain": "robinhood",
  "chain_id": 4663,
  "address": "string",
  "logo_url": "https://example.com",
  "fomo_url": "https://example.com",
  "thesis_count": 0,
  "unique_thesis_authors": 0,
  "recent_thesis_count": 0,
  "first_seen_at": "2026-10-07T10:04:12.000Z",
  "last_activity_at": "2026-10-07T10:04:12.000Z",
  "metrics_scope": "ingested",
  "source": "fomo",
  "livemode": true,
  "updated_at": "2026-10-07T10:04:12.000Z",
  "source_updated_at": "2026-10-07T10:04:12.000Z",
  "stale": true
}

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)
`409`	Conflict (e.g. ambiguous token symbol)
`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