Links

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 and to: restrict transactions to the specified Ethereum addresses.
gas_price: restrict transactions based on their gas price, denominated in wei. Hex values are also valid.
method_id: restrict transactions based on their method ID in the TX input.
The SQL-like syntax also supports and and or : logical operations.

Examples

Value
Address
Gas Price
Method ID
Filter transactions between 1-4 ETH
Go Gateway/Cloud-API (Enterprise) Example:
# "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)"}]}
Python Gateway/Cloud-API (Non Enterprise) Example:
# "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
Go Gateway/Cloud-API (Enterprise) Example:
# "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'])"}]}
Python Gateway/Cloud-API (Non Enterprise) Example:
# "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
Go Gateway/Cloud-API (Enterprise) Example:
# "filters" Example
"({gas_price} > 183000000000)"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "({gas_price} > 183000000000)"}]}
Python Gateway/Cloud-API (Non Enterprise) Example:
# "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
Go Gateway/Cloud-API (Enterprise) Example:
# "filters" Example
"{method_id} == '0xa9059cbb'"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "{method_id} == '0xa9059cbb'"}]}
Python Gateway/Cloud-API (Non Enterprise) Example:
# "filters" Example
"method_id = a9059cbb"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "method_id = a9059cbb"}]}
‌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
Method ID , Address and Gas Price
GO Gateway/Cloud-API (Enterprise) Example:
# "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'])"}]}
Python Gateway/Cloud-API (Non Enterprise) Example:
# "filters" Example
"to = 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 and
((value > 1000000000000000000 and value < 4000000000000000000)
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 > 1000000000000000000 and value < 4000000000000000000) or from in [0x8fdc5df186c58cdc2c22948beee12b1ae1406c6f, 0x77e2b72689fc954c16b37fbcf1b0b1d395a0e288])"}]}
GO Gateway/Cloud-API Example:
# "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)"}]}
Python Gateway/Cloud-API (Non Enterprise) Example:
# "filters" Example
"method_id = a9059cbb and
from in [0x8fdc5df186c58cdc2c22948beee12b1ae1406c6f,
0x77e2b72689fc954c16b37fbcf1b0b1d395a0e288] and
gas_price > 100000000000"
# wscat Subscribe Example
{"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["newTxs", {"include": ["tx_hash"], "filters": "method_id = a9059cbb and from in [0x8fdc5df186c58cdc2c22948beee12b1ae1406c6f,0x77e2b72689fc954c16b37fbcf1b0b1d395a0e288] and gas_price > 100000000000"}]}