Skip to content
New guideAgent Cookbook 12 copy-ready prompts for AI coding agents.See recipes
All blog posts
Reserve Ethereum nonces without gaps or collisions

Reserve Ethereum nonces without gaps or collisions

By Elias Faltin13 min read

Two workers send withdrawals from the same Ethereum account. Both read 42 as the next transaction number, then sign different payments with that number. Ethereum can include only one of those payments at number 42. The other withdrawal stays unpaid.

That sequence number is the account's nonce. eth_getTransactionCount reads it from a block's state or a node's transaction pool, where transactions wait for inclusion. The method does not reserve a number for your worker.

Use one shared allocator to reserve nonces before signing. This guide shows how to compare node counts with saved reservations, detect missing transactions, and replace them without allocating another nonce.

Read latest and pending as different questions

The execution API specification defines the result as the account nonce in the state after the requested block. The block parameter is optional and defaults to latest. The specification also notes that, since EIP-7702, the nonce no longer equals the number of transactions the account sent.

TagWhat the count describesUse it for
latestNonces consumed up to the node's current head blockDeciding which saved nonces are already used
pendingThe client's candidate account nonce, using its local pool and the rules belowA hint for the next nonce on that node
safe, finalizedNonces consumed at an older block with stronger settlement guaranteesSettlement and audit, not allocation

Send the tag on every call so the request states which count you need. Set DWELLIR_API_KEY to your API key, then request pending:

Bash
curl --max-time 15 --silent --show-error \
  "https://api-ethereum-mainnet.n.dwellir.com/${DWELLIR_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_getTransactionCount","params":["0x7d0ebbe6f5308b9ef4e6108247cf793bab98ffcd","pending"]}'

Repeat with latest for the chain count. The response's result is a hexadecimal quantity. For example, "0x6" means 6.

safe and finalized select blocks with stronger settlement guarantees than the latest head. Their counts can lag latest, so do not use them to allocate new nonces.

Pending means one pool's view

Clients compute pending from their own pool, and they do not agree on gaps. The table describes the linked source revisions.

Clientpending resultSource
GethNext nonce after the executable pool sequence. Queued transactions behind a gap do not countapi.go, txpool.go, legacypool.go
RethHighest consecutive pool nonce plus 1, never below the chain noncestate.rs
NethermindWalks pooled nonces upward from the chain nonce and stops at the first gapEthRpcModule.cs, TxPool.cs
ErigonHighest nonce in the pool for the sender plus 1, with no gap checketh_accounts.go, senders.go

On Geth, Reth and Nethermind, pending stops at the missing nonce. On Erigon, the same pool contents can return a value above the gap. Code that treats pending as "next free nonce" can then sign above the missing nonce. Every later transaction then waits behind it.

Endpoints also see different pools. A hosted URL can route requests to several backends. A web3_clientVersion response identifies what the endpoint reports, not necessarily the client behind every request.

Dwellir exposes both api-ethereum-mainnet.n.dwellir.com and api-ethereum-mainnet-erigon.n.dwellir.com. Both serve latest and pending reads. Their reported identities are Reth and Erigon, respectively. Keep hosted endpoints in the allocator's unknown mode unless you have implementation and routing evidence for every backend.

A missing nonce blocks later transactions

A gap forms when a node lacks a lower nonce while higher transactions remain queued. The node cannot execute those later transactions until the missing nonce is used.

Dwellir's default Ethereum endpoint supports txpool_contentFrom, which separates a sender's pending and queued transactions. Use it to inspect a gap without downloading the whole pool:

Bash
curl --max-time 15 --silent --show-error \
  "https://api-ethereum-mainnet.n.dwellir.com/${DWELLIR_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"txpool_contentFrom","params":["0x7d0ebbe6f5308b9ef4e6108247cf793bab98ffcd"]}'

For this sender, both counts are 6 while the pool contains 16 queued transactions, with nonces from 7 to 70. Nonce 6 is missing. Equal latest and pending values therefore do not prove that the sender has no queued transactions.

Dwellir Ethereum mainnet responses, 13 November 2026, sender 0x7d0ebbe6…, head 26,405,002. Calls are separate reads. Counts change as blocks and pools change.

The diagram uses consecutive-pool behavior, as in the cited Geth, Reth and Nethermind revisions.

Nonce 6 returns to the pool, allowing queued nonces 7 and 8 to become executable in order.

This fixture uses a consecutive-pool client such as Geth, Reth or Nethermind. The chain nonce, latest, stays at 6 in both rows. In the first row, nonce 6 is missing and nonces 7 and 8 are queued, so pending is 6. In the second row, nonce 6 returns to the pool and all three transactions can execute in nonce order, so pending becomes 9. No transaction has to be mined for this pool count to change.

Repair a gap from your own records. Find the lowest nonce at or above latest that the node does not count. Rebroadcast its saved signed bytes, or replace it at the same nonce. The next queued transaction can execute once all lower nonces are used. The monitoring guide covers alert thresholds for this state.

Replace at the same nonce, with both fees raised

A replacement uses the same sender and nonce with new signed bytes. Pools enforce a minimum increase before they accept it.

PoolOrdinary transactionsBlob transactionsSource
GethFee cap and tip must increase and meet the 10% bump's integer thresholds100%list.go, legacypool.go, blobpool
RethFee cap at least 10% higher. Tip 10% higher when both tips are nonzero100%config.rs
Erigon10%100%txpoolcfg.go

These are defaults. Operators can change them, and each node in a load-balanced pool applies its own setting.

The following formula applies to ordinary EIP-1559 transactions. Blob transactions use the separate thresholds in the table.

Geth rejects a replacement that raises only maxFeePerGas. The tip must rise too. Compute each new value as max(old + 1, (old * 110 + 99) / 100) in integer wei. The ceiling division keeps rounding from leaving you one wei short. The old + 1 covers a zero tip. Meeting the threshold clears the fee-bump check. The node still checks transaction validity and balance. It does not evict the original from other pools, so the original can still be mined.

Keep every hash you sign for a nonce. The by-hash guide shows how to find which one was included. Never sign a replacement with a nonce below latest. That nonce is already used in that node's current chain state, and the node rejects the transaction as nonce too low.

When the count is enough

SituationThe count is enough?What else you need
One signer, one transaction at a time, wait for the receipt before the nextYes, latestReceipt polling
Several workers share a keyNoOne allocator per key that allocates nonces from durable records
Allocator restartPartlyCompare latest and pending with saved records before allocating a nonce
A higher nonce is stuck behind a missing oneNoSaved records, or txpool_contentFrom where the endpoint supports it
Private submissionNoSaved hashes and submission-service status information, where available. Public pools may never see the transaction

Dwellir's default Ethereum endpoint also serves txpool_status, txpool_inspect and eth_pendingTransactions. Use txpool_contentFrom for a sender. Pool-wide totals and transaction lists do not establish which nonce your allocator can reserve.

Dwellir's Erigon endpoint does not expose these methods. It returns JSON-RPC error -32601 for them. Use saved reservations and receipt polling there. For pool inspection, use Dwellir's default endpoint, remembering that its pool can differ from the Erigon endpoint's pool.

Treat a missing txpool method as normal. Your records are the source of truth for what you signed. latest describes chain state. pending adds one endpoint's view of the transaction pool.

Where the count fits in the transaction lifecycle

  1. Reserve a nonce from your allocator. Store the allocator's baseline after the custody handover. Check every reservation against both counts. The next section describes both steps.
  2. Sign, save the signed bytes and hash, then submit with the submission guide.
  3. Track the hash with the by-hash lookup and the receipt polling loop.
  4. When a hash goes missing, compare latest with the saved nonce. A count above it means the nonce is used. It does not tell you which hash used it.
  5. Close a record only after a receipt for one of its saved hashes reaches your settlement target.

Reconcile an allocator before it allocates a nonce

Get the complete allocator example and offline tests. It runs with Node.js 22 or later. readNonces reads both counts and checks each JSON-RPC reply. reconcile compares the counts with saved reservations for one sender. Neither function signs or sends a transaction.

The allocator must store consecutive reservations under one lock, starting at its saved baseline. Keep every reservation, including consumed ones, and store nonces as BigInt values. Keep separate records for each sender and chain. Check the endpoint's eth_chainId against the intended chain before you read these counts.

For hosted endpoints without backend evidence, leave poolSemantics as unknown. Use one outstanding reservation per sender, with a durable settledNext checkpoint. This checkpoint is the next nonce after your settled records. It is separate from the endpoint's counts.

  1. Take exclusive custody of the key, including EIP-7702 authorization signing. For a new, unused key, initialize the baseline and settledNext to 0. For an existing key, stop every previous signer and inventory all signed transactions and authorizations. Set both values to the finalized account nonce only after all earlier signed activity settles. If that inventory is incomplete, use a new key. Do not sign new authorizations while this allocator controls the key.
  2. Reserve one nonce under the allocator lock, persist it, then sign and save its bytes and hash before submission. Do not reserve another nonce while that record remains unresolved.
  3. Poll every saved hash for the lowest reservation at or above settledNext. Require a receipt whose block hash matches the canonical block at that height. Require that block to be at or below the finalized head. A reverted transaction still consumes its nonce. Advance settledNext through consecutive settled records only. A null receipt never clears a reservation. Rebroadcast saved bytes or replace at the same nonce, then wait again.
  4. Resume only when no reservation remains open and latest, pending, and settledNext agree. If lowestUnresolved is null, check the receipt checkpoint and count agreement instead of looking for a missing reservation. Keep waiting when receipts have not finalized. Investigate unexplained counts or missing records. Never copy latest into the checkpoint to bypass a stop.

This is a fallback for workloads that can wait. Each sender can start only one new transaction per finalization cycle, so it cannot pipeline withdrawals. On Ethereum mainnet, finalized trails the head by about 64 to 95 blocks, or roughly 13 to 19 minutes. That allows about three to five new transactions per hour for each sender, before inclusion and polling delays. In exchange, the path does not depend on pool gap rules. Equal counts alone never establish an empty pool. Exclusive custody and complete records establish what you signed.

For pipelining, verified-consecutive requires an audited implementation and routing evidence. One supported implementation is Geth at revision 931dacf5f9c58cdf2dc859625fffc2da999d89ee, linked above. Check the provenance of the deployed binary against that revision. Keep the backend inventory and proxy configuration that prove every route, including failover, uses that audited implementation. Revalidate after deployment or routing changes. A public probe or web3_clientVersion string cannot prove every backend's behavior.

These reads are not an atomic snapshot. Retry inconsistent replies and investigate count decreases before allocating. If a reorganization removes an included transaction, reopen its record and check its receipt again.

With unknown pool behavior, this guard stops allocation until the receipt checkpoint and both counts agree:

JavaScript
  const settled = open.length === 0 && latest === pending && latest === settledNext;
  if (poolSemantics !== 'verified-consecutive' && !settled) {
    return {
      action: 'stop',
      reason: 'need settled receipt checkpoint or verified consecutive pool',
      lowestUnresolved: open.length ? open[0].nonce : null,
    };
  }

Call reconcile under the same lock that allocates nonces. Load the saved checkpoint from the procedure above. Leave it null until custody and settlement evidence establish it. Allocate only when the action is ok, then persist the reservation before releasing the lock.

The example's read-nonces.mjs checks Ethereum mainnet's chain ID before reading the counts. It takes the Dwellir key and sender from environment variables:

JavaScript
  const url = `https://api-ethereum-mainnet.n.dwellir.com/${process.env.DWELLIR_API_KEY}`;
  await requireEthereumMainnet(url);
  const view = await readNonces(url, process.env.SENDER);
  console.log(view);

For example, an existing key has completed the custody handover at finalized nonce 42. Its saved baseline and checkpoint are both 42. This fixture allocates its first reservation without assuming pool behavior:

JavaScript
const result = reconcile([], { latest: 42n, pending: 42n }, 42n, 'unknown', 42n);
console.log(result);
// { action: 'ok', lowestUnresolved: null, notCounted: [], usedNeedReceipt: [], next: 42n }

After reserving 42, further calls stop until its receipt finalizes and the checkpoint becomes 43. With that record retained and both counts at 43, reconciliation returns ok with next 43. Calls with fully consumed records but no receipt checkpoint still return stop.

With latest and pending both 6, synthetic records for nonces 5 to 8 demonstrate the repair path. Under verified-consecutive semantics, reconciliation returns repair, notCounted 6, 7 and 8, usedNeedReceipt 5, and next 9. Records ending at nonce 2 return stop. This fixture tests the algorithm. It does not establish the routing evidence needed to select verified-consecutive for Dwellir.

An Erigon fixture holds either nonces 6, 7 and 8, or only 7 and 8. Both pools return latest 6 and pending 9. Even with settledNext 6, unknown or highest-nonce behavior makes both cases return stop. Both identify 6 as the lowest unresolved reservation. Counts alone cannot distinguish them.

next comes from your records and latest, never from pending alone. A count above your records stops the allocator. Investigate another signer, an EIP-7702 authorization, missing records, or an inconsistent backend view. repair means this node does not count some nonces you signed. Rebroadcast the lowest first, or check another endpoint before replacing it.

Put the allocator into service

Keep one allocator per key and chain ID, with nonces stored before signing. Read both counts from the endpoint you submit to, and send the tag every time. Treat a pending disagreement between endpoints as routing evidence, not as a reason to reset the allocator.

Connect your allocator to Dwellir's Ethereum endpoint for both nonce reads and receipt polling. Use the eth_getTransactionCount reference for the request format. Keep poolSemantics as unknown and resume through the records-and-receipts procedure above.

Start free.1 response = 1 credit.

100,000 responses a day at 20 per second, on 150+ networks. Upgrade when you need more.