Resolve a name, symbol or address

Open USDC's entity page →

The starting point when you have a name and need an address. Text is looked up among token contracts, by the symbol and name they declare, and among the names TraceFast shows for projects, exchanges, protocols and ENS names; the answer is the matching addresses, best first. An address is answered with what TraceFast shows for it: its name, how that name is presented, what kind of address it is and its token identity.

GET https://tracefast.xyz/api/v1/chains/1/resolve?q={query}

Parameter	In	Type	Notes
`q`	query	string	an address (`0x` + 40 hex, any case), or a name, ENS name, token symbol or token name — 2 to 100 characters, matched ignoring ASCII case
`limit`	query	integer, optional	1..20, default 10

chains/1 is a literal: the method serves Ethereum mainnet data. Other chain ids answer 404 chain_not_supported. Any other parameter is refused rather than ignored.

Access — an API key on the Intelligence plan or higher (plans), or no key at all: pay per call with x402 at the same path on https://mpp.tracefast.xyz/api/v1, at the price its 402 states. As a tool for AI agents: resolve_entity on the MCP server. Stable — see stability.

Response

200 application/json, here for ?q=usdc&limit=1:

{
  "data": {
    "chainId": 1,
    "query": "usdc",
    "queryKind": "text",
    "searched": ["tokens", "names"],
    "matches": [
      {
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "matchedOn": "token_symbol",
        "match": "exact",
        "name": "Circle: USDC Token",
        "nameStanding": "verified",
        "type": {
          "state": "known",
          "attributes": [
            "address_nature:account_state_ever_touched",
            "address_nature:contract_currently",
            "address_nature:ever_had_runtime_code",
            "address_nature:has_onchain_existence",
            "asset:fungible_token",
            "asset:transfers_state_backed",
            "derived:account_type"
          ]
        },
        "token": { "state": "found", "name": "USD Coin", "symbol": "USDC" }
      }
    ],
    "hasMore": true
  },
  "meta": {
    "chain": "ethereum",
    "timestamp": 1790781894330,
    "cached": false,
    "docs": "https://docs.tracefast.xyz/api/entity-resolve"
  }
}

Field	Meaning
`query`	the query as it was looked up, trimmed of surrounding whitespace
`queryKind`	`address` when `q` is an address, `text` otherwise
`searched`	for `text`: the collections the text was looked up in — `tokens` (token contracts by the symbol and name they declare) and `names` (the names TraceFast shows for projects, exchanges, protocols and ENS names). A collection missing from the list was not consulted, so no match in it means nothing. Absent for an address
`matches`	the addresses the query can mean, best first — see Order. Empty when nothing matched
`hasMore`	`true` when more addresses matched than were returned: ask with a larger `limit` or a more specific query. There is no cursor

meta states no block: the answer is about what TraceFast shows now.

One match

Field	Meaning
`address`	lowercase, `0x`-prefixed — pass it to the address methods
`matchedOn`	where the query matched: `address`, `token_symbol`, `token_name` or `name`
`match`	how closely: `exact`, `prefix`, `substring`, or `address_fragment` — the query matched only inside a text that carries a hex string of 12 characters or more, which is often an imitation. For a token, `exact` means the symbol equals the query; a name equal to it is a `prefix` match
`name`	the name TraceFast shows for the address — a project, exchange or protocol name, an ENS name, or the name a contract declares where that is what is shown. Absent when TraceFast shows the address under no name
`nameStanding`	how TraceFast presents the address: `verified` (confirmed by an official source), `normal`, `qualified` (shown with a qualifier — for example a name the contract declares about itself), `warning`, `danger` (flagged, for example as an impersonation or a scam) or `unknown`. More values may be added. Absent when TraceFast holds no presentation for the address
`impersonates`	the symbol of the asset this address is flagged as imitating. Absent when it is not flagged
`type`	what kind of address it is. `state`: `known`, `unknown` (not evaluated yet — not a denial) or `unavailable`. With `known`, `attributes` lists its proven attribute ids of the families `asset`, `address_nature` and `derived:account_type` — the ones a type is read from; the full set is attributes of an address
`token`	the token identity the contract declares. `state`: `found`, `absent` (no token metadata — not a statement that it is not a token) or `unavailable`. `symbol` and `name` are what the contract declares — verbatim, not verified

Order

Matches are ordered first by whose name it is, then by how closely it matched:

addresses TraceFast presents as verified;
projects, exchanges, protocols and ENS names TraceFast knows by name — flagged ones included, since a sanctioned protocol is still the protocol you asked for;
everything else that is not flagged, such as tokens known only by what they declare about themselves;
last, addresses flagged as imitating an asset, or flagged without a known name — shown, never hidden.

Inside each group: exact, then prefix, then substring, then address_fragment matches; then tokens with more holders; then the shorter matching text.

Reading it

Read nameStanding before you trust a name. Anyone can deploy a contract that declares the symbol USDC. A match with impersonates, or with nameStanding: danger, is listed on purpose — at the end — so that a lookup never hides a lookalike.
A token's symbol and name are claims. They are what the contract says about itself; name and nameStanding are what TraceFast shows.
An address query describes one address. queryKind: address answers that address as the only match, with matchedOn: address, whether or not TraceFast holds a name for it.
An ENS name is found when it is the address's primary name — the one TraceFast shows for it. Finding an address by any other ENS name it owns is not supported yet.
Names are read fresh, new names are found later. name, nameStanding and impersonates are current on every answer, and a candidate whose name no longer matches drops out. A name TraceFast has just started showing can take up to an hour to be found by text. While that lookup is not ready, names is missing from searched.
meta.cached speaks only of token candidates, which are kept for a few minutes. On an address query meta.cached and hasMore are always false.
No match is an empty list with hasMore: false — the collections in searched were consulted and hold nothing that matches.

Errors

HTTP	`code`	When	`details`
400	`bad_request`	`q` is missing	`reason: query_missing`
400	`bad_request`	`q` is shorter than 2 or longer than 100 characters	`reason: query_too_short` / `query_too_long`
400	`bad_request`	`q` carries control characters	`reason: query_invalid`
400	`bad_request`	`q` is a 32-byte hash — it names a transaction or a block: ask one transaction or one block	`reason: query_is_hash`
400	`bad_request`	`limit` is outside 1..20	`reason: limit_out_of_range`

Unknown parameters, the chain check and the key check's 401/403/429 are the same for every method — see conventions and API keys.

One address — the address as the chain sees it
Attributes of an address — every fact proven about it
One token — a token contract, its standard and counts
Connect an AI agent over MCP — resolve_entity as a tool
Addresses & Labels — names and labels in the app

Last updated 01 Oct 2026, 13:38 UTC · verified against TraceFast v1.0.135 · Markdown