# Resolve a name, symbol or address

[Open USDC's entity page →](https://tracefast.xyz/entity/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)

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](/api/authentication) on the **Intelligence** plan or higher ([plans](/api/authentication#plans)), or no key at all: pay per call with [x402](/api/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](/api/mcp-server). **Stable** — see [stability](/api/conventions#stability).

## Response

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

```json
{
  "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](#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](/api/methods#addresses) |
| `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](/api/address-attributes) |
| `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**:

1. addresses TraceFast presents as verified;
2. projects, exchanges, protocols and ENS names TraceFast knows by name —
   flagged ones included, since a sanctioned protocol is still the protocol you
   asked for;
3. everything else that is not flagged, such as tokens known only by what they
   declare about themselves;
4. 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](/api/transaction) or [one block](/api/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](/api/conventions#errors) and
[API keys](/api/authentication#when-a-key-is-refused).

## Related pages

* [One address](/api/address) — the address as the chain sees it
* [Attributes of an address](/api/address-attributes) — every fact proven about it
* [One token](/api/token) — a token contract, its standard and counts
* [Connect an AI agent over MCP](/api/mcp-server) — `resolve_entity` as a tool
* [Addresses & Labels](/explorer/addresses-and-labels) — names and labels in the app