Creates a subscription that pushes a notification to your callback URL whenever a subscribed wallet transacts. The typical use case is wallet activity alerts, like the push notifications in the Zerion app.

Your callback host has to be whitelisted before it will receive anything. webhook.site URLs work out of the box for testing. To use your own host, request whitelisting from the Dashboard or email api@zerion.io with the address and the callback URL. A dev key is limited to one subscription of at most 5 wallets, valid for one week. Production keys have no wallet or time limit.

Only transactions mined after the subscription is created are reported, prices in the payload are always null, and delivery is best-effort. The Webhooks guide covers the payload format, signature verification, retry behavior and delivery guarantees.

Event filtering. Attach filters to narrow what a subscription delivers. Only exclusion is supported: a matching event is dropped and no webhook is sent for it.

{
  "callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
  "addresses": ["0x42b9df65b219b3dd36ff330a4dd8f327a6ada990"],
  "chain_ids": ["ethereum"],
  "filters": {
    "exclude": {
      "types": ["send"],
      "is_spam": true,
      "protocol_ids": ["uniswap-v3"],
      "addresses": ["0x0000000000000000000000000000000000000001"]
    }
  }
}

Conditions are independent and combined with OR, so the example above drops a send, or spam, or anything attributed to uniswap-v3, or anything involving that address. Adding a condition can only reduce what you receive. is_spam accepts only true; empty lists, duplicates, unknown transaction types and unknown field names are rejected. Omitting filters, or sending null, leaves the subscription unfiltered, and responses omit the field when none are set.

Failed transactions. Failed transactions sent from a subscribed wallet have always been reported. Webhooks are now also delivered when a transaction addressed to a subscribed smart-contract wallet fails onchain, with "status": "failed". The payload carries one execute act with the wallet as contract_address, and empty transfers and approvals arrays. An ERC-4337 UserOperation that fails inside a successful bundle transaction is not reported. This applies to EVM chains only; Solana subscriptions are unaffected.

See also: Webhooks guide · Resource IDs

{
  "callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
  "addresses": [
    "0x42b9df65b219b3dd36ff330a4dd8f327a6ada990"
  ],
  "chain_ids": [
    "polygon"
  ],
  "filters": {
    "exclude": {
      "types": [
        "send"
      ],
      "is_spam": true,
      "protocol_ids": [
        "uniswap-v3"
      ],
      "addresses": [
        "0x0000000000000000000000000000000000000001"
      ]
    }
  }
}

{
  "data": {
    "type": "transactions_subscription",
    "id": "52d994a173d755e99845e861d534a419",
    "attributes": {
      "callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
      "created_at": "2022-08-15T11:26:31+00:00",
      "updated_at": "2022-08-15T11:26:31+00:00",
      "filters": {
        "exclude": {
          "types": [
            "send"
          ],
          "is_spam": true,
          "protocol_ids": [
            "uniswap-v3"
          ],
          "addresses": [
            "0x0000000000000000000000000000000000000001"
          ]
        }
      }
    },
    "relationships": {
      "chains": [
        {
          "links": {
            "related": "https://api.zerion.io/v1/chains/polygon"
          },
          "data": {
            "type": "chains",
            "id": "polygon"
          }
        }
      ]
    }
  }
}