API keys

Compare plans →

Every method of the TraceFast REST API is called with an API key. The key goes in one request header; the plan the key belongs to decides which methods it may call, how many requests a day it gets and how fast it may send them.

The same key connects an AI agent to the TraceFast MCP server, where the methods are tools under the same plan and limits; there an agent can also sign in with a TraceFast account instead. The REST API itself takes keys only — a sign-in token sent to /api/v1 is refused with 401. AI agents that would rather not hold a key can pay per call instead — every method is also sold over x402, with no account at all.

Sending the key

Base URL: https://tracefast.xyz/api/v1
Header:   x-api-key: <your key>

curl -s https://tracefast.xyz/api/v1/chains/1/blocks/latest \
  -H "x-api-key: $TRACEFAST_API_KEY"

Without a key every method answers 401 with reason: api_key_required. The OpenAPI document needs no key, so a client can be generated from it before you have one:

https://tracefast.xyz/api/v1/openapi.json

It declares the x-api-key scheme on every method, and marks each operation with x-minimum-plan — the lowest plan that opens it: data (Enriched Data), intelligence or investigation. Every method page names the same plan. An operation without the field states no plan — that does not make it free.

Getting and managing keys

Keys are issued in the TraceFast app under Settings → API keys, on an account with a paid plan; the secret is shown once, at creation. Send it in the x-api-key header from your server — a key does not work from a browser, and belongs in a secret manager, never in a repository. Creating, rotating, disabling and revoking keys, and reading their usage and audit log, are described on Managing API keys.

Plans

Methods are grouped by what they tell you. Each plan opens more of them, and includes everything in the plan below it:

Plan	Opens
Enriched Data	blocks — their transactions, withdrawals and EIP-7702 authorizations; a transaction, its events and why it reverted; token contracts and their transfers; network token statistics; contracts — metadata, bytecode, selectors, proxy implementations; an address's overview, activity and native balance history
Intelligence	everything in Enriched Data, plus resolving a name, symbol or address to the addresses it can mean; what the TraceFast knowledge graph states about an address: attributes and relations — now, at a block, their history and their proof — counterparties, portfolio, token balances and token holders; the accounts a block touched; and the consensus layer — validator queues, block proposers and a validator's withdrawals
Investigation	everything in Intelligence, plus the deep feeds: an address's transactions, token transfers and internal transfers, a contract's events; a transaction's execution trace, its call frames page by page and its storage writes; and an address's on-chain blacklist status and events

The Free plan opens the explorer only, not the API. Every method page names the plan it needs. Prices, daily quotas, request rates and the number of keys per plan are on the pricing page.

When a key is refused

The key check answers before the method runs. Its refusals keep the usual envelope and add a reason next to the code — branch on reason:

{
  "error": {
    "code": "auth_failed",
    "message": "authentication failed: this route requires an API key",
    "reason": "api_key_required"
  }
}

Status	`reason`	What happened	What to do
401	`api_key_required`	no key was sent	send `x-api-key`
401	`invalid_api_key`	the string is not a key	check the value you send
401	`key_disabled`	the key was switched off	enable it, or use another key
401	`key_expired`	the key's validity ran out	issue a new key
401	`key_revoked`	the key was revoked	issue a new key — a revoked key never comes back
403	`plan_scope_missing`	your plan does not include this method	upgrade the plan; the key itself is fine
403	`key_scope_missing`	your plan includes this method, but the key was issued without it	issue or rotate a key that includes it
403	`endpoint_group_not_allowed`	this key may not call this method	check the plan and the key's permissions
403	`account_suspended`	the account is suspended	contact support

None of these is fixed by retrying: nothing about waiting changes the answer.

Rate limits and quotas

Each plan sets a daily request quota, a request rate and a cap on concurrent requests per key. Past a limit, a call answers 429 with one of three codes — rate_limited, concurrency_limited or quota_exceeded — and a bucket that names what refused:

`bucket`	Meaning	`Retry-After`
`base`	the plan's request rate, per key	1 second
`class:standard`, `class:heavy`, `class:extreme`	a smaller budget for costlier methods, on top of the plan's rate	the class's window
`concurrency`	too many requests in flight on this key	—
`quota_daily`	the account's daily quota is spent	—

The daily quota belongs to the account and resets at 00:00 UTC. Honour Retry-After when it is present; a spent daily quota does not come back before the reset.

Conventions — requests, responses, errors and pagination
Connect an AI agent over MCP — the same key, for AI agents
Paying with x402 — the key-less way, for AI agents
API overview — every method, by family
Pricing — plans, quotas and rates

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