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. Add your API token
3. Configure the indexer for Sei
4. Define the data schema
5. Write the event handler
6. Generate types
7. Run the indexer
8. Query your data
9. 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

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: Add your API token​

The scaffolded .env file ships with three commented lines:

# To create or update a token visit https://envio.dev/app/api-tokens
# Uncomment the line below and set a valid token
# ENVIO_API_TOKEN="<YOUR-API-TOKEN>"

Uncomment the last line and replace <YOUR-API-TOKEN> with your token so it reads:

ENVIO_API_TOKEN="your-token-here"

Note: A token is required. Without a valid token, the indexer stops immediately with the error "An API token is required for using HyperSync as a data-source."

Step 3: 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 4: 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 5: 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 6: 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 7: 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 8: 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 9: 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 (see Step 2: Add your API token above).

• 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)

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 is HyperSync?​

HyperSync is Envio's data engine. Instead of pulling historical data through standard RPC, HyperSync fetches filtered event data in bulk from a purpose-built data lake, delivering up to 2,000x faster data access than RPC. 87+ EVM chains have native HyperSync coverage.

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. 86+ 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.

What skills ship with HyperIndex?​

HyperIndex projects scaffold a .claude/skills/ directory that auto-discovers for Cursor, Claude Code, and Codex. The canonical templates ship 14 skill definitions covering indexer-configuration, indexer-schema, indexer-handlers, indexer-factory (dynamic contracts), indexer-external-calls (Effect API), indexer-multichain, indexer-performance, indexer-blocks, indexer-transactions, indexer-traces, indexer-filters, indexer-wildcard, indexer-testing, and migrate-from-subgraph. The full list lives at the canonical skills directory.

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.

What chains does HyperIndex support for AI agents?​

Any EVM chain. 86+ have native HyperSync coverage for maximum speed. Any EVM chain without native HyperSync is accessible via standard RPC.

How does HyperIndex handle reorgs for agents?​

At the framework level. Entity state history is persisted for unfinalized blocks. The framework rolls back automatically on reorg. No handler code is required.

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.

What are the built-in HyperIndex skills?​

HyperIndex projects scaffolded with v3 rc ship a .claude/skills/ directory pre-populated with 14 skills covering the core indexing patterns: indexer-configuration, indexer-schema, indexer-handlers, indexer-factory, indexer-multichain, indexer-external-calls, indexer-performance, indexer-testing, indexer-blocks, indexer-filters, indexer-traces, indexer-transactions, indexer-wildcard, and migrate-from-subgraph. Claude Code auto-discovers them at session start.

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.

What chains are supported?​

Any EVM chain. 86+ have native HyperSync coverage for maximum speed. Any EVM chain without native HyperSync is accessible via standard RPC. The current chain count is published on envio.dev.

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

Three small differences from subgraph YAML to know up front: HyperIndex uses chains: (not networks:), declares contracts once at the top level with addresses supplied per-chain, and auto-registers handlers from src/handlers/<ContractName>.ts (subgraphs require explicit handler-to-event mapping).

This single file replaces what would otherwise be eight separate subgraph.yaml files. Every shared event (PositionSplit, PositionsMerge, PayoutRedemption) is declared once and routed to a single TypeScript handler that updates every relevant entity in one pass. That architectural detail, "handler merging," is the structural win of the consolidation pattern.

schema.graphql carries across with two specific rewrites. Subgraph schemas decorate every type with @entity. HyperIndex schemas have no decorators, per the AGENTS.md: "Unlike TheGraph, schema types have no decorators." Subgraph relations like @derivedFrom are kept; ID conventions stay; the type body is otherwise identical. The built-in indexer-schema skill knows the diffs and applies them.

Handlers are where the migration work happens. The Polymarket reference repo's Exchange.ts shows the canonical TypeScript shape and the conventions the migrate-from-subgraph skill applies (simplified for the post, helper functions inlined):

// Source: https://github.com/enviodev/polymarket-indexer/blob/main/src/handlers/Exchange.ts
import { Exchange, type Orderbook } from "generated";
import {
  parseOrderFilled,
  updateUserPositionWithBuy,
  updateUserPositionWithSell,
} from "../utils/pnl.js";
import { COLLATERAL_SCALE } from "../utils/constants.js";
import { scaleBigInt, ZERO_BD } from "../utils/fpmm.js";
import { getMarketMetadata } from "../effects/marketMetadata.js";

const TRADE_TYPE_BUY = "Buy";
const TRADE_TYPE_SELL = "Sell";

Exchange.OrderFilled.handler(async ({ event, context }) => {
  const side = event.params.makerAssetId === 0n ? TRADE_TYPE_BUY : TRADE_TYPE_SELL;
  const tokenId = side === TRADE_TYPE_BUY
    ? event.params.takerAssetId.toString()
    : event.params.makerAssetId.toString();

  // 1. Persist the OrderFilled event (chainId in ID prevents cross-chain collisions)
  context.OrderFilledEvent.set({
    id: `${event.chainId}_${event.block.number}_${event.logIndex}`,
    transactionHash: event.transaction.hash,
    timestamp: BigInt(event.block.timestamp),
    orderHash: event.params.orderHash,
    maker: event.params.maker,
    taker: event.params.taker,
    // ... rest of the event
  });

  // 2. Read-then-write Orderbook (spread mandatory, returned entities are read-only)
  const orderbook = (await context.Orderbook.get(tokenId)) ?? defaultOrderbook(tokenId);
  context.Orderbook.set({
    ...orderbook,
    tradesQuantity: orderbook.tradesQuantity + 1n,
    collateralVolume: orderbook.collateralVolume + size,
  });

  // 3. PnL update. Handler merged with what was previously a separate pnl subgraph
  const order = parseOrderFilled(event.params);
  if (order.side === "BUY") {
    await updateUserPositionWithBuy(context, order.account, order.positionId, price, order.baseAmount);
  } else {
    await updateUserPositionWithSell(context, order.account, order.positionId, price, order.baseAmount);
  }
});

The same handler file also processes OrdersMatched and TokenRegistered. The TokenRegistered handler fetches Polymarket Gamma API metadata via the Effect API:

// Same source file, TokenRegistered handler
const metadata = await context.effect(getMarketMetadata, token0Str);

createEffect plus context.effect() is the documented pattern for any external call (fetch, RPC, async I/O). From the project's AGENTS.md: "All fetch, RPC, or other async I/O must use createEffect + context.effect(). Never call external services directly in handlers."

The comparable AssemblyScript handler on The Graph would be split across three subgraph repos, each parsing the same OrderFilled log independently, each writing to its own subgraph database, with cross-domain joins happening at query time. Handler merging is the architectural reason the Polymarket reference consolidates 8 subgraphs into 1. It is also the thing that makes AssemblyScript handlers straightforward for an agent to translate: the event parsing is mechanical, the entity writes are explicit, and the conventions are documented in the project-resident skills.

How the AI-Assisted Migration Workflow Runs​

The flow assumes a developer with Claude Code or Cursor installed, the Envio docs MCP server configured, and the HyperIndex CLI on their machine. From the HyperIndex Quickstart with AI the MCP setup is one command for Claude Code:

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

Cursor or VS Code uses the JSON config form on the same page. Once added, every Claude session in that workspace can query the live docs.

Step 1: Scaffold a HyperIndex project from a template​

Scaffold a fresh HyperIndex project using the template flow. Pass --api-token "" so the init runs non-interactively when an agent is driving:

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

This produces a working HyperIndex project shell with config.yaml, schema.graphql, handler stubs, an AGENTS.md, and the auto-discovered .claude/skills/ directory (including the migrate-from-subgraph skill). The current release is tracked at github.com/enviodev/hyperindex/releases.

Step 2: Hand Claude the AssemblyScript mappings​

You: I just initialised a HyperIndex project and the /XYZ folder has my subgraph
could you help me migrate that to my HyperIndex project. The generated
config.yaml and schema.graphql are in place. The original AssemblyScript
mappings are in ../old-subgraph/src/mappings/. Use the migrate-from-subgraph
skill to translate them into TypeScript handlers under src/handlers/. Apply the
project conventions in AGENTS.md: spread operator for entity updates, Effect
API for any external calls, entity_id fields for relationships. Flag anything
that uses nested entity loads or AssemblyScript-specific helpers so I can
review.

Claude opens the migration skill, walks the mapping files in dependency order, and produces TypeScript handlers under src/handlers/. Every entity load and write is explicit. Every BigInt operation uses native JavaScript BigInt rather than the AssemblyScript BigInt class. Imports come from the auto-generated types, not from @graphprotocol/graph-ts.

Step 3: Run the indexer locally and compare​

pnpm install
pnpm dev

The indexer comes up against a local Postgres and a Hasura GraphQL endpoint. The deployed subgraph endpoint and the local HyperIndex endpoint can be queried side by side for any entity at any block height. Claude knows how to write the comparison queries because the indexer-testing skill ships in the project.

Step 4: Ship to Envio Cloud​

Envio Cloud uses a GitHub-native deploy model. Push the indexer to a GitHub repo on the envio branch, connect the Envio GitHub App, and register the indexer with envio-cloud indexer add. The full flow from the agentic indexing blog:

npm install -g envio-cloud
envio-cloud login

# push the migrated indexer to the envio branch
git checkout -b envio && git push -u origin envio

# install the Envio GitHub App on the repo
# https://github.com/apps/envio-deployments/installations/select_target

# register the indexer
envio-cloud indexer add \
  --name my-migrated-indexer \
  --repo my-migrated-indexer \
  --description "Subgraph migrated to HyperIndex" \
  --branch envio \
  --skip-repo-check \
  --yes

# track sync state
envio-cloud deployment status my-migrated-indexer <commit-hash> {org}

Every command supports -o json for parseable output. The Polymarket reference indexer is live at envio.dev/app/moose-code/polymarket-indexer/7cad3ad. Full CLI reference at docs.envio.dev/docs/HyperIndex/envio-cloud-cli.

What the AI Catches and What It Doesn't​

After running this workflow on smaller subgraphs internally, here is the honest split.

Claude is reliably good at:

• Translating event parsing and entity writes (the bulk of any handler)
• Replacing AssemblyScript BigInt with native JS BigInt
• Replacing @graphprotocol/graph-ts imports with the HyperIndex generated types
• Stripping the @entity decorator from every schema type (HyperIndex schemas have no decorators per AGENTS.md)
• Applying the spread operator pattern on entity updates (mandatory in HyperIndex, returned entities are read-only)
• Wrapping any external call from a mapping in createEffect plus context.effect() (the Effect API)
• Generating the matching test cases against the Vitest framework HyperIndex ships with

Claude needs human review on:

• Cross-handler shared state. Subgraphs sometimes encode shared state in entity IDs in ways that look fine until two handlers race at the same block. Handler merging in HyperIndex usually fixes this, but the migration is the moment to redesign it consciously.

A migration that runs all four steps with Claude driving and a developer reviewing typically turns a multi-week AssemblyScript rewrite into a one or two day exercise. The Polymarket reference is the upper bound: 8 subgraphs' worth of logic, 50+ entities, four years of handler history. Smaller subgraphs are correspondingly faster.

Why Migrate at All: The Numbers​

The reason teams move off The Graph is performance and developer experience. From the public benchmarks:

Full benchmark comparison at docs.envio.dev/docs/HyperIndex/benchmarks.

Polymarket's full historical sync, 4,000,000,000 events on Polygon, completed in 6 days, and the indexer has since indexed over 6,500,000,000 events in total. The same workload on a single subgraph in the Polymarket setup would have been measured in months and would still leave eight separate APIs to query.

Speed is one half of the story. Developer experience is the other. TypeScript handlers, native npm package use, generated types, real test runners, multichain configuration in a single file, dynamic contract registration without redeployment. Once a team has been on HyperIndex for a sprint, the subgraph workflow stops feeling like a viable alternative.

Frequently Asked Questions​

How long does an AI-assisted subgraph migration to HyperIndex take?​

For a single-domain subgraph with one or two contracts, the AI-assisted workflow with Claude typically runs in a few hours. For a complex multi-domain setup at the scale of the Polymarket reference (8 subgraphs' worth of logic, 50+ entities, four years of handler history), the migration with Claude assistance runs in days, not weeks. The bulk of the time is human review, not generation.

Does HyperIndex support every subgraph schema directive?​

Most directives carry across. @derivedFrom and ID-based relations have direct HyperIndex equivalents. The biggest difference is decorators: HyperIndex schemas have no @entity decorator at all. Per the project's AGENTS.md: "Unlike TheGraph, schema types have no decorators." The indexer-schema skill knows the translations and the migrate-from-subgraph skill applies them. Anything without a direct equivalent gets flagged for manual handling.

Can I migrate an Alchemy subgraph the same way?​

Yes. Alchemy Subgraphs are technically subgraphs, and the same AI-assisted migration flow described in this blog applies, scaffold a HyperIndex project from a template, hand Claude the AssemblyScript mappings, validate locally, and ship.

What if my subgraph uses dynamic contracts (factory pattern)?​

HyperIndex supports dynamic contract registration as a first-class feature. Polymarket uses it for FPMM pools created by FPMMFactory. The indexer-factory skill in .claude/skills/ handles the translation. See the Polymarket reference handler at github.com/enviodev/polymarket-indexer/blob/main/src/handlers/FPMMFactory.ts.

How do I validate that the migrated indexer matches the original subgraph?​

Run both endpoints side by side and query the same entity at the same block. The indexer-testing skill in .claude/skills/ generates the comparison queries. For production migrations, Envio also provides a CLI validation tool that diffs entity state across both endpoints over a block range. The Polymarket reference repo is the public production example to compare your migrated output against.

Does the AI workflow work without Claude?​

Yes. Skills in .claude/skills/ auto-discover for Cursor, Claude Code, and Codex per the project's CLAUDE.md. The docs MCP server is MCP-standard so any MCP-capable agent works. The setup commands on the Quickstart with AI page cover Claude Code, Cursor, and VS Code explicitly.

What does HyperIndex do that subgraphs do not?​

Single multichain config (subgraphs are single-chain). Native TypeScript handlers (subgraphs require AssemblyScript). 142x faster sync on the Sentio Uniswap V2 Factory benchmark. Framework-level reorg handling with no handler logic required. Self-hostable or deployed to Envio Cloud with a GitHub-native flow (envio-cloud indexer add against an envio branch).

Where is the production reference for a large subgraph migration?​

The Polymarket HyperIndex reference indexer. 8 subgraphs' worth of logic consolidated into one indexer, with the first 4,000,000,000 events synced in 6 days and over 6,500,000,000 indexed to date. The full repo is public on GitHub and the case study can be found in our blog.

Get Started​

Migration starts with two things: an existing subgraph (deployed or local) and a Claude Code or Cursor session pointed at a fresh HyperIndex project.

• HyperIndex Quickstart with AI
• HyperIndex docs MCP server
• Polymarket reference indexer
• Migration guide (manual reference)
• Envio Cloud CLI

For larger migrations, the Envio team supports the planning and review pass directly. Reach out via Discord or Telegram.

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

A production indexer fails in three ways. The chain reorgs and the indexer either misses the rollback or hand-rolls bespoke logic that breaks at the next edge case. The data source goes down and the indexer either stalls silently or fails over and never comes back to primary. The indexer hits a counter ceiling, a memory leak in a long-running handler, or another silent failure, and the operator finds out from a downstream outage instead of an alert.

HyperIndex is Envio's multichain blockchain indexing framework for EVM chains. Reliability lives at the framework level so that any indexer built on it inherits the behaviour without writing operational code. Four guarantees compound to keep an indexer production-correct: framework-level reorg handling, restart-resistant operation, HyperSync data validation, and multi data-source recovery. Observability through Prometheus layers on top.

Why These Four Reliability Pillars Reinforce Each Other​

Reorg handling guarantees your indexer doesn't carry corrupt state forward when a chain rolls back. Restart-resistant operation means a failed indexer process doesn't leak that corruption into a stuck or amnesiac state. HyperSync validation means the data feeding both is the canonical chain, not a stale or partial fork. Multi-source recovery keeps the whole stack live when upstream sources fail. Each pillar protects the rest.

Reorg Handling at the Framework Level​

The reorg architecture is the deepest piece of work HyperIndex's reliability story rests on. To understand why "framework-level" matters, it helps to be precise about what a reorg actually does to an indexer.

A reorg is a chain rolling back to a previous point in time. A recent block (or several) is no longer canonical, and the new canonical chain has different events at those heights. The implications for an indexer split along a single axis, stateless versus stateful.

Stateless indexers only create entities. On a reorg, the fix is mechanical. Delete the entities written from orphaned blocks, re-ingest from the canonical chain, move on. Stateless indexing parallelises well and is fast.

Stateful indexers also update and delete entities based on previous state. An order book's running volume, an account's balance, a market's open interest, all of these aggregate prior state into current state. On a reorg, you cannot just delete and replay. You have to revert previous operations to the entity state at the pre-reorg point, then replay forward against the canonical chain. Doing that correctly requires tracking the history of every change to every entity for the entire unfinalized window.

HyperIndex's framework keeps that entity history for you.

"Envio HyperIndex tracks entity state history for all unfinalized blocks. When a reorg is detected, it rolls back entity state to the correct point and reprocesses events from the canonical chain. This happens automatically and does not require any custom rollback logic in your event handlers."

Denham Preen, Envio Co-founder

Learn more in our Indexing and Reorgs blog.

Three architectural details worth knowing about that mechanism:

1. History is per-entity, not per-block. The framework persists the prior state of each entity each time a handler writes to it within the unfinalized window. On a reorg, the rollback walks the per-entity history backwards to the pre-reorg state, applies it, and reprocesses forward.

2. History is pruned automatically. Once a block is finalised, its entries in the entity history are no longer needed. The framework prunes them. The unfinalized window is the only window that ever carries history overhead, which keeps the storage cost bounded regardless of total chain length.

3. Multichain reorg handling is harder than single-chain, and the framework does it. When a single entity's state is updated by events from multiple chains, a reorg on chain A may force the framework to also reprocess events on chain B that were applied after the reorg point but depended on the rolled-back state. The reorg blog calls this out explicitly. Hand-rolling correct multichain reorg logic is the kind of thing you do not want any application engineer to have to write.

Reorgs in the Wild​

These are not theoretical edge cases. From the same reorg blog:

• Polygon has frequent and sometimes deep reorgs. The forum has documented a single 157-block reorg at block height 39,599,624. Polymarket runs on Polygon. Polymarket's reference indexer at github.com/enviodev/polymarket-indexer has stayed correct through every Polygon reorg, including the deep ones, because the framework does the work.
• Ethereum mainnet sees roughly 1% of blocks affected by reorgs. Assuming a 50/50 chance of a transaction landing in the orphaned versus canonical fork, that's about 1 in 200 transactions ending up in a reorged block. An indexer that does not roll back state is silently wrong for ~0.5% of the transactions it ingests.
• Base and OP-stack chains are largely reorg-resistant due to single-slot finality, with documented exceptions.

Why this matters operationally:

• No bespoke per-handler logic. The most common subgraph reliability bug is a handler that does not handle a reorg correctly because the dev forgot to. With HyperIndex that bug class does not exist.
• No "wait for N confirmations" delay. Some indexers paper over reorgs by lagging behind the chain head by N blocks. HyperIndex stays at chain head and rolls back if needed.
• Multichain stays correct. A multichain indexer with one chain reorging does not corrupt the cross-chain aggregates. The framework rolls back the dependent state on every other chain too.

Multi Data-Source Recovery​

HyperIndex's multi data-source recovery is documented in the dev update archive and tracked in the GitHub releases.

The feature has three concrete pieces.

1. Smarter source selection​