### Start Services with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to start the project's services. Set LOCALNET=1 for local network mode.

```bash
make up
```

--------------------------------

### Install tidx (Binary)

Source: https://context7.com/tempoxyz/tidx/llms.txt

Installs the latest version of tidx to ~/.local/bin/. You can also install a specific version or self-update.

```bash
# Install latest to ~/.local/bin/
curl -sSf https://tidx.vercel.app/install | sh

# Install specific version
curl -sSf https://tidx.vercel.app/install | sh -s v0.5.4

# Self-update
tidx upgrade
```

--------------------------------

### Start Tidx with Configuration

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to initialize Tidx with a specified configuration file.

```bash
# Start with config
tidx up --config config.toml
```

--------------------------------

### Tidx Configuration File Example

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Example of a TOML configuration file for Tidx, showing settings for HTTP, Prometheus, and multiple blockchain chains, including optional ClickHouse integration.

```toml
[http]
enabled = true
port = 8080
bind = "0.0.0.0"
trusted_cidrs = ["100.64.0.0/10"]   # Optional: trusted IPs for admin operations (e.g., Tailscale)

[prometheus]
enabled = true
port = 9090

[[chains]]
name = "mainnet"
chain_id = 4217
rpc_url = "https://rpc.tempo.xyz"
pg_url = "postgres://user@tidx.example.com:5432/tidx_mainnet"
pg_password_env = "TIDX_PG_PASSWORD"  # Password from environment variable
batch_size = 100

# Optional: ClickHouse for OLAP queries
[chains.clickhouse]
enabled = true
url = "http://clickhouse:8123"

[[chains]]
name = "moderato"
chain_id = 42431
rpc_url = "https://rpc.testnet.tempo.xyz"
pg_url = "postgres://user@tidx.example.com:5432/tidx_moderato"
pg_password_env = "TIDX_PG_PASSWORD"

```

--------------------------------

### Start tidx Indexer

Source: https://context7.com/tempoxyz/tidx/llms.txt

Starts the tidx indexer using the configuration file. You can specify a custom config path.

```bash
tidx up                            # reads config.toml
tidx up --config /etc/tidx.toml   # custom config path
```

--------------------------------

### Tidx Up Command

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Command to start Tidx syncing blocks and serving the HTTP API. Allows specifying a custom configuration file path.

```text
Usage: tidx up [OPTIONS]

Options:
  -c, --config <CONFIG>  Path to config file [default: config.toml]
  -h, --help             Print help

```

--------------------------------

### Query ClickHouse (OLAP) with Tidx

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Example of querying the ClickHouse backend for the last 10 transfers, demonstrating faster analytics for large datasets. Specify `engine=clickhouse`.

```bash
curl "https://tidx.example.com/query \
  ?chainId=4217 \
  &engine=clickhouse \
  &signature=Transfer(address,address,uint256) \
  &sql=SELECT * FROM Transfer WHERE from = '0x...' ORDER BY block_num DESC LIMIT 10"
```

--------------------------------

### Download Tidx Docker Image

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to download the Tidx Docker image. Ensure you have curl installed.

```bash
curl -L https://tidx.vercel.app/docker | bash
```

--------------------------------

### Test TIDX Agent Infrastructure

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Start PostgreSQL and Tempo node services using Docker Compose, check service status, and then run all tests or specific tests like smoke_test.

```bash
# Start test infrastructure (PostgreSQL + Tempo node)
docker compose -f docker/local/docker-compose.yml up -d postgres tempo

# Wait for services to be healthy
docker compose -f docker/local/docker-compose.yml ps

# Run tests
cargo test

# Run specific test
cargo test smoke_test
```

--------------------------------

### Get View Details with Tidx CLI

Source: https://context7.com/tempoxyz/tidx/llms.txt

Retrieve detailed information about a specific materialized view by providing its name and the chain ID.

```bash
tidx views --url https://tidx.example.com get --chain-id 4217 --name top_holders
```

--------------------------------

### List Views API

Source: https://context7.com/tempoxyz/tidx/llms.txt

Use this GET request to list all available views for a given chain ID. The response includes view names, engines, databases, and column definitions.

```bash
curl "http://localhost:8080/views?chainId=4217"
```

--------------------------------

### Query ClickHouse Pre-computed Views with Tidx

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Example of querying pre-computed views in ClickHouse. First, fetch available views, then query a specific view like 'top_holders'.

```bash
curl "https://tidx.example.com/views?chainId=4217"
> {"ok":true,"views":[{"name":"top_holders","columns":[{"name":"token","type":"String"},{"name":"holder","type":"String"},{"name":"balance","type":"UInt256"}]}]}
```

```bash
curl "https://tidx.example.com/query \
  ?chainId=4217 \
  &engine=clickhouse \
  &sql=SELECT * FROM top_holders WHERE token = '0x...' LIMIT 10"
```

--------------------------------

### Query PostgreSQL (OLTP) with Tidx

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Example of querying the PostgreSQL backend for the last 10 transfers from a specific address. Requires chainId, signature, and a SQL query.

```bash
curl "https://tidx.example.com/query \
  ?chainId=4217 \
  &signature=Transfer(address,address,uint256) \
  &sql=SELECT * FROM Transfer WHERE from = '0x...' ORDER BY block_num DESC LIMIT 10"
```

--------------------------------

### Run TIDX Agent Locally

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Start the TIDX Agent locally using 'cargo run -- up'. Use a custom configuration file with '--config /path/to/config.toml' or check sync status with 'cargo run -- status'.

```bash
# Start indexing (reads from config.toml)
cargo run -- up

# Use custom config file
cargo run -- up --config /path/to/config.toml

# Check sync status
cargo run -- status
```

--------------------------------

### Tidx Materialized View List Response

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Example JSON response when listing materialized views via the Tidx HTTP API.

```json
{
  "ok": true,
  "views": [
    {
      "name": "token_holders",
      "engine": "MaterializedView",
      "database": "analytics_42431",
      "columns": [
        {"name": "token", "type": "String"},
        {"name": "holder", "type": "String"},
        {"name": "balance", "type": "UInt256"}
      ]
    }
  ]
}
```

--------------------------------

### Migrate production DBs with Docker Compose

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

This command runs the normal migration flow before starting or updating the 'tidx' service using Docker Compose. It verifies the final pgroll version.

```bash
PGROLL_POSTGRES_URLS="postgres://.../tidx_moderato?sslmode=disable postgres://.../tidx_mainnet?sslmode=disable" docker compose --profile migrations run --rm pgroll-migrate
```

--------------------------------

### Check Tidx Service Health via HTTP API

Source: https://context7.com/tempoxyz/tidx/llms.txt

Make a GET request to the /health endpoint to verify if the Tidx service is running and responsive.

```bash
curl http://localhost:8080/health
# OK
```

--------------------------------

### Tidx Views Command

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Command for managing ClickHouse materialized views. Supports listing, getting, creating, and deleting views via the Tidx API.

```text
Usage: tidx views --url <URL> <COMMAND>

Commands:
  list    List all views for a chain
  get     Get view details
  create  Create a new materialized view
  delete  Delete a view

Options:
      --url <URL>  TIDX HTTP API URL [env: TIDX_URL]
  -h, --help       Print help

```

--------------------------------

### pgroll-migrate verification

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

The pgroll-migrate command verifies the final pgroll version and exits with a non-zero status if migrations do not reach the expected version, for example, if bootstrap was skipped on a non-empty database.

```bash
pgroll-migrate
```

--------------------------------

### Basic Event CTE Query

Source: https://context7.com/tempoxyz/tidx/llms.txt

Query raw event logs by providing the event signature. The `signature` parameter decodes ABI data into SQL columns. This example retrieves Transfer events from a specific token contract.

```bash
curl "http://localhost:8080/query?chainId=4217\n&signature=Transfer(address%20indexed%20from,address%20indexed%20to,uint256%20value)\n&sql=SELECT%20%22from%22,%22to%22,%22value%22%20FROM%20Transfer%20WHERE%20address='0xdAC17F958D2ee523a2206206994597C13D831ec7'%20ORDER%20BY%20block_num%20DESC%20LIMIT%2010"
```

--------------------------------

### Run TIDX Agent in Production with Docker

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Deploy the TIDX Agent using Docker Compose for a production setup including PostgreSQL, Prometheus, and Grafana. Ensure config.toml is edited for chain configuration. View logs with 'docker compose logs -f tidx'.

```bash
# Production deployment with PostgreSQL, Prometheus, Grafana
# Edit config.toml to configure chains
docker compose up -d

# View logs
docker compose logs -f tidx

# Access services:
# - HTTP API: http://localhost:8080
# - Prometheus: http://localhost:9091
# - Grafana: http://localhost:3000 (admin/admin)
```

--------------------------------

### Get Materialized View Details via HTTP API

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Retrieve detailed information about a specific materialized view using its name and chain ID via the Tidx HTTP API.

```bash
curl "https://tidx.example.com/views/token_holders?chainId=42431"
```

--------------------------------

### Predicate Pushdown for Indexed Params

Source: https://context7.com/tempoxyz/tidx/llms.txt

Filters on `indexed` parameters in event CTEs are automatically pushed down to the raw logs level as topic filters for efficient querying. This example filters Transfer events by the `from` address.

```bash
tidx query \n  -s "Transfer(address indexed from, address indexed to, uint256 value)" \n  'SELECT "to", "value" FROM Transfer\n   WHERE "from" = '\''0xdAC17F958D2ee523a2206206994597C13D831ec7'\'\n   ORDER BY block_num DESC LIMIT 20'
```

--------------------------------

### Bootstrap production database with make

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

This command is used for a one-time bootstrap of an existing production database using the make utility. Ensure the POSTGRES_URL environment variable is set.

```bash
POSTGRES_URL=... make pgroll-bootstrap
```

--------------------------------

### Create a baseline migration

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

Use this command for a one-time bootstrap of an existing production database. Specify a baseline version and a temporary output directory.

```bash
pgroll baseline <baseline-version> <temporary-output-dir>
```

--------------------------------

### Build Tidx from Source

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Steps to clone the Tidx repository and build the release binary using Cargo.

```bash
git clone https://github.com/tempoxyz/tidx
cd tidx
cargo build --release
```

--------------------------------

### Get Tidx HTTP API Status

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Retrieve the synchronization status of all chains indexed by Tidx via the HTTP API.

```bash
# Status
curl https://tidx.example.com/status
> {"ok":true,"chains":[{"chain_id":4217,"synced_num":567890,"head_num":567890,"lag":0}]}
```

--------------------------------

### Build Docker Image with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to build the project's Docker image.

```bash
make build
```

--------------------------------

### Run Benchmarks with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to run benchmarks for the project.

```bash
make bench
```

--------------------------------

### Run Tests with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to run all project tests.

```bash
make test
```

--------------------------------

### Tidx Materialized View Delete Response

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Example JSON response after successfully deleting materialized views via the Tidx HTTP API.

```json
{
  "ok": true,
  "deleted": ["token_holders_mv", "token_holders"]
}
```

--------------------------------

### Perform a complete migration

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

Execute this command for normal deploys after the initial bootstrap. It applies all pending migrations to the database.

```bash
pgroll migrate db/pgroll --complete
```

--------------------------------

### Bootstrap production DBs with Docker Compose

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

This command performs a one-time bootstrap for existing production databases using Docker Compose. Multiple database URLs can be specified.

```bash
PGROLL_POSTGRES_URLS="postgres://.../tidx_moderato?sslmode=disable postgres://.../tidx_mainnet?sslmode=disable" docker compose --profile migrations run --rm pgroll-bootstrap
```

--------------------------------

### Tidx Init Command

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Command to initialize a new Tidx configuration file. Supports specifying an output path and overwriting existing files.

```text
Usage: tidx init [OPTIONS]

Options:
  -o, --output <OUTPUT>  Output path for config file [default: config.toml]
      --force            Overwrite existing config file
  -h, --help             Print help

```

--------------------------------

### TIDX Agent HTTP API Sync Status

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Retrieve the current sync status of the TIDX Agent by sending a GET request to the /status endpoint.

```bash
# Sync status
curl http://localhost:8080/status
```

--------------------------------

### Tidx Service Status Response

Source: https://context7.com/tempoxyz/tidx/llms.txt

Example JSON response from the /status HTTP API endpoint, detailing chain synchronization progress, watermarks, and backfill estimates.

```json
{
  "ok": true,
  "version": "0.5.4",
  "rev": "abc1234",
  "chains": [
    {
      "chain_id": 4217,
      "head_num": 1234567,
      "synced_num": 1234563,
      "tip_num": 1234567,
      "lag": 4,
      "gap_blocks": 0,
      "gaps": [],
      "backfill_num": 800000,
      "backfill_remaining": 800000,
      "sync_rate": 850.5,
      "eta_secs": 940,
      "postgres": {
        "blocks": 1234563,
        "txs": 1234560,
        "logs": 1234558,
        "receipts": 1234560,
        "rate": 850.5,
        "blocks_count": 1234563,
        "txs_count": 8234100,
        "logs_count": 42100300,
        "receipts_count": 8234100
      },
      "clickhouse": null
    }
  ]
}
```

--------------------------------

### Initialize tidx Configuration

Source: https://context7.com/tempoxyz/tidx/llms.txt

Generates a skeleton config.toml file. You can specify an output path and force overwriting an existing file.

```bash
tidx init                          # writes config.toml in current directory
tidx init --output /etc/tidx.toml  # custom path
tidx init --force                  # overwrite existing
```

--------------------------------

### Migrate production database with make

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

This command is used for the normal migration flow after bootstrapping, utilizing the make utility. Ensure the POSTGRES_URL environment variable is set.

```bash
POSTGRES_URL=... make pgroll-migrate
```

--------------------------------

### Initialize pgroll

Source: https://github.com/tempoxyz/tidx/blob/main/db/pgroll/README.md

Run this command to initialize pgroll in your project. It sets up the necessary configuration for migration management.

```bash
pgroll init
```

--------------------------------

### TIDX Agent Prometheus Metrics Endpoint

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Access Prometheus metrics exposed by the TIDX Agent by sending a GET request to the /metrics endpoint, typically on port 9090.

```bash
# Prometheus metrics (default port 9090)
curl http://localhost:9090/metrics
```

--------------------------------

### Generate Load for TIDX Agent Benchmarking

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Utilize tempo-bench via Docker to generate millions of transactions for benchmarking. Configure duration, transactions per second, accounts, target URLs, and faucet usage.

```bash
# Use tempo-bench to generate millions of transactions
docker run --rm --network host ghcr.io/tempoxyz/tempo-bench:latest \
  run-max-tps \
  --duration 60 \
  --tps 5000 \
  --accounts 10000 \
  --target-urls http://localhost:8545 \
  --faucet
```

--------------------------------

### Clean Services and Data with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to stop services and clean up project data.

```bash
make clean
```

--------------------------------

### TIDX Agent HTTP API Health Check

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Perform a health check on the TIDX Agent's HTTP API by sending a GET request to the /health endpoint.

```bash
# Health check
curl http://localhost:8080/health
```

--------------------------------

### Tail Indexer Logs with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to tail the indexer logs.

```bash
make logs
```

--------------------------------

### Generate Transactions with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to generate transactions for the project.

```bash
make seed
```

--------------------------------

### Run tidx with Docker

Source: https://context7.com/tempoxyz/tidx/llms.txt

Pulls the latest tidx image and runs it with a configuration file. Also shows commands for a production stack with monitoring.

```bash
# Pull and run with a config file
docker pull ghcr.io/tempoxyz/tidx:latest
docker run -v $(pwd)/config.toml:/config.toml ghcr.io/tempoxyz/tidx up

# Production stack: PostgreSQL + ClickHouse + Prometheus + Grafana
git clone https://github.com/tempoxyz/tidx
docker compose -f docker/prod/docker-compose.yml up -d

# With monitoring dashboards
docker compose -f docker/prod/docker-compose.yml --profile monitoring up -d
# HTTP API:   http://localhost:8080
# Prometheus: http://localhost:9091
# Grafana:    http://localhost:3000  (admin/admin)
```

--------------------------------

### Decode Transfer Events via HTTP API

Source: https://context7.com/tempoxyz/tidx/llms.txt

Decode Transfer events by providing the chain ID, the event signature, and a SQL query to the /query endpoint. This example targets the PostgreSQL engine.

```bash
curl "http://localhost:8080/query?chainId=4217\
&signature=Transfer(address%20indexed%20from,%20address%20indexed%20to,%20uint256%20value)\
&sql=SELECT%20%22from%22,%20%22to%22,%20%22value%22%20FROM%20Transfer%20ORDER%20BY%20block_num%20DESC%20LIMIT%2010"
```

--------------------------------

### Tidx CLI Usage

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Overview of the Tidx command-line interface, listing available commands and global options.

```text
Usage: tidx <COMMAND>

Commands:
  init         Initialize a new config.toml
  up           Start syncing blocks from the chain (continuous) and serve HTTP API
  status       Show sync status
  query        Run a SQL query (use --signature to decode event logs)
  views        Manage ClickHouse materialized views
  upgrade      Update tidx to the latest version
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

```

--------------------------------

### Run Clippy Lints with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to run Clippy lints, a linter for Rust code.

```bash
make check
```

--------------------------------

### Get Tidx Service Status via HTTP API

Source: https://context7.com/tempoxyz/tidx/llms.txt

Retrieve detailed status information about the Tidx service, including chain sync progress and backfill estimates, by querying the /status endpoint.

```bash
curl http://localhost:8080/status
```

--------------------------------

### Create Hourly Swap Volume View

Source: https://context7.com/tempoxyz/tidx/llms.txt

This POST request creates a materialized view named `swap_volume_hourly` to track hourly Uniswap swap volume. It aggregates swap data from the `Swap` event signature and uses the `SummingMergeTree` engine.

```bash
curl -X POST "http://localhost:8080/views" \n  -H "Content-Type: application/json" \n  -d '{\n    "chainId": 4217,\n    "name": "swap_volume_hourly",\n    "signature": "Swap(address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to)",\n    "sql": "SELECT address as pair, toStartOfHour(block_timestamp) as hour, COUNT(*) as swaps, SUM(\"amount0In\") + SUM(\"amount0Out\") as volume0, SUM(\"amount1In\") + SUM(\"amount1Out\") as volume1 FROM Swap GROUP BY pair, hour",\n    "orderBy": ["pair", "hour"],\n    "engine": "SummingMergeTree()"\n  }'
```

--------------------------------

### Stop Services with Make

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Use this command to stop all project services.

```bash
make down
```

--------------------------------

### TIDX Agent HTTP API Query Decoded Event Logs

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Query decoded event logs from the TIDX Agent by sending a GET request to the /logs/{EventName} endpoint. Filter by limit and time using query parameters like 'after'.

```bash
# Query decoded event logs
curl "http://localhost:8080/logs/Transfer(address,address,uint256)?limit=10&after=1h"
```

--------------------------------

### Token Supply Calculation (ClickHouse)

Source: https://context7.com/tempoxyz/tidx/llms.txt

Calculates the token supply by summing mints and burns for the top 20 tokens using ClickHouse. Requires a specific event signature.

```bash
# Token supply (mints minus burns)
tidx query --engine clickhouse 
  -s "Transfer(address indexed from, address indexed to, uint256 value)" 
  "SELECT address as token, SUM(CASE WHEN \"from\" = '0x0000000000000000000000000000000000000000' THEN CAST(\"value\" AS Int256) WHEN \"to\" = '0x0000000000000000000000000000000000000000' THEN -CAST(\"value\" AS Int256) ELSE 0 END) as supply FROM Transfer GROUP BY token ORDER BY supply DESC LIMIT 20"
```

--------------------------------

### Create a Materialized View with Tidx CLI

Source: https://context7.com/tempoxyz/tidx/llms.txt

Create a new materialized view by specifying its name, SQL definition, and ordering criteria. This operation requires a trusted IP address.

```bash
tidx views --url https://tidx.example.com create \
  --chain-id 4217 \
  --name top_holders \
  --sql "SELECT holder, SUM(balance) as total FROM token_balances GROUP BY holder" \
  --order-by holder
```

--------------------------------

### Run TIDX Agent Benchmarks

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Execute benchmarks for the TIDX Agent using the 'cargo bench' command.

```bash
cargo bench
```

--------------------------------

### Tidx Configuration Reference

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Reference for Tidx configuration parameters, detailing each setting's type, purpose, and default values.

```text
[http]                                             HTTP server configuration
├── enabled                 bool      = true         Enable HTTP API server
├── port                    u16       = 8080         HTTP server port
├── bind                    string    = "0.0.0.0"    Bind address
└── trusted_cidrs           string[]  = []           Trusted CIDRs for admin ops (e.g., Tailscale)

[prometheus]                                       Prometheus metrics server
├── enabled                 bool      = true         Enable metrics endpoint
└── port                    u16       = 9090         Metrics server port

[[chains]]                                         Chain configuration 
├── name                    string    (required)     Display name for logging
├── chain_id                u64       (required)     Chain ID
├── rpc_url                 string    (required)     JSON-RPC endpoint URL
├── pg_url                  string    (required)     PostgreSQL connection string
├── pg_password_env         string    (optional)     Env var name for PostgreSQL password
├── api_pg_url              string    (optional)     Separate PostgreSQL URL for API (e.g., read replica)
├── api_pg_password_env     string    (optional)     Env var name for API PostgreSQL password
├── batch_size              u64       = 100          Blocks per RPC batch request
└── [clickhouse]                                     ClickHouse OLAP settings
    ├── enabled             bool      = false        Enable ClickHouse OLAP queries
    └── url                 string    = "http://clickhouse:8123"  ClickHouse HTTP URL

```

--------------------------------

### Build and Check TIDX Agent

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Use cargo check for fast type checking, cargo build for a debug build, and cargo build --release for an optimized release build.

```bash
cargo check          # Fast type checking
cargo build          # Debug build
cargo build --release # Release build
```

--------------------------------

### Create Token Holder Snapshot View

Source: https://context7.com/tempoxyz/tidx/llms.txt

This curl command creates a ClickHouse Materialized View named `token_holders`. It calculates the balance of token holders by processing `Transfer` events and uses the `SummingMergeTree` engine.

```bash
curl -X POST "http://localhost:8080/views" \n  -H "Content-Type: application/json" \n  -d '{\n    "chainId": 4217,\n    "name": "token_holders",\n    "signature": "Transfer(address indexed from, address indexed to, uint256 value)",\n    "sql": "SELECT address as token, holder, SUM(delta) as balance FROM (SELECT address, \"to\" as holder, CAST(\"value\" AS Int256) as delta FROM Transfer UNION ALL SELECT address, \"from\" as holder, -CAST(\"value\" AS Int256) as delta FROM Transfer) GROUP BY token, holder HAVING balance > 0",\n    "orderBy": ["token", "holder"],\n    "engine": "SummingMergeTree()"\n  }'
```

--------------------------------

### Execute SQL Query via HTTP API (Aggregation)

Source: https://context7.com/tempoxyz/tidx/llms.txt

Run an aggregation query by specifying the chain ID and SQL statement. The system auto-detects and routes this to the ClickHouse engine.

```bash
curl "http://localhost:8080/query?chainId=4217&sql=SELECT+toDate(block_timestamp)+as+day,+COUNT(*)+as+txs+FROM+txs+GROUP+BY+day+ORDER+BY+day+DESC+LIMIT+30"
```

--------------------------------

### Prometheus Metrics for Tempo Indexer

Source: https://context7.com/tempoxyz/tidx/llms.txt

Fetch and grep Prometheus metrics from the Tempo Indexer. Key metrics include sync status, indexed data counts, RPC request performance, and sink write durations.

```bash
curl http://localhost:9090/metrics | grep tidx_
```

```text
# Key metrics:
# tidx_sync_head_block{chain_id="4217"}          1234567
# tidx_synced_block{chain_id="4217"}             1234563
# tidx_sync_lag_blocks{chain_id="4217"}          4
# tidx_sync_blocks_per_second{chain_id="4217"}   850.5
# tidx_backfill_remaining_blocks{...}            800000
# tidx_blocks_indexed_total{chain_id="4217"}     1234563
# tidx_txs_indexed_total{chain_id="4217"}        8234100
# tidx_logs_indexed_total{chain_id="4217"}       42100300
# tidx_rpc_requests_total{method="eth_getBlockByNumber",success="true"}  1234567
# tidx_rpc_request_duration_seconds{...}         (histogram)
# tidx_query_duration_seconds                    (histogram)
# tidx_sink_write_duration_seconds{sink="postgres",table="blocks"}  (histogram)
# tidx_sink_write_rows_total{sink="clickhouse",table="logs"}        (counter)
# tidx_sink_errors_total{sink="postgres"}        (counter)
```

--------------------------------

### Query with Basic Auth in URL using Tidx CLI

Source: https://context7.com/tempoxyz/tidx/llms.txt

Embed basic authentication credentials directly within the URL for secure access to the Tidx service.

```bash
tidx query --url http://user:pass@tidx.example.com:8080 --chain-id 4217 \
  "SELECT num FROM blocks LIMIT 1"
```

--------------------------------

### List All Views for a Chain with Tidx CLI

Source: https://context7.com/tempoxyz/tidx/llms.txt

Use the `tidx views list` command to retrieve a list of all materialized views configured for a specific blockchain.

```bash
tidx views --url https://tidx.example.com list --chain-id 4217
```

--------------------------------

### List Tidx Views

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

List available materialized views for a specific chain ID via the Tidx CLI.

```bash
# List views
tidx views --url https://tidx.example.com list --chain-id 4217
```

--------------------------------

### Basic Event Query

Source: https://context7.com/tempoxyz/tidx/llms.txt

Query raw ABI-encoded log data into typed SQL columns on demand without pre-registration. Pass any event signature and query the event name as a virtual table.

```APIDOC
## Basic event query

### Description
Query raw ABI-encoded log data into typed SQL columns on demand. This feature allows you to query event data using its signature without prior registration.

### Method
GET

### Endpoint
`/query?chainId=<chainId>&signature=<event_signature>&sql=<sql_query>`

### Query Parameters
- **chainId** (integer) - Required - The ID of the blockchain to query.
- **signature** (string) - Required - The ABI signature of the event to decode. Format: `EventName(type [indexed] name, ...)`.
- **sql** (string) - Required - The SQL query to execute against the virtual table representing the event.

### Example
```bash
# All Transfer events from a specific token contract
curl "http://localhost:8080/query?chainId=4217\&signature=Transfer(address%20indexed%20from,address%20indexed%20to,uint256%20value)\
&sql=SELECT%20%22from%22,%22to%22,%22value%22%20FROM%20Transfer%20WHERE%20address='0xdAC17F958D2ee523a2206206994597C13D831ec7'%20ORDER%20BY%20block_num%20DESC%20LIMIT%2010"
```

### Available columns in every CTE
`block_num`, `block_timestamp`, `log_idx`, `tx_idx`, `tx_hash`, `address` (emitting contract), `selector`, `topic1`, `topic2`, `topic3`, `data` — plus all decoded parameters from the signature.
```

--------------------------------

### Full tidx Configuration Reference

Source: https://context7.com/tempoxyz/tidx/llms.txt

A comprehensive TOML configuration file for tidx, detailing all available options for HTTP, Prometheus, and chain settings, including ClickHouse integration.

```toml
[http]
enabled       = true
port          = 8080
bind          = "0.0.0.0"
trusted_cidrs = ["100.64.0.0/10"]   # IPs allowed to create/delete views (e.g. Tailscale)

[prometheus]
enabled = true
port    = 9090

[[chains]]
name                  = "mainnet"
chain_id              = 4217
rpc_url               = "https://rpc.mainnet.tempo.xyz"
pg_url                = "postgres://tidx@primary:5432/tidx_mainnet"
pg_password_env       = "PG_PASSWORD"          # password injected from env at runtime
api_pg_url            = "postgres://tidx@replica:5432/tidx_mainnet"  # read replica for API
api_pg_password_env   = "PG_API_PASSWORD"
batch_size            = 500    # blocks per RPC batch (default: 100)
concurrency           = 8      # parallel gap-fill workers (default: 4)
backfill              = true   # sync to genesis (default: true)
backfill_first        = false  # complete backfill before serving realtime queries
trust_rpc             = false  # skip reorg detection (faster, for private RPCs)

[chains.clickhouse]
enabled       = true
url           = "http://clickhouse:8123"
failover_urls = ["http://clickhouse-2:8123"]
user          = "default"
password_env  = "CH_PASSWORD"

[[chains]]
name         = "testnet"
chain_id     = 42431
rpc_url      = "https://rpc.testnet.tempo.xyz"
pg_url       = "postgres://tidx@localhost:5432/tidx_testnet"
pg_password_env = "PG_PASSWORD"
```

--------------------------------

### Query Tidx via HTTP API (PostgreSQL)

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Execute a SQL query against Tidx using the HTTP API, routed to PostgreSQL for point lookups.

```bash
# Point lookup (auto-routed to PostgreSQL)
curl "https://tidx.example.com/query?chainId=4217&sql=SELECT * FROM blocks WHERE num = 12345"
> {"columns":["num","hash","timestamp"],"rows":[[12345,"0xabc...","2024-01-01T00:00:00Z"]],"row_count":1,"engine":"postgres","ok":true}
```

--------------------------------

### Minimal tidx Configuration

Source: https://context7.com/tempoxyz/tidx/llms.txt

A minimal TOML configuration file for tidx, specifying HTTP port and chain details.

```toml
[http]
port = 8080

[[chains]]
name        = "mainnet"
chain_id    = 4217
rpc_url     = "https://rpc.mainnet.tempo.xyz"
pg_url      = "postgres://user:pass@localhost:5432/tidx_mainnet"
```

--------------------------------

### Live SSE Streaming Query

Source: https://context7.com/tempoxyz/tidx/llms.txt

Use this curl command to stream live block data using Server-Sent Events (SSE). The `live=true` parameter enables streaming, and the SQL query specifies the data to retrieve.

```bash
curl -N "http://localhost:8080/query?chainId=4217&live=true\n&sql=SELECT%20num,%20gas_used%20FROM%20blocks%20ORDER%20BY%20num%20DESC%20LIMIT%201"
```

--------------------------------

### Query Tidx via HTTP API (ClickHouse)

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Execute a SQL query against Tidx using the HTTP API, routed to ClickHouse for aggregations.

```bash
# Aggregation (auto-routed to ClickHouse)
curl "https://tidx.example.com/query?chainId=4217&sql=SELECT type, COUNT(*) FROM txs GROUP BY type"
> {"columns":["type","count"],"rows":[[0,50000],[2,120000]],"row_count":2,"engine":"clickhouse","ok":true}
```

--------------------------------

### Query Contract Deployments

Source: https://context7.com/tempoxyz/tidx/llms.txt

Retrieves contract addresses from receipts where a contract was deployed. Uses the tidx CLI.

```bash
# Contract deployments
tidx query "SELECT tx_hash, contract_address FROM receipts WHERE contract_address IS NOT NULL ORDER BY block_num DESC LIMIT 10"
```

--------------------------------

### Execute SQL Query

Source: https://context7.com/tempoxyz/tidx/llms.txt

Executes SQL queries against specified chain data, supporting PostgreSQL and ClickHouse engines, ABI event decoding, and SSE live streaming.

```APIDOC
## GET /query

### Description
Core query endpoint. Supports PostgreSQL (OLTP) and ClickHouse (OLAP) engines, ABI event decoding via `signature`, and SSE live streaming.

### Method
GET

### Endpoint
/query

### Parameters
#### Query Parameters
- **sql** (string) - Required - SELECT statement
- **chainId** (string) - Required - Chain ID (e.g. `4217`)
- **engine** (string) - Optional - `postgres` or `clickhouse` (defaults to auto)
- **signature** (string) - Optional - ABI event signature (repeatable)
- **timeout_ms** (integer) - Optional - Query timeout in milliseconds (defaults to `5000`)
- **limit** (integer) - Optional - Max rows (hard cap: 10,000) (defaults to `10000`)
- **live** (boolean) - Optional - SSE streaming mode (PostgreSQL only) (defaults to `false`)

### Request Example
```bash
# Point lookup → auto-routes to PostgreSQL
curl "http://localhost:8080/query?chainId=4217&sql=SELECT+*+FROM+txs+WHERE+hash='0xabc...'"

# Aggregation → auto-routes to ClickHouse
curl "http://localhost:8080/query?chainId=4217&sql=SELECT+toDate(block_timestamp)+as+day,+COUNT(*)+as+txs+FROM+txs+GROUP+BY+day+ORDER+BY+day+DESC+LIMIT+30"

# Decode Transfer events (PostgreSQL)
curl "http://localhost:8080/query?chainId=4217\n&signature=Transfer(address%20indexed%20from,%20address%20indexed%20to,%20uint256%20value)
&sql=SELECT%20%22from%22,%20%22to%22,%20%22value%22%20FROM%20Transfer%20ORDER%20BY%20block_num%20DESC%20LIMIT%2010"

# Decode Transfer + Approval (two signatures, one query)
curl "http://localhost:8080/query?chainId=4217\n&signature=Transfer(address%20indexed%20from,address%20indexed%20to,uint256%20value)
&signature=Approval(address%20indexed%20owner,address%20indexed%20spender,uint256%20value)
&sql=SELECT%20block_num,%20%22from%22,%20%22to%22%20FROM%20Transfer%20LIMIT%205"

# Force ClickHouse for heavy analytics
curl "http://localhost:8080/query?chainId=4217&engine=clickhouse\n&sql=SELECT%20address%20as%20contract,%20COUNT(*)%20as%20log_count%20FROM%20logs%20GROUP%20BY%20address%20ORDER%20BY%20log_count%20DESC%20LIMIT%2020"
```
```

--------------------------------

### List Materialized Views via HTTP API

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Fetch a list of all materialized views for a given chain ID using the Tidx HTTP API.

```bash
curl "https://tidx.example.com/views?chainId=42431"
```

--------------------------------

### Execute SQL Query via HTTP API (Point Lookup)

Source: https://context7.com/tempoxyz/tidx/llms.txt

Perform a point lookup query by providing the chain ID and SQL statement to the /query endpoint. This typically routes to the PostgreSQL engine.

```bash
curl "http://localhost:8080/query?chainId=4217&sql=SELECT+*+FROM+txs+WHERE+hash='0xabc...'"
```

--------------------------------

### Query Multiple Event Signatures via HTTP API

Source: https://context7.com/tempoxyz/tidx/llms.txt

Execute a single query that decodes multiple event signatures (Transfer and Approval) by providing both signatures and a combined SQL statement.

```bash
curl "http://localhost:8080/query?chainId=4217\
&signature=Transfer(address%20indexed%20from,address%20indexed%20to,uint256%20value)\
&signature=Approval(address%20indexed%20owner,address%20indexed%20spender,uint256%20value)\
&sql=SELECT%20block_num,%20%22from%22,%20%22to%22%20FROM%20Transfer%20LIMIT%205"
```

--------------------------------

### Run Tidx Docker Container

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Command to run the Tidx Docker container, mounting a local config.toml file for configuration.

```bash
docker run -v $(pwd)/config.toml:/config.toml ghcr.io/tempoxyz/tidx up
```

--------------------------------

### Execute SQL Query

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Executes a SQL query against the indexed blockchain data.

```APIDOC
## POST /query

### Description
Executes a SQL query against the indexed blockchain data.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body
- **sql** (string) - Required - The SQL query to execute.

### Request Example
{
  "sql": "SELECT num FROM blocks ORDER BY num DESC LIMIT 5"
}

### Response
#### Success Response (200)
Returns the result of the SQL query.
```

--------------------------------

### Create Tidx View

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Create a new materialized view in Tidx. This operation must be performed from a trusted IP address.

```bash
# Create a view (must be run from trusted IP)
tidx views --url https://tidx.example.com create \
  --chain-id 4217 \
  --name top_holders \
  --sql "SELECT holder, SUM(balance) as total FROM balances GROUP BY holder" \
  --order-by holder
```

--------------------------------

### Top 20 Contracts by Log Emissions (ClickHouse)

Source: https://context7.com/tempoxyz/tidx/llms.txt

Identifies the top 20 contracts emitting the most logs, using ClickHouse. Uses curl.

```bash
# Top 20 contracts by log emissions
curl "http://localhost:8080/query?chainId=4217&engine=clickhouse\
&sql=SELECT+encode(address,'hex')+as+contract,+COUNT(*)+as+logs+FROM+logs+GROUP+BY+address+ORDER+BY+logs+DESC+LIMIT+20"
```

--------------------------------

### Force ClickHouse Engine and CSV Output with Tidx CLI

Source: https://context7.com/tempoxyz/tidx/llms.txt

Execute a query forcing the ClickHouse engine and specifying CSV as the output format for aggregated data.

```bash
tidx query --engine clickhouse --format csv \
  "SELECT toDate(block_timestamp) as day, COUNT(*) as txs FROM txs GROUP BY day ORDER BY day DESC LIMIT 30"
```

--------------------------------

### Create Materialized View via HTTP API

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Create a new materialized view using the Tidx HTTP API. Requires a trusted IP and sends a JSON payload with view details.

```bash
curl -X POST "https://tidx.example.com/views" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 42431,
    "name": "token_holders",
    "sql": "SELECT token, holder, sum(balance) AS balance FROM token_balances GROUP BY token, holder HAVING balance > 0",
    "orderBy": ["token", "holder"]
  }'
```

--------------------------------

### Stream New Blocks (SSE)

Source: https://context7.com/tempoxyz/tidx/llms.txt

Streams new blocks as they are added to the chain using Server-Sent Events (SSE). Uses curl with live=true.

```bash
# Stream new blocks as they arrive (SSE)
curl -N "http://localhost:8080/query?chainId=4217&live=true&sql=SELECT num,gas_used FROM blocks ORDER BY num DESC LIMIT 1"
```

--------------------------------

### View Details API

Source: https://context7.com/tempoxyz/tidx/llms.txt

Retrieve detailed information about a specific view by its name and chain ID. This includes the view's definition, engine, database, and row count.

```bash
curl "http://localhost:8080/views/token_holders?chainId=4217"
```

--------------------------------

### Query with Multiple Signatures using Tidx CLI

Source: https://context7.com/tempoxyz/tidx/llms.txt

Query data using multiple event signatures by repeating the -s flag. This allows combining data from different event types using UNION ALL.

```bash
tidx query \
  -s "Transfer(address indexed from, address indexed to, uint256 value)" \
  -s "Approval(address indexed owner, address indexed spender, uint256 value)" \
  'SELECT * FROM Transfer UNION ALL SELECT block_num, block_timestamp, log_idx, tx_idx, tx_hash, address, selector, topic1, topic2, topic3, data, "owner" as "from", "spender" as "to", "value" FROM Approval LIMIT 20'
```

--------------------------------

### Query Transactions with Tidx CLI

Source: https://context7.com/tempoxyz/tidx/llms.txt

Use the tidx query command to count all transactions on a specific chain. Requires specifying the URL and chain ID.

```bash
tidx query --url http://localhost:8080 --chain-id 4217 \
  "SELECT COUNT(*) FROM txs"
```

--------------------------------

### Tidx Upgrade Command

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Command to update Tidx to the latest version by downloading and replacing the current binary from GitHub releases.

```text
Usage: tidx upgrade

Downloads and replaces the current binary from GitHub releases.

```

--------------------------------

### Query Txs Data with Event Decoding

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Perform SQL queries on transaction data, including decoding specific events using their signatures.

```bash
# Query with event decoding
tidx query \
  --signature "Transfer(address indexed from, address indexed to, uint256 value)" \
  "SELECT * FROM Transfer LIMIT 10"
```

--------------------------------

### Daily Transaction Count (ClickHouse)

Source: https://context7.com/tempoxyz/tidx/llms.txt

Calculates the daily transaction count for the last 30 days using ClickHouse as the query engine. Uses curl.

```bash
# Daily transaction count for the last 30 days
curl "http://localhost:8080/query?chainId=4217&engine=clickhouse\
&sql=SELECT+toDate(block_timestamp)+as+day,+COUNT(*)+as+txs+FROM+txs+GROUP+BY+day+ORDER+BY+day+DESC+LIMIT+30"
```

--------------------------------

### Tidx Query Command

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Command to execute SQL queries against Tidx. Supports specifying URL, chain ID, query engine, output format, and event signatures.

```text
Usage: tidx query [OPTIONS] <SQL>

Arguments:
  <SQL>  SQL query (SELECT only). Use event name from --signature as table

Options:
  -u, --url <URL>              TIDX HTTP API URL (e.g., http://localhost:8080)
  -n, --chain-id <CHAIN_ID>   Chain ID to query (uses first chain if not specified)
  -e, --engine <ENGINE>        Force query engine (postgres, clickhouse)
  -f, --format <FORMAT>        Output format (table, json, csv, toon) [default: table]
  -l, --limit <LIMIT>          Maximum rows to return [default: 10000]
  -s, --signature <SIGNATURE>  Event signature to create a CTE
  -t, --timeout <TIMEOUT>      Query timeout in milliseconds [default: 30000]
  -c, --config <CONFIG>        Path to config file [default: config.toml]
  -h, --help                   Print help

```

--------------------------------

### Prometheus Metrics

Source: https://github.com/tempoxyz/tidx/blob/main/AGENTS.md

Exposes Prometheus metrics for monitoring.

```APIDOC
## GET /metrics

### Description
Exposes Prometheus metrics for monitoring the TIDX agent.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
Returns metrics in Prometheus text format.
```

--------------------------------

### Query tidx HTTP API

Source: https://context7.com/tempoxyz/tidx/llms.txt

Runs an SQL query against the tidx HTTP API. If no URL is provided, it uses the local config for the default chain.

```bash
# Simple SQL query
tidx query "SELECT num, gas_used FROM blocks ORDER BY num DESC LIMIT 5"
```

--------------------------------

### Query Materialized View via HTTP API

Source: https://github.com/tempoxyz/tidx/blob/main/README.md

Execute a SQL query against a materialized view using the Tidx HTTP API, specifying ClickHouse as the engine.

```bash
# Query the view (auto-prefixed)
curl "https://tidx.example.com/query?chainId=42431&engine=clickhouse&sql=SELECT * FROM token_holders WHERE token = '0x...' ORDER BY balance DESC LIMIT 10"
```