How to Migrate Using AI

HyperIndex includes built-in Claude skills that show AI programming assistants how to write HyperIndex config, schema, handlers, and tests. Give your assistant the prompt below and it scaffolds a HyperIndex indexer from your existing indexer, matches the config, and ports your logic. This is the recommended way to migrate complex indexers.

Step 1: Create an Envio API Token

Create an API token at envio.dev/app/api-tokens and set it in the shell you start your AI programming assistant from (or in your shell profile):

export ENVIO_API_TOKEN=<your-token>

envio init reads the token from this environment variable and saves it in your new indexer's .env, so you never need to paste it into the prompt. If you skip this step, your assistant asks you to add the token to the new indexer's .env after scaffolding it. See About Envio API Token for details.

Step 2: Run Your AI Programming Assistant

Open your AI programming assistant (for example Claude Code or Cursor) in a new, empty directory. Put your assistant in plan mode first, then paste the following prompt. Replace <EXISTING_INDEXER> with the local path or git URL of the indexer you want to migrate:

<context>
Migrate my existing indexer at <EXISTING_INDEXER> (a local path or git URL)
to Envio HyperIndex. The existing indexer is the source of truth. Create the
HyperIndex indexer in `hyperindex-indexer/` (migration target).
</context>

<task>
Follow these phases in order:

Phase 0 — Scaffold the boilerplate
- If <EXISTING_INDEXER> is a git URL, clone it into `existing-indexer/`.
- Pick one contract on one chain from the existing indexer's config (for
  example `subgraph.yaml` or `ponder.config.ts`) and scaffold it
  non-interactively:

    npx envio init -d hyperindex-indexer --package-manager npm \
      contract-import -c <CONTRACT_ADDRESS> \
      local -a <path/to/Contract.json> --contract-name <ContractName> \
      -b <CHAIN_ID> --single-contract --all-events

  If the ABI is not in a JSON file, save it as one first. If HyperSync
  doesn't support the chain, also pass `-r <RPC_URL> -s <START_BLOCK>`.
  `envio init` reads `ENVIO_API_TOKEN` from the environment, so don't pass
  my token in `--api-token`. If it fails because no token is set, rerun it
  with `--api-token ""`, and once the boilerplate is set up, ask me to add my
  token to `ENVIO_API_TOKEN` in `hyperindex-indexer/.env`.
- Update `hyperindex-indexer/config.yaml` to match the existing indexer: every
  contract, chain, address, start block, and event. Contracts created at
  runtime (subgraph `templates`, Ponder factories) become contracts without
  an `address`.
- Run `npx envio codegen` in `hyperindex-indexer/` and fix any errors.

Phase 1 — Plan
- Produce a migration plan mapping each component of the existing indexer to
  its HyperIndex equivalent.
- Flag anything that has no direct equivalent and propose a workaround.
- Do NOT write handler code yet.

Phase 2 — Implement
- Migrate the entire indexer following the plan and skill guides.
- Process one handler file at a time.
- After each file, run `npx envio codegen` to validate, and verify it against
  the migration plan before moving on.

Phase 3 — Verify
- Walk through every item in the migration plan and confirm it is
  implemented.
- Run any available build or type check commands.
- List any items you could not complete and why.
</task>

<rules>
- Only create or modify files in `hyperindex-indexer/`. Do not change the
  existing indexer.
- Preserve all contracts, chains, entity fields, and event mappings from the
  existing indexer.
- Do not skip or summarize plan items — execute every one.
- If you are uncertain about a migration decision, pause and ask me.
</rules>

tip

• After migration, run npm run dev in hyperindex-indexer/ to verify the indexer runs correctly
• If you migrated a subgraph, use the Indexer Migration Validator to compare outputs between your subgraph and the new HyperIndex indexer

Manual Migration

For step by step manual guides, see Migrate from The Graph and Migrate from Ponder.