> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# EVM RPC data source

> Index EVM data straight from a JSON-RPC endpoint with EvmRpcDataSourceBuilder.

`EvmRpcDataSourceBuilder` builds a data source that ingests EVM data from any JSON-RPC endpoint.
It is the RPC counterpart of the [EVM Portal stream](./evm-stream): the query surface
(`setFields`, `addLog`, `addTransaction`, `addTrace`, `addStateDiff`, `includeAllBlocks`,
`addQuery`) is identical, and the built source runs anywhere a Portal source does — including
[`run()` and `Processor`](./batch-processor) and the [EVM fallback data source](./evm-fallback).
The only difference is `setRpc(...)` in place of `setPortal(...)`.

Use it when a Portal dataset is not available for your network, or as a standby source behind a
Portal primary — see [High availability](../guides/advanced/high-availability).

## Install

```bash theme={"system"}
npm i @subsquid/squid-sdk @subsquid/evm-rpc @subsquid/evm-normalization
```

`@subsquid/evm-rpc` and `@subsquid/evm-normalization` are optional peers of the SDK package —
required only when an RPC source is used.

## Complete example

```ts theme={"system"}
import {run} from '@subsquid/squid-sdk/processor'
import {EvmRpcDataSourceBuilder} from '@subsquid/squid-sdk/evm/rpc'

const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
const TRANSFER = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

const dataSource = new EvmRpcDataSourceBuilder()
  .setRpc({
    url: process.env.RPC_URL!,
    network: 'ethereum-mainnet',
  })
  .setFields({log: {address: true, topics: true, data: true}})
  .addLog({
    where: {address: [USDC], topic0: [TRANSFER]},
    range: {from: 18_000_000},
  })
  .build()

run(dataSource, db, async (ctx) => {
  // Same handler context as with a Portal source.
})
```

## `setRpc(options)`

Accepts a bare endpoint URL string, or an options object:

| Option              | Meaning                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `url`               | JSON-RPC endpoint URL (required)                                                                             |
| `network`           | Known network slug or chainId — selects the per-network preset (block validation, trace/debug method choice) |
| `rpc`               | Explicit validation/finality overrides, merged over the preset                                               |
| `method`            | Explicit trace/stateDiff method overrides, merged over the preset                                            |
| `capacity`          | Max concurrent requests                                                                                      |
| `rateLimit`         | Requests per second cap                                                                                      |
| `strideSize`        | Blocks per ingestion stride                                                                                  |
| `strideConcurrency` | Concurrent strides                                                                                           |

## Network presets

Setting `network` to a known slug (or its chainId) enables block validation and selects the right
trace/debug methods for that chain, so the produced dataset matches what the Portal serves:

`ethereum-mainnet`, `optimism-mainnet`, `base-mainnet`, `arbitrum-one`, `gnosis-mainnet`,
`polygon-mainnet`, `cronos-mainnet`

Known slugs are offered in TypeScript autocomplete. Any other slug or chainId is accepted but runs
without a preset.

<Warning>
  With no matching preset and no explicit `rpc`/`method` overrides, block validation is disabled and
  **dataset parity with the Portal is not guaranteed** — the source logs a warning at build time.
  Supplying your own `rpc`/`method` overrides counts as taking ownership of the per-chain
  configuration and silences the warning.
</Warning>

## Query methods

`setFields`, `setBlockRange`, `addLog`, `addTransaction`, `addTrace`, `addStateDiff`,
`includeAllBlocks`, and `addQuery` behave exactly as on the Portal builder — see the
[EVM Portal stream reference](./evm-stream) for the full query surface.

## `build()`

Returns an EVM data source with the standard interface (`getHead`, `getFinalizedHead`,
`getStream`, `getFinalizedStream`). Pass it to [`run()` or `Processor`](./batch-processor), use it
as a downstream source of an [EVM fallback](./evm-fallback), or consume the stream directly.
Throws if `setRpc(...)` was not called.