Migrate a squid to Portal

This guide walks you through migrating EVM and Solana indexer setups that use .setGateway() (and optionally .setRpc()) over to Portal data sources. It works whether or not you have already migrated to a Portal for historical data.

Prefer to run this with Claude Code, Codex, or another AI coding agent? Install the migration skill in your squid’s directory:

npx skills add subsquid-labs/skills/squid-sdk/migrate-to-portal

Then open your agent in the same directory and ask it to migrate. The agent should find the skill; if it doesn’t, stop it and tell it where to look in plain English (e.g. at ./.agents/skills/migrate-to-portal if you installed the skill project-scoped for Claude).The skill detects your chain and follows the same steps as this guide. Skill source: subsquid-labs/skills/squid-sdk/migrate-to-portal.

If you’re reading this because you have been self-hosting gateway-based squids after May 19, 2026 12:00 UTC and received an error requesting a gateway API key, migrating to Portal is the recommended path, but not the only one. The alternative is to register and access gateways with API keys.

Prerequisites

An existing squid based on
- @subsquid/evm-processor on EVM: will typically use .setGateway() and .setRpcEndpoint(), in rare cases without either or with a .setPortal() - all of these cases are covered
- @subsquid/solana-stream on Solana: using .setGateway() and/or .setRpc()
Node.js 22+ and npm installed
An SQD Portal URL for your dataset:
- For public Portal: https://portal.sqd.dev/datasets/<slug> (find your slug on the networks page)
- For a private Portal: get an URL from SQD or supply your own if self-hosting

Migration steps

Pick your chain.

EVM
Solana

Jump to: Reference templates · Common errors

Install new packages

Replace the old processor package with the new packages:

npm uninstall @subsquid/evm-processor @subsquid/archive-registry
npm i @subsquid/evm-stream @subsquid/evm-objects @subsquid/batch-processor @subsquid/logger

@subsquid/archive-registry and lookupArchive are deprecated. Remove the package and all lookupArchive(...) calls (we cover the data source replacement in Step 3).

If your handler imports decodeHex or assertNotNull from @subsquid/evm-processor, move those imports too. They are exported only by their utility packages now (both pulled in transitively by @subsquid/evm-stream and @subsquid/batch-processor, so no extra install needed):

-import {decodeHex, assertNotNull} from '@subsquid/evm-processor'
+import {decodeHex} from '@subsquid/util-internal-hex'
+import {assertNotNull} from '@subsquid/util-internal'

Switch the processor to a Portal data source

In src/processor.ts or src/main.ts, swap the processor imports and initialization:

-import {EvmBatchProcessor} from '@subsquid/evm-processor'
+import {DataSourceBuilder} from '@subsquid/evm-stream'
+import {augmentBlock} from '@subsquid/evm-objects'
+import {createLogger} from '@subsquid/logger'

-const processor = new EvmBatchProcessor()
-  .setGateway('https://v2.archive.subsquid.io/network/ethereum-mainnet')
-  .setRpcEndpoint('https://rpc.ankr.com/eth')
-  .setFinalityConfirmation(75)
+const dataSource = new DataSourceBuilder()
+  .setPortal('https://portal.sqd.dev/datasets/ethereum-mainnet')
   // ... .addLog(...), .setFields(...), etc.
+  .build()

RPC endpoint and finality confirmation settings are no longer needed.

If your squid still uses the older `.setDataSource({archive, chain})` shape

Squids untouched since 2024 may use the pre-setGateway API:

.setDataSource({
  archive: lookupArchive('eth-mainnet'),
  chain: 'https://rpc.ankr.com/eth',
})

The destination is the same. Replace the whole block with .setPortal(...) and drop the lookupArchive import (@subsquid/archive-registry is gone, see Step 1).

Have data & context type aliases exported alongside the processor object? Rewrite them here.

The data types are now split across two packages: @subsquid/evm-stream exports FieldSelection; @subsquid/evm-objects exports the augmented block data types (BlockHeader, Block — previously BlockData — Log, Transaction, Trace, StateDiff). Three changes to be aware of:

BlockData<F> is renamed to Block<F>. The single-block type previously called Block (just the header) is now BlockHeader<F>.
The upstream DataHandlerContext lives in @subsquid/batch-processor. Its generic arguments are flipped (DataHandlerContext<Block, Store>, not <Store, Fields>) and it has only {store, blocks, isHead}. Add log (and _chain if you make RPC calls) yourself.
The Fields type alias should be derived from the same fields constant you pass to .setFields().

-import {
-  BlockHeader,
-  DataHandlerContext,
-  EvmBatchProcessor,
-  Log as _Log,
-  Transaction as _Transaction,
-  BlockData as _BlockData,
-  FieldSelection,
-} from '@subsquid/evm-processor'
+import * as evmObjects from '@subsquid/evm-objects'
+import {DataSourceBuilder, FieldSelection} from '@subsquid/evm-stream'
+import type {DataHandlerContext as BaseDataHandlerContext} from '@subsquid/batch-processor'
+import type {Logger} from '@subsquid/logger'

 const fields = {
   log: { transactionHash: true },
 } satisfies FieldSelection

 export type Fields = typeof fields
-export type Block = BlockHeader<Fields>
-export type BlockData = _BlockData<Fields>
-export type Log = _Log<Fields>
-export type Transaction = _Transaction<Fields>
-export type ProcessorContext<Store> = DataHandlerContext<Store, Fields>
+export type Block = evmObjects.BlockHeader<Fields>
+export type BlockData = evmObjects.Block<Fields>
+export type Log = evmObjects.Log<Fields>
+export type Transaction = evmObjects.Transaction<Fields>
+export type DataHandlerContext<Store> = BaseDataHandlerContext<BlockData, Store> & {
+  log: Logger
+  // include `_chain` here if you make direct RPC calls (see the optional step below)
+}

If your squid uses `.setPortal()` alongside `.setRpcEndpoint()` (Portal beta participants)

Treat the .setPortal call in the same way as you would a .setGateway call - remove it alongside the processor initialization and set up a new one.

If your squid is not using real time data (.setGateway without .setRpcEndpoint)

Previously, using a gateway data source only (without RPC) enabled the regime when the squid only consumes and processes finalized data. This introduces a significant delay between the data appearing on chain and in the indexer, but allows you to forward data to append-only destinations, which is not possible with real time data. To enable this regime in Portal-powered squids, explicitly disable hot blocks support in the target database, e.g.

const db = new TypeormDatabase({supportHotBlocks: false})

A data source streaming into such a target will automatically switch to ingesting from /finalized-stream instead of /stream.

Expand the field selection

Every field your handler reads must be listed in .setFields(). With EvmBatchProcessor, common fields like log.address, log.topics, log.data, block.timestamp and transaction.from/to/hash were merged in from a built-in default set. DataSourceBuilder fetches only the fields you list, and TypeScript will reject any unlisted access.

A minimum set typical for an EVM logs indexer:

const fields = {
  block: { timestamp: true },
  log: {
    address: true,
    topics: true,
    data: true,
    transactionHash: true, // and anything else you were already selecting
  },
} satisfies FieldSelection

Add transaction/trace/stateDiff entries as needed. TypeScript errors at compile time will point you at any field still missing.The top-level block.height and block.timestamp shortcuts are also gone. Read them from block.header.number and block.header.timestamp. block.header.height still exists but is @deprecated.

If your squid is from pre-@subsquid/[email protected] era, rename evmLog to log.

Update data requests

Rewrite data requests using the new where-include-range syntax:

 .addLog({
-  address: [USDC_CONTRACT_ADDRESS],
-  topic0: [usdcAbi.events.Transfer.topic],
-  transaction: true, // include the parent transaction
+  where: {
+    address: [USDC_CONTRACT_ADDRESS],
+    topic0: [usdcAbi.events.Transfer.topic],
+  },
+  include: {
+    transaction: true, // include the parent transaction
+  },
   range: { from: 6_082_465 },
 })

Update the run function

Replace processor.run() with the unified run function. Add the import, create a logger, and enrich the context with augmentBlock:

+import {run} from '@subsquid/batch-processor'

+const logger = createLogger('sqd:processor:mapping')

-processor.run(db, async (ctx) => {
+run(dataSource, db, async (simpleCtx) => {
+  const ctx = {
+    ...simpleCtx,
+    blocks: simpleCtx.blocks.map(augmentBlock),
+    log: logger,
+  }
   // ... handler body
 })

Used `.setPrometheusPort()` / `.setPrometheusServer()`? Move them here.

PrometheusServer is now passed to run() via the prometheus option instead of being attached to the processor. Construct one and hand it over; the runner still attaches the built-in sqd_processor_* metrics and calls .serve() itself.

-processor.setPrometheusPort(3000)
-processor.setPrometheusServer(myServer)
+import {PrometheusServer} from '@subsquid/batch-processor'
+
+const prometheus = new PrometheusServer()
+prometheus.setPort(3000)
+// prometheus.addMetricsSink({ register(registry) { /* register custom prom-client metrics */ } })
+
+run(dataSource, db, async (simpleCtx) => { /* ... */ }, {prometheus})

setPort() overrides PROCESSOR_PROMETHEUS_PORT / PROMETHEUS_PORT. For custom metrics, register them on the server’s registry via addMetricsSink() so they share the /metrics endpoint with sqd_processor_* — see this branch for a worked example.

Add an RPC client

Optional Only do this if your batch handler makes direct RPC calls (contract state queries). Otherwise skip.Install the client, initialize an RpcClient, and enrich the batch context with a _chain field:

npm i @subsquid/rpc-client

import {RpcClient} from '@subsquid/rpc-client'

const rpcClient = new RpcClient({
  url: 'https://my_rpc_url',
  rateLimit: 100,
})

  const ctx = {
    ...simpleCtx,
    blocks: simpleCtx.blocks.map(augmentBlock),
    log: logger,
+    _chain: {
+      client: rpcClient
+    }
  }

If you keep a DataHandlerContext<Store> alias in src/processor.ts, extend it so _chain is part of the type your handlers see:

 export type DataHandlerContext<Store> = BaseDataHandlerContext<BlockData, Store> & {
   log: Logger
+  _chain: { client: RpcClient }
 }

Contract state queries then work as before:

const usdcContract = new usdcAbi.Contract(ctx, blocks[0].header, USDC_CONTRACT_ADDRESS)
const decimals = await usdcContract.decimals()

Smoke-test locally

Build and run the squid locally before deploying. If the first batch lands without TypeScript or missing-field runtime errors, you’re ready to deploy:

npm run build
npx squid-typeorm-migration apply
node lib/main.js

Re-sync the squid

We highly recommend that all squids migrated to Portal are re-synced. This allows you to make sure that everything works as expected for the whole length of the chain and catch any bugs early.If your squid is deployed to the Cloud, follow the zero-downtime update procedure:

Deploy your squid into a new slot.
Wait for it to sync, observing the improved data fetching.
Assign your production tag to the new deployment to redirect the GraphQL requests there.

See the slots and tags guide for details.Can’t afford a re-sync? Simply re-deploy your squid without resetting its database.

Common errors (EVM)

A few canonical TypeScript errors map back to specific steps above. If you hit one, jump to the fix:

Symptom	Root cause	Fix
`Property 'transactionHash' does not exist on type 'Log'` (used `log` key)	Forgot to list `transactionHash: true` under `.setFields().log`	Add `transactionHash: true` (and any other fields you read) under `.setFields().log`
`Property 'height' does not exist on type 'BlockHeader'` (or `'timestamp'`)	Top-level `block.height`/`block.timestamp` shortcuts removed	Use `block.header.number` / `block.header.timestamp`. `block.header.height` still works (deprecated) if `.height` is baked into entity columns and you want a literal rename.
`'apiKey' does not exist in type 'GatewaySettings'`	You’re on `evm-processor < 1.30.0` and tried to add `apiKey` before bumping the package.	Either (a) migrate to `evm-stream` / `.setPortal('...')`: Portal needs no API key today. (b) Bump `@subsquid/evm-processor` to `^1.30.0` to get the `apiKey` field on `GatewaySettings`.
`Module '"@subsquid/evm-processor"' has no exported member 'decodeHex'`	`decodeHex` is only exported by `@subsquid/util-internal-hex` now	See Step 1 Install new packages
`Module '"@subsquid/evm-processor"' has no exported member 'assertNotNull'`	`assertNotNull` is only exported by `@subsquid/util-internal` now	Same step
`Module '"@subsquid/archive-registry"' has no exported member 'lookupArchive'` (or `Cannot find module`)	Package removed entirely	Uninstall `@subsquid/archive-registry` and replace the whole data source block with `.setPortal(...)`
`Object literal may only specify known properties, and 'evmLog' does not exist`	`.setFields()` key renamed in `evm-processor@^1.21.0`	Rename `evmLog` to `log` in `.setFields()` (see Expand the field selection)
`Property 'transactionHash' does not exist on type 'Log'` (used `evmLog` key)	`evmLog` key no longer projects `transactionHash` onto `Log`	Rename `evmLog` to `log` in `.setFields()`

Reference templates (EVM)

If you want to diff against a known-good shape, these are the canonical post-migration templates:

squid-evm-rt-template@with-logger

Portal data source, augmented context, no direct RPC calls

squid-evm-rt-template@with-rpc-client

Same as above plus an RpcClient wired into the context for state queries

Next steps (EVM)

Portal EVM API

Complete Portal API documentation for EVM

EVM examples

More examples of Portal API usage on EVM

Jump to: Reference template · Common errors

Stop using the RPC client

Remove the SolanaRpcClient import and the .setRpc({...}) call from your data source. Your project still compiles on your current @subsquid/solana-stream version after this edit; once you bump to ^1.x.x in the next step (where SolanaRpcClient and .setRpc() disappear), you avoid a broken intermediate state.

-import {DataSourceBuilder, SolanaRpcClient} from '@subsquid/solana-stream'
+import {DataSourceBuilder} from '@subsquid/solana-stream'

   const dataSource = new DataSourceBuilder()
     .setGateway('https://v2.archive.subsquid.io/network/solana-mainnet')
-    .setRpc({
-      client: new SolanaRpcClient({
-        url: process.env.SOLANA_NODE
-      })
-    })

Upgrade SDK packages

From your squid’s folder, upgrade every @subsquid/* package to its latest release:

npx --yes npm-check-updates --filter "@subsquid/*" --target "@latest" --upgrade

This should bump @subsquid/solana-stream to a 1.x.x version.Then install:

NPM
Yarn
PNPM

npm install

yarn install

pnpm install

Switch the data source to Portal

Replace the gateway URL with the Portal URL:

+  .setPortal({
+    url: 'https://portal.sqd.dev/datasets/solana-mainnet',
+      http: {
+        retryAttempts: Infinity
+      }
+   })
-  .setGateway('https://v2.archive.subsquid.io/network/solana-mainnet')

(The SolanaRpcClient import and .setRpc({...}) call are already gone from Step 1.)

Have data & context type aliases exported alongside the processor object? Rewrite them here.

If your project re-exports Fields/Block/Transaction/Context aliases that handlers consume, re-derive them against the new packages:

-import {DataSourceBuilder, FieldSelection, Block as _Block, Transaction as _Transaction, Instruction as _Instruction} from '@subsquid/solana-stream'
+import {DataSourceBuilder, FieldSelection} from '@subsquid/solana-stream'
+import * as solanaObjects from '@subsquid/solana-objects'
+import type {DataHandlerContext as BaseDataHandlerContext} from '@subsquid/batch-processor'

 const fields = {
   block: {timestamp: true},
   transaction: {signatures: true, err: true, accountKeys: true},
 } satisfies FieldSelection

 export type Fields = typeof fields
-export type Block = _Block<Fields>
-export type Transaction = _Transaction<Fields>
-export type Instruction = _Instruction<Fields>
-export type Context = DataHandlerContext<Store, Fields>
+export type BlockHeader = solanaObjects.BlockHeader<Fields>
+export type Block = solanaObjects.Block<Fields>
+export type Transaction = solanaObjects.Transaction<Fields>
+export type Instruction = solanaObjects.Instruction<Fields>
+export type DataHandlerContext<Store> = BaseDataHandlerContext<Block, Store>

Use the solana-example template as a reference if your squid has unusual aliases.

If your squid is not using real time data (.setGateway without .setRpcEndpoint)

const db = new TypeormDatabase({supportHotBlocks: false})

A data source streaming into such a target will automatically switch to ingesting from /finalized-stream instead of /stream.

Keep block ranges in slots

DataSourceBuilder.setBlockRange() uses the same slot-number coordinate returned as block.header.number. Keep existing slot ranges unchanged. There is no separate contiguous Portal-height coordinate for this API.

Replace `block.header.slot` reads

If your handler code reads the slot field of a block header, rename it to .number:

-  slot: block.header.slot,
+  slot: block.header.number,

Expand the field selection

tokenBalance.preMint / postMint are the #1 silent break on real Solana migrations. DEX squids that read these to recover swap-side mints will hit Property 'preMint' does not exist on type 'TokenBalance' until you add them to .setFields().tokenBalance. Pre-1.x @subsquid/solana-stream merged them in for free; the current release returns only the fields you list.

transaction.accountKeys was never in the old SDK’s defaults either — add it if you read the fee payer via tx.accountKeys[0].

Full set of fields the old `@subsquid/solana-stream` used to merge in for free

Object	Fields merged in by the old SDK
`block`	`timestamp`
`transaction`	`signatures`, `err`
`instruction`	`programId`, `accounts`, `data`, `isCommitted`
`log`	`programId`, `kind`, `message`
`balance`	`pre`, `post`
`tokenBalance`	the full `pre`/`post` family (`preMint`, `postMint`, `preOwner`, `postOwner`, `preAmount`, `postAmount`, `preDecimals`, `postDecimals`, `preProgramId`, `postProgramId`)
`reward`	`lamports`, `rewardType`

block.header.number is always available and contains the slot. The current Portal source does not return height, even though @subsquid/[email protected] accepts it in the TypeScript field selection. Migrate height reads to number.

   .setFields({
     block: { // block header fields
       timestamp: true,
     },
+    transaction: {
+      signatures: true,
+      err: true,
+      accountKeys: true,  // needed for tx.accountKeys[0] (fee payer)
+    },
+    tokenBalance: {
+      preMint: true,
+      postMint: true,
+      // add preAmount / postAmount / preDecimals / postDecimals / preOwner / postOwner as needed
+    },
   })

Add instruction/log/balance/reward entries the same way. TypeScript errors at compile time will point you at any field still missing from the selection.

Smoke-test locally

Build and run the squid locally before deploying. If the first batch lands without TypeScript or missing-field runtime errors, you’re ready to deploy:

npm run build
npx squid-typeorm-migration apply
node lib/main.js

Re-sync the squid

Deploy your squid into a new slot.
Wait for it to sync, observing the improved data fetching.
Assign your production tag to the new deployment to redirect the GraphQL requests there.

See the slots and tags guide for details.Can’t afford a re-sync? See the manual workaround (not recommended; edits the status schema directly).

Common errors (Solana)

Symptom	Root cause	Fix
`Property 'preMint' does not exist on type 'TokenBalance'` (or `postMint`/`preOwner`/`postAmount`/…)	Pre-1.x `solana-stream` merged the `tokenBalance.pre`/`post` family for free; the current release does not	Add the field to `.setFields().tokenBalance` (see Expand the field selection)
`Property 'timestamp' does not exist on type 'BlockHeader'`	`block.timestamp` was in the old SDK’s default set	Add `block: {timestamp: true}` to `.setFields()`
`Property 'signatures' does not exist on type 'Transaction'` (or `accountKeys`/`err`)	Same: was in the old SDK’s defaults, no longer merged in	Add to `.setFields().transaction`
`Property 'height' does not exist on type 'BlockHeader'`	The Portal source identifies Solana blocks by slot and does not return `height`	Use `block.header.number` and keep range values in the same slot-number coordinate
`Module '"@subsquid/solana-stream"' has no exported member 'SolanaRpcClient'`	You bumped to `solana-stream@^1.x.x` but kept the import	Remove the import (see Stop using the RPC client)
`Property 'apiKey' does not exist in type 'GatewaySettings'`	You’re calling `.setGateway({url, apiKey})` on the new SDK	Portal uses `.setPortal('...')` and needs no API key today

Reference template (Solana)

If you want to diff against a known-good shape, this is the canonical post-migration template:

solana-example@master

Portal-based Solana indexer with the field selection, hot-block support, and types this guide produces

Overview

Pipes SDK

Squid SDK

Alternative clients

Prerequisites

Migration steps

Reference templates (EVM)

squid-evm-rt-template@with-logger

squid-evm-rt-template@with-rpc-client

Next steps (EVM)

Portal EVM API

EVM examples

Reference template (Solana)

solana-example@master

Next steps (Solana)

Portal Solana API

Solana examples

​Prerequisites

​Migration steps

​Reference templates (EVM)

squid-evm-rt-template@with-logger

squid-evm-rt-template@with-rpc-client

​Next steps (EVM)

Portal EVM API

EVM examples

​Reference template (Solana)

solana-example@master

​Next steps (Solana)

Portal Solana API

Solana examples

Prerequisites

Migration steps

Reference templates (EVM)

Next steps (EVM)

Reference template (Solana)

Next steps (Solana)