Stories

Who runs Nuthatch

Nuthatch has three front doors: an SQL endpoint for application backends, published nests for people who want data without writing indexing code, and a built-in MCP server for agents. Same data and the same nest definition, on hardware you control.

Illustrative workflows, not customer stories - current for Nuthatch v5.3.0.

These workflows run on v5.3.0. Multi-contract nests, every declared event as a queryable table, nine built-in chains, user-authored views/*.sql, maintained entities.toml relations, init --from, read-only /sql, and the MCP server all ship today - as do factories, the compliance pack, the admin UI, and webhooks. GraphQL is not one of the front doors: it shipped in 3.7.0 only as a partial read surface, exact for a subgraph's event-shaped fields and a named refusal for the rest, it is parked, and the default binary has no GraphQL route: it is served only by the nuthatch-graph download attached to every release since 4.11.0. The personas are illustrative. See the roadmap for the dividing line.

A dapp backend

Maya's three-person team needs an auditable USDC transfer activity feed in its backend. The read path is ordinary application data, but it is usually where a managed indexer starts charging by query or by entity.

She points one command at the contract and runs it on a small VPS. Nothing else to provision: no Postgres, no queue, no second box.

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

Every declared event becomes a queryable table as the backfill streams through history. The explicit alias makes the table name predictable: usdc__transfer. Her API can read the raw layer directly, put a derived view in front of it for a stable model, or make a repeatedly-read aggregate a maintained entity.

Her API route calls GET /sql?q=…, a read-only HTTP endpoint on localhost. It is not Postgres and it does not accept JSON POST bodies:

curl -G 'http://127.0.0.1:8288/sql' \
  --data-urlencode 'q=SELECT "to", value FROM usdc__transfer \
ORDER BY block_number DESC, log_index DESC LIMIT 20'

When the chain reorgs, the affected rows are rolled back and anything derived from them is retracted.

What she stopped doing: paying per entity for her own application's data, and trusting a third party's uptime for a read path she now runs herself.

A dashboard, no indexing code

Petar delegates GRT and wants one thing: to see which Graph Horizon indexers actually earn. He does not want to write handlers, and he does not need to.

He pulls a published nest - the horizon-nest, with contracts, vendored ABIs, and derived views all included - and runs it against his own node. He wrote no indexing code; he ran someone else's definition:

nuthatch init --from https://github.com/nuthatch-org/horizon-nest

From there the data is just SQL. One query drives a Grafana panel, or a bare HTML page with a single fetch:

select * from indexers order by cast(rewards as double) desc limit 20;

The point is that a nest is a shareable indexing definition, not a hosted feed: he ran it on his own hardware and can read every line of what produced the numbers.

Derived views read finalized data; the raw event tables are fresh to the tip. A dashboard built on views trails the chain head by finality - the honest trade for numbers that never retract under you. An incremental entity is different: it follows its source through the hot tip and carries its own applied-through provenance.

An agent, locally

Dana builds a DeFi assistant. She wants it to answer questions about on-chain data without shipping that data - or her users' questions - to anyone.

She adds Nuthatch to the agent's MCP config. That is the whole integration:

{
  "mcpServers": {
    "nuthatch": { "command": "nuthatch", "args": ["mcp"] }
  }
}

The agent discovers the schema itself through the schema tool and composes queries through the sql tool, so when her user types "which indexers grew delegation the most this month?" it writes the query rather than guessing the shape.

Nothing leaves the machine: no API key, no per-query bill, and it works offline against the local instance.

The pattern across all three: nobody deployed to someone else's platform, nobody got an API key, and nobody's story ends with a monthly invoice. To a frontend, Nuthatch looks like a read-only database that fills itself from the chain and rolls back through reorgs. GraphQL is a partial read surface, and parked: an analytics client cannot adopt it unmodified, because GraphQL refuses a whole query for one field it cannot answer.

Try the quickstart See the full example