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, 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 to read indexed chain data without running your own pipeline.

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

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

Tempo data the indexer API covers

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

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

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

Querying the Indexer API

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

Self-hosting the indexer API

tidx is open source and can run from Docker or source against your own PostgreSQL (and optional ClickHouse). See the repository and the Indexer guide for configuration and deployment.