Skip to main content
Filters allow you to receive only messages that match specific criteria. This reduces bandwidth and allows you to focus on relevant data.

​
Filter Structure

Filters are JSON objects with the following structure: 
{
  "field": "status",
  "operator": "=",
  "value": "active"
}

​
Field Paths

Use dot notation to access nested fields in your data: 
{
  "field": "user.profile.age",
  "operator": ">=",
  "value": 18
}
Examples of field paths:
  • status - Top-level field
  • user.email - Nested field
  • transaction.from_address - Blockchain transaction field
  • payload.metadata.timestamp - Deeply nested field

​
Comparison Operators

​
Equals (=)

Match exact values. 
{
  "field": "blockchain",
  "operator": "=",
  "value": "ethereum"
}
Use cases:
  • Filter by specific blockchain
  • Match exact addresses
  • Filter by transaction type
Example: Only Ethereum transactions 
{
  "field": "blockchain",
  "operator": "=",
  "value": "ethereum"
}

​
Not Equals (!=)

Exclude specific values. 
{
  "field": "status",
  "operator": "!=",
  "value": "pending"
}
Use cases:
  • Exclude failed transactions
  • Filter out specific addresses
  • Remove test data
Example: Exclude zero-value transfers 
{
  "field": "value",
  "operator": "!=",
  "value": "0"
}

​
Greater Than (>)

Match values greater than the specified value. 
{
  "field": "block_number",
  "operator": ">",
  "value": 18000000
}
Use cases:
  • Filter by block number ranges
  • Minimum transaction values
  • Time-based filtering
Example: Large transactions only (> 1 ETH in wei) 
{
  "field": "value",
  "operator": ">",
  "value": "1000000000000000000"
}

​
Greater Than or Equal (>=)

Match values greater than or equal to the specified value. 
{
  "field": "gas_price",
  "operator": ">=",
  "value": 30
}
Use cases:
  • Minimum thresholds
  • Starting from a specific block
  • Value ranges (inclusive)
Example: Transactions from block 18M onwards 
{
  "field": "block_number",
  "operator": ">=",
  "value": 18000000
}

​
Less Than (<)

Match values less than the specified value. 
{
  "field": "gas_used",
  "operator": "<",
  "value": 21000
}
Use cases:
  • Maximum thresholds
  • Filter small transactions
  • Gas optimization analysis
Example: Low gas transactions 
{
  "field": "gas_used",
  "operator": "<",
  "value": 50000
}

​
Less Than or Equal (<=)

Match values less than or equal to the specified value. 
{
  "field": "confirmations",
  "operator": "<=",
  "value": 6
}
Use cases:
  • Maximum thresholds (inclusive)
  • Confirmation tracking
  • Value caps
Example: Recent blocks (last 100) 
{
  "field": "block_number",
  "operator": "<=",
  "value": 18000100
}

​
Special Operators

​
Exists

Check if a field exists or doesn’t exist in the data. Check if field exists: 
{
  "field": "to_address",
  "operator": "exists",
  "value": true
}
Check if field doesn’t exist: 
{
  "field": "error",
  "operator": "exists",
  "value": false
}
Use cases:
  • Filter contract creations (no to_address)
  • Exclude failed transactions (no error field)
  • Find records with optional fields
Example: Only contract deployments 
{
  "field": "to_address",
  "operator": "exists",
  "value": false
}
Example: Only successful transactions 
{
  "field": "error",
  "operator": "exists",
  "value": false
}

​
In

Check if a value matches any value in an array or data source. Using an array of values: 
{
  "field": "blockchain",
  "operator": "in",
  "value": ["ethereum", "polygon", "arbitrum"]
}
Using a data source (not supported in websockets): 
{
  "field": "contract_address",
  "operator": "in",
  "data_source_id": "whitelisted_addresses"
}
The data_source_id parameter is not currently supported for websocket streams. Use the value array instead.
Use cases:
  • Filter multiple blockchains
  • Whitelist addresses
  • Match multiple statuses
  • Check against large lists (with data sources)
Example: EVM L2 chains only 
{
  "field": "blockchain",
  "operator": "in",
  "value": ["arbitrum", "optimism", "base", "polygon"]
}
Example: Specific DEX contracts 
{
  "field": "contract_address",
  "operator": "in",
  "value": [
    "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
    "0xd9e1ce17f2641f24ae83637ab66a2cca9c378b9f",
    "0x1111111254fb6c44bac0bed2854e76f90643097d"
  ]
}

​
Compound Filters

Combine multiple conditions with AND/OR logic.

​
AND Logic

All conditions must be true. 
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "=",
      "value": "ethereum"
    },
    {
      "field": "value",
      "operator": ">",
      "value": "1000000000000000000"
    }
  ]
}
Example: Large Ethereum transactions to specific address 
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "=",
      "value": "ethereum"
    },
    {
      "field": "to_address",
      "operator": "=",
      "value": "0x..."
    },
    {
      "field": "value",
      "operator": ">=",
      "value": "1000000000000000000"
    }
  ]
}

​
OR Logic

At least one condition must be true. 
{
  "op": "OR",
  "conditions": [
    {
      "field": "type",
      "operator": "=",
      "value": "swap"
    },
    {
      "field": "type",
      "operator": "=",
      "value": "transfer"
    }
  ]
}
Example: Multiple transaction types 
{
  "op": "OR",
  "conditions": [
    {
      "field": "method",
      "operator": "=",
      "value": "transfer"
    },
    {
      "field": "method",
      "operator": "=",
      "value": "transferFrom"
    },
    {
      "field": "method",
      "operator": "=",
      "value": "mint"
    }
  ]
}

​
Nested AND/OR

Combine AND and OR logic for complex queries. 
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "in",
      "value": ["ethereum", "polygon"]
    },
    {
      "op": "OR",
      "conditions": [
        {
          "field": "value",
          "operator": ">",
          "value": "1000000000000000000"
        },
        {
          "field": "gas_price",
          "operator": ">=",
          "value": 100
        }
      ]
    }
  ]
}
Example: High-value OR high-gas transactions on specific chains 
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "in",
      "value": ["ethereum", "base", "arbitrum"]
    },
    {
      "field": "to_address",
      "operator": "exists",
      "value": true
    },
    {
      "op": "OR",
      "conditions": [
        {
          "field": "value",
          "operator": ">",
          "value": "5000000000000000000"
        },
        {
          "field": "gas_price",
          "operator": ">=",
          "value": 50
        }
      ]
    }
  ]
}

​
Complete Examples

​
Example 1: DeFi Swap Monitoring

Monitor large swaps on Uniswap V3: 
{
  "op": "AND",
  "conditions": [
    {
      "field": "contract_address",
      "operator": "=",
      "value": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45"
    },
    {
      "field": "value",
      "operator": ">",
      "value": "10000000000000000000"
    },
    {
      "field": "status",
      "operator": "=",
      "value": "success"
    }
  ]
}

​
Example 2: NFT Transfer Tracking

Track NFT transfers for specific collections: 
{
  "op": "AND",
  "conditions": [
    {
      "field": "token_standard",
      "operator": "in",
      "value": ["ERC721", "ERC1155"]
    },
    {
      "field": "contract_address",
      "operator": "in",
      "value": [
        "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "0x60e4d786628fea6478f785a6d7e704777c86a7c6"
      ]
    },
    {
      "field": "from_address",
      "operator": "!=",
      "value": "0x0000000000000000000000000000000000000000"
    }
  ]
}

​
Example 3: Multi-Chain Whale Watching

Monitor large transactions across multiple chains: 
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "in",
      "value": ["ethereum", "bsc", "polygon", "arbitrum", "optimism"]
    },
    {
      "op": "OR",
      "conditions": [
        {
          "field": "value_usd",
          "operator": ">=",
          "value": 1000000
        },
        {
          "op": "AND",
          "conditions": [
            {
              "field": "token_type",
              "operator": "=",
              "value": "ERC20"
            },
            {
              "field": "amount_usd",
              "operator": ">=",
              "value": 500000
            }
          ]
        }
      ]
    }
  ]
}

​
Example 4: Failed Transaction Analysis

Find failed transactions with high gas: 
{
  "op": "AND",
  "conditions": [
    {
      "op": "OR",
      "conditions": [
        {
          "field": "status",
          "operator": "=",
          "value": "failed"
        },
        {
          "field": "error",
          "operator": "exists",
          "value": true
        }
      ]
    },
    {
      "field": "gas_used",
      "operator": ">",
      "value": 100000
    },
    {
      "field": "gas_price",
      "operator": ">=",
      "value": 30
    }
  ]
}

​
Best Practices

  1. Be specific: Use the most restrictive filters possible to reduce data transfer
  2. Use IN for multiple values: More efficient than multiple OR conditions for the same field
  3. Combine with EXISTS: Check field existence before comparing values
  4. Test incrementally: Start with simple filters and add complexity gradually
  5. Monitor performance: Complex nested filters may impact latency

Websocket Streams

Use filters with websocket streams

Stream Transformations

Use filters with stream transformations