API Conventions

The Tempo API follows consistent formatting rules for identifiers, amounts, timestamps, and shared query parameters. This page is a quick reference for the patterns you'll encounter on every endpoint.

For authentication and pagination, see the dedicated Authentication and Pagination pages.

Tempo API base URL

The Tempo API is served from a single base URL, with endpoints versioned under the /v1 prefix:

https://api.tempo.xyz/v1

For example: https://api.tempo.xyz/v1/tokens. See the Versioning Policy for how versions, breaking changes, and deprecations work.

Chain identifiers

Tempo runs multiple chains. Select one per request with the chainId query parameter, which accepts a chain alias or a numeric chain id:

curl 'https://api.tempo.xyz/v1/blocks?chainId=testnet' \
  --header 'Authorization: Bearer tempo:sk:...'

chainId defaults to mainnet when omitted. A sandbox API key steers an omitted chainId to testnet — see Authentication for how key environments interact with chain selection.

Resource identifiers

On-chain identifiers are 0x-prefixed lowercase hex strings. They are returned in lowercase, and are accepted case-insensitively on input.

Token amount formats

Token amounts are returned as decimal strings in the token's smallest unit, never as numbers. This preserves full precision for large values that exceed the range of a JSON number.

{
  "amount": "1000000"
}

The value above is 1000000 smallest units — for example, 1.00 of a 6-decimal stablecoin. Convert to a human-readable amount by dividing by 10 raised to the token's decimals.

Raw EVM quantities (such as gas values) use a 0x-prefixed hexadecimal integer instead, for example 0x1a (which is 26).

API timestamp formats

All datetime fields are returned in UTC, formatted as ISO 8601 with a Z suffix:

YYYY-MM-DDTHH:MM:SSZ

For example: 2024-01-01T00:00:00Z. Date-range query parameters accept the same ISO 8601 format.

API query parameters

A few conventions are shared by query parameters across endpoints:

• Booleans are the literal strings true or false (for example, ?verified=true).
• Opt-in fields are requested with a comma-separated include parameter (for example, ?include=token,totalCount). Expensive fields are computed only when you ask for them. The available values differ per endpoint and are documented on each operation.

API request IDs

Every response carries a tempo-request-id header that uniquely identifies the request. Error responses also echo it as requestId in the body. Include this value when contacting support so a request can be traced.

tempo-request-id: 0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9

API error conventions

Errors use a single, consistent envelope with a conventional HTTP status code and a stable, machine-readable error.code you branch on. See Errors for the envelope and the full code catalog.

API rate-limit conventions

Every response carries standard RateLimit-* headers, and requests that exceed quota receive 429 Too Many Requests with a Retry-After header. See Rate Limits for the full model and best practices.