Notifications: Filtering

Conditions let you control which notifications reach your webhook. Instead of receiving every event on a monitored address, you define rules only events that satisfy all rules trigger a webhook delivery.

📘

Conditions are available on v4 subscriptions only. Use the v4 REST API endpoint.

Quick Start

Add a conditions array inside the attr object when creating a subscription via POST /v4/subscription:

{
  "type": "ADDRESS_EVENT",
  "attr": {
    "chain": "ethereum-mainnet",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "url": "https://your-app.com/webhook",
    "conditions": [
      {
        "field": "value",
        "operator": ">",
        "value": "1000000000000000000"
      }
    ]
  }
}

This subscription fires only when a transfer exceeds 1 ETH (1000000000000000000 wei).

Condition Structure

Each condition is an object with three properties:

When multiple conditions are provided, all must match (AND logic). If any condition fails, the notification is not sent.

Available Fields

Available Operators

⚠️

Important: The value field uses the raw amount in the chain's smallest unit.

• 1 ETH = "1000000000000000000" (18 decimals)
• 1 USDT = "1000000" (6 decimals)
• 1 SOL = "1000000000" (9 decimals)

Always pass the value as a string, not a number.

Supported Subscription Types

Conditions work with all v4 address-based subscription types:

Examples

Filter by transfer amount

Only notify when a transfer exceeds 1 ETH:

{
  "type": "ADDRESS_EVENT",
  "attr": {
    "chain": "ethereum-mainnet",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "url": "https://your-app.com/webhook",
    "conditions": [
      {
        "field": "value",
        "operator": ">",
        "value": "1000000000000000000"
      }
    ]
  }
}

Filter by token contract

Only notify for incoming USDT transfers:

{
  "type": "INCOMING_FUNGIBLE_TX",
  "attr": {
    "chain": "ethereum-mainnet",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "url": "https://your-app.com/webhook",
    "conditions": [
      {
        "field": "contractAddress",
        "operator": "==",
        "value": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
      }
    ]
  }
}

Filter by token type

Only notify for NFT transfers on a watched address:

{
  "type": "ADDRESS_EVENT",
  "attr": {
    "chain": "ethereum-mainnet",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "url": "https://your-app.com/webhook",
    "conditions": [
      {
        "field": "tokenMetadata.type",
        "operator": "==",
        "value": "nft"
      }
    ]
  }
}

Filter by sender

Only notify when a specific wallet sends to your address:

{
  "type": "INCOMING_NATIVE_TX",
  "attr": {
    "chain": "ethereum-mainnet",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "url": "https://your-app.com/webhook",
    "conditions": [
      {
        "field": "from",
        "operator": "==",
        "value": "0x8ba1f109551bD432803012645Ac136Ddd64DBA72"
      }
    ]
  }
}

Combine multiple conditions (AND logic)

Only notify for incoming USDT transfers above 1,000 USDT:

{
  "type": "INCOMING_FUNGIBLE_TX",
  "attr": {
    "chain": "ethereum-mainnet",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "url": "https://your-app.com/webhook",
    "conditions": [
      {
        "field": "contractAddress",
        "operator": "==",
        "value": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
      },
      {
        "field": "value",
        "operator": ">=",
        "value": "1000000000"
      }
    ]
  }
}

📘

Both conditions must match. If the transfer is USDT but below 1,000 USDT, no notification is sent.

Updating Conditions

Update conditions on an existing subscription using PUT /v4/subscription/{id}:

{
  "conditions": [
    {
      "field": "value",
      "operator": ">=",
      "value": "5000000000000000000"
    }
  ]
}

⚠️

Passing a new conditions array replaces all existing conditions. To remove all conditions, pass an empty array [].

Best Practices

• Use the most specific subscription type. Instead of ADDRESS_EVENT with a tokenMetadata.type == "fungible" condition, prefer INCOMING_FUNGIBLE_TX it's more efficient.
• Combine conditions to reduce noise. Filter by both contract address and minimum amount to receive only high-value transfers for a specific token.
• Use raw units carefully. Always verify the token's decimal count before setting amount thresholds. A mistake in decimals can result in missed notifications or excessive alerts.
• Use different webhook URLs to monitor the same address with different filter configurations.