Entities

Every entity filter in API v3 takes an id, not a name. GET /v3/entities turns what you hold into that id.

btc · $BTC · wbtc · bitcoin · 0x2260fa…c599
        │
        ▼  GET /v3/entities
b23e0b47-deec-4161-b49c-7e2652f07fe6   (Bitcoin)
        │
        ▼  entityIds on events, storylines, arcs, calls, episodes
           entityId on positioning

Resolve once and cache the id. If a request later answers Unknown id, resolve again.

It matches exactly. It is not a search. A prefix or a misspelling returns nothing. Telegram channels have no id, and neither has an address nobody has catalogued: find those in trending contracts.

Two Kinds of Identifier

	Entity id	X handle
Looks like	b23e0b47-deec-4161-b49c-7e2652f07fe6	VitalikButerin, with or without @
Names	A token, equity, project, person or organisation	An X account
Comes from	/v3/entities, or an entity, asset or impacts[].entityId in any response	Top accounts, an entity's handle, a call's handle
Goes to	entityIds, entityId	handle on calls and episodes

A person is not an account. Vitalik Buterin is an entity; @VitalikButerin is his X account. Events filter on the person; calls and standing on the account. The entity's handle leads to the account, and q=@VitalikButerin leads back:

{
  "id": "adba4f64-5471-4a80-a1e2-8bec7ad0cc45",
  "entityType": "person",
  "name": "Vitalik Buterin",
  "handle": "VitalikButerin"
}

A project and its token are two entities. Over 29 days, the UNI token returned 28 events and the Uniswap project 41, only 2 of them shared. Pass both ids to cover both: each event comes back once.

Asset Families

One asset in all its forms gets one id: BTC, WBTC and cbBTC are all Bitcoin; NVDA and its tokenised versions are all Nvidia.

• Every form resolves to the family. q=wbtc returns Bitcoin's id, and matchedOn says which identifier hit.
• A family id filters every form. Bitcoin's events include WBTC's.
• Responses name the family, never a form inside it.

Not every form is grouped yet: q=btc also returns Osmosis allBTC with its own id, covering only itself. Check name. A tokenised equity resolves to the equity: q=nvdax returns Nvidia with entityType: equity. People, projects and organisations have no families.

Resolve an Identifier

GET /v3/entities: entities whose identifier matches q exactly, best match first. Case and surrounding spaces are ignored.

q	Returns
sol, $SOL, solana	Solana, first
sola	SOLA AI. Not a prefix of Solana
vitalik	Nothing
vitalik buterin, @VitalikButerin	The person
tesla	Nothing. The registered name is Tesla, Inc. Common Stock
tsla, BBG000N9MNX3, 0001318605, 1318605	Tesla. tsla also returns a token TSLA, second

{
  "entities": [
    {
      "id": "584f4b42-abf9-4bf4-b5d5-193531f4ab43",
      "entityType": "token",
      "name": "Bio Protocol",
      "symbol": "BIO",
      "handle": null,
      "matchedOn": "symbol",
      "score": 0.9,
      "externalIds": {
        "coingeckoId": "bio-protocol",
        "figi": null,
        "cik": null
      }
    },
    {
      "id": "54cc5269-fa91-4e5a-b8a1-d4a38534c303",
      "entityType": "equity",
      "name": "Bio-Rad Laboratories, Inc.Class A",
      "symbol": "BIO",
      "handle": null,
      "matchedOn": "symbol",
      "score": 0.9,
      "externalIds": {
        "coingeckoId": null,
        "figi": "BBG000DY28W5",
        "cik": "0000012208"
      }
    }
  ],
  "nextCursor": "P5O7xFKK.MC45fDAuMDAwOTA3NDQxMDE2MzMzOTM4M3wxODA3NA",
  "hasMore": true
}

GET /v3/entities?q=bio&limit=2, read on 6 October 2026: a token and an equity sharing the ticker BIO. Both score 0.9; the token ranks higher among tokens than Bio-Rad among equities, so it comes first.

Field	Meaning
id	The id to pass on. For a token or equity, its family's
entityType	token, equity, project, person or organisation
name, symbol	symbol on tokens and equities only. name can be null
handle	Its X account, the most-followed one. Null if none. Store the id: handles change
matchedOn, score	Which identifier q hit, and how strongly. Not a confidence
externalIds	coingeckoId, figi, cik, where we hold them

How results rank. By score, then by each asset's market rank within its own class, so a top coin beats an obscure stock sharing its ticker. People, projects and organisations come after ranked assets.

matchedOn	score
contractAddress, handle written with @, externalId for a FIGI or CIK	1.0
contractAddress on another chain than the address's home chain	0.95
symbol, externalId for a CoinGecko id, handle written without @	0.9
cashtag	0.85
name	0.8
alias	0.6
tickerRoot, exchangeSymbol	0.5

A CoinGecko id or a bare handle scores as a ticker because short words collide: uni is also a small token's CoinGecko id. An address several tokens share ranks the one on its home chain first (Solana for base58; Ethereum, Base, Arbitrum, BNB Chain, Optimism, Polygon, Avalanche for 0x): wrapped SOL returns Solana at 1.0, then Ethereum and Fogo at 0.95.

A word can be both a small token's ticker and a leading asset's name. A token or equity hit on any lane scoring 0.9 or less, other than an address, scores 0.5 lower when another asset in the results ranks at least 20 times higher in its own class. apple returns Apple Inc. (alias, 0.6) before the APPLE memecoin (symbol, 0.4), and dogwifhat returns WIF (name, 0.8) before DOGWIFHAT.

Parameter	Values	Default	Notes
q	1 to 128 characters, required		A ticker, $cashtag, name, @handle, address, CoinGecko id, FIGI or CIK
entityType	token, equity, project, person, organisation, a list	all	Narrows the match
limit	1 to 200	10
cursor

No match is a 200 with an empty list. Try the ticker, the full registered name, the @handle or an external id.

Choosing a Match

A ticker is not unique: q=btc returns ten rows at 0.9, Bitcoin first.

# Wrong: pick by symbol. All ten rows have symbol "BTC"
entities.filter(e => e.symbol === "BTC")   // ten rows, no way to choose

# Right: take the first row, then check its name
entities[0]                                   // Bitcoin

# Better, when you know the kind: narrow first
GET /v3/entities?q=btc&entityType=token&limit=1

Then check name: q=uni returns Uniswap, then a token named Uni. To be sure, resolve by something unique: a contract address, FIGI or CIK scores 1.0. A fund company's CIK returns every fund it files for.