eth_newFilter

Creates a filter object, based on filter options, to notify when the state changes (logs) on the Zora network. This method is essential for tracking smart contract events and state changes.

Parameters

• filter (object, required): The filter object with the following properties:
  • fromBlock (string, optional): Block number (hex) or tag ("earliest", "latest", "pending", "safe", "finalized") to start filtering from. Default: "latest"
  • toBlock (string, optional): Block number (hex) or tag to stop filtering at. Default: "latest"
  • address (string or array, optional): Contract address or array of addresses to monitor for logs
  • topics (array, optional): Array of 32-byte DATA topics. Topics are order-dependent:
    • First topic is typically the event signature hash
    • Use null to match any value at a specific position
    • Can provide arrays for "OR" conditions at each position

Returns

• filterID (string): A hexadecimal filter identifier to be used with:
  • eth_getFilterChanges - Get new logs since last poll
  • eth_getFilterLogs - Get all accumulated logs
  • eth_uninstallFilter - Remove the filter when no longer needed

Implementation Example

cURL

curl -X POST https://api-zora-mainnet.n.dwellir.com/2307f636-d01d-4f85-ba5e-514ff37069f5 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_newFilter",
    "params": [{
      "fromBlock": "0x1",
      "toBlock": "0x2",
      "address": "0x8888f1f195afa192cfee860698584c030f4c9db1",
      "topics": [
        "0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"
      ]
    }],
    "id": 1
  }'

JavaScript

const response = await fetch('https://api-zora-mainnet.n.dwellir.com/2307f636-d01d-4f85-ba5e-514ff37069f5', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_newFilter',
    params: [{
      fromBlock: '0x1',
      toBlock: '0x2',
      address: '0x8888f1f195afa192cfee860698584c030f4c9db1',
      topics: [
        '0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b'
      ]
    }],
    id: 1
  })
});

const data = await response.json();
const filterID = data.result;
console.log('Filter ID:', filterID);

Python

import requests
import json

url = 'https://api-zora-mainnet.n.dwellir.com/2307f636-d01d-4f85-ba5e-514ff37069f5'
headers = {'Content-Type': 'application/json'}
payload = {
    "jsonrpc": "2.0",
    "method": "eth_newFilter",
    "params": [{
        "fromBlock": "0x1",
        "toBlock": "0x2",
        "address": "0x8888f1f195afa192cfee860698584c030f4c9db1",
        "topics": [
            "0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"
        ]
    }],
    "id": 1
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
filter_id = data['result']
print(f'Filter ID: {filter_id}')

Response Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x990a0ab959f87cc519ae825a7e6e7a46"
}

Advanced Usage

Monitor Multiple Contracts

{
  "params": [{
    "fromBlock": "latest",
    "address": [
      "0x1234567890abcdef1234567890abcdef12345678",
      "0xabcdef1234567890abcdef1234567890abcdef12"
    ]
  }]
}

Complex Topic Filtering

{
  "params": [{
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",  // Transfer event
      null,  // Any sender
      [      // Specific recipients
        "0x0000000000000000000000001234567890abcdef1234567890abcdef12345678",
        "0x000000000000000000000000abcdef1234567890abcdef1234567890abcdef12"
      ]
    ]
  }]
}

Monitor All Events from Latest Block

{
  "params": [{
    "fromBlock": "latest",
    "toBlock": "latest"
  }]
}

Workflow Example

// 1. Create filter
const createFilter = await fetch(url, {
  method: 'POST',
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_newFilter',
    params: [{ fromBlock: 'latest' }],
    id: 1
  })
});
const { result: filterID } = await createFilter.json();

// 2. Poll for changes
const getChanges = await fetch(url, {
  method: 'POST',
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_getFilterChanges',
    params: [filterID],
    id: 2
  })
});
const { result: logs } = await getChanges.json();

// 3. Clean up
const uninstall = await fetch(url, {
  method: 'POST',
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_uninstallFilter',
    params: [filterID],
    id: 3
  })
});

Notes

• Block Range Limits: Free plans typically limited to 5 blocks, paid plans up to 10,000 blocks
• Filter Timeout: Filters expire after ~5 minutes of inactivity - poll regularly with eth_getFilterChanges
• Topics Order: Topics are order-dependent; the first topic is usually the event signature hash
• Filter Management: Always uninstall filters when done to free up resources
• Performance: Create specific filters to reduce the amount of data processed

---

Need help? Contact our support team or check the Zora documentation.