> Feedback: If these docs are stale, missing, or confusing, post sanitized feedback to `https://docs.tempo.xyz/api/feedback` with `source: "mcp"`, a short `message`, and any relevant `toolName`, `relatedResource`, or `client`.
# 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](/api/authentication) and [Pagination](/api/pagination) pages.

## 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](/api/versioning-policy) for how versions, breaking changes, and deprecations work.

## Chains

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` |
| Testnet | `testnet` | `42431` |

```bash
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](/api/authentication) for how key environments interact with chain selection.

## 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.
:::

## Amounts

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.

```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`).

## Timestamps

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.

## 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.

## 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
```

## Errors

Errors use a single, consistent envelope with a conventional HTTP status code and a stable, machine-readable `error.code` you branch on. See [Errors](/api/errors) for the envelope and the full code catalog.

## Rate Limits

Every response carries standard `RateLimit-*` headers, and requests that exceed quota receive `429 Too Many Requests` with a `Retry-After` header. See [Rate Limits](/api/rate-limits) for the full model and best practices.