API conventions

Open the block explorer →

Every TraceFast API method follows the same rules, whether it is called with an API key or paid for with x402. This page states them once; the method pages only add what is particular to a method.

Requests

Responses

A successful call answers 200 application/json with two members:

{
  "data": { "…": "…" },
  "meta": {
    "chain": "ethereum",
    "timestamp": 1789047095512,
    "cached": false,
    "asOfBlock": 25947302,
    "docs": "https://docs.tracefast.xyz/api/block-latest"
  }
}

• Numbers that can exceed 2^53 — amounts, balances, gas, wei — are JSON strings in decimal. Block heights and counts are JSON integers.
• Field names are camelCase.
• Absence is not falsity. A fact that is missing from an answer is not proven — it never means the opposite. Where a method has a place for an absent value, the page says whether it is omitted or null, and what that means.
• Methods answer with facts. The one exception is resolve, on the Intelligence plan: it returns the name TraceFast shows for an address and how TraceFast presents it (name, nameStanding, impersonates). No other method carries names or labels, and none carries where a name comes from, a taxonomy or tags.

meta

meta is stamped per response, so a cached body never carries a stale meta.

Errors

Every refusal is JSON — never plain text:

{
  "error": {
    "code": "block_not_available",
    "message": "block is past the covered history; the highest block that can be answered is 25901228",
    "details": { "reason": "block_not_available", "maxAvailableBlock": 25901228 },
    "requestId": "01a07bc5-0da1-7f3e-9c2a-…"
  }
}

• code — a stable word from the table below. Branch on it.
• message — for a human. It may be reworded; never parse it.
• details — present only when there is something to act on: a reason that refines the code, and the bound that was hit. Absent — never null — when there is nothing to add.
• requestId — quote it when you contact support. It is also in the X-Request-Id response header.

The key check (401, 403) and the rate limits (429) are described on API keys; over x402, a 402 is the payment challenge — see Paying with x402.

A 422 is not a failed request: it states what the API can and cannot answer. It is never replaced by a zero, an empty list or a truncated answer.

details.reason

Numbers a client acts on are in details, built from the same values as the sentence in message.

Data freshness

Most TraceFast methods answer up to the head of the chain. Some data is built behind the head, and the methods that serve it refuse rather than answer empty: an empty list would mean "nothing happened in this block", and that is a statement we do not have.

The refusal is HTTP 422 with error.code block_not_available:

{
  "error": {
    "code": "block_not_available",
    "message": "block is past the covered history; the highest block that can be answered is 26091091",
    "details": { "reason": "block_not_available", "maxAvailableBlock": 26091091 },
    "requestId": "01a0f2e7-0e5e-7eb0-ab47-53e3b52bffde"
  }
}

• details.maxAvailableBlock — the highest block the method can answer right now. Ask again at that block, or repeat the request later.
• maxAvailableBlock is in every 422 but one. On the methods keyed by a transaction hash — trace, call frames, why it reverted, storage writes — the data may not have reached the transaction at a moment when its own bound cannot be read either. The refusal is then reason: coverage_gap with no bound, and the only move is to retry later. Code that takes maxAvailableBlock and asks again must check that it is present. On methods keyed by a block number the same situation answers 503 instead.
• details.reason coverage_gap — a different case: the block exists, but it sits in a range that is temporarily unavailable. The bounds of the range are in coverageGapFromBlock and coverageGapToBlock. It never means "no such block" — retry later; see coverage gaps.
• HTTP 503 service_unavailable — the coverage bound could not be read. Retry with backoff.
• HTTP 404 not_found — the block is above the head of the chain: it does not exist yet.

What trails the head, as it stood on 2026-09-30. This is an example on a date, not a guarantee — the values move, so go by the response, not by this list:

An empty list on HTTP 200 always means "we looked, and there is nothing" — never "we have not looked yet".

Coverage gaps

A range of blocks can be temporarily unreadable here even though it exists on chain — a coverage gap. Any method may then answer 422 block_not_available with reason: coverage_gap and the bounds of the gap in details. The verdict comes before the read: a method keyed by a block never answers an empty page for a block inside the gap.

The same refusal covers keys whose block is not known in advance:

• A transaction hash — absence cannot be confirmed while a gap is open.
• An address or a token contract with no recorded history — its first activity, or its first transfer, could sit inside the gap, so the API answers coverage_gap rather than 404 not_found. The message names the key it is about; details is the same.
• Execution traces and the classification of failures become available minutes to hours after the transaction, sometimes later. A transaction whose trace or failure classification is not available yet is refused with the maxAvailableBlock that data has reached; coverageGapFromBlock is the next block, and coverageGapToBlock is absent because the range is open-ended. The refusal says nothing about the transaction's outcome.

Read it as "ask again later", never as "this does not exist". Requests at or below maxAvailableBlock outside the gap are unaffected, and the refusal disappears on its own when the gap closes. Retrying within seconds is pointless; within hours it is not. Where a method's reach is bounded, its meta.coverage names the bounds on every answer.

Pagination

Feeds page by keyset, never by offset — ?page= and ?offset= are refused by name.

• limit — rows per page, 1 up to the method's cap; the cap and the default are on each method page.
• nextCursor — in data while there are more rows; absent on the last page.
• cursor — pass nextCursor back unchanged, with the same filters. A cursor is sealed to its method, chain, direction and filters: altered, or reused under different ones, it answers 400 invalid_cursor. A cursor can also expire. The recovery is the same in every case — restart from the first page.
• A page holds at most limit rows and may hold fewer while nextCursor is still present: a page of large rows — an event log's data is bounded only by gas — is cut by size, never by cutting a value. A single row larger than that is served whole.
• total is stated only where it is cheap to know.

Stability

Every public method is stable since 2026-10-01. A method added later may start in beta; its page says so.

A retired method is marked deprecated in the OpenAPI document and announces itself on every response with Deprecation, Sunset and Link headers — the last pointing to its documentation and its successor. Nothing is deprecated today.

Headers

The OpenAPI document at https://tracefast.xyz/api/v1/openapi.json needs no key and answers conditional requests: its ETag is its info.version, so an unchanged document costs a 304.

Related pages

• API keys — sending the key, plans, refusals and limits
• Connect an AI agent over MCP — the same rules, as tools
• Paying with x402 — the key-less way, for AI agents
• API overview — every method, by family

Last updated 22 Oct 2026, 08:06 UTC · verified against TraceFast v1.0.261 · Markdown