Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and stablecoin payments, embed digital wallets into your product or service, or power your internet marketplace.

Confirmations

"Reorgs" and Associated Risks

Transactions in a blockchain are packaged into blocks. Different blockchains have different rules for how to decide which transactions get packaged into a block, but they often include rules for invalidating recently generated blocks.

This rewrite of history is called a "reorganization" ("reorg" for short) and invalidates any transactions included in the invalidated blocks, thus returning any transferred funds to their original owners.

Such events can represent a security risk, because an attacker could use a cryptocurrency transfer as payment for a good or service, and subsequently trigger a reorg, thus invalidating his transfer (and getting his cryptocurrency back) while keeping the good or service he paid for. Cryptocurrency exchanges have lost hundreds of millions of dollars in such attacks (often referred to as "51% attacks" after a particular methodology).

Confirmations

To protect yourself against reorg attacks, you can wait for a number of blocks before recognizing a transfer. As more blocks are processed after a given block, the difficulty with which that block may be invalidated increases. Therefore, by choosing how many blocks to wait before recognizing a transfer, a receiver is able to balance speed (waiting very few blocks in order to process the transfer quickly while taking on risk of losing money due to a reorg) and security (waiting more blocks to minimize the risk of a reorg at the cost of slower transfer processing).

The number of blocks you wait before considering a transfer valid is called the "confirmation number", which is typically different for different chains. The Circle Wallets API uses sensible confirmation numbers for each supported chain.

📘

In the case of incoming USDC transfers on Ethereum, the Circle Wallets API waits for 30 confirmations (or blocks) before deeming such transfer "completed". This corresponds to about 6 minutes. We consider this to be a very safe number.

Confirmations and Transfer Status

As soon as an incoming USDC transfer is included in a block, the Wallets API will make it available for you (whether you poll the get transfers endpoint or subscribe to notifications). However, the transfer will have a running status and it will not credit the balance of the associated hosted wallet with the transfer amount until 30 confirmations are reached.

At that point the transfer status will change to completed. If you have subscribed to notifications, you will receive a message indicating such status change.

You might want to deem an incoming USDC transfer completed before such status change, and fulfill your business process that depends on that transfer. But note that you will be doing so at your own risk, as you might never actually receive the transfer credit in case there is a reorg before 30 confirmations.

It is also technically possible for you to wait longer than 30 confirmations to deem an incoming USDC transfer completed, but the Wallets API will not provide you with additional notifications after 30 confirmations and so you'll need to build your own tracking system. We believe this is not necessary given the safety of 30 confirmations.

In the future we may consider allowing you to configure the number of confirmations yourself.

🚧

Please note that waiting for confirmations before crediting a wallet only applies for on-chain transfers, where the source is of type blockchain. Transfers between hosted wallets, where the source is of type wallet do not require waiting on confirmations and are credited instantly.

Updated 3 months ago



Confirmations


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.