Configure Ponder with Portal - SQD Documentation

Add a Portal dataset to each Ponder chain that should use Portal for historical backfill:

import { createConfig } from "@subsquid/ponder";

export default createConfig({
  chains: {
    mainnet: {
      id: 1,
      rpc: process.env.PONDER_RPC_URL_1,
      portal: "https://portal.sqd.dev/datasets/ethereum-mainnet",
    },
    base: {
      id: 8453,
      rpc: process.env.PONDER_RPC_URL_8453,
      portal: "https://portal.sqd.dev/datasets/base-mainnet",
    },
  },
});

If a chain has no portal field, it uses Ponder’s stock RPC historical sync. Dataset URLs and capabilities are listed on the EVM networks page.

Portal access

The public Portal at https://portal.sqd.dev does not require an API key. It shares capacity across users and is intended for development and bounded evaluation. For an authenticated or dedicated Portal, set PORTAL_API_KEY. The integration sends it in the x-api-key header on Portal requests. See Portal pricing for current access options.

Memory and observability

The defaults adapt request concurrency and read-ahead automatically. The settings most likely to be useful in an application are:

Variable	Default	Use
`PORTAL_MAX_ROWS_IN_MEM`	`250000`	Limits buffered rows shared across chains. The default typically consumes about 1.5 to 2.5 GB after Ponder’s derived copies.
`PORTAL_METRICS_FILE`	unset	Writes cumulative per-chain metrics to `<path>.<chainId>`.
`PORTAL_GATE_LOG`	unset	Set to `1` to log the shared concurrency and buffer controller every 20 seconds.
`PORTAL_PROGRESS_INTERVAL`	`10000`	Sets the Portal progress-log interval in milliseconds. Set to `0` to disable it.
`PORTAL_CHECKS`	`on`	Runs constant-time runtime invariant checks. `strict` adds full-structure checks intended for tests.

For chunk sizing, concurrency, timeouts, and discovery settings, use the repository’s configuration reference. Raising concurrency does not help when Ponder’s indexing loop is already the bottleneck.

Realtime

Realtime indexing uses Ponder’s RPC path by default. This is also the default for reorg handling. Keep the RPC configured for chain setup and readContract even if you test another realtime mode.

PORTAL_REALTIME=stream is experimental. The current implementation accepts only log sources that do not request transaction receipts. It rejects block, transaction, trace, transfer, and receipt-dependent sources at startup. Use RPC realtime unless you have validated this mode for your app.

When stream realtime is enabled, historical sync stops at Portal’s finalized head and the Portal /stream supplies the later blocks. Without this flag, an interval beyond the Portal finalized head falls back to stock RPC historical sync.

​Portal access

​Memory and observability

​Realtime

Portal access

Memory and observability

Realtime