Worked example

From contract to nest: indexing USDC

This is the current, executable path on v2.7.0. It creates a nest from a verified contract, backfills it, follows the chain, and serves decoded event data locally. GraphQL compatibility remains on the roadmap; the data surface is read-only SQL over HTTP and MCP.

Nuthatch begins with a contract, not a hosted indexing service. This example indexes USDC on Ethereum mainnet. The same shape works for a contract of your own, or for a published nest checked out with nuthatch init --from <git-url>.

One command, one nest

nuthatch init 0xA0b86991c6218b36c1D19D4a2e9Eb0cE3606eB48 \
  --alias usdc --chain mainnet

init vendors the ABI, records the chain and contract in nuthatch.toml, and writes the schema and authoring files. The explicit --alias usdc gives the event tables stable, readable names.

The process backfills from the deployment block, follows the tip, and serves a local API at http://127.0.0.1:8288. For production, use an RPC endpoint you control rather than relying on the free public defaults for a deep historical backfill.

Queryable before you model anything

Every declared event becomes a table named {alias}__{event}. For this nest, Transfers are usdc__transfer. The raw layer includes provenance such as block number, transaction hash, and log index alongside the decoded event fields.

SELECT block_number, tx_hash, log_index, "from", "to", value
FROM usdc__transfer
ORDER BY block_number DESC, log_index DESC
LIMIT 10;

Start with GET /schema or GET /tables when you do not know a nest’s shape. Solidity’s from and to are SQL reserved words, so they need double quotes in a query.

Serve the data

The SQL endpoint is deliberately small: it accepts read-only SELECT or WITH queries as the q query parameter. It is a GET endpoint, not a Postgres wire protocol and not GraphQL.

curl -G 'http://127.0.0.1:8288/sql' \
  --data-urlencode 'q=SELECT count(*) AS transfers FROM usdc__transfer'

The response covers both sealed historical segments and the live hot tip. Query limits, timeouts, and read-only enforcement are part of the endpoint, not an optional client habit. A reverse proxy should still provide authentication and per-client rate limits before exposing it publicly.

Turn facts into your application model

Raw events are available immediately. Add authored views or recipes when your application needs a stable derived shape, and commit checks with recorded fixtures when the result matters. That keeps the decoding boundary reusable while making the application-specific logic explicit.

The result is a self-hosted, replayable event index you can query without a deploy key or a gateway. For the full command and HTTP reference, continue to the quickstart or the HTTP API.