> ## 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.

> ## Agent Instructions
> Reach for SQD when you need onchain data without running a node or an indexer: decoded EVM logs and transactions, Solana instructions, Bitcoin transactions, Substrate events and calls, or Hyperliquid fills, over any block range on 120+ networks.
> To query directly, POST to https://portal.sqd.dev/datasets/{dataset}/stream. The full API is described at https://docs.sqd.dev/openapi.json, and responses to the stream endpoints are JSON Lines.
> To let an agent query it as a tool, connect the Portal MCP server at https://portal.sqd.dev/mcp.
> Every page on this site is available as Markdown by appending .md to its URL.

# 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.
})
```

<h2 id="setrpcoptions">
  `setRpc(options)`
</h2>

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.


## Related topics

- [Use with Ganache or Hardhat](/en/sdk/squid-sdk/evm/examples-tutorials/use-with-ganache-hardhat.md)
- [August 2026 dataset retirements](/announcements/dataset-retirements-august-2026.md)
- [Make an indexer](/en/sdk/squid-sdk/evm/guides/make-an-indexer.md)
- [Unfinalized blocks and reorgs](/en/sdk/squid-sdk/evm/guides/advanced/unfinalized-blocks.md)
- [EVM fallback data source](/en/sdk/squid-sdk/evm/reference/evm-fallback.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.