Skip to main content

Incoming Payment Monitor

Notify when an address receives a payment, and act on it.

MCP tools

  • get_transaction_history

API endpoints

  • POST /v4/subscription
  • GET /v4/subscription
  • DELETE /v4/subscription/{id}

Steps

  1. Subscribe to incoming transactions for the target address via the Notifications API.
  2. Configure the public webhook URL and signing secret.
  3. On delivery, verify the HMAC signature, dedupe, and process.
  4. Maintain subscription lifecycle (rotate secrets, delete on user opt-out).

Agent trace

The call sequence an MCP-capable agent logs when it runs this workflow.

  1. Create a webhook subscription (one-time) 
    POST https://api.tatum.io/v4/subscription
x-api-key: $TATUM_API_KEY
{ "type": "ADDRESS_EVENT",
  "attr": { "chain": "ethereum-mainnet",
            "address": "0xab58…c9b",
            "url": "https://app.example/webhook" } }
  2. Receive event → verify amount + asset 
    // inbound POST from Tatum
{ "subscriptionType": "ADDRESS_EVENT",
  "address": "0xab58…c9b",
  "txId": "0x…",
  "asset": "USDC",
  "amount": "250.00" }
  3. Resolve human-readable info, ack 
    // agent fetches tx detail to confirm finality
mcp.tatumio.get_transaction_history({
  chain: "ethereum-mainnet",
  address: "0xab58…c9b",
  pageSize: 1
})

Possible failures

  • Webhook endpoint unreachable
  • HMAC signature mismatch
  • Duplicate webhook delivery

Recovery guidance

  • Tatum retries failed deliveries; ensure 2xx within the retry budget
  • Reject unsigned/wrong-signature payloads and alert
  • Deduplicate by event id; treat handlers as idempotent