eth_newFilter

Creates a filter object, based on filter options, to notify when the state changes (logs) on the Gravity Alpha 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-gravity-alpha-mainnet.n.dwellir.com/YOUR_API_KEY \
  -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-gravity-alpha-mainnet.n.dwellir.com/YOUR_API_KEY', {
  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-gravity-alpha-mainnet.n.dwellir.com/YOUR_API_KEY'
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 Gravity Alpha documentation.