Filter Syntax

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

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

Websocket Streams

Use filters with websocket streams

Stream Transformations

Use filters with stream transformations

Use Cases

Allium App

Allium Datashares

Allium Datastreams

Allium Beam

Filter Structure

Field Paths

Comparison Operators

Equals (`=`)

Not Equals (`!=`)

Greater Than (`>`)

Greater Than or Equal (`>=`)

Less Than (`<`)

Less Than or Equal (`<=`)

Special Operators

Exists

In

Compound Filters

AND Logic

OR Logic

Nested AND/OR

Complete Examples

Example 1: DeFi Swap Monitoring

Example 2: NFT Transfer Tracking

Example 3: Multi-Chain Whale Watching

Example 4: Failed Transaction Analysis

Best Practices

Websocket Streams

Stream Transformations

​Filter Structure

​Field Paths

​Comparison Operators

​Equals (=)

​Not Equals (!=)

​Greater Than (>)

​Greater Than or Equal (>=)

​Less Than (<)

​Less Than or Equal (<=)

​Special Operators

​Exists

​In

​Compound Filters

​AND Logic

​OR Logic

​Nested AND/OR

​Complete Examples

​Example 1: DeFi Swap Monitoring

​Example 2: NFT Transfer Tracking

​Example 3: Multi-Chain Whale Watching

​Example 4: Failed Transaction Analysis

​Best Practices

​Related Documentation

Websocket Streams

Stream Transformations

Filter Structure

Field Paths

Comparison Operators

Equals (`=`)

Not Equals (`!=`)

Greater Than (`>`)

Greater Than or Equal (`>=`)

Less Than (`<`)

Less Than or Equal (`<=`)

Special Operators

Exists

In

Compound Filters

AND Logic

OR Logic

Nested AND/OR

Complete Examples

Example 1: DeFi Swap Monitoring

Example 2: NFT Transfer Tracking

Example 3: Multi-Chain Whale Watching

Example 4: Failed Transaction Analysis

Best Practices

Related Documentation