Filters

You can specify filters when subscribing to pendingTx and newTx streams to only receive certain transactions.‌ The filter string uses a SQL-like syntax for logical operations.

This filter dictionary is passed into the options argument of the subscribe() call:

ws.subscribe("newTxs", {"filters": "...", ...})

Available Filters

value : Restrict transactions based on their value, denominated in wei. Hex values are also valid.

from : Deprecated. Restrict transactions sender to the specified Ethereum addresses. Requires --tx-include-sender-in-feed argument. See local gateway Startup Arguments.

to: Restrict transactions recepient to the specified Ethereum addresses.

gas_price, max_fee_per_gas , max_priority_fee_per_gas and max_fee_per_blob_gas: Restrict transactions based on their gas price attributes, denominated in wei. Hex values are also valid.

method_id: Restrict transactions based on their method ID in the TX input.

chain_id: Restrict transactions based on their chain ID.

The SQL-like syntax also supports and and or : logical operations.

Examples

Value

Filter transactions between 1-4 ETH

# "filters" Example
"({value} > 1000000000000000000) AND ({value} < 4000000000000000000)"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "({value} > 1000000000000000000) AND ({value} < 4000000000000000000)"}]}

Address

Filter transactions with specific to account

# "filters" Example
"{to} == '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "{to} == '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'"}]}

Filter transactions from two accounts

# "filters" Example
"({from} IN ['0x6671799F031059e017bBc9E9FCbE6721cc2Bd798',
 '0x09eDBC6ed492C6D4274810E257A690a11d71ce43'])"
# wscat Subscribe Example 
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "({from} IN ['0x6671799F031059e017bBc9E9FCbE6721cc2Bd798', '0x09eDBC6ed492C6D4274810E257A690a11d71ce43'])"}]}
 

Gas Price

Filter transactions with specific gas price

# "filters" Example
"({gas_price} > 183000000000)"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "({gas_price} > 183000000000)"}]}

Method ID

Filter transactions with specific method ID

# "filters" Example
"{method_id} == '0xa9059cbb'"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "{method_id} == '0xa9059cbb'"}]}

‌Furthermore, logical operations and and or may also be used to combine multiple filters. The above examples can be used together as shown in the examples below:

Address and Value

# "filters" Example
"{TO} == '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' AND
 ({value} > 4000000000000000000 AND {value} < 5000000000000000000) 
 OR ({from} IN ['0x8fdc5df186c58cdc2c22948beee12b1ae1406c6f',
  '0x77e2b72689fc954c16b37fbcf1b0b1d395a0e288'])"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "{TO} == '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' AND({value} > 4000000000000000000 AND {value} < 5000000000000000000) OR ({from} IN ['0x8fdc5df186c58cdc2c22948beee12b1ae1406c6f','0x77e2b72689fc954c16b37fbcf1b0b1d395a0e288'])"}]}

Method ID , Address and Gas Price

# "filters" Example
"{method_id} == '0xa9059cbb' AND
({from} IN ['0x8fdc5df186c58cdc2c22948beee12b1ae1406c6f',
        '0x77e2b72689fc954c16b37fbcf1b0b1d395a0e288']) AND
({gas_price} < 30000000000000000000)"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "{method_id} == '0xa9059cbb' AND({from} IN ['0x8fdc5df186c58cdc2c22948beee12b1ae1406c6f', '0x77e2b72689fc954c16b37fbcf1b0b1d395a0e288']) AND ({gas_price} < 30000000000000000000)"}]}