<!-- tempo-docs-context -->
> Source: [/docs/api/conventions](https://tempo.com/developers/docs/api/conventions.md)
> Section: [API reference](https://tempo.com/developers/docs/api.md). Tempo API reference: authentication, conventions, endpoints grouped by product, Console management endpoints, JSON-RPC, and the indexer. An API key authenticates API requests; an account signing key authorizes transactions.
> [Documentation index](https://tempo.com/developers/llms.txt) · [Docs skill](https://tempo.com/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.com/developers/llms.txt) and Markdown pages directly.

# Tempo API conventions and base URL

The Tempo API uses the same formatting rules for identifiers, amounts, timestamps, and shared query parameters on every endpoint.

For authentication and pagination, see the dedicated [Authentication](https://tempo.com/developers/docs/api/authentication) and [Pagination](https://tempo.com/developers/docs/api/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](https://tempo.com/developers/docs/api/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:

| Chain | Alias | Chain id |
| --- | --- | --- |
| Mainnet | `mainnet` | `4217` |
| Moderato testnet | `testnet` | `42431` |

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

`chainId` defaults to `mainnet` when omitted. Sandbox keys must explicitly select a non-mainnet chain, such as `chainId=testnet`. See [Authentication](https://tempo.com/developers/docs/api/authentication).

## Resource identifiers

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

| Identifier | Format | Example |
| --- | --- | --- |
| Account address | `0x`-prefixed, 20 bytes (40 hex chars) | `0xbe058e1c4df8a4366a387bf595b284246a93039e` |
| Token address | `0x`-prefixed, 20 bytes; TIP-20 tokens start with `0x20c` | `0x20c0000000000000000000008f5425160ebe5525` |
| Transaction / block hash | `0x`-prefixed, 32 bytes (64 hex chars) | `0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665` |

:::info
Treat identifiers as opaque strings. Always compare them in lowercase, since the API normalizes them to lowercase on output.
:::

## Token amount formats

Raw token amounts use **decimal strings in base units** to preserve precision. Some fields, such as a transfer's `sourceAmount`, return an amount object with `baseUnits`, `decimals`, and `formatted` instead. Check the endpoint's response schema.

```json
{
  "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`.

:::warning
Never parse amounts into floating-point numbers. JSON floats lose precision for many values (for example, `0.1 + 0.2 !== 0.3`) and silently overflow for large token balances. Use a big-integer or arbitrary-precision decimal type.
:::

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.

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

## API error conventions

REST API errors normally use a JSON envelope with an HTTP status and a machine-readable `error.code`. MPP challenges, JSON-RPC errors, and edge-level failures can use different formats. See [Errors](https://tempo.com/developers/docs/api/errors) for the envelope and the full code catalog.

## API rate-limit conventions

Responses that consume quota report it in `RateLimit-*` headers; cached responses may omit them. Over-quota requests receive `429 Too Many Requests`, or an MPP `402` challenge when eligible. See [Rate Limits](https://tempo.com/developers/docs/api/rate-limits) for the full model and best practices.
