Just-in-time indexing is a way of using an AI agent to answer one-off questions about onchain data without maintaining permanent infrastructure or finding a pre-indexed data point. Rather than building an indexer in advance and keeping it running, the dataset is built on demand when a question comes up, read once, and deleted afterward.

How it Works​

One user, Michael K from Curve Finance, uses it for ad hoc analysis of pool activity. The flow starts with a plain-language prompt to Claude, for example: "Use Envio to parse all the trades from this pool."

Claude, using Envio's tooling, generates the indexer: the config, schema, and event handlers, scoped to the specific contract and events in the question. It deploys to Envio's free development plan cloud service with envio-cloud, the CLI, and the indexer backfills from scratch. After 5 to 10 minutes, the data is ready to query. Once the researcher has pulled what they need, they delete the indexer.

Why the Free Tier Covers it​

The workflow runs on Envio's free hosted cloud tier. The requests are one-off, so a single repo is enough: the agent manages it and deploys each question as a branch. A backfill of 5 to 10 minutes is acceptable for ad hoc work, where the alternative is building a pipeline by hand.

The Pattern​

Traditional indexing requires deciding what data is needed, building the pipeline, and then querying it, which limits the user to questions planned for in advance. Just-in-time indexing reverses the order: the question comes first, and the dataset is built to answer it.

This works because backfilling takes minutes rather than days, and because an agent can stand up the indexer from a natural-language prompt without anyone writing config by hand. The same pattern applies to any agent or user asking one-off onchain questions.

Build With Envio​

Envio is a real-time multichain blockchain indexer that turns onchain events into a queryable GraphQL API. Supports any EVM chain, plus Solana and Fuel. Use Envio Cloud or self-host. If you're building onchain, come talk to us about your data needs.

Subscribe to our newsletter 💌

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

This guide walks you through building a HyperIndex indexer for a smart contract on Sei. By the end, you will have a local indexer that streams Sei blockchain data into a Postgres database and serves it through a GraphQL API.

What you will build​

An indexer for USDC on Sei mainnet (Circle's native USDC). It tracks Transfer and Approval events, keeps a running token balance per account, and records every approval.

Target contract:

• Chain: Sei mainnet, chain ID 1329
• Contract address: 0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392
• Explorer: seitrace.com

Indexing testnet instead? See the Indexing on Sei testnet section at the bottom of this guide for the testnet config changes.

Steps at a glance​

1. Scaffold the indexer
2. Configure the indexer for Sei
3. Define the data schema
4. Write the event handler
5. Generate types
6. Run the indexer
7. Query your data
8. Stop the indexer

Before you begin​

Make sure you have the following prerequisites installed. Run each check in a terminal:

• Node.js v22 or later. Check with node -v.
• pnpm v8 or later. Check with pnpm -v.
• Docker installed and running. Check with docker ps.
• A free Envio API token. HyperIndex requires an API token to use HyperSync as a data source. Create one at envio.dev/app/api-tokens.

Step 1: Scaffold the indexer​

Create a new HyperIndex project from the ERC20 template, then move into the project folder:

pnpx envio init template -t erc20 -d ./sei-indexer
cd sei-indexer

During the init flow you'll be prompted for an Envio API token. Paste an existing one or follow the prompt to create a new one at envio.dev/app/api-tokens. The CLI writes it to .env for you.

A new sei-indexer folder is created with config.yaml, schema.graphql, a .env file, and a src/handlers/ directory. Every file in src/handlers/ is registered automatically, so there is no central EventHandlers.ts file. Generated types are written to the .envio/ directory.

Step 2: Configure the indexer for Sei​

Replace the contents of config.yaml with the configuration below. This points the indexer at Sei mainnet and the USDC contract, and selects the two events to index:

# yaml-language-server: $schema=./node_modules/envio/evm.schema.json
name: sei-indexer
description: Sei ERC20 indexer

contracts:
  - name: MyContract
    events:
      - event: Transfer(address indexed from, address indexed to, uint256 value)
      - event: Approval(address indexed owner, address indexed spender, uint256 value)

chains:
  - id: 1329 # Sei mainnet (pacific-1)
    start_block: 79123881
    contracts:
      - name: MyContract
        address:
          - "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392"

Important: start_block: 79123881 is the first EVM block on Sei mainnet. Earlier blocks are non-EVM and have no Solidity events to index. Setting it to 0 will waste time scanning blocks that can never match. Sei is a supported HyperSync network, so the endpoint resolves automatically from the chain ID. No hypersync_config block is needed.

Step 3: Define the data schema​

Replace the contents of schema.graphql with the schema below. Each type becomes a database table and a GraphQL query:

type Account {
  id: ID!
  balance: BigInt!
  approvals: [Approval!]! @derivedFrom(field: "owner")
}

type Approval {
  id: ID!
  owner: Account!
  spender: String!
  value: BigInt!
  blockNumber: BigInt!
  timestamp: BigInt!
}

The @derivedFrom directive creates a virtual reverse lookup, so each Account exposes its list of approvals without you storing that list explicitly.

Step 4: Write the event handler​

The ERC20 template ships a handler and a test file that both reference the template contract. Remove them first:

rm -f src/handlers/ERC20.ts src/indexer.test.ts

Note: Removing src/indexer.test.ts matters. It imports the deleted ERC20 handler, so leaving it in place breaks pnpm test.

Now create a new handler file at src/handlers/MyContract.ts with the following content:

import { indexer } from "envio";

indexer.onEvent(
  { contract: "MyContract", event: "Transfer" },
  async ({ event, context }) => {
    const { from, to, value } = event.params;

    const sender = await context.Account.get(from);
    context.Account.set({
      id: from,
      balance: (sender?.balance ?? 0n) - value,
    });

    const receiver = await context.Account.get(to);
    context.Account.set({
      id: to,
      balance: (receiver?.balance ?? 0n) + value,
    });
  },
);

indexer.onEvent(
  { contract: "MyContract", event: "Approval" },
  async ({ event, context }) => {
    const { owner, spender, value } = event.params;

    const existing = await context.Account.get(owner);
    context.Account.set({
      id: owner,
      balance: existing?.balance ?? 0n,
    });

    context.Approval.set({
      id: `${event.block.hash}-${event.logIndex}`,
      owner_id: owner,
      spender,
      value,
      blockNumber: BigInt(event.block.number),
      timestamp: BigInt(event.block.timestamp),
    });
  },
);

Key points about the handler API:

• Handlers are registered with indexer.onEvent, imported from the envio package.
• Linked entities are set with the <field>_id convention, so the owner relation is written as owner_id.
• Event metadata is available on the event object, including event.block (number, timestamp, hash), event.logIndex, event.srcAddress, and more. See the Event Handlers docs for the full list.

Step 5: Generate types​

Generate the typed code from your config and schema:

pnpm codegen

The command reads config.yaml and schema.graphql, writes typed code into .envio/, and exits with no errors. Run this again any time you change the config or schema.

Step 6: Run the indexer​

Start the indexer in development mode:

pnpm dev

Envio starts Postgres and Hasura in Docker, then begins streaming Sei blocks through HyperSync. Indexed data appears within seconds. Leave this terminal running.

You can explore the data in the Envio Console.

Step 7: Query your data​

With the indexer still running, open a new terminal and query the GraphQL API. This asks for the top 3 accounts by USDC balance and the 3 most recent approvals:

curl -s -X POST http://localhost:8080/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ Account(limit: 3, order_by: { balance: desc }) { id balance } Approval(limit: 3, order_by: { blockNumber: desc }) { id spender value blockNumber } }"}'

You will get back JSON with Account and Approval rows from live Sei USDC activity. If the response is empty, wait a few seconds for the indexer to sync further and run the query again. USDC has six decimals on Sei, so a balance of 1000000 represents 1 USDC.

Step 8: Stop the indexer​

Stop pnpm dev with Ctrl+C in its terminal, then clean up the local environment:

pnpm envio stop

Important: This stops the Docker containers and removes the local database. Do not use docker compose down. HyperIndex manages its containers directly, so docker compose down fails.

Indexing on Sei testnet​

To target Sei testnet (atlantic-2) instead of mainnet, swap three values in the chains block of config.yaml:

chains:
  - id: 1328 # Sei testnet (atlantic-2)
    start_block: 186100000
    contracts:
      - name: MyContract
        address:
          - "0x4fCF1784B31630811181f670Aea7A7bEF803eaED" # Testnet USDC

Notes for testnet:

• Chain ID is 1328 (vs. 1329 on mainnet).
• Testnet USDC address: 0x4fCF1784B31630811181f670Aea7A7bEF803eaED (verified on Seitrace).
• start_block: 186100000 is the first EVM block on Sei testnet. Earlier blocks are non-EVM.
• The HyperSync endpoint (https://sei-testnet.hypersync.xyz) auto-resolves from the chain ID.
• To get testnet USDC, use the Circle Faucet so the contract has activity to index.

Docs: Sei Testnet on Envio | USDC on Sei (Sei docs)

Troubleshooting​

• "An API token is required for using HyperSync as a data-source": set ENVIO_API_TOKEN in .env. The init flow normally prompts for this; if you skipped it, paste a token from envio.dev/app/api-tokens into .env.

• The indexer resumes but makes no progress (progress shows -1): the database holds stale state from an earlier aborted run. Run pnpm envio dev -r to wipe the database and re-index from scratch.

• No events showing up on mainnet: confirm start_block is at least 79123881. Blocks before that are non-EVM on Sei mainnet and contain no Solidity events. On testnet, the equivalent floor is 186100000.

• "Failed to automatically find HyperSync endpoint for the chain 1329": if the endpoint doesn't auto-resolve for your CLI version, set it explicitly under the chain entry in config.yaml:

  chains:
    - id: 1329
      start_block: 79123881
      hypersync_config:
        url: https://sei.hypersync.xyz
      contracts:
        # ...
  

  Use https://sei-testnet.hypersync.xyz for testnet (chain 1328).

Resources​

• HyperIndex overview
• Sei on Envio
• HyperSync supported networks
• Configuration file
• Schema reference
• Event handlers
• Envio CLI reference
• Running locally
• USDC on Sei (Sei docs)

Build With Envio​

Envio is a real-time multichain blockchain indexer that turns onchain events into a queryable GraphQL API. Supports any EVM chain, plus Solana and Fuel. Use Envio Cloud or self-host. If you're building onchain, come talk to us about your data needs.

Subscribe to our newsletter

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

At some point every onchain product needs the same thing. It needs to read data off a chain that was designed for sequential writes, not efficient reads. Envio ships two tools for that job at different layers of the stack, and the right choice depends on how much of the data pipeline you want to own.

In this blog we'll walk through what HyperSync and HyperIndex each are, the architecture that connects them, the code you actually write for each, the production systems running on them today, and a decision framework grounded in those mechanics.

How the Two Layers Relate​

HyperSync is the data engine. It is written in Rust and delivers up to 2000x faster data access than JSON-RPC across 85+ EVM chains and Fuel. You describe the logs, transactions, traces, or blocks you want, and it streams them back.

HyperIndex is the framework that sits on top. It uses HyperSync as its primary data source, then adds a config file, a schema, event handlers, multichain coordination, automatic reorg handling, and a GraphQL API. HyperRPC is an abstraction layer on top of HyperSync that exposes a standard JSON-RPC interface, making it a drop-in replacement for a traditional RPC endpoint in existing code.

The Envio data stack. Your application can reach the chain three ways, through the HyperIndex framework, through HyperRPC's JSON-RPC interface, or by querying the HyperSync engine directly. All three sit on the same HyperSync engine, which does the actual work of retrieving data from the blockchain.

The practical consequence of this layering is that raw retrieval speed is not the axis you choose on. All three paths pull data through the same engine. What changes is how much of the pipeline, storage, and API you build yourself.

HyperSync: The Data Engine​

HyperSync gives you the data and nothing else. There is no database, no schema, no API layer, and no hosting. There is a query interface, a fast stream of results, and whatever you build downstream.

You work with a small set of primitives. A query is a single object describing a block range, a filter section, and a field selection. Filters narrow results across logs, transactions, traces, and blocks. Field selection returns only the columns you ask for, which keeps responses small and credit usage low. Output modes decide how you consume results, with client.stream() for in-memory processing, client.collect_json() for small datasets, and client.collect_parquet() for analytical workloads.

A useful way to see what the engine unlocks is native ETH transfers. They do not emit event logs, so the only way to track them is by reading execution traces, which is slow and awkward over RPC. HyperSync exposes trace filtering directly. The example below streams call traces on Ethereum using the trace-enabled endpoint, taken from the native ETH transfers tutorial.

import { HypersyncClient, type TraceField } from "@envio-dev/hypersync-client";

const client = new HypersyncClient({
  url: "https://eth-traces.hypersync.xyz",
  apiToken: process.env.ENVIO_API_TOKEN!,
});

let query = {
  fromBlock: 22000000,
  traces: [{ callType: ["call"] }],
  fieldSelection: {
    trace: ["From", "To", "Value", "CallType", "BlockNumber"] as TraceField[],
  },
};

const stream = await client.stream(query, {});

while (true) {
  const res = await stream.recv();
  if (res === null) break;
  if (res.data?.traces) {
    console.log(`Got ${res.data.traces.length} traces`);
  }
  if (res.nextBlock) {
    query.fromBlock = res.nextBlock;
  }
}

Two mechanics in that loop are worth calling out. Filtering on callType rather than trace kind lets the engine skip irrelevant trace types upfront. Feeding res.nextBlock back into the query is the standard way to page through a large range, since a single request has a processing window and returns where it stopped. Trace endpoints are available on a growing set of chains, so check the supported networks page for the current list.

Switching chains is a one-line change to the URL, and the same client works against any supported network. Client libraries ship for TypeScript/Node.js, Python, Rust, and Go, plus a curl interface for quick testing.

In production, HyperSync is the layer behind tools that would be impractical on RPC. ChainDensity.xyz scans entire chains to render transaction and event density for any address in seconds. Scope.sh is an Account Abstraction block explorer that leans on HyperSync for fast historical retrieval. LogTUI is a zero-install terminal event viewer you can try right now with pnpx logtui aave arbitrum. The open-source Polymarket reference indexer used HyperSync to sync 4 billion events in 6 days.

HyperIndex: The Framework​

HyperIndex turns onchain events into a structured, queryable database. You declare what to index in a config.yaml, define your data model in a schema.graphql, and write handlers that map events onto entities. The framework owns the rest, including fetching data through HyperSync, persisting to Postgres, serving GraphQL, and rolling back on reorgs.

The config file is the first step to indexing. This one tracks Approval and Transfer on the UNI token across two chains at once, straight from the configuration docs.

# yaml-language-server: $schema=./node_modules/envio/evm.schema.json
name: erc20-indexer
description: ERC-20 Indexer
contracts:
  - name: ERC20
    events:
      - event: "Approval(address indexed owner, address indexed spender, uint256 value)"
      - event: "Transfer(address indexed from, address indexed to, uint256 value)"
chains:
  - id: 1 # Ethereum Mainnet
    start_block: 0
    contracts:
      - name: ERC20
        address: "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984" # UNI
  - id: 100 # Gnosis Mainnet
    start_block: 0
    contracts:
      - name: ERC20
        address: "0x4537e328Bf7e4eFA29D05CAeA260D7fE26af9D74" # UNI

Notice there is no RPC URL. For chains supported by HyperSync, it is the primary data source out of the box, and you can add an RPC entry purely as a fallback. Setting start_block to 0 is safe because HyperSync fast-forwards to the first block that holds data for your contracts.

The schema defines the entities you query.

type Transfer {
  id: ID!
  from: String!
  to: String!
  value: BigInt!
}

The handler maps each event onto those entities. This is the full v3 mental model, where you describe what an event means for your data and the framework keeps the database current.

import { indexer } from "envio";

indexer.onEvent(
  { contract: "ERC20", event: "Transfer" },
  async ({ event, context }) => {
    context.Transfer.set({
      id: `${event.chainId}_${event.block.number}_${event.logIndex}`,
      from: event.params.from,
      to: event.params.to,
      value: event.params.value,
    });
  },
);

Three framework features do real work here that you would otherwise build by hand.

Factory contracts are handled with a contractRegister handler. When a factory emits a creation event, you register the new contract address and the framework starts indexing it, including events in the same block as the creation. This is how Envio indexes data from over 1M dynamically registered contracts.

import { indexer } from "envio";

indexer.contractRegister(
  { contract: "NftFactory", event: "SimpleNftCreated" },
  ({ event, context }) => {
    context.chain.SimpleNft.add(event.params.contractAddress);
  },
);

External calls run through the Effect API, which batches and memoizes requests so a network call inside a handler does not become a per-event bottleneck. You define an effect once with optional caching and rate limiting, then call it from any handler.

import { indexer, createEffect, S } from "envio";

const getMetadata = createEffect(
  {
    name: "getMetadata",
    input: S.string,
    output: { description: S.string, value: S.bigint },
    cache: true,
    rateLimit: { calls: 5, per: "second" },
  },
  async ({ input }) => {
    const response = await fetch(`https://api.example.com/metadata/${input}`);
    const data = await response.json();
    return { description: data.description, value: data.value };
  },
);

Reorg handling is automatic. rollback_on_reorg defaults to true, so the indexer detects reorganisations and rolls affected entities back without you writing recovery logic. You can also keep the indexer a few blocks behind the head with block_lag if you want extra safety, or store entities in ClickHouse alongside Postgres for analytics workloads.

On performance, HyperIndex is the fastest indexer in independent testing. In Sentio's May 2025 benchmark of the Uniswap V2 Factory case, it finished in 8 seconds, 15x faster than the nearest competitor (Subsquid) at 2 minutes, 142x faster than The Graph at 19 minutes, and 157x faster than Ponder at 21 minutes. Historical backfills run at 30,000+ events per second. The full table is on the benchmarks page, and the open-indexer-benchmark repo lets you reproduce it.

In production, the framework shows up wherever a team needs a backend rather than a script. Sablier replaced 12 separate indexer deployments with one multichain indexer now spanning 27 chains. The Polymarket case study consolidated 8 subgraphs into a single indexer on Polygon. Revert Finance synced a PancakeSwap V3 dataset on BNB Smart Chain that had been stuck at 70% on The Graph for over two years, reaching 100% in 10 days across 1.7 billion events.

The Decision, by Mechanics​

The choice follows from the architecture. HyperIndex gives you a persistent, structured store and an API in exchange for working within a schema and handler model. HyperSync gives you raw data and total control in exchange for building storage and any API yourself. The table maps concrete needs onto the layer that serves them.

A shorter version of the same logic. If you would otherwise stand up a database, a GraphQL server, and reorg handling, use HyperIndex, because it already did that work. If you would otherwise fight a framework to get at raw data, use HyperSync, because that is all it returns.

Using HyperIndex & HyperSync Together​

The layering means these are not exclusive choices, and many teams run both. A common split is HyperIndex for the application backend that powers the product and HyperSync directly for a side workload, such as a nightly Parquet export or an internal analytics dashboard. The product gets a managed API, the data team gets raw access, and both ride the same engine.

The other common path is to start with HyperIndex and reach for HyperSync only when a specific need appears, like a one-off backfill or a monitoring script that does not belong in your indexer. Because HyperIndex already runs on HyperSync, dropping to the raw engine for one job is a natural step rather than a migration.

Where HyperRPC Fits​

HyperRPC is the option for existing RPC-based code you do not want to rewrite. It is an abstraction over HyperSync that exposes a standard JSON-RPC interface, supporting methods like eth_getLogs, eth_getBlockByNumber, and eth_getTransactionReceipt, with early benchmarks showing up to 5x improvement over traditional nodes like geth, erigon, and reth on data-heavy reads.

Use it when you need a drop-in speed boost for tooling that expects standard JSON-RPC. For new projects where you design the data layer, the docs recommend HyperSync, because it is faster and far more flexible. Neither HyperRPC nor HyperSync can send transactions; both are read paths, and you still need a standard RPC for writes.

How to Try Each​

To feel HyperSync with zero install, run the LogTUI event viewer.

pnpx logtui aave arbitrum

To scaffold a full indexer with config, schema, handlers, and a GraphQL API, initialise a HyperIndex project.

pnpx envio init

Both paths use HyperSync, which requires an API token. Indexers deployed to Envio Cloud have special access and do not need a custom token.

Frequently Asked Questions​

I already run a HyperIndex indexer. When would I ever query HyperSync directly?​

When you have a data job that does not belong in your indexer. HyperIndex keeps a structured, reorg-safe dataset in sync for your application, but a one-off Parquet export, a chain-wide scan for sparse data, or a standalone monitoring script with custom logic are all lighter on raw HyperSync. Since HyperIndex already uses HyperSync as its data source, you are reaching one layer down for a specific task rather than replacing anything.

Is HyperIndex slower than querying HyperSync directly?​

For backfilling and serving structured data, no. HyperIndex uses HyperSync as its primary data source and adds preload optimization on top, so the framework layer manages schema, storage, reorgs, and the API rather than slowing retrieval. Raw HyperSync only feels faster on narrow tasks where you deliberately skip building a database and API, such as a streaming script.

Do I have to run my own database with HyperSync?​

If you want to persist what you pull, yes. HyperSync streams data to you and stores nothing on your behalf, so you bring your own storage, whether that is Postgres, a Parquet file, or a warehouse. HyperIndex is the layer that gives you a managed Postgres database and GraphQL API without setting one up.

Which layer handles factory contracts and dynamic addresses?​

HyperIndex, through the contractRegister handler. You register a contract type without an address in config.yaml, then call context.chain.<Contract>.add(address) when a factory event fires, and the framework indexes every instance, including events in the creation block. Doing the equivalent on raw HyperSync means tracking the address set and filtering queries yourself.

How do I track native ETH transfers, which do not emit logs?​

Query traces on HyperSync. Native transfers only appear in execution traces, so you filter on callType: ["call"] against a trace-enabled endpoint like https://eth-traces.hypersync.xyz and stream the results. Check the supported networks page for the current list.

Can I start with HyperIndex and move a workload to HyperSync later?​

Yes. Starting with HyperIndex gets a working backend up quickly, and because it runs on HyperSync, moving a specific workload to the raw engine later is straightforward. Most teams end up using each where it fits rather than committing to one for everything.

Does HyperIndex handle reorgs, or do I build that myself?​

HyperIndex handles them automatically. rollback_on_reorg defaults to true, so the indexer detects a reorganisation and rolls affected entities back without recovery code. On raw HyperSync, you would design reorg handling yourself, which is one of the main reasons to use the framework for stateful backends.

Build With Envio​

Envio is a real-time multichain blockchain indexer that turns onchain events into a queryable GraphQL API. Supports any EVM chain, plus Solana and Fuel. Use Envio Cloud or self-host. If you're building onchain, come talk to us about your data needs.

Subscribe to our newsletter

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

May was our biggest month yet. After five months of alpha and release candidates, HyperIndex V3 officially shipped, production-ready, faster, and the foundation for everything we build next. Alongside it we went live on Katana, published four large-scale case studies (Polymarket, Revert Finance, Privacy Pools, and Katana's SushiSwap migration off The Graph), and shipped a stack of deep-dive guides on HyperSync, production reliability, and building onchain with AI.

We also joined Monad's Devrel livestream to talk HyperIndex, started rolling out HyperSync rate limits ahead of paid plans, and confirmed our ETHConf New York sponsorship in June.

Let's dive in!

HyperIndex V3 Is Here​

After five months of alpha, HyperIndex V3 officially shipped. This is the biggest release in the framework's history, a full modernisation that bundles five months of work into a stable, production-ready release. A unified handlers API, ESM with top-level await, a purpose-built testing framework, 3x faster historical sync, Solana support, ClickHouse as a second storage backend, and a much smaller package. With V3 we are back to following SemVer and set up for the next year of features.

To upgrade an existing project, follow the Migrate to V3 guide. For the complete rundown, see What's New in V3.

Unified Handlers API​

All handler registrations now flow through a single indexer value. Contract-specific exports are replaced by indexer.onEvent, indexer.contractRegister, and indexer.onBlock.

import { indexer } from "envio";

indexer.onEvent(
  {
    contract: "ERC20",
    event: "Transfer",
    wildcard: true,
    where: ({ chain }) => ({
      params: [
        { from: chain.Safe.addresses },
        { to: chain.Safe.addresses },
      ],
    }),
  },
  async ({ event, context }) => {
    // Handler logic
  },
);

3x Faster Historical Backfill​

We added chunking logic to request events across multiple ranges at once, removed overfetching for contracts with a much later start block, and sped up dynamic contract registration.

25k events per second is now standard.

A Purpose-Built Testing Framework​

HyperIndex now ships its own testing framework powered by createTestIndexer(). You write tests against the same indexer that runs in production, with no database, no Docker, and no manual mock wiring. It integrates with Vitest, includes snapshot testing out of the box, and gives you three ways to feed events (auto-exit, explicit block range, or simulate).

import { describe, it } from "vitest";
import { createTestIndexer } from "envio";

describe("ERC20 indexer", () => {
  it("processes the first block with events", async (t) => {
    const indexer = createTestIndexer();

    const result = await indexer.process({ chains: { 1: {} } });

    // Auto-filled by Vitest on first run -- just review and commit
    t.expect(result).toMatchInlineSnapshot(`
      {
        "changes": [
          {
            "Transfer": {
              "sets": [
                {
                  "blockNumber": 10861674,
                  "from": "0x0000000000000000000000000000000000000000",
                  "id": "1-10861674-23",
                  "to": "0x41653c7d61609D856f29355E404F310Ec4142Cfb",
                  "transactionHash": "0x4b37d2f343608457ca...",
                  "value": 1000000000000000000000000000n,
                },
              ],
            },
            "block": 10861674,
            "chainId": 1,
            "eventsProcessed": 1,
          },
        ],
      }
    `);
  });
});

ESM and Top-Level Await​

We migrated HyperIndex from CommonJS to ESM. That unlocks the latest versions of libraries that dropped CommonJS long ago, and lets you use await directly at the top of your handler files.

Solana Support (Experimental)​

HyperIndex now supports Solana with RPC as a source. Spin up a Solana project with pnpx envio init svm. Solana exposes its block-stream handler as indexer.onSlot rather than onBlock, matching Solana's slot-based model.

ClickHouse as an Additional Storage Backend (Experimental)​

HyperIndex can now run with multiple storage backends side by side. Postgres remains the primary database, and entities can additionally be written to a ClickHouse database that is restart and reorg resistant. Enable it in config.yaml and route each entity via the @storage directive in schema.graphql.

storage:
  postgres: true
  clickhouse: true

Envio Cloud supports ClickHouse on the Dedicated Plan.

A Much Smaller Package and Bun Support​

You can run HyperIndex on Bun with bun --bun envio dev, and we removed the runtime ReScript compiler from the published package by eliminating dynamically generated ReScript code.

The envio npm package shrank from 141MB to 53MB.

Agentic Mode in envio init​

envio init now ships an agentic mode. When an AI coding assistant runs the command, it produces an AI-readable guiding prompt instead of a TTY error, so the agent knows exactly how to scaffold an indexer end to end.

Welcome to Envio Indexer! Let's set up an indexer that will become a reliable blockchain backend you trust, love, and own.

Leave the rest to your favorite agent:

  1. Prompt the user for the project intent if it is missing from context (what should the indexer track and surface?).
  2. Determine the chain, contract, and addresses needed to produce that result. Use web search or block-explorer tool calls when the user hasn't supplied them.
  3. To continue, call:

       pnpx envio init contract-import explorer \
         -n ${indexer-name} \
         -c ${address} \
         -b ${chainId} \
         --single-contract \
         --all-events \
         -d ${directory}

Then `cd ${directory}` and run `pnpm test`. Don't hand the project off yet -- keep iterating on the indexer with a TDD loop (extend tests, run them, fix handlers) until the user's goal is met.

See the full release notes

Star us on GitHub ⭐

Envio is Live on Katana​

We launched production-grade indexing on Katana, the DeFi-first chain built where liquidity concentrates and real yield flows back to users. Developers can now access real-time and historical onchain data on Katana, up to 2000x faster than RPC.

Easy, fast, and fully customisable.

Original post on X: https://x.com/katana/status/2056389958303441051

Indexing 4 Billion Polymarket Events​

We replaced Polymarket's eight production subgraphs, four years of fragmentation across separate AssemblyScript codebases on The Graph, with a single HyperIndex indexer written in TypeScript. Over 4 billion events synced in 6 days on Polygon.

The unlock is handler merging. A shared contract event like ConditionalTokens.PositionSplit previously fired across three or four separate subgraphs. In the unified indexer, one handler fires once and updates open interest, activity, and PnL together. That is 25+ entity types behind a single GraphQL endpoint, and one deployment to maintain instead of eight. The full indexer is open source as a reference for any team migrating from The Graph.

Read the case study: https://docs.envio.dev/blog/polymarket-hyperindex-case-study

Revert Finance Fixed 2 Years of Unsynced PancakeSwap V3 Data​

Revert Finance builds analytics and management tools for AMM liquidity providers. Their PancakeSwap V3 subgraph on BNB Smart Chain had been stuck at 70% sync for over two years, unable to reach chain head, because the chain's throughput outpaced what RPC-based indexing could sustain.

We built a HyperIndex indexer covering the full PancakeSwap V3 contract surface on BNB Smart Chain. 1,711,569,200 events synced to 100% in 10 days.

Read the case study: https://docs.envio.dev/blog/revert-finance-pancakeswap-bnb-hyperindex

Privacy in Public, Indexing Privacy Pools​

Privacy Pools is a privacy primitive co-authored by Vitalik Buterin that pairs a zero-knowledge proof of pool membership with an off-chain compliance layer. We indexed every deposit, withdrawal, ragequit, ASP root update, and relayer fee across all 21 live pools on four chains (Ethereum, Optimism, BSC, and Arbitrum) with a single HyperIndex indexer using dual Postgres and ClickHouse storage.

Full multichain sync to head in roughly 30 seconds, and 91% of withdrawals use the privacy-preserving relayed path. The full stack, including the indexer, the analytics queries, and the BI report generator, is open source under MIT license. It is a great example of multichain coverage and an analytics-grade columnar store as first-class features.

Read the case study: https://docs.envio.dev/blog/privacy-in-public-case-study

Katana Migrates SushiSwap Off The Graph​

Katana migrated two production subgraphs, SushiSwap V3 and the Sushi staker, from The Graph to Envio HyperIndex without disrupting the app surfacing the data. Katana's existing subgraph-style queries kept working through Envio's subgraph-compatible endpoint, and for the full GraphQL feature set its app needed, Katana moved onto Envio's native endpoint, with our team supporting the move directly.

SushiSwap V3 synced 11,473,382 events in about two hours, and the Sushi staker synced 68,201 events in under 20 seconds.

Read the case study: https://docs.envio.dev/blog/case-study-katana-sushiswap

What is HyperSync?​

Reading onchain data over standard JSON-RPC breaks down the moment you need fast, filtered, or multichain historical data. HyperSync is our high-performance data retrieval layer built to fix exactly that. It is written in Rust, uses optimised binary encoding and parallel fetching, and exposes a single query interface across every supported chain.

Scanning Arbitrum for sparse log data takes 2 seconds with HyperSync, up to 2000x faster than RPC. HyperSync is the engine behind HyperIndex. Client libraries are available for TypeScript, Python, Rust, and Go. This blog covers what it is, how it works, and how to use it in your own application.

Learn more here: https://docs.envio.dev/blog/what-is-hypersync

Production Indexer Reliability with HyperIndex​

Speed wins benchmarks, but reliability is what keeps an indexer running for years. This post walks through the four reliability guarantees HyperIndex provides at the framework level, so any indexer built on it inherits them without writing operational code. Those guarantees are built-in reorg handling with automatic rollback, restart-resistant operation, HyperSync data validation, and multi data-source recovery.

Reorgs are handled automatically by tracking entity state history for every unfinalized block and rolling back without any custom handler logic. Multi data-source recovery fails over to a fallback within seconds and recovers to the primary 60 seconds later. Observability comes through a semver-stable Prometheus endpoint.

More here: https://docs.envio.dev/blog/production-indexer-reliability-hyperindex

Why AI Agents Acting Onchain Need an Indexer​

SQL warehouses let agents ask. Indexers let them act. An agent reading raw RPC hits four walls quickly, namely reorgs, no schema, low throughput, and per-chain quirks at multichain scale. A SQL warehouse fronted by an LLM solves the read side, but an agent acting onchain needs to build, deploy, and own new data pipelines mid-session, not just query existing ones.

This post makes the case for a programmable indexer over a query layer, backed by the docs MCP server, the auto-discovered .claude/skills/ directory, and the GitHub-native deploy flow.

One prompt, roughly 20 seconds, 400,000 events indexed on Monad.

Read the full breakdown: https://docs.envio.dev/blog/ai-agents-acting-onchain-indexer

AI-Assisted Subgraph Migration to HyperIndex with Claude​

The hardest part of moving off The Graph has always been the AssemblyScript rewrite. With the docs MCP server and the dedicated migrate-from-subgraph skill shipped in every HyperIndex project, Claude can handle the AssemblyScript-to-TypeScript translation end to end while a developer reviews the diff, runs the tests, and ships the indexer.

This guide walks the full workflow on a real surface area, anchored to the open-source Polymarket reference. A migration that used to take weeks becomes a one or two day exercise.

Read the full tutorial: https://docs.envio.dev/blog/ai-subgraph-migration-hyperindex-claude

Build an AI-Powered Onchain App with HyperIndex and Claude​

A practical, end-to-end walkthrough of building a multichain HyperIndex indexer with Claude as a pair programmer. It covers wiring up the docs MCP server, scaffolding the project, making it multichain, writing the schema and handlers, running locally, and deploying to Envio Cloud through the GitHub-native flow.

Every command is reproducible against the current release, and the patterns come straight from the public Polymarket reference indexer. With Claude driving, you can go from a blank project to a deployed, queryable indexer in minutes.

More here: https://docs.envio.dev/blog/ai-onchain-app-hyperindex-claude

Migrating from Ponder to Envio​

Both Ponder and HyperIndex are TypeScript-first and expose a GraphQL API, so migration is mostly mechanical translation. Three things change. ponder.config.ts becomes config.yaml, ponder.schema.ts becomes schema.graphql, and event handlers adapt to the HyperIndex entity API. This guide walks all three steps end to end, with every code block taken from the official migration reference.

Up to 157x faster historical sync via HyperSync, with multichain support by default.

For teams looking for a clear path forward, our team supports the migration end to end, from planning the rewrite to getting the indexer live on Envio Cloud.

Read the full tutorial: https://docs.envio.dev/blog/migrate-from-ponder-to-envio

HyperSync Rate Limits​

Throughout May we have been rolling out HyperSync rate limits more aggressively. Limits ratchet down gradually so you get the smoothest possible transition to paid plans without disruption to your services. Keep an eye out for 429 rate limit exceeded errors.

If you are already on a paid HyperSync plan, your normal plan limits apply and no action is needed. If you are not on a paid plan yet, get sorted as soon as possible by opening a Discord ticket to arrange one with the team, or by picking a plan directly.

This affects all HyperSync users and anyone self-hosting HyperIndex with a HyperSync token. Envio Cloud deployments are not affected.

Polymarket's Top Traders Run on Indexed Data​

Co-founder Jonjon Clark published a data-driven series profiling the top 100 Polymarket traders by realised PnL, and the deeper he digs, the clearer it becomes that these operations live or die on fast, real-time access to onchain data, exactly the workload HyperIndex and HyperSync are built for. Here are a few that stand out.

The 95% Win Rate Trader​

$23.6M in realised PnL and a 95.4% win rate. It runs a live NBA model that prices games faster than the order book, pre-positions on the cheap side before tip-off, and rides the eventual winner to oracle redemption.

Read the thread

The 15-Minute Bitcoin Loop Trader​

7.6 million fills across 32,021 markets in 111 days, about one fill per second, netting $2.38M. It posts resting bids on both sides of Polymarket's 15-minute BTC binaries and captures the spread off retail flow, completely indifferent to which way Bitcoin moves.

Read the thread

The UMA Gap Trader​

Number 26 on the leaderboard with $8M in lifetime realised PnL. Its cleanest mechanism is the settlement sweep, buying near-par winning tokens in the gap between when a result is known and when the UMA oracle finalises payout, for a 98.2% win rate across more than 4,000 positions.

Read the thread

Envio x Monad's Devrel Livestream​

Co-founder Denham joined Monad's Devrel Livestream to chat HyperIndex on Monad, Monskills, and how to vibecode your way to a production indexer.

Missed it live? Catch the full recording on X.

Current & Upcoming Events & Hackathons​

• ETHConf - New York: June 8th -> 10th (sponsoring)

Playlist of the Month​

▶ Open Spotify

Build With Envio​

Envio is a multichain EVM blockchain indexer for querying real-time and historical data. If you're working on a Web3 project and want a smoother development process, Envio's got your back(end). Check out our docs, join the community, and let's talk about your data needs.

Stay tuned for more monthly updates by subscribing to our newsletter, following us on X, or hopping into our Discord for more up-to-date information.

Subscribe to our newsletter 💌

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

Migrating your data infrastructure from one provider to another is rarely simple, mostly because of everything that has to change around it. Katana is a DeFi network, and its app surfaces SushiSwap data such as V3 pools, swaps, fees, positions, and staking to its users. That data was served by two production subgraphs running on The Graph. Katana wanted to move this data layer to Envio HyperIndex without disrupting the apps that depend on it.

Because this was a live production system rather than a greenfield build, the priority was continuity. The existing queries had to keep working and the data had to stay correct. This case study walks through how the migration came together, from the subgraph-compatible endpoint that kept Katana's queries running to the hands-on support that handled the rest.

The Challenge: Moving a Production Data Layer Without Disrupting It​

Katana's existing subgraph queries were wired into production and had to keep working. Data quality and expected behaviour had to be preserved. And it had to be efficient, a swap, not a multi-week infrastructure project. For DeFi data, correctness and uptime were non-negotiable, because their application and users depended on it.

During development, the team also noticed the existing subgraph data often running around three blocks behind the chain head. For user-facing DeFi data, that kind of freshness gap matters.

The Solution: A Subgraph-Compatible Path off The Graph​

The migration came down to two things. Envio's tooling fit the setup Katana already had, and the support was there at every step.

The foundation was schema parity. The HyperIndex deployment reproduces the original Sushi V3 subgraph entity-for-entity, all 23 entity types, tracking the Uniswap V3 factory, the position manager, and every pool it deploys. Same entities, same shape, so Katana did not have to redesign its data or rebuild against a new model.

Envio exposes two GraphQL endpoints, a subgraph-compatible one that runs existing subgraph-style queries as a drop-in, and a native one with the full query feature set. Katana's standard queries ran against the compatible endpoint, and for the full feature set its app needed, Katana standardised on the native endpoint, with the Envio team working through the move alongside them.

Contracts Indexed​

The SushiSwap V3 indexer runs on Katana mainnet:

The process was a fork-and-deploy flow. Katana forked the indexer, connected it to Envio Cloud, and deployed, while the Envio team handled the backend configuration, set up the subgraph-compatible endpoint, and managed the caching for the deployment. The team could also validate on a fast instance first. With the most RPC-heavy fields turned off, backfill ran about ten times faster, so they could confirm everything looked right before running the full indexer with every field populated.

The Envio team set up the endpoints, configured the caching, and worked through the query migration directly with Katana's engineers.

The Results​

Katana migrated both production subgraphs, SushiSwap V3 and the Sushi staker, from The Graph to Envio. Its existing queries kept working through the subgraph-compatible endpoint, so the app did not need a rewrite. A third subgraph, a pre-staking one with deprecation already planned, was left as-is by design.

The SushiSwap V3 indexer on Envio, fully synced (11,473,382 events) in about two hours.

The Sushi staker subgraph, fully synced (68,201 events) in under 20 seconds on Envio.

With the migration complete, both SushiSwap indexers run on Envio Cloud, serving Katana's app through the same queries it used before. Where the original subgraph had drifted a few blocks behind, the new indexer indexes in real time at the chain head.

Before and After the Migration​

What Carries Over When You Move Off The Graph​

A subgraph rarely sits on its own. Queries, dashboards, and app code are all built against its schema, which is what makes moving it feel risky. The part that carries over cleanly is the data model. Because the HyperIndex indexer reproduced the Sushi V3 subgraph entity-for-entity, Katana did not have to redesign its data or rebuild against a new model. On the query side, Envio gives you a subgraph-compatible endpoint for a drop-in start and a native GraphQL endpoint for the full feature set, and Katana's app runs on the native one.

For a team considering a migration off The Graph, Envio's subgraph-compatible endpoint is what makes it a swap rather than a multi-week rebuild.

Relevant Resources​

• Katana SushiSwap V3 indexer (GitHub)
• Original Sushi staker subgraph on The Graph
• Indexing Katana Data with Envio
• Migrating from The Graph
• HyperIndex Quickstart
• HyperSync
• Envio Cloud

Frequently Asked Questions​

What is Katana?​

Katana is a DeFi-focused blockchain, designed to concentrate liquidity into a small set of core applications instead of spreading it thin across many. SushiSwap V3 is its spot exchange, which is why the Katana app surfaces SushiSwap data such as pools, swaps, fees, and staking to its users.

What is SushiSwap?​

SushiSwap is a decentralised exchange (DEX). Its V3 deployment, the concentrated-liquidity version, is Katana's spot trading venue, and it generates the pools, positions, swaps, and fees that the migrated subgraphs index.

What did Katana migrate?​

Two production subgraphs, the SushiSwap V3 subgraph and the Sushi staker subgraph, both from The Graph to Envio HyperIndex. A third, pre-staking subgraph scheduled for deprecation was not migrated.

What did Katana have to change to migrate?​

The data model carried over entity-for-entity, so there was no schema rebuild. Katana's existing queries ran against Envio's subgraph-compatible endpoint, and for the full GraphQL feature set its app needed, Katana moved its queries onto Envio's native endpoint, with the Envio team supporting the move.

What is the subgraph-compatible endpoint?​

It is an Envio feature that runs existing The Graph subgraph-style GraphQL queries against a HyperIndex deployment, a drop-in path for standard subgraph queries. For the full GraphQL feature set, Envio also exposes a native endpoint, which is what Katana's app runs on.

How do I migrate from The Graph to HyperIndex?​

HyperIndex handlers are written in TypeScript, and AssemblyScript is a subset of TypeScript, so most handler logic carries across directly. Envio provides a migration guide, a subgraph-compatible endpoint that preserves existing queries, and hands-on migration support.

Build With Envio​

Envio is a real-time multichain blockchain indexer that turns onchain events into a queryable GraphQL API. Supports any EVM chain, plus Solana and Fuel. Use Envio Cloud or self-host. If you're building onchain, come talk to us about your data needs.

Subscribe to our newsletter

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

If you are running a Ponder indexer in production, you already know two things. The framework is TypeScript end-to-end, and historical backfills using RPC are the bottleneck. Envio HyperIndex keeps the TypeScript and removes the bottleneck. Up to 157x faster sync via HyperSync, same GraphQL API on top.

This blog walks the three-step migration end to end. Every code block is taken directly from the official migration reference in our docs.

AI-Assisted Migration​

If you prefer not to do the rewrite by hand, HyperIndex ships with built-in Claude skills that guide AI coding assistants through the migration. See our Quickstart with AI guide that walks you through the full setup.

Combined with the Envio docs MCP server, an agent can read your Ponder config, schema, and handlers, and produce the HyperIndex equivalents while you review the diff. Learn more about general AI-assisted migration in our blog. The same flow applies to Ponder migration.

Migration Overview​

Three steps plus a bootstrap:

1. ponder.config.ts becomes config.yaml
2. ponder.schema.ts becomes schema.graphql
3. Event handlers adapt syntax and entity operations

At any point during the migration, run:

pnpm envio codegen   # validate config + schema, regenerate types
pnpm dev             # run the indexer locally

If you are new to HyperIndex, see the Getting Started guide.

Step 0: Bootstrap the Project​

pnpx envio init

Follow the prompts, using your Ponder project as the source of truth for contract addresses, ABIs, and events. This generates a boilerplate indexer you can use as a base to edit.

Convert your ABIs first. Ponder exports ABIs as TypeScript (as const). For each contract, strip the export const ... = wrapper and the as const, and save it as a plain .json file in abis/. Have these ready before running envio init, because the local ABI import asks for the path to each contract's JSON ABI file. If a contract is verified on a block explorer, envio init can fetch the ABI for you instead.

Step 1: ponder.config.ts to config.yaml​

Here is the same indexer configured in both frameworks, taken from the migration docs.

Ponder:

import { createConfig } from "ponder";

export default createConfig({
  chains: {
    mainnet: { id: 1, rpc: process.env.PONDER_RPC_URL_1 },
  },
  contracts: {
    MyToken: {
      abi: myTokenAbi,
      chain: "mainnet",
      address: "0xabc...",
      startBlock: 18000000,
    },
  },
});

HyperIndex:

# yaml-language-server: $schema=./node_modules/envio/evm.schema.json
name: my-indexer
contracts:
  - name: MyToken
    abi_file_path: ./abis/MyToken.json
    events:
      - event: Transfer
      - event: Approval
chains:
  - id: 1
    start_block: 0
    contracts:
      - name: MyToken
        address:
          - 0xabc...
        start_block: 18000000

Key differences:

Field selection for transaction and block fields​

By default, only a minimal set of fields is available on event.transaction and event.block. Fields like event.transaction.hash are undefined unless explicitly requested.

Per-event:

events:
  - event: Transfer
    field_selection:
      transaction_fields:
        - hash

Or declared once at the top level to apply to all events:

name: my-indexer
field_selection:
  transaction_fields:
    - hash
contracts:
  # ...

See full list of available fields in our docs.

Step 2: ponder.schema.ts to schema.graphql​

Ponder:

import { onchainTable, primaryKey, index } from "ponder";

export const token = onchainTable("token", (t) => ({
  address: t.hex().primaryKey(),
  symbol: t.text().notNull(),
  balance: t.bigint().notNull(),
}));

export const transferEvent = onchainTable(
  "transfer_event",
  (t) => ({
    id: t.text().primaryKey(),
    from: t.hex().notNull(),
    to: t.hex().notNull(),
    amount: t.bigint().notNull(),
    timestamp: t.integer().notNull(),
  }),
  (table) => ({
    fromIdx: index().on(table.from),
  }),
);

HyperIndex:

type Token {
  id: ID!
  symbol: String!
  balance: BigInt!
}

type TransferEvent {
  id: ID!
  from: String! @index
  to: String!
  amount: BigInt!
  timestamp: Int!
}

Type mapping, taken from the migration docs:

Three more conversion rules.

Primary keys. HyperIndex requires a single id: ID! string field on every entity. For composite primary keys (e.g. owner + spender), construct the ID string manually: ${owner}_${spender}.

Indexes. Replace Ponder's index().on(column) with an @index directive on the field.

Relations. Replace Ponder's relations() call with @derivedFrom on the parent entity:

type NftCollection {
  id: ID!
  contractAddress: Bytes!
  name: String!
  symbol: String!
  maxSupply: BigInt!
  currentSupply: Int!
  tokens: [Token!]! @derivedFrom(field: "collection")
}

type Token {
  id: ID!
  tokenId: BigInt!
  collection: NftCollection!
  owner: User!
}

Full schema reference at https://docs.envio.dev/docs/HyperIndex/schema.

Step 3: Event Handlers​

Handler registration changes shape.

Ponder:

import { ponder } from "ponder:registry";

ponder.on("MyToken:Transfer", async ({ event, context }) => {
  // ...
});

HyperIndex (v3):

import { indexer } from "envio";

indexer.onEvent({ contract: "MyToken", event: "Transfer" }, async ({ event, context }) => {
  // ...
});

Event data access​

The accessors are slightly different. Here is the full mapping from the migration docs:

Entity operations​

This is the part that takes the most rewriting. The Ponder drizzle-style API maps to a different shape in HyperIndex.

Full handler example

Ponder:

ponder.on("MyToken:Transfer", async ({ event, context }) => {
  await context.db.insert(transferEvent).values({
    id: event.id,
    from: event.args.from,
    to: event.args.to,
    amount: event.args.amount,
    timestamp: Number(event.block.timestamp),
  });

  await context.db
    .update(token, { address: event.args.to })
    .set((row) => ({ balance: row.balance + event.args.amount }));
});

HyperIndex (v3):

import { indexer } from "envio";

indexer.onEvent({ contract: "MyToken", event: "Transfer" }, async ({ event, context }) => {
  context.TransferEvent.set({
    id: `${event.transaction.hash}_${event.logIndex}`,
    from: event.params.from,
    to: event.params.to,
    amount: event.params.amount,
    timestamp: event.block.timestamp,
  });

  const token = await context.Token.getOrThrow(event.params.to);
  context.Token.set({
    ...token,
    balance: token.balance + event.params.amount,
  });
});

Heads up. The ID above uses event.transaction.hash, which is not available by default. Add transaction_fields: [hash] under field_selection in config.yaml as shown in Step 1, or build the ID from fields that are always available (e.g. ${event.chainId}_${event.block.number}_${event.logIndex}).

One rule that catches every team. Entity objects from context.Entity.get() are read-only. Always spread (...existing) and set new fields. Never mutate directly.

Full event handlers reference at https://docs.envio.dev/docs/HyperIndex/event-handlers.

Factory Contracts (Dynamic Registration)​

Ponder uses a factory() helper in the config. HyperIndex uses a contractRegister handler.

import { indexer } from "envio";

indexer.contractRegister({ contract: "MyFactory", event: "ContractCreated" }, ({ event, context }) => {
  context.chain.MyContract.add(event.params.contractAddress);
});

In config.yaml, omit the address field for the dynamically registered contract.

The Polymarket reference indexer uses dynamic contract registration for FPMM pools created by FPMMFactory. See https://github.com/enviodev/polymarket-indexer/blob/main/src/handlers/FPMMFactory.ts for the production example (note: Polymarket is still on v2 syntax, the v3 equivalent is shown above).

External Calls (Effect API)​

Replace context.client.readContract(...) with the Effect API. This isolates external calls (fetch, RPC, async I/O) from the sync path safely.

import { createEffect, S } from "envio";

export const getSymbol = createEffect(
  {
    name: "getSymbol",
    input: S.string,
    output: S.string,
    cache: true,
    rateLimit: { calls: 5, per: "second" },
  },
  async ({ input }) => {
    // implementation: fetch the symbol from RPC for the given address
  },
);

Per the Effect API guide, external calls (fetch, RPC, async I/O) should be wrapped in createEffect and invoked via context.effect, which provides automatic batching, memoization, deduplication, and rate-limiting.

What Carries Across, What Changes​

A condensed summary.

Carries across without change:

• TypeScript handler logic (entity writes, math, conditionals)
• GraphQL API (your frontend queries do not change)
• ABI bytes (just re-serialised as JSON)
• Indexed entities (data model)

Changes during migration:

• Config file format (.ts to .yaml)
• Schema file format (drizzle table builder to GraphQL SDL)
• Entity operation API (db.insert/update to context.Entity.set)
• External calls (use Effect API)
• Factory contract pattern (config factory() to handler indexer.contractRegister)
• Event parameter access (event.args to event.params)
• Transaction field access (needs explicit field_selection)

For most projects, the body of the work is mechanical translation. Claude with the built-in HyperIndex skills can handle most of it under developer review.

Why Migrate​

From the Sentio Uniswap V2 Factory benchmark:

HyperIndex completed the workload 157x faster.

Three concrete reasons to migrate.

Speed. Up to 157x faster historical sync via HyperSync. For Ponder users running backfills against RPC, that is hours into minutes.

Multichain by default. One config covers any number of chains. Ponder's per-chain configuration is replaced by a single chains: array.

Same language. TypeScript handlers transfer directly. The migration is syntax adjustment, not a language rewrite.

Get Started​

• Full Ponder migration reference: https://docs.envio.dev/docs/HyperIndex/migrate-from-ponder
• Getting Started: https://docs.envio.dev/docs/HyperIndex/getting-started
• Quickstart with AI: https://docs.envio.dev/docs/HyperIndex/quickstart-with-ai
• Configuration reference: https://docs.envio.dev/docs/HyperIndex/configuration-file
• Schema reference: https://docs.envio.dev/docs/HyperIndex/schema
• Event handlers reference: https://docs.envio.dev/docs/HyperIndex/event-handlers
• Polymarket production reference: https://github.com/enviodev/polymarket-indexer
• GitHub releases (current versions): https://github.com/enviodev/hyperindex/releases

For teams affected by the Ponder acquisition looking for a clear path forward, the Envio team supports the migration end-to-end, from planning the rewrite to reviewing the diff to getting the indexer live on Envio Cloud. Reach out on Discord and we will help you scope it.

Frequently Asked Questions​

How long does a Ponder-to-HyperIndex migration take?​

For a small project (one or two contracts, single chain), a manual migration is typically a few hours. With the AI-assisted flow, faster. Larger projects with multiple contracts, factory patterns, and external calls take longer, but the bulk of the work is mechanical translation that Claude can often complete in a few hours to a day, with a developer reviewing the output.

Is HyperIndex faster than Ponder in production?​

Yes. In the Sentio Uniswap V2 Factory benchmark, HyperIndex completed in 8 seconds. Ponder completed in approximately 21 minutes. HyperIndex was 157x faster on that workload. See benchmark comparison.

Does HyperIndex support TypeScript like Ponder?​

Yes. HyperIndex handlers are standard TypeScript. Both frameworks share the same language and same general shape of code. The differences are the entity operation API, the config format, and the data engine underneath.

Can I run multiple chains in one HyperIndex indexer?​

Yes. A single config.yaml declares all chains under a chains: array. Multichain is the default. Ponder configures chains separately per setup.

What does HyperSync replace in a Ponder setup?​

Ponder pulls historical data through standard RPC, which is the bottleneck for backfills against high-event contracts. HyperSync replaces that RPC fetch with a purpose-built data lake, delivering up to 2,000x faster data access than RPC. 85+ EVM chains have native HyperSync coverage, so most Ponder workloads can migrate without changing data-source configuration.

How do I handle reorgs in HyperIndex?​

At the framework level. HyperIndex tracks entity state history for every unfinalized block and rolls back automatically on reorg. No handler code is required.

Can I use HyperIndex with Cursor or Claude Code?​

Yes. HyperIndex v3 ships with built-in Claude skills that guide AI coding assistants through building with HyperIndex, plus a docs MCP server for live access to the documentation.

Where is the production reference for a HyperIndex indexer?​

The Polymarket reference indexer. It syncs 4,000,000,000 events on Polygon in 6 days, replacing 8 separate subgraphs on The Graph.

Build With Envio​

Envio is the fastest independently benchmarked EVM blockchain indexer for querying real-time and historical data. If you are building onchain and need indexing that keeps up with your chain, check out the docs, run the benchmarks yourself, and come talk to us about your data needs.

Stay tuned for more updates by subscribing to our newsletter, following us on X, or hopping into our Discord.

Subscribe to our newsletter

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

The agentic-onchain conversation in 2026 has settled into two camps. One says agents need a reconciled SQL warehouse to make sense of raw blockchain data. The other says agents need a programmable indexer that lets them act, not just analyse. Both are right about the diagnosis. Raw RPC is unworkable for an agent. The disagreement is about what replaces it.

This blog is the case for indexers, not warehouses. A SQL warehouse lets an agent ask questions. An indexing framework lets an agent build, deploy, and own new data pipelines mid-session. The first is a query tool, the second is infrastructure. Agents acting onchain need the second. HyperIndex ships it today.

Why Raw Blockchain Data Breaks Agents​

An agent reading from RPC directly hits four problems within minutes.

1. Reorgs. A recent block can be reorged. An agent that wrote a record based on an unfinalized block has to either lag the chain head (and miss real-time signals) or roll its own rollback logic (and get it wrong on the next edge case). Neither is acceptable for an agent running in a production environment.

2. Schema. RPC returns logs and transactions. It does not return entities, relationships, or aggregations. The agent has to assemble the schema in memory on every query. Cross-contract state, factory pattern instances, and anything time-windowed have to be rebuilt from scratch.

3. Throughput. An agent that wants to know the last 1,000 trades on a market has to issue 1,000 eth_getLogs calls or hand-tune a paginated request. A historical sweep across a year of activity can take hours to query from RPC.

4. Multichain. Most agents that matter operate across at least two chains. Each chain is a separate RPC, separate quirks, separate rate limits. The application code that joins those RPCs is exactly the indexing code an indexer would write for you.

The standard response to "raw RPC is unworkable for agents" is to put a SQL warehouse in front of it. That works for read-only analytical queries. It does not work for an agent that needs to spin up a new product on top of the data within a session.

What HyperIndex Provides Instead​

HyperIndex addresses all four problems by being a blockchain indexing framework rather than a query layer.

• Reorg safety at the framework level. Entity state history, automatic rollback, no reorg logic required in handlers. Learn more in Indexing and Reorgs.
• Structured GraphQL output. Entities, relationships, aggregations, time-windowed views, all queryable from one endpoint. Agents read GraphQL, not raw logs.
• HyperSync historical throughput. Up to 2,000x faster than RPC. The Polymarket reference indexer synced its first 4,000,000,000 events in 6 days and has indexed over 6,500,000,000 to date.
• Multichain in one config. 85+ have native HyperSync coverage, any EVM chain accessible via standard RPC, all in a single config.yaml.

That is the read side. The act side is what makes HyperIndex an agent's infrastructure, not just an agent's data layer.

The Three Things That Make It Programmable for Agents​

1. The Envio Docs MCP Server​

The docs MCP server exposes the entire Envio docs site as two MCP tools:

• docs_search for semantic search across the docs
• docs_fetch to retrieve a docs page by ID

Endpoint: https://docs.envio.dev/mcp. Transport: Streamable HTTP.

Setup is one command for Claude Code:

claude mcp add --transport http envio-docs https://docs.envio.dev/mcp

Cursor and VS Code use the JSON config form on the same page. Once added, every agent session in that workspace grounds its answers about HyperIndex in the live docs rather than stale training data.

This matters because agents writing indexer code typically hallucinate APIs that do not exist. The MCP server gives the agent a fresh source of truth on every request, so it cites real HyperIndex syntax instead of guessing.

2. Auto-Discovered Skills in .claude/skills/​

When a HyperIndex project is initialised, it scaffolds a .claude/skills/ directory pre-populated with skill definitions. Cursor, Claude Code, and Codex all auto-discover skills from this directory at session start. The descriptions load up front, full skill content loads on demand. Confirmed in the public Polymarket reference repo's CLAUDE.md:

Skills in .claude/skills/ are auto-discovered — descriptions load at startup, full content on demand.

HyperIndex projects scaffolded with v3 rc ship 14 skill definitions:

.claude/skills/
  indexer-blocks/
  indexer-configuration/
  indexer-external-calls/   # Effect API for fetch / RPC / async I/O
  indexer-factory/          # Dynamic contract registration
  indexer-filters/
  indexer-handlers/
  indexer-multichain/
  indexer-performance/
  indexer-schema/
  indexer-testing/          # Vitest patterns for handler tests
  indexer-traces/
  indexer-transactions/
  indexer-wildcard/
  migrate-from-subgraph/    # AssemblyScript-to-TypeScript conversion

The canonical skill set lives at github.com/enviodev/hyperindex/tree/main/packages/cli/templates/static/shared/.claude/skills and ships into every new HyperIndex project.

These skills encode the patterns that make a HyperIndex project work. A developer running Claude Code, Cursor, or Codex in a HyperIndex project does not need to teach the agent what HyperIndex is. The skills do that, scoped to the actual conventions the framework expects.

3. The envio-cloud CLI​

The envio-cloud CLI is the GitHub-native deploy surface for HyperIndex indexers running on Envio Cloud. The three core agent-facing commands are:

• envio-cloud login to authenticate via GitHub
• envio-cloud indexer add to register a new indexer
• envio-cloud deployment status to check sync state

Every command supports -o json for parseable output. Install with npm install -g envio-cloud.

The full CLI reference is in the docs.

The deploy model is GitHub-native. An agent commits the indexer code to a GitHub repo, pushes to the envio branch (the default deploy branch), and registers the indexer with envio-cloud indexer add. The Envio GitHub App handles deployments from there. No deploy button, no dashboard step.

The published agentic demo did exactly that for a wstETH indexer on Monad Mainnet. 400,000 events indexed in approximately 20 seconds. The agent reads the contract, scaffolds the project from the ERC20 template, configures config.yaml for Monad, runs codegen and a type check, pushes to GitHub, and registers the indexer. End to end, no human in the loop after the first prompt. Loom walkthrough. Live deployment.

That is the act in "programmable infrastructure for agents that need to act, not just query."

A Concrete Example: The Published wstETH-on-Monad Demo​

The agentic indexing blog documents the full end-to-end flow an agent ran from scaffold to live deployment. This is not a hypothetical. The live deployment and the Loom walkthrough are both public.

The commands the agent ran (from the published blog):

Step 1: Scaffold from the ERC20 template

pnpx envio@3.0.0-rc.0 init template -t erc20 -l typescript -d ./my-indexer --api-token ""

The --api-token "" makes the init non-interactive. No token is needed at scaffold time; auth is handled at deploy.

Step 2: Configure for the target chain

The agent edits config.yaml to target the wstETH contract on Monad Mainnet. From the published blog: chain ID 143, contract 0x10Aeaf63194db8d453d4D85a06E5eFE1dd0b5417, start_block: 0.

Then runs codegen and a type check:

pnpm codegen
pnpm tsc --noEmit

Step 3: Push to GitHub on the deploy branch

Envio Cloud deploys from the envio branch by default:

gh repo create wsteth-monad-indexer-demo --public
git init && git add . && git commit -m "init"
git push -u origin main
git checkout -b envio && git push -u origin envio

Step 4: Connect the Envio GitHub App to the repo

A one-time install at github.com/apps/envio-deployments. The app handles the actual deployment when commits land on the envio branch.

Step 5: Register and deploy

pnpx envio-cloud login
pnpx envio-cloud indexer add \
  --name wsteth-monad-indexer-demo \
  --repo wsteth-monad-indexer-demo \
  --description "wstETH ERC20 indexer on Monad" \
  --branch envio \
  --skip-repo-check \
  --yes

Step 6: Verify

pnpx envio-cloud indexer get wsteth-monad-indexer-demo {org}
pnpx envio-cloud deployment status wsteth-monad-indexer-demo <commit-hash> {org}

Once synced, the indexer is at https://envio.dev/app/{org}/{indexer-name}/{commit-hash}.

Result: 400,000 events indexed in ~20 seconds.

Every command above is taken directly from the published blog. Every flag exists. The flow is what this whole blog is arguing for, an agent that scaffolds, configures, deploys, and verifies an indexer end to end, with no human stepping in. The Polymarket reference indexer is the production-scale reference for what this stack produces at full scale. The wstETH demo is the documented one-prompt run.

Why This Beats a SQL Warehouse for Agentic Workflows​

A SQL warehouse fronted by an LLM is excellent for analysts. The agent reads a question, writes SQL, returns a number. The agent does not change the warehouse, does not deploy new ingestion, does not branch the schema.

An agent acting onchain needs the opposite. It needs to:

• Add a new contract to its data ingestion mid-session
• Branch the schema to add a new entity type for a workflow it is exploring
• Spin up a brand-new indexer for an opportunity it just discovered
• Deploy to a hosted runtime and stream results back

HyperIndex gives the agent that ability. The indexer is a project the agent owns, not a warehouse it queries. The same agent can have ten indexers running at any time, each tracking a different market. None of that is possible if the only interface is read-only SQL.

For analysts: SQL warehouses are the right tool. For agents acting on the data: an indexing framework is the right tool. Both can coexist. The case here is for the agent side, which is the side under-served by the current SQL-warehouse-plus-LLM consensus.

Get Started​

• HyperIndex Quickstart with AI
• Envio docs MCP server
• Agentic indexing case (400k events, 20s)
• envio-cloud CLI reference
• Polymarket production reference

Frequently Asked Questions​

Why do AI agents acting onchain need an indexer at all?​

Raw RPC has four problems for an agent: reorgs, no schema, low throughput, and per-chain quirks at multichain scale. An indexer addresses all four. HyperIndex addresses them at the framework level, with reorg-safe storage, structured GraphQL output, HyperSync throughput, and a single multichain config.

What is the Envio docs MCP server?​

A Model Context Protocol server at https://docs.envio.dev/mcp that exposes the Envio docs as two tools, docs_search and docs_fetch. Configured into Claude Code, Cursor, or VS Code with one setup command. Announcement blog: Introducing the Envio Docs MCP Server.

How fast can an AI agent deploy a HyperIndex indexer?​

The agentic indexing blog documents a single-prompt flow that scaffolds, deploys, and runs an indexer covering 400,000 events on Monad in roughly 20 seconds.

Does the envio-cloud CLI support agent-driven deploys?​

Yes. The CLI surface includes envio-cloud login, envio-cloud indexer add, envio-cloud deployment status, envio-cloud deployment metrics, envio-cloud deployment promote, with -o json on any command for parseable output. Deployments are GitHub-native: an agent commits to the envio branch and the registered indexer deploys automatically.

How does HyperIndex differ from a SQL warehouse for agents?​

A SQL warehouse is a read-only query layer. HyperIndex is a programmable indexer the agent can own, branch, and deploy. Both have a place. SQL warehouses suit analytical workflows. Indexers suit agents that need to act, not just query.

Can an agent register a new contract mid-session without a redeploy?​

Yes, when the contract is created by a factory the agent has already configured. HyperIndex's dynamic contract registration is a first-class feature, and the indexer-factory skill in .claude/skills/ is the canonical reference for the pattern. Adding a brand-new chain or an unrelated contract still requires a config change and a redeploy, which the agent can run from the envio-cloud CLI in one command.

Where can I watch an agent run this end-to-end?​

The published Loom walkthrough shows the full wstETH-on-Monad demo, scaffold to live deployment. The live indexer is public.

Build With Envio​

Envio is the fastest independently benchmarked EVM blockchain indexer for querying real-time and historical data. If you are building onchain and need indexing that keeps up with your chain, check out the docs, run the benchmarks yourself, and come talk to us about your data needs.

Stay tuned for more updates by subscribing to our newsletter, following us on X, or hopping into our Discord.

Subscribe to our newsletter

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

This is a practical, end-to-end walkthrough of building a HyperIndex indexer with Claude as a pair programmer. Every command is from the published Envio docs. Every code shape is taken directly from the public Polymarket reference indexer. The aim is to show the shortest reliable path from a blank project to a deployed multichain indexer that an engineer (or an agent) can actually run today.

What You're Building​

A multichain HyperIndex indexer that tracks ERC20 transfers across two chains (Ethereum and Base) and exposes the data through a GraphQL endpoint. Two contracts, one schema, one config, deployed to Envio Cloud and queryable in roughly 30 minutes if you are reading along, or roughly 5 minutes if Claude is driving.

The structure of the project will be three files plus generated TypeScript:

my-erc20-indexer/
  config.yaml          # Networks, contracts, events
  schema.graphql       # Entity model
  src/EventHandlers.ts # The handler logic

Source for the three-file structure: docs.envio.dev/docs/HyperIndex/quickstart-with-ai.

Step 0: Wire Up Claude​

Once. Then never again. The Envio docs MCP server exposes the live docs to any MCP-capable agent. From the docs MCP server reference, the setup commands are:

For Claude Code:

claude mcp add --transport http envio-docs https://docs.envio.dev/mcp

For Cursor or VS Code, drop this into the MCP config:

{
  "mcpServers": {
    "envio-docs": {
      "url": "https://docs.envio.dev/mcp",
      "transport": "http"
    }
  }
}

After this, Claude has two tools available in any session: docs_search (semantic search) and docs_fetch (retrieve a page). The agent uses these instead of guessing at API surface from training data.

Step 1: Scaffold the Project​

Use the template flow to scaffold an ERC20 indexer in one non-interactive command.

pnpx envio@3.0.0-rc.0 init template -t erc20 -l typescript -d ./my-indexer --api-token ""

This pulls the current HyperIndex v3 release candidate, which ships with the V3 testing framework, the built-in .claude/skills/ directory, and the current CLI flags. The current release is tracked at github.com/enviodev/hyperindex/releases.

The --api-token "" flag tells the init to run non-interactively, with no prompt for an Etherscan-style API token. If an agent is driving, every interactive prompt is a failure mode.

The init produces the three files plus a package.json, tsconfig.json, an AGENTS.md and CLAUDE.md documenting the conventions, and an auto-discovered .claude/skills/ directory. Every project scaffolded with v3 rc ships these skills out of the box, encoding the indexing patterns Claude needs to write idiomatic HyperIndex code without improvising.

Step 2: Make It Multichain​

The init scaffolds for one chain. Adding a second is a config edit, not a fresh project. Open config.yaml and add a second chain entry. The shape mirrors the public Polymarket config. HyperIndex uses two-tier declaration. Top-level contracts: for global event signatures, then a chains: array for per-chain addresses and start blocks.

# Pattern from: https://github.com/enviodev/polymarket-indexer/blob/main/config.yaml
# yaml-language-server: $schema=./node_modules/envio/evm.schema.json
name: erc20-multichain

contracts:
  - name: USDC
    events:
      - event: "Transfer(address indexed from, address indexed to, uint256 value)"

field_selection:
  transaction_fields:
    - hash
    - from
    - to

chains:
  - id: 1
    start_block: 17000000
    contracts:
      - name: USDC
        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  - id: 8453
    start_block: 2000000
    contracts:
      - name: USDC
        address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

Three things to call out:

• chains: is the keyword, not networks:. Per the AGENTS.md generated into every HyperIndex project: "Uses chains (not networks)." If your editor or an AI agent suggests networks:, the schema validation will fail.
• The handler: field is optional. Handlers auto-register from src/handlers/. Same AGENTS.md.
• field_selection controls which transaction fields HyperSync ships down. Asking for fewer fields is faster and uses less memory.

For the current set of supported config options including per-contract start_block and environment variable interpolation, the full configuration reference lives in the docs.

Step 3: The Schema​

Edit schema.graphql to model entities the application will query. The shape uses a chainId-first pattern (per-chain entities plus aggregated entities) for clean cross-chain queries:

# Pattern from: https://github.com/enviodev/polymarket-indexer/blob/main/schema.graphql
type Transfer
  @index(fields: ["from", ["timestamp", "DESC"]])
  @index(fields: ["to", ["timestamp", "DESC"]])
{
  id: ID!
  from: String! @index
  to: String! @index
  value: BigInt!
  chainId: Int!
  blockNumber: Int!
  timestamp: Int!
}

type AccountBalance {
  id: ID!
  account: String! @index
  chainId: Int!
  balance: BigInt!
  lastUpdated: Int!
}

type AggregateBalance {
  id: ID!
  account: String! @index
  totalAcrossChains: BigInt!
  lastUpdated: Int!
}

Two HyperIndex-specific things worth noting in this schema:

• No @entity decorator. From the project's AGENTS.md: "Unlike TheGraph, schema types have no decorators." Subgraphs put @entity on every type. HyperIndex does not.
• @index is composable. The Polymarket schema uses both per-field @index and per-type composite indexes like @index(fields: ["from", ["timestamp", "DESC"]]) to drive the queries the application needs.

Transfer carries every transfer event with chainId first-class. AccountBalance is per-chain. AggregateBalance is the cross-chain rollup. The same indexer writes to all three.

After editing the schema, run pnpm codegen to regenerate the typed bindings. The project's AGENTS.md is explicit that codegen is required after any schema or config change. Types go stale otherwise.

Step 4: The Handler​

In v3 rc, types come from the envio package directly. The handler imports indexer plus any entity types it needs, then registers handlers as indexer.onEvent({ contract: "CONTRACT_NAME", event: "EVENT_NAME" }, handler).

import {
  indexer,
  type Transfer,
  type AccountBalance,
  type AggregateBalance,
} from "envio";

indexer.onEvent(
  { contract: "USDC", event: "Transfer" },
  async ({ event, context }) => {
    const transferId = `${event.chainId}_${event.block.number}_${event.logIndex}`;

    const transfer: Transfer = {
      id: transferId,
      from: event.params.from,
      to: event.params.to,
      value: event.params.value,
      chainId: event.chainId,
      blockNumber: event.block.number,
      timestamp: event.block.timestamp,
    };
    context.Transfer.set(transfer);

    const fromKey = `${event.chainId}_${event.params.from}`;
    const toKey = `${event.chainId}_${event.params.to}`;

    const fromBal: AccountBalance = (await context.AccountBalance.get(fromKey)) ?? {
      id: fromKey,
      account: event.params.from,
      chainId: event.chainId,
      balance: 0n,
      lastUpdated: event.block.timestamp,
    };
    context.AccountBalance.set({
      ...fromBal,
      balance: fromBal.balance - event.params.value,
      lastUpdated: event.block.timestamp,
    });

    const toBal: AccountBalance = (await context.AccountBalance.get(toKey)) ?? {
      id: toKey,
      account: event.params.to,
      chainId: event.chainId,
      balance: 0n,
      lastUpdated: event.block.timestamp,
    };
    context.AccountBalance.set({
      ...toBal,
      balance: toBal.balance + event.params.value,
      lastUpdated: event.block.timestamp,
    });

    const fromAgg: AggregateBalance = (await context.AggregateBalance.get(event.params.from)) ?? {
      id: event.params.from,
      account: event.params.from,
      totalAcrossChains: 0n,
      lastUpdated: event.block.timestamp,
    };
    context.AggregateBalance.set({
      ...fromAgg,
      totalAcrossChains: fromAgg.totalAcrossChains - event.params.value,
      lastUpdated: event.block.timestamp,
    });

    const toAgg: AggregateBalance = (await context.AggregateBalance.get(event.params.to)) ?? {
      id: event.params.to,
      account: event.params.to,
      totalAcrossChains: 0n,
      lastUpdated: event.block.timestamp,
    };
    context.AggregateBalance.set({
      ...toAgg,
      totalAcrossChains: toAgg.totalAcrossChains + event.params.value,
      lastUpdated: event.block.timestamp,
    });
  },
);

Three project-enforced conventions visible in this snippet, all spelled out in the AGENTS.md generated into every HyperIndex project:

• Spread operator for updates. Entities returned by context.Entity.get() are read-only. Always spread: context.Entity.set({ ...existing, field: newValue }). Direct mutation throws.
• Composite IDs for cross-chain uniqueness. ${event.chainId}_${event.block.number}_${event.logIndex} is the Polymarket pattern. Without chainId in the ID, two chains writing the same (block, logIndex) collide.
• Effect API for any external call. If the handler needs to fetch Gamma metadata, call an RPC, or hit any other async I/O, use createEffect plus context.effect(). Never call external services directly. The Polymarket TokenRegistered handler shows the pattern with context.effect(getMarketMetadata, token0Str).

This is the structure an agent with the indexer-handlers and indexer-external-calls skills produces when asked to "write the Transfer handler that updates per-chain and aggregate balances." The skills encode these conventions so the agent does not improvise them wrongly.

Step 5: Run It Locally​

pnpm install
pnpm codegen          # regenerate types from schema + config
pnpm tsc --noEmit     # type-check without emitting
TUI_OFF=true pnpm dev # run indexer (TUI_OFF gives AI-friendly stdout)

Source for these exact commands: polymarket-indexer/AGENTS.md.

The local dev environment spins up a Postgres and a Hasura GraphQL instance. The indexer starts pulling events from both chains via HyperSync. Sync rates of 25,000 events per second on historical backfill are standard. The Polymarket case study documents 4,000,000,000 events synced in 6 days on Polygon; the indexer has since indexed over 6,500,000,000 in total.

The Hasura GraphQL endpoint is available locally. Once the indexer is at chain head, queries like:

query AggregateBalanceForAccount {
  AggregateBalance(where: { account: { _eq: "0xabc..." } }) {
    account
    totalAcrossChains
    lastUpdated
  }
}

return live data.

Step 6: Deploy to Envio Cloud​

Envio Cloud uses a GitHub-native deploy model. An agent commits the indexer to a GitHub repo, pushes to the envio branch (the default deploy branch), and registers the indexer with envio-cloud indexer add. The Envio GitHub App handles deployments from there. No deploy button, no dashboard step.

Install the CLI and authenticate:

npm install -g envio-cloud
envio-cloud login

Push the project to GitHub on the envio branch:

gh repo create my-erc20-indexer --public
git init && git add . && git commit -m "init"
git push -u origin main
git checkout -b envio && git push -u origin envio

Connect the Envio GitHub App to the repo (one-time install at github.com/apps/envio-deployments), then register the indexer:

envio-cloud indexer add \
  --name my-erc20-indexer \
  --repo my-erc20-indexer \
  --description "Multichain ERC20 indexer" \
  --branch envio \
  --skip-repo-check \
  --yes

The verified CLI surface (from the agentic indexing blog) includes:

• envio-cloud login authenticates via GitHub
• envio-cloud indexer add registers a new indexer pointing at a GitHub repo and branch
• envio-cloud indexer get fetches indexer details
• envio-cloud deployment status returns the current sync state of a deployment
• envio-cloud deployment metrics returns runtime metrics
• envio-cloud deployment promote promotes a deployment to production
• -o json on any command for parseable output

Track sync progress with envio-cloud deployment status and envio-cloud deployment metrics. Full reference at docs.envio.dev/docs/HyperIndex/envio-cloud-cli.

Step 7: Test It​

pnpm test runs the project's Vitest suite. In v3 rc, tests import createTestIndexer and TestHelpers from the envio package directly, so tests use the same types as handlers. The indexer-testing skill in .claude/skills/ encodes the current API surface (mock event factories, test indexer setup, assertion patterns) and the testing reference docs cover it end to end.

What the Stack Looks Like End to End​

[Claude Code or Cursor]
         |
         | (reads docs via MCP server, applies built-in Claude skills)
         v
[HyperIndex Project (config.yaml + schema.graphql + handlers)]
         |
         | (pnpm dev locally, or push to GitHub envio branch)
         v
[HyperIndex Runtime + HyperSync]
         |
         | (live indexes EVM chains natively, any EVM via RPC)
         v
[Postgres + Hasura GraphQL endpoint]
         |
         | (queried by application, dashboard, agent, or downstream service)
         v
[Your AI-Powered Onchain App]

Each layer is a piece you have full control over. None of them require black-box assumptions about how an indexer behaves under reorgs, source outages, or scale. The reliability blog covers what HyperIndex provides at the framework level.

Get Started​

• HyperIndex Quickstart with AI
• Envio docs MCP server
• envio-cloud CLI reference
• config.yaml reference
• Testing docs (V3 framework)
• Polymarket production reference
• Companion: AI-assisted subgraph migration

Frequently Asked Questions​

What does an AI-powered onchain app stack look like?​

The stack is: Claude Code (or another MCP-aware editor) as the development surface, a HyperIndex project with an auto-discovered .claude/skills/ directory shipped by v3 rc, the HyperIndex runtime with HyperSync as the data engine, Postgres plus Hasura for GraphQL, and the application or agent on top. Every layer is real and shipping today.

How do I deploy a HyperIndex indexer programmatically?​

Install the envio-cloud CLI with npm install -g envio-cloud and authenticate with envio-cloud login. Push the indexer code to a GitHub repo on the envio branch, connect the Envio GitHub App to the repo, then register with envio-cloud indexer add. Track sync state with envio-cloud deployment status and envio-cloud deployment metrics. Every command supports -o json for parseable output. Full reference at docs.envio.dev/docs/HyperIndex/envio-cloud-cli.

Can I add a chain to a HyperIndex indexer without redeploying?​

Adding a chain requires a config change and a redeploy because the indexer needs to start a new HyperSync stream. The redeploy itself is one CLI command. Adding a contract on an existing chain that uses the factory pattern can be done dynamically without a redeploy. See the indexer-factory skill in the project.

How does HyperIndex compare to subgraphs for an AI workflow?​

Subgraphs use AssemblyScript handlers, single-chain config per subgraph, and matchstick for testing. HyperIndex uses TypeScript handlers, multichain config in one file, and Vitest for testing. The TypeScript surface is what makes Claude's involvement straightforward. The migration story is covered in AI-assisted subgraph migration.

Is HyperIndex faster than other indexers in benchmarks?​

In Sentio's independent Uniswap V2 Factory benchmark, HyperIndex completed in 8 seconds, 142x faster than The Graph and 15x faster than the nearest competitor.

Where can I see a public production reference?​

The Polymarket reference indexer. Synced its first 4,000,000,000 events from block 3,764,531 in 6 days, replacing 8 separate subgraphs, and has indexed over 6,500,000,000 to date. Live at envio.dev/app/moose-code/polymarket-indexer/7cad3ad.

Build With Envio​

Envio is the fastest independently benchmarked EVM blockchain indexer for querying real-time and historical data. If you are building onchain and need indexing that keeps up with your chain, check out the docs, run the benchmarks yourself, and come talk to us about your data needs.

Stay tuned for more updates by subscribing to our newsletter, following us on X, or hopping into our Discord.

Subscribe to our newsletter

Website | X | Discord | Telegram | GitHub | YouTube | Reddit

The hardest part of migrating off The Graph to HyperIndex has always been the AssemblyScript rewrite. Subgraphs run handler code in WebAssembly, which means handlers are written in AssemblyScript, a stricter subset of TypeScript with its own constraints, its own tooling, and its own foot-guns. Teams who otherwise live in TypeScript every day end up maintaining one codebase in a language they touch only when their indexer breaks.

The HyperIndex reference indexer for Polymarket demonstrates the consolidation pattern at scale, 8 subgraphs' worth of logic rewritten as a single TypeScript indexer. The full reference is public on GitHub and is documented in our Polymarket case study.

This blog is about how you can leverage Claude (or any coding agent) to migrate your subgraphs to HyperIndex. The agent does the AssemblyScript-to-TypeScript rewrite; a developer reviews the diff, runs the tests, and ships the indexer.

What HyperIndex Is and Why the Migration Story Changed​

HyperIndex is Envio's multichain blockchain indexing framework for EVM chains. HyperIndex handlers are written in regular TypeScript. Unlike AssemblyScript, which restricts which npm packages handlers can use, HyperIndex lets you bring in any npm package you want. Since handlers are TypeScript, there is no WebAssembly compilation step and no AssemblyScript-specific syntax to learn, you write handlers in the language you already use every day.

Two things changed in the last six months that turned subgraph migration into a tractable AI-assisted workflow:

1. The HyperIndex docs MCP server went live, exposing the entire docs site as two tools (docs_search and docs_fetch) over Streamable HTTP at https://docs.envio.dev/mcp. Any IDE or assistant that speaks MCP, including Claude Code, Cursor, Codex, and VS Code, can now ground answers about HyperIndex in the live docs rather than stale training data.
2. HyperIndex projects ship a .claude/skills/ directory that auto-discovers for Cursor, Claude Code, and Codex. The Polymarket reference repo's directory currently ships 14 skills, including a dedicated migrate-from-subgraph skill purpose-built for this workflow, plus indexer-configuration, indexer-schema, indexer-handlers, indexer-factory (dynamic contracts), indexer-external-calls (the Effect API), indexer-multichain, indexer-performance, indexer-testing, indexer-blocks, indexer-filters, indexer-traces, indexer-transactions, and indexer-wildcard. The full list lives at the canonical skills directory.

Combined, these mean a developer can hand the agent a subgraph repo and a working HyperIndex project shell and ask for a migration. The agent has live docs, a project-resident migration skill, and its own validation tooling.

The Polymarket case study is the production reference for what the end state looks like. The rest of this post walks the AI-assisted version of that same migration on a smaller surface area, anchored to real artifacts in the Polymarket repo.

The Four Files Claude Needs to See​

Every subgraph has the same four primary inputs. Claude reads them in this order.

my-subgraph/
  subgraph.yaml          # contracts, networks, event handlers, start blocks
  schema.graphql         # entity types and relations
  src/mappings/*.ts      # AssemblyScript handler logic (despite the .ts extension)
  abis/*.json            # contract ABIs the handlers parse logs against

subgraph.yaml carries the network, the contract addresses, the start blocks, and the event-to-handler mapping. schema.graphql carries the entity model. The mappings carry the actual logic. The ABIs carry the signatures for the events mappings parse.

HyperIndex needs the same four kinds of input, restructured. The Polymarket reference shows the target shape. From the canonical config.yaml (selected events shown for brevity):

# Source: https://github.com/enviodev/polymarket-indexer/blob/main/config.yaml
# yaml-language-server: $schema=./node_modules/envio/evm.schema.json
name: polymarket-indexer
description: Unified Polymarket HyperIndex

contracts:
  - name: Exchange
    abi_file_path: ./abis/Exchange.json
    events:
      - event: "OrderFilled(bytes32 indexed orderHash, address indexed maker, address indexed taker, uint256 makerAssetId, uint256 takerAssetId, uint256 makerAmountFilled, uint256 takerAmountFilled, uint256 fee)"
      - event: "OrdersMatched(...)"
      - event: "TokenRegistered(...)"
  - name: ConditionalTokens
    abi_file_path: ./abis/ConditionalTokens.json
    events:
      - event: "PositionSplit(...)"
      - event: "PositionsMerge(...)"
      - event: "PayoutRedemption(...)"

field_selection:
  transaction_fields:
    - hash
    - from
    - to

chains:
  - id: 137 # Polygon
    start_block: 3764531
    contracts:
      - name: Exchange
        address:
          - "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E"
          - "0xC5d563A36AE78145C45a50134d48A1215220f80a"
        start_block: 33605403
      - name: ConditionalTokens
        address: "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045"
        start_block: 4023686