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

> Subscribe to EVM transaction data with addTransaction() — filter by sender, receiver and sighash.

<h4 id="add-transaction">
  `addTransaction(options)`
</h4>

Get some *or all* transactions on the network. `options` has the following structure:

```typescript theme={"system"}
{
  // item filters
  where?: {
    from?: string[]
    to?: string[]
    sighash?: string[]
    type?: number[]
  }

  // related data retrieval
  include?: {
    logs?: boolean
    traces?: boolean
    stateDiffs?: boolean
  }

  // block range override
  range?: {from: number, to?: number}
}
```

Item filters (`where`):

* `from` and `to`: the sets of addresses of tx senders and receivers. Omit to subscribe to transactions from/to any address.
* `sighash`: [first four bytes](https://ethereum.org/en/developers/docs/transactions/#the-data-field) of the Keccak hash (SHA3) of the canonical representation of the function signature. Omit to subscribe to any transaction.
* `type`: transaction type numbers, such as `0`, `1`, `2`, `3`, or `4`. Type `4` is used by EIP-7702 authorization-list transactions.

<Warning>
  Filter values are matched as exact strings by the Portal — always pass addresses and sighashes as lowercase hex strings. `@subsquid/evm-stream` does not normalize the case for you.
</Warning>

Enabling the `logs`, `traces` and/or `stateDiffs` flags of `include` will cause the data source to retrieve [event logs](./logs), [traces](./traces) and/or [state diffs](./state-diffs) that occurred as a result of each selected transaction. The data is added to the appropriate flat iterables within the [block data](./context-interfaces); call `augmentBlock()` from `@subsquid/evm-objects` to navigate between the related items conveniently (e.g. `transaction.logs`).

`range` overrides the global [`setBlockRange()`](../evm-stream) for this particular request.

Note that transactions can also be requested by [`addLog()`](./logs), [`addTrace()`](./traces) and [`addStateDiff()`](./state-diffs) as related data.

Selection of the exact fields to be retrieved for each transaction and the optional related data items is done with the `setFields()` method documented on the [Field selection](./field-selection) page. There are no default fields — request everything your handler reads. Some examples are available below.

<Tip>
  Typescript ABI modules generated by [`squid-evm-typegen`](../evm-typegen/generating-utility-modules) provide function sighashes as constants, e.g.

  ```ts theme={"system"}
    import * as erc20abi from './abi/erc20'
    // ...
        sighash: [erc20abi.functions.transfer.sighash],
    // ...
  ```
</Tip>

## Examples

1. Request all EVM calls to the contract `0x6a2d262D56735DbA19Dd70682B39F6bE9a931D98`:

```ts theme={"system"}
source.addTransaction({
  where: {to: ['0x6a2d262d56735dba19dd70682b39f6be9a931d98']}
})
```

2. Request all transactions matching sighash of `transfer(address,uint256)`:

```ts theme={"system"}
source.addTransaction({
  where: {sighash: ['0xa9059cbb']}
})
```

3. Request all `transfer(address,uint256)` calls to the specified addresses, from block `6_000_000` onwards, and fetch their inputs. Also retrieve all logs emitted by these calls.

```ts theme={"system"}
source
  .addTransaction({
    where: {
      to: [
        '0x6a2d262d56735dba19dd70682b39f6be9a931d98',
        '0x3795c36e7d12a8c252a20c5a7b455f7c57b60283'
      ],
      sighash: [
        '0xa9059cbb'
      ]
    },
    include: {
      logs: true
    },
    range: {
      from: 6_000_000
    }
  })
  .setFields({
    transaction: {
      input: true
    }
  })
```

4. Mine all transactions to and from Vitalik Buterin's address [`vitalik.eth`](https://etherscan.io/address/vitalik.eth). Fetch the involved addresses, ETH value and hash for each transaction. Get execution traces for outgoing transactions — request the trace fields you need with `setFields()` as described in the [traces section of Field selection](./field-selection#traces).

```ts theme={"system"}
import {run} from '@subsquid/batch-processor'
import {DataSourceBuilder} from '@subsquid/evm-stream'
import {createLogger} from '@subsquid/logger'
import {TypeormDatabase} from '@subsquid/typeorm-store'

const VITALIK_ETH = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'.toLowerCase()

const dataSource = new DataSourceBuilder()
  .setPortal('https://portal.sqd.dev/datasets/ethereum-mainnet')
  .addTransaction({
    where: {to: [VITALIK_ETH]}
  })
  .addTransaction({
    where: {from: [VITALIK_ETH]},
    include: {traces: true}
  })
  .setFields({
    transaction: {
      from: true,
      to: true,
      value: true,
      hash: true
    }
  })
  .build()

const log = createLogger('sqd:processor:vitalik-txs')

run(dataSource, new TypeormDatabase({supportHotBlocks: true}), async (ctx) => {
  for (let block of ctx.blocks) {
    for (let txn of block.transactions) {
      if (txn.to === VITALIK_ETH || txn.from === VITALIK_ETH) {
        // just output the tx data to console
        log.info(txn, 'Tx:')
      }
    }
  }
})
```