Skip to main content
For API request rate limits (GET/POST calls per second on Wallets endpoints), see Wallets API rate limits.

Per-wallet queue limits

EVM blockchains use a mempool that queues pending transactions per sender address, up to a limit set by full nodes. Theoretical throughput is queueLimit / blockTime, though priority fees, congestion, and network liveness affect actual inclusion. Solana doesn’t use a mempool and has no per-account queue limit, which is one reason its throughput is significantly higher.

Circle Wallets queue

To smooth over short bursts that exceed the blockchain limit, Circle Wallets queues additional transactions for a bounded duration. The service caps how many transactions a single wallet can hold in this queue. When you hit the cap, the API returns error code 155264:
Wait for pending transactions to be included on the blockchain before submitting new requests. EVM chains restrict the number of queued transactions per sender address.

Monitor pending transactions

Use webhooks or the transactions API to track state changes on pending transactions.

Increase throughput

Three strategies scale throughput past the per-wallet ceiling:
  • Raise the fee level: setting feeLevel: MEDIUM or HIGH prioritizes inclusion, which shortens confirmation time and reduces backpressure on subsequent transactions from the same wallet. See Gas fees for how fee levels work.
  • Shard across multiple sender wallets: splitting sends across multiple wallets bypasses the per-wallet queue limit and increases parallelism. Works on every supported blockchain.
  • Batch with smart contracts: for repetitive workloads, batch operations in a single contract call instead of sending individual transactions. For example, an airdrop contract that processes 500 transfers per call reduces 1,000,000 individual transfers to 2,000 batched calls. A batched call costs more gas per call than a single transfer, but the total gas and time saved make batching more efficient at scale. See the Airdrop template for Circle Contracts for a working example.

Resolve stuck transactions

A STUCK transaction has been sent to the blockchain but can’t be included in a block because the network fee is below the current floor. This usually happens when gas prices spike during congestion, or when the feeLevel (or custom priorityFee/maxFee) is set too low. Resolve a stuck transaction two ways:
  • Accelerate: call the accelerate transaction API to resubmit at the HIGH fee level. The wallet’s native balance must cover maxFee × gasLimit for all of its pending transactions, not just the final fee of the one you’re accelerating. On chains that charge an L1 data fee, the balance must cover that fee as well. If it doesn’t, the API returns error 155201 with the message insufficient native token balance in the wallet to cover all pending transactions. Top up the wallet’s native balance and retry.
  • Cancel: call the cancel transaction API before the transaction is mined. Cancellation is itself an onchain transaction that must outbid the original, so the wallet needs enough native token to beat the stuck transaction’s fee. You must cancel before resending, otherwise the resend queues behind the stuck nonce until the original is canceled or confirmed.
Monitor the new state using webhook notifications (recommended) or by polling the list transactions API.
If a transaction stays STUCK and you take no action, it can block subsequent transactions from the same wallet. STUCK is a signal for intervention, not a terminal failure. For the full state reference, see Transaction states and errors.