Address Monitoring API: How It Works and How to Build It
What a crypto address monitoring API does, how webhooks deliver deposit and withdrawal events, and how to handle confirmations, retries and security.
Reviewed by Maurice Sobiera

An address monitoring API is a service that watches blockchain addresses and notifies your application when something happens on them: a deposit arrives, funds leave, a token moves or a transaction confirms. You register an address and a callback URL. The service then sends a webhook with the transaction details, so you don’t poll nodes or decode logs yourself.
“Address monitoring” means two different jobs. The first is operational: knowing when money reaches or leaves an address your app controls, so you can credit a customer or release an order. The second is compliance: analyzing the behavior of addresses over time to spot risky activity. This article covers the first job, which most product teams need, and shows where the second begins.
TL;DR
- An address monitoring API tracks chosen blockchain addresses and pushes events to your server by webhook, so you don’t run nodes or poll.
- Events should arrive decoded: sender, recipient, token, amount and status, not raw hex logs.
- Verify the signature of every webhook, deduplicate by transaction ID, and credit funds only after the confirmation level you have chosen.
- Chaingateway webhooks are not retried automatically. Reconcile against the API to catch events you missed.
- Operational monitoring (payments) differs from compliance monitoring (risk patterns over time). Many teams need both, from different tools.
- Chaingateway offers wallets, transfers, decoded transaction data and signed webhooks for Ethereum, Bitcoin, Tron, Polygon, BNB Smart Chain and Arbitrum. Solana is supported, but it has no webhooks.
Table of Contents
- What an address monitoring API actually does
- Why not just run your own nodes and poll?
- How webhook-based address monitoring works
- Which networks and address types should it support?
- Confirmations, delays and reorgs: when is a payment real?
- Handling retries and duplicate notifications
- Security, authentication and rate limits
- What to look for when choosing an address monitoring API
- Should you build monitoring yourself or use an API?
- Try it on your own addresses
- A minimal implementation checklist
- FAQ
- Sources
What an address monitoring API actually does
A blockchain is a public ledger, but it does not call you when something happens. Nothing in the protocol will push a message to your backend because address 0xABC... received 250 USDT. Someone has to read new blocks, filter them for the addresses you care about, decode the result into something meaningful, and notify you. An address monitoring API is that someone, offered as a service.
In practice the API does five things:
- Registers addresses. You add the addresses to watch, usually ones you generated for customers, invoices or internal wallets.
- Reads the chain. The provider runs nodes or indexers for each network and scans every new block.
- Matches activity. It finds native-coin transfers and token transfers that touch your watched addresses.
- Decodes the data. Raw transactions and event logs are turned into readable fields: direction, token symbol, amount with correct decimals, fee, block, status.
- Delivers events. It sends them to your endpoint, typically as an HTTPS POST webhook, and lets you query the same data on demand.
What it detects depends on the chain. On Bitcoin, it is outputs paid to an address. On Ethereum and other EVM networks, it is native transfers plus token events such as ERC-20 Transfer logs. On Tron, it covers TRX and TRC-20 tokens. Our TRC20 address API page shows how generating and monitoring addresses fits together on that network.
Operational monitoring versus compliance monitoring
The phrase also appears in the compliance world, and the two should not be confused. Compliance-focused providers describe transaction monitoring as ongoing analysis of blockchain activity over time, looking for patterns such as structuring, layering, unusual velocity, mixer use, sanctions evasion and dormant-wallet activity. Risk shows up in behavior across many transactions, and humans investigate the alerts.
An operational monitoring API answers a simpler question: “Did the payment I’m waiting for arrive, and is it final?” If you run a regulated business, you will likely need both layers. The operational layer feeds your ledger and customer experience. The compliance layer feeds your risk team. When an alert needs a deeper look, such as tracing funds across several hops, that work belongs to specialists, not to a payments webhook.

Why not just run your own nodes and poll?
It is a fair question, and for a few teams the answer is to do exactly that. Here is what you take on when you do.
- Node operations. Each chain needs its own node or a hosted endpoint, with upgrades, storage growth and uptime to manage. Each additional network means another setup.
- Chain-specific logic. Bitcoin’s UTXO model, Ethereum’s logs, Tron’s resource model and Solana’s account model each need their own parsing code.
- Decoding. Token amounts come as integers that need the right decimals. Contract events need ABIs. Internal transfers and batched transactions are easy to miss.
- Reorg handling. Recent blocks can be replaced. Your scanner must notice and correct itself.
- Delivery. Once you detect an event, you still need a queue, retries and a signature scheme to deliver it safely to your own services.
A monitoring API collapses most of that into one integration. The tradeoff is dependence on a provider, so judge it on reliability, data quality and how cleanly it hands you events. For a wider look at the alternatives, see our comparison of six types of blockchain APIs and when to use each.
How webhook-based address monitoring works
The typical flow has four steps, and it is the same whether you build it or buy it.
1. Create or register the address
For payments, the cleanest pattern is one address per customer, invoice or order. When a payment lands on a unique address, you know who paid without asking for a memo or reference. With Chaingateway you can create wallets through the API and use the resulting addresses directly. If customers supply their own addresses for withdrawals, validate them first. Our free crypto address validator covers Tron, Ethereum and BSC formats and is a handy reference while you build your own checks.
2. Subscribe to events
You tell the API which addresses and event types matter and where to send them: your HTTPS endpoint. Subscriptions can be as narrow as one address and one token, or as broad as every address in your account. Details on this model are on the blockchain webhooks and event notifications page.
3. Receive a decoded payload
A useful payload tells you, without further lookups, the sender, the recipient, the asset, the amount, the block and the transaction hash. A Chaingateway webhook for a TRC-20 transfer looks like this (webhook guide):
{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM", "blocknumber": "65542464", "datetime": "2024-09-25 14:48:27", "tokenid": null, "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}The id identifies the notification and txid identifies the transaction. This is the difference between decoded data and raw chain data: with raw data you write the parser, with decoded data you read a field. The payload has no confirmation counter, so your own code decides when a transaction counts as final.
4. Acknowledge, verify and act
Your server verifies the signature, stores the event, returns a 2xx response quickly, and processes the business logic asynchronously. Everything after that, such as crediting an account or shipping an order, depends on the rules you set for confirmations.

Which networks and address types should it support?
Before you commit, list what your product will touch in the next year, not only today. A checkout that starts with USDT on one network often gets asked for another within months.
Check for coverage of:
- Native coins and tokens. Bitcoin, ETH, TRX, SOL, MATIC-network and BNB-chain assets, plus token standards such as ERC-20, BEP-20 and TRC-20.
- NFTs. If you issue or accept collectibles or tickets, you need ERC-721-style transfer events too.
- Address formats. Bitcoin has several formats; EVM chains share one format across networks, which can cause mistakes when a customer sends on the wrong network. Your app should state the expected network next to every deposit address.
- Outgoing activity. Many tools only catch deposits. If you send payouts, you want the same decoded view of outgoing transactions and their status.
Chaingateway covers Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain and Arbitrum behind a single blockchain API, including the major token standards and NFT transfers. Webhooks exist for every chain except Solana. A Solana integration has to poll balances or transactions of its addresses.
Confirmations, delays and reorgs: when is a payment real?
The first notification is not the last word. A transaction can be seen in the mempool, included in a block, and later reach a level of finality that you consider safe. Chains differ widely here: block times, confirmation conventions and finality models are not the same on Bitcoin, Ethereum, Tron or Solana, so your thresholds should be set per network and per amount.
| Network | What the documentation says | Source |
|---|---|---|
| Bitcoin | Competing blocks can appear at the same height, and nodes drop stale blocks of the shorter fork. There is no fixed finality point, so you choose a confirmation depth. | Bitcoin developer guide |
| Ethereum | A block takes about 15 minutes to finalize. | ethereum.org |
| Tron | A block becomes irreversible after confirmation by the super representatives, about 19 blocks. | TRON developer hub |
A practical policy looks like this:
| Stage | What it means | What your app should do |
|---|---|---|
| Detected | The transaction is seen but not yet in a block | Show “payment pending”; do not release goods |
| Included | It is in a block, with few confirmations | Credit a pending balance for small amounts if your risk allows |
| Confirmed | It has reached your chosen confirmation depth | Credit the account, release the order |
| Failed or dropped | It was replaced, reverted or never mined | Reverse the pending state and tell the customer |
Two rules keep you out of trouble. First, scale the confirmation requirement with the value at risk: a small subscription payment can tolerate a lower threshold than a large withdrawal. Second, make the state machine explicit in your database. “Pending”, “confirmed” and “failed” should be stored states, not inferred ones.
Also expect events to arrive late or out of order. A confirmation notice can reach you before a slow handler finishes processing the detection notice. Use the transaction hash and status as the source of truth, not arrival order.
Handling retries and duplicate notifications
Chaingateway does not retry webhooks automatically. If your server times out or returns an error, the notification is recorded as failed. You list failed notifications per chain, for example GET /api/v2/tron/webhooks/notifications/failed, and re-send them with POST /api/v2/tron/webhooks/notifications/{id}/retry. Until you do, your system does not know about that event.
Duplicates can still happen, for example when you re-send a notification that your server had already processed. Design for both cases from day one. Other providers may retry on their own, so the same handler design works across providers.
- Make handlers idempotent. Store a unique key per event, such as the transaction hash plus the log index or the delivery ID, with a unique database constraint. If the key exists, return success and do nothing.
- Respond fast. Write the raw event to a queue or table, return a 2xx status, then process. Slow handlers cause timeouts, and every timeout becomes a failed notification.
- Reconcile. Webhooks can be missed during your own downtime. Run a periodic job that lists failed notifications and recent notifications (
GET /api/v2/<chain>/webhooks/notifications) and compares them with your records. This turns a lost event from an incident into a delayed fix. - Log everything. Keep the raw payload, signature header and your processing result. When a customer says they paid, you will want the evidence in a minute, not an hour.
- Alert on silence. If an address that normally gets traffic produces no events for an unusual period, check the pipeline.
Security, authentication and rate limits
An endpoint that credits money on request is a target. Treat it like one.
Verify every webhook
Anyone who finds your URL can post a fake “payment received” message, so require a signature. Once you set a personal secret in your profile, Chaingateway adds an X-Signature header to every webhook. The header is a Base64-encoded HMAC-SHA256 of the transaction ID, keyed with your personal secret. Your server recomputes it and rejects anything that does not match (signature guide). Compare the values with a constant-time function, such as hmac.compare_digest in Python. HMAC itself is defined in RFC 2104.
Protect your API keys
Keep keys in a secrets manager or environment variables, never in client-side code or repositories. Use separate keys per environment and rotate them on a schedule and after any staff change. We collected more habits like these in our six security tips for using a blockchain API.
Harden the endpoint
- Serve it over HTTPS only.
- Use a hard-to-guess path, and where your provider publishes source IP ranges, allow only those.
- Reject oversized bodies and unexpected content types.
- Never trust amounts or addresses in a webhook that you have not matched against your own records: the address must be one you issued, and the amount must make sense for the order.
Plan for rate limits
When you query for reconciliation or batch address lookups, you will meet request limits on any provider. Cache what does not change, batch where the API allows, back off exponentially on throttling responses, and spread scheduled jobs rather than firing them at the top of the hour. Know your plan’s limits before launch, not during your first traffic spike.
What to look for when choosing an address monitoring API
Use this checklist when comparing providers or deciding whether to build.
| Criterion | Why it matters | Question to ask |
|---|---|---|
| Chain coverage | Avoids a second integration when you expand | Are all the networks and token standards I need in one API? |
| Decoded data | Cuts parser code and bugs | Do events include token, amount, direction and status? |
| Delivery guarantees | Determines your idempotency and reconciliation work | Are failed deliveries retried automatically or on request, and is there a notification ID? |
| Signatures | Prevents spoofed payments | Is every webhook signed, and how do I verify it? |
| Fee and gas help | Outgoing transfers fail without the right fee | Does the API estimate gas and fees automatically? |
| Wallet tooling | Saves stitching together services | Can I create wallets and send transfers from the same API? |
| Pricing model | Predictability at scale | Is pricing tied to usage tiers I can forecast? |
It also helps to ask a blunt question: do you need a monitoring-only product, or the full loop of create wallet, receive, send and reconcile? Many payment projects start with only monitoring and end up wanting the rest. Our overview of use cases of a blockchain API shows how the pieces tend to combine, and the e-commerce article walks through a checkout example.
Should you build monitoring yourself or use an API?
Scanning the chain yourself works in a first version. Problems appear later: a reorg credits a payment that then disappears, a token with unusual decimals shows the wrong amount, a node falls behind during a busy hour, and support is chasing a customer who says they paid.
With Chaingateway you create a wallet, create a webhook for its address, and receive decoded, signed events. The request shapes are the same across Ethereum, Bitcoin, Tron, Polygon, BNB Smart Chain and Arbitrum, so adding a network is a configuration change. You do not run a node.
Three habits matter more than the provider you pick: decide your confirmation policy early, write idempotent handlers before your first live payment, and reconcile on a schedule. A monitoring API should make them easy, not replace the need for them.
Try it on your own addresses
If you are building payments, deposits or wallet features, you can see how monitoring fits into a full integration with Chaingateway. Webhooks, wallet creation, token and NFT transfers and decoded transaction data come from one REST API. Plans are tiered by usage and features: Plus is €49 per month (or €490 per year), Pro is €99 per month (€990 per year), Premium is €249 per month (€2,490 per year) and Enterprise is €499 per month (€4,990 per year). You start with a free trial, and the pricing page has the current plan details. To see how events reach your app, read about Chaingateway Webhooks.
A minimal implementation checklist
Before your first live payment, run through this list.
- Generate one address per invoice or customer, and show the expected network beside it.
- Subscribe those addresses to incoming and outgoing events.
- Expose an HTTPS endpoint that verifies the
X-Signatureheader. - Store each event with a unique key and ignore repeats.
- Move payments through stored states: pending, confirmed, failed.
- Set confirmation thresholds per network and per amount.
- Schedule a reconciliation job against the API’s transaction history.
- Alert on failed deliveries, long silences and signature failures.
- Test with small real amounts on every network and token you support, including a wrong-network deposit, so you know your support answer in advance.
Sources
- What is crypto transaction monitoring? | Elliptic
- RFC 2104: HMAC, keyed hashing for message authentication
- Chaingateway OpenAPI definition
Recommended
Frequently asked questions
It is a service that watches blockchain addresses and reports activity on them to your application, usually through webhooks and a query endpoint. You get decoded events such as an incoming token transfer or a confirmed withdrawal without running nodes yourself.
No. Operational address monitoring tells your app that a payment arrived or left. Compliance transaction monitoring looks at behavior over time to flag risky patterns, and people investigate the alerts. Regulated businesses often use both.
It depends on the network and the value at risk, so there is no single number. Set a threshold per chain, raise it for larger amounts, and store pending and confirmed as separate states in your database.
Give every event a unique key, such as the transaction hash with the log index or a delivery ID, and enforce it with a unique constraint. If your handler sees a key it already stored, it returns success and does nothing else.
Yes, if the API is multi-chain. Chaingateway covers Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain and Arbitrum through one REST API. Webhooks cover all of them except Solana.
Ready to build this yourself? Get your API key — 7-day trial, no card required — or see the Blockchain API for the full endpoint reference.