nuthatch
Documentation Quickstart

This is the golden path: from a bare contract address to a decoded, tip-following, queryable API - on your own machine, with no external data service.

1. Install the binary

curl -fsSL https://nuthatch-indexer.com/install.sh | sh

Or build it with cargo:

cargo install --git https://github.com/nuthatch-indexer/nuthatch nuthatch

2. Scaffold a nest from an address

init detects the chain, resolves the ABI (Sourcify first, then an Etherscan-class API), vendors it locally, and generates the schema, views, and AI surface - no API key required.

nuthatch init 0xA0b86991c6218b36c1D19D4a2e9Eb0cE3606eB48 --chain mainnet

You now have a nest directory: nuthatch.toml, abis/, schema.json, views/, llms.txt.

3. Run it

dev backfills from the deployment block, follows the tip, decodes every declared event, and serves an HTTP API - all in one process.

nuthatch dev
# ✓ indexing USDC on mainnet - serving http://127.0.0.1:8288

4. Query it

Point-read an entity, run analytical SQL over the hot tip ∪ sealed history, or read a derived view.

nuthatch sql "SELECT to, value FROM usdc__transfer ORDER BY block_number DESC LIMIT 5"

…or over HTTP:

curl 'http://127.0.0.1:8288/sql?q=SELECT+count(*)+FROM+usdc__transfer'
curl http://127.0.0.1:8288/balance/0xYourAddress

What you just got

  • A decoded database. Every declared event becomes a table {alias}__{event}, with implicit columns (block_number, tx_hash, log_index, address, …) alongside the decoded fields.
  • Hot + cold storage. A redb tip store for point-reads, sealed content-addressed Parquet past finality, unified behind DuckDB SQL. See Storage & sealing.
  • Derived state, no eth_call. Add nuthatch recipe add total_supply for an ERC-20’s supply derived from Transfers - no archive node. See Recipes.
  • An admin UI and metrics at /_admin/ and /metrics.
  • An MCP server so an agent can drive it offline. See MCP.

Under two minutes. That’s the whole demo - install, init, dev, query. Everything after this page is about going deeper: authored logic, factories, roosts, upgrades, and operating it in production.

Next