Transaction Rate Limits and Optimizations

In this guide, you’ll learn about the transaction rate limits imposed by supported blockchains and Circle Wallets. You’ll also get client-side optimization tips to ensure smooth transaction processing within your applications.

EVM-compatible blockchains typically use a Mempool system. The Mempool queues transactions sent from a wallet up to a certain limit defined by the full node. If you exceed this limit, you receive an error from the full node. All queued transactions in the Mempool can potentially be included in a single block. Therefore, you can estimate the theoretical transaction throughput as queueLimit / blockTime. However, various factors can influence whether your transaction gets included in a block, such as priority fees, network congestion, and network liveness. In contrast, the Solana blockchain does not use a Mempool system and, thus, does not have a queue limit. This contributes to its transaction throughput being significantly higher.

The overall transaction throughput is fundamentally constrained by the blockchain account queue limit and the blockchain's inherent throughput. To mitigate the impact of these limitations, Circle Wallets provide a queuing mechanism for transactions that exceed the blockchain limit for a certain duration. There is a limit on the number of transactions your wallet can queue in the Circle Wallets service to prevent resource wastage and false expectations. This limit affects the user experience when too many transaction requests are made. When you reach this limit, you receive an error message:

More detailed error descriptions and suggestions can be found in the Transaction error codes section.

To check the number of pending transactions and their status, use the list transactions API. The transaction state should be one of the following: INITIATED, CLEARED, QUEUED, SENT, STUCK.

While transaction queuing provides a convenient feature, fee fluctuations and network congestion can still impact transaction processing times. Below are some tips to ensure a smooth experience, especially when dealing with a high volume of transaction requests.

Consider setting the fee_level parameter to at least MEDIUM or HIGH. This ensures that your transactions are processed with higher priority in a reasonable timeframe, reducing delays for subsequent transactions.

This section describes how to monitor and manage transactions that are pending but still processing normally (for example, in the QUEUED or SENT states). If a transaction remains unconfirmed for an extended period and enters the STUCK state, see Handling Stuck Transactions.

You can monitor and manage pending transactions in several ways.

1. Monitor Transaction Status: Use the get transaction API if you know the transaction ID, or the list transactions API to query multiple transactions or filter by state.
2. Cancellation or Acceleration: Use the cancel transaction API or accelerate transaction API to manage transactions that have been pending for an extended period.
3. Transaction Notifications: Implement webhook events to confirm the completion of transactions before sending more requests.

In rare cases, a transaction might remain unconfirmed onchain for an extended period because its network fee is too low to meet the current blockchain requirements. When this happens, the transaction enters the STUCK state.

A STUCK transaction is one that has been sent to the blockchain but could not be included in a block because the network fee is below the level required for inclusion. This state specifically refers to transactions that are underpriced relative to current network conditions, such as when gas prices rise during high congestion, or when the provided feeLevel or the custom priorityFee and maxFee values are too low.

To resolve a stuck transaction:

1. Accelerate it: Use the accelerate transaction API to resubmit the transaction with a higher fee. The acceleration API automatically applies a HIGH fee level.
2. Cancel it: If you prefer not to accelerate the transaction, use the cancel transaction API to cancel it before it's mined. Note that this action also incurs gas fees.

After taking one of these actions, monitor the transaction status using webhook notifications (recommended) or the list transactions API to confirm that the state has updated.

If a transaction remains in the STUCK state, you must either accelerate or cancel it. Leaving it unresolved may block subsequent transactions from the same wallet.

The STUCK state is not a terminal failure but a signal that manual or programmatic intervention is required to ensure confirmation.

Using multiple sender wallets can help bypass the per-wallet queue limit and increase the level of parallel processing. This strategy is generally effective across various blockchains.

Leveraging smart contracts for batch transactions can significantly reduce the number of transactions needed for repetitive tasks. For instance, instead of sending 1,000,000 transfer transactions individually, you can deploy an airdrop contract that processes transfers to 500 wallets in a single execution call, requiring only 2,000 transactions in total. Although a single contract execution call may incur higher gas costs than a simple transfer, it is often more gas and time-efficient for batch transactions.

For more details, please refer to our Airdrop template for Circle Contracts .

By understanding the transaction queue limits and exploiting the above optimization tips, you can improve the transaction throughput of your applications, thereby increasing their overall efficiency when interacting with blockchain networks.