Create a subscription (V4)

/v4/subscription

50 credits per sent Notification + 50 credits per day per subscription

Create and manage blockchain event notification subscriptions. This endpoint allows you to receive real-time webhook alerts for address activity, token transfers, and native currency transactions across supported blockchains.

Tip: Notifications are formatted using Templates. We recommend using the enriched template because it provides clean, human-readable enhanced data with token metadata. Learn more: 👉 https://docs.tatum.io/reference/createnotificationtemplate

Supported Notification Types:

• ADDRESS_EVENT – Triggered for any address-level transaction or event.
• INCOMING_FUNGIBLE_TX / OUTGOING_FUNGIBLE_TX – Detects ERC20 or equivalent token transfers.
• INCOMING_NATIVE_TX / OUTGOING_NATIVE_TX – Detects native currency transfers (ETH, MATIC, etc.).

For a full explanation of subscription types, see the Subscriptions Overview: 👉 https://docs.tatum.io/reference/notification-subscriptions

Webhook Response Format

Recommended Default: templateId = "enriched"

If you do not specify a custom template, the response will use the legacy format. However, the enriched template is recommended because it provides structured, human-readable fields and token metadata.

To learn about legacy format, custom templates, or enriched_with_raw_data, visit: 👉 https://docs.tatum.io/reference/createnotificationtemplate

Example: Enriched Template Webhook Payload

  {
    "data": {
      "kind": "transfer",
      "blockHash": "0x1234567890abcdef...",
      "blockNumber": 18500000,
      "blockTimestamp": 1699123456,
      "txId": "0xabcdef1234567890...",
      "currency": "ETH",
      "txTimestamp": 1699123456,
      "from": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
      "to": "0x8ba1f109551bD432803012645Hac136c",
      "value": "1000000000000000000",
  "contractAddress": "0xA0b86a33E6441b8c4C8C0C8C0C8C0C8C0C8C0C8C0C",
  "tokenId": "12345",

  "additionalData": {
    "gasUsed": "21000",
    "gasPrice": "20000000000"
  },

  "tokenMetadata": {
    "type": "nft",
    "decimals": 0,
    "symbol": "NFT",
    "name": "My NFT",
    "uri": "https://api.example.com/metadata/12345"
  },

  "subscriptionId": "64f1a2b3c4d5e6f7g8h9i0j1",
  "subscriptionType": "ADDRESS_EVENT"
},
"location": "...",
"scheme": "..."
}