> 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`.
# Indexer API

The Tempo API exposes an **Indexer entrypoint** for read-only SQL over chain data alongside its REST and JSON-RPC surfaces. It is backed by [`tidx`](https://github.com/tempoxyz/tidx), Tempo's hosted chain indexer, which continuously follows Tempo, stores raw blocks, transactions, logs, and receipts, and pre-computes analytics tables — then exposes everything as queryable SQL. Reach it at [`GET /v1/indexer/query`](/api/indexer) to read indexed chain data without running your own pipeline.

:::info
This page explains what the indexer is and how it's organized. For the request/response contract of the API endpoint, see the [indexer query reference](/api/indexer). For the full table schema, an interactive query console, and self-hosting, see the [Indexer guide](/docs/developer-tools/indexer).
:::

## Architecture

`tidx` writes the same chain data into two stores and routes each query to the right one:

* **PostgreSQL** — the primary OLTP store. Always present, optimized for low-latency point lookups, and the source for live streaming.
* **ClickHouse** — an optional OLAP store for aggregations, large scans, and pre-computed analytics tables (tokens, holders, transfers, DEX data).

Queries route to PostgreSQL by default and to ClickHouse with `engine=clickhouse`. When ClickHouse is enabled, both stores are written in parallel and kept consistent, so the same query returns the same data regardless of engine (subject to each store's available tables).

The sync engine runs two jobs concurrently: a **realtime** loop that follows the chain head, and a **backfill** loop that fills historical gaps — recent gaps first, so new data becomes queryable quickly.

```text
                    ╭───────────────╮
   Tempo JSON-RPC ─▶│   tidx sync   │ realtime + backfill
                    │    engine     │
                    ╰───────┬───────╯
                            │ writes in parallel
                ╭───────────┴───────────╮
                ▼                       ▼
        ╭───────────────╮       ╭───────────────╮
        │  PostgreSQL   │       │  ClickHouse   │
        │  point reads  │       │   analytics   │
        │  + live SSE   │       │   + rollups   │
        ╰───────┬───────╯       ╰───────┬───────╯
                ╰───────────┬───────────╯
                            ▼
                  GET /v1/indexer/query
```

## What it indexes

Every Tempo block is decoded into a set of **base tables**, available in both stores:

| Table | Contents |
| --- | --- |
| `blocks` | Block headers: number, hash, parent hash, timestamp, gas, proposer. |
| `txs` | Transactions: block, index, hash, type, from/to, value, calldata, gas, nonce, fee token. |
| `logs` | EVM logs: block, log index, transaction hash, emitting contract, topics, data. |
| `receipts` | Receipts: status, gas used, effective gas price, contract address, fee payer. |

## Analytics tables

With `engine=clickhouse`, the indexer additionally exposes pre-computed tables maintained from the base data. These exist so common reads are sort-key seeks instead of full scans:

* **Tokens** — `token_balances`, `token_holder_counts`, `token_holder_deltas`, `token_metadata`, `token_supply`, `token_transfers`, `token_approvals`, `token_transfer_stats`.
* **Addresses** — `address_balances`, `address_transfers`, `address_txs`, `address_holder_deltas`.
* **DEX** — `dex_pairs`, `dex_orders`, `dex_fills`, `dex_ohlc_1m`, `dex_pair_liquidity`.
* **Contracts** — `contract_creations`.

:::info
The typed REST endpoints (tokens, balances, activity, exchanges) are the stable, supported interface for these common reads. Query the analytics tables directly when you need custom SQL the REST endpoints don't cover.
:::

## Decoded events

There are two ways to read decoded event data:

* **Pre-decoded tables** — common events are decoded at insert time into ClickHouse tables such as `token_transfers` (`Transfer`), `token_approvals` (`Approval`), and the DEX tables. Prefer these when available.
* **Query-time decoding** — pass a `signature` parameter and the indexer exposes the matching `logs` as a virtual table named after the event, so you can select its arguments directly. This works on either engine. See the [indexer query reference](/api/indexer).

## Querying

Run read-only `SELECT` queries through [`GET /v1/indexer/query`](/api/indexer), optionally streaming live as new blocks arrive over Server-Sent Events. Requests share the same [authentication](/api/authentication), [rate limits](/api/rate-limits), and `RateLimit-*` headers as the rest of the API. See the [indexer query reference](/api/indexer) for parameters, response shape, live streaming, and errors.

## Self-hosting

`tidx` is open source and can run from Docker or source against your own PostgreSQL (and optional ClickHouse). See the [repository](https://github.com/tempoxyz/tidx) and the [Indexer guide](/docs/developer-tools/indexer) for configuration and deployment.