# trace_filter - Tempo RPC Method

Returns traces matching a filter on Tempo.

This method requires an archive node. It is not available on full nodes.

## When to Use This Method

- **Search for traces matching address criteria** - Find all internal transactions involving a specific address on Tempo
- **Find all interactions with a contract** - Track every call, delegate call, and create operation targeting a contract for merchant settlement, treasury operations, payout automation, and stablecoin-native financial applications
- **Audit contract usage patterns** - Analyze how contracts are used over time across block ranges
- **Forensic analysis** - Investigate transaction patterns and address-level activity across the chain

## Best Practices

- Very resource-intensive on large block ranges; narrow the range as much as possible
- Use specific fromAddress or toAddress filters to reduce response size
- Limit block range to small chunks and paginate results
- Many provider-managed endpoints disable this method due to computational cost

## Request Parameters

- `filterObject` (`Object, required`): Filter criteria (see below)
- `fromBlock` (`QUANTITY|TAG, required`): Start block (hex or tag)
- `toBlock` (`QUANTITY|TAG, required`): End block (hex or tag)
- `fromAddress` (`Array<DATA>, required`): Filter by sender addresses
- `toAddress` (`Array<DATA>, required`): Filter by receiver addresses
- `after` (`QUANTITY, required`): Offset for pagination
- `count` (`QUANTITY, required`): Max results to return

## Request Example

```json
{
  "jsonrpc": "2.0",
  "method": "trace_filter",
  "params": [{
    "fromBlock": "latest",
    "toBlock": "latest",
    "toAddress": ["0x0bd34b0a5be345c9bf7a147eb698e993511180cb"],
    "count": 10
  }],
  "id": 1
}
```

## Response Fields

This method returns no documented fields.

## Successful Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

## Code Examples

cURL
JavaScript
Python

```bash
curl -X POST https://api-tempo-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "trace_filter",
    "params": [{
      "fromBlock": "latest",
      "toBlock": "latest",
      "toAddress": ["0x0bd34b0a5be345c9bf7a147eb698e993511180cb"],
      "count": 10
    }],
    "id": 1
  }'
```

```javascript
import { JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://api-tempo-mainnet.n.dwellir.com/YOUR_API_KEY');

const traces = await provider.send('trace_filter', [{
  fromBlock: 'latest',
  toBlock: 'latest',
  toAddress: ['0x0bd34b0a5be345c9bf7a147eb698e993511180cb'],
  count: 10
}]);
console.log('Matching traces:', traces.length);
for (const trace of traces) {
  console.log(`  Block ${trace.blockNumber}: ${trace.action.from} -> ${trace.action.to}`);
}
```

```python
from web3 import Web3

w3 = Web3(Web3.HTTPProvider('https://api-tempo-mainnet.n.dwellir.com/YOUR_API_KEY'))

traces = w3.provider.make_request('trace_filter', [{
    'fromBlock': 'latest',
    'toBlock': 'latest',
    'toAddress': ['0x0bd34b0a5be345c9bf7a147eb698e993511180cb'],
    'count': 10
}])
for trace in traces['result']:
    action = trace['action']
    print(f'Block {trace["blockNumber"]}: {action["from"]} -> {action.get("to", "CREATE")}')
```

## Related Methods

- [`trace_block`](https://www.dwellir.com/docs/tempo/trace_block) - Get all traces in a block
- [`trace_transaction`](https://www.dwellir.com/docs/tempo/trace_transaction) - Get traces for a specific transaction
- [`eth_getLogs`](https://www.dwellir.com/docs/tempo/eth_getLogs) - Filter event logs