🔔 Deposit Tracking / Transaction Alerts

Once your users start depositing stablecoins, you need to know immediately when funds arrive — without constantly polling the blockchain.
Tatum makes this possible using subscriptions and webhook-based transaction alerts. These APIs notify your backend the moment a deposit, withdrawal, or on-chain event occurs.

📘

Create Subscription (Popular 🔔)

• POST /v4/subscription — Subscribe to blockchain events such as incoming transactions, outgoing transfers, or account balance changes.
• GET /v4/subscription — List your active subscriptions.
• DELETE /v4/subscription/{id} — Unsubscribe when no longer needed.

Explore Docs →

Key Use Cases

• Deposit Tracking: Detect incoming stablecoin deposits to user addresses automatically.
• Withdrawal Confirmation: Get notified when your users’ stablecoin transfers are mined or confirmed.
• Wallet Monitoring: Watch specific addresses or smart contracts for USDT/USDC events.
• Webhook Automation: Trigger balance updates or payment confirmations via webhooks.
• Security Auditing: Log every event for compliance and fraud monitoring.

Sample Request – Subscribe to Incoming Transactions (cURL)

curl --request POST \
     --url https://api.tatum.io/v4/subscription \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "type": "ADDRESS_EVENT",
  "attr": {
    "chain": "arb-one-mainnet",
    "address": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ",
    "url": "YOUR_WEBHOOK_URL"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    type: 'ADDRESS_EVENT',
    attr: {
      chain: 'arb-one-mainnet',
      address: 'FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ',
      url: 'YOUR_WEBHOOK_URL'
    }
  })
};

fetch('https://api.tatum.io/v4/subscription', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Sample Response

{  
  "id": "YOUR_SUBSCRIPTION_ID",  
}  

Webhook Payload Example

When an on-chain event occurs, Tatum sends a webhook POST request to your provided URL.

{  
  "id": "YOUR_SUBSCRIPTION_ID",  
  "subscriptionType": "ADDRESS_TRANSACTION",  
  "chain": "ETH",  
  "txId": "0x7b1d92b870acfded67f2e6b9f0b38dcb0cfaa7b1e5153dcb7dba86d13b5b5e1e",  
  "address": "0x2474a7227877f2b65185f09468af7c6577fa207c",  
  "amount": "50.0",  
  "tokenSymbol": "USDC",  
  "blockNumber": 20948719,  
  "type": "incoming",  
  "timestamp": 1734182014  
}  

Handling Webhooks Securely

1. Validate Signatures:
   Always verify webhook authenticity using request headers or a secret token.

2. Idempotent Processing:
   Ensure your backend handles duplicate webhook events gracefully (e.g., via transaction hash deduplication).

3. Acknowledge Quickly:
   Respond to the webhook with a 200 OK as soon as possible, then process asynchronously.

4. Retry Logic:
   Tatum retries webhook delivery if your endpoint is temporarily unavailable.

Example: Deposit Confirmation Flow

[User Wallet] → [Blockchain Tx Detected] → [Tatum Subscription Webhook] → [Your Backend] → [Database Update / Notify User]  

1. User Deposits Stablecoin

User sends USDC/USDT to their deposit address generated earlier.

2. Transaction Detected

Tatum watches the blockchain for incoming transactions to that address.

3. Webhook Triggered

Your webhook endpoint receives transaction details.

4. Backend Processes Deposit

Mark the user’s account as credited once the transaction is confirmed.

FAQs

Best Practices

• ⚙️ Use unique addresses per user (from the Address Management guide).
• 🧩 Combine subscription alerts with wallet portfolio APIs to verify balances.
• 🔐 Secure your webhook endpoints using HMAC signatures or IP allowlists.
• 📦 Store incoming webhook payloads for reconciliation and auditing.
• ⏱ Process deposits asynchronously to ensure performance and reliability.

By implementing deposit tracking with webhooks, your platform gains real-time visibility into all stablecoin activity — powering seamless, automated payment experiences.