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
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)"}]}
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'])"}]}
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)"}]}
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:
# "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'])"}]}
# "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)"}]}