Skip to content

docs: bso automatic retries fee estimation update #1222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avarobinson wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: bso automatic retries fee estimation update #1222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c9dc835
docs: improve BSO documentation for automatic retries and fee estimation
athanor-omgwinning[bot] Apr 15, 2026
61df700
docs: simplify BSO documentation — remove comparison table and drop-a…
athanor-omgwinning[bot] Apr 16, 2026
cc829f8
Merge branch 'main' into docs/bso-automatic-retries-fee-estimation
avarobinson Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions content/wallets/pages/bundler-api/bundler-api-fee-logic.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ slug: reference/bundler-api-fee-logic

Fee logic for Bundler API ( `eth_sendUserOperation` )

<Tip title="Want to skip fee estimation?">
[Bundler Sponsored Operations](/docs/reference/bundler-sponsored-operations) handle fee estimation and automatic retries for you. Set a max spend limit, pass zero for gas fees, and the bundler takes care of the rest. The fee logic below only applies when you're managing fees yourself without bundler sponsorship.
</Tip>

## Fee Logic

To provide its services, Rundler requires fees when using [`eth_sendUserOperation`](/docs/wallets/api-reference/bundler-api/bundler-api-endpoints/eth-send-user-operation), and these fees differ based on the mainnet or testnet in use. Rundler's requirements for priority fees are expressed via the [`rundler_maxPriorityFeePerGas`](/docs/wallets/api-reference/bundler-api/bundler-api-endpoints/rundler-max-priority-fee-per-gas) endpoint.
Expand Down
4 changes: 4 additions & 0 deletions content/wallets/pages/bundler-api/bundler-api-quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@ The Bundler APIs are a collection of [ERC-4337](https://eips.ethereum.org/EIPS/e
way to send transactions without directly dealing with the raw Bundler APIs.
</Info>

<Tip title="Skip fee estimation with Bundler Sponsored Operations">
With [Bundler Sponsored Operations](/docs/reference/bundler-sponsored-operations), you can skip fee estimation. Set a max spend limit per operation, pass zero for gas fees, and the bundler handles fee calculation, gas pricing, and automatic retries.
</Tip>

## Bundler API Endpoints

All of the Bundler API endpoints are listed below along with links to their individual pages and brief descriptions.
Expand Down
38 changes: 27 additions & 11 deletions content/wallets/pages/bundler-api/bundler-faqs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,23 @@ slug: wallets/reference/bundler-faqs

### How can I track the status of a userOp?

To understand the status of a userOp you can use the `eth_getUserOperationByHash` method as follows: loop over `eth_getUserOperationByHash` for as long as you are willing to wait for the userOp to land. If it still returns `null` after the timeout, there are two possibilities:
To understand the status of a userOp you can use the `eth_getUserOperationByHash` method as follows: loop over `eth_getUserOperationByHash` for as long as you are willing to wait for the userOp to land. If it still returns `null` after the timeout, there are two possibilities:

1. **The userOp is still pending**: This is the most common scenario and typically means *the fees are too low*. In this case, you should drop and replace the userOp with higher fees.
2. **The userOp has been dropped**: The most common (but rare) reason is that they paymaster signature has expired. However, this should rarely happen if you set a reasonable sponsorship expiry time, unless there is a significant delay in sending the userOp after the paymaster signs it.
1. **The userOp is still pending**: This is the most common scenario and typically means *the fees are too low*. In this case, you should drop and replace the userOp with higher fees.
2. **The userOp has been dropped**: The most common (but rare) reason is that they paymaster signature has expired. However, this should rarely happen if you set a reasonable sponsorship expiry time, unless there is a significant delay in sending the userOp after the paymaster signs it.

<Tip>
With [Bundler Sponsored Operations](/docs/reference/bundler-sponsored-operations), the bundler handles retries and fee adjustments automatically, which can help reduce stuck operations. There is no guarantee every operation will land, but the bundler resubmits with updated fees as needed.
</Tip>

### How do I get my userOp unstuck from the mempool?

For EIP-1559 fee markets, the base fee is fixed per block. To prioritize the inclusion of your userOp and get it unstuck from the mempool, you need to increase the `maxPriorityFeePerGas`. This can be achieved by dropping and replacing the userOp with a new one that has a higher `maxPriorityFeePerGas`.

<Tip>
[Bundler Sponsored Operations](/docs/reference/bundler-sponsored-operations) can help with this — the bundler manages fees and retries automatically, which reduces the likelihood of operations getting stuck.
</Tip>

### Can accepted userOps be dropped?

This is a possible but rare scenario and can occur due to several reasons:
Expand All @@ -32,7 +40,7 @@ This is a possible but rare scenario and can occur due to several reasons:

The transaction hash is not included in the response of `eth_sendUserOperation` for the following reasons:

* The hash of the bundle transaction that a userOp is included in can change before that userOp is mined. This can happen for multiple reasons, such as the pending bundle transaction being dropped and replaced by the bundler if it’s underpriced, or the bundle transaction being frontrun by another bundle that includes the userOp.
* The hash of the bundle transaction that a userOp is included in can change before that userOp is mined. This can happen for multiple reasons, such as the pending bundle transaction being dropped and replaced by the bundler if it's underpriced, or the bundle transaction being frontrun by another bundle that includes the userOp.
* Adding the transaction hash to the response of `eth_sendUserOperation` is incompatible with the future P2P mempool, since any bundler can bundle the userOp and land it onchain.

## Common Errors
Expand All @@ -48,11 +56,15 @@ To handle these errors, you should:
* add buffers on top of the gas estimates to account for market fluctuations
* implement retry mechanisms.

<Tip>
[Bundler Sponsored Operations](/docs/reference/bundler-sponsored-operations) can help avoid `precheck failed` fee errors because the bundler estimates and manages fees internally. You set gas fees to zero and configure a max spend limit — the bundler handles fee estimation and retries from there.
</Tip>

### Resolve `Replacement Underpriced` errors

You might get a `"Replacement Underpriced Error"` when using `eth_sendUserOperation`. This error occurs when a user already has an existing userOp in the mempool. userOps can become "stuck" in the mempool if their gas fee limits are too low to be included in a bundle.
You might get a `"Replacement Underpriced Error"` when using `eth_sendUserOperation`. This error occurs when a user already has an existing userOp in the mempool. userOps can become "stuck" in the mempool if their gas fee limits are too low to be included in a bundle.

To resolve this, you need to increase both `maxFeePerGas` and `maxPriorityFeePerGas` by at least 10%.
To resolve this, you need to increase both `maxFeePerGas` and `maxPriorityFeePerGas` by at least 10%.

To do so, follow the next steps:

Expand All @@ -62,9 +74,9 @@ To do so, follow the next steps:

2. **Choose the suitable increase values**: Once you have the re-estimated gas fees, choose the maximum of a 10% increase or the re-estimated values. This ensures that your new gas fee is competitively priced to be included in a block.

3. **Account for Rundler's service tip**: Rundler requires a small tip for its services via `maxPriorityFeePerGas`. Detailed information about this can be found [below](/docs/reference/bundler-faqs#fees).
3. **Account for Rundler's service tip**: Rundler requires a small tip for its services via `maxPriorityFeePerGas`. Detailed information about this can be found [below](/docs/reference/bundler-faqs#fees).

After calculating the new values, send your `userOp` again with the updated fees and it should go through successfully.
After calculating the new values, send your `userOp` again with the updated fees and it should go through successfully.

### Debug `-32521: Execution reverted` errors

Expand All @@ -79,7 +91,7 @@ To debug these errors, you should:

* Isolate the first 4 bytes of `revertData`.
* Paste into a signatures DB (e.g. [4byte.sourcify.dev](https://4byte.sourcify.dev)).
* If it matches a known error, you’ll see the standard signature.
* If it matches a known error, you'll see the standard signature.
* If not, it's a **custom error** - check the contract's ABI or source for error declarations.
* Decode any arguments (using a tool like [calldata.swiss-knife.xyz](https://calldata.swiss-knife.xyz/decoder) or your ABI).
* Map the error back to the contract source code to understand under what conditions it reverts.
Expand Down Expand Up @@ -152,6 +164,10 @@ Recommended Actions for Calculating `maxFeePerGas`:
estimating userOp gas fees.
</Info>

<Tip>
To avoid manual fee estimation, consider [Bundler Sponsored Operations](/docs/reference/bundler-sponsored-operations). The bundler estimates fees, applies buffers, and retries automatically — you just set a max spend limit per operation.
</Tip>

### How fee values are determined

* [alchemy\_requestGasAndPaymasterAndData](/docs/wallets/api-reference/gas-manager-admin-api/gas-abstraction-api-endpoints/alchemy-request-gas-and-paymaster-and-data) is an opinionated endpoint that tries to set fee values that give your userOps a high chance of landing onchain. The estimates may be slightly high, but this is intentional to land your UOs faster.
Expand All @@ -173,9 +189,9 @@ Versions v0.6, v0.7, and v0.8 of ERC-4337 are currently supported.

The latest version of ERC-4337 is v0.8, which builds on v0.7 with additional improvements including native support for [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) account delegation and further gas optimizations.

The appropriate version to use is determined by the smart account for which you are trying to send a userOp. Typically, a smart account is written to be compatible with a specific EntryPoint version. To determine which version is compatible, look at the smart account’s source code and check the first parameter of the `validateUserOp` function. If it has type `UserOperation`, the account uses v0.6. If the parameter type is `PackedUserOperation`, the account uses v0.7 or v0.8.
The appropriate version to use is determined by the smart account for which you are trying to send a userOp. Typically, a smart account is written to be compatible with a specific EntryPoint version. To determine which version is compatible, look at the smart account's source code and check the first parameter of the `validateUserOp` function. If it has type `UserOperation`, the account uses v0.6. If the parameter type is `PackedUserOperation`, the account uses v0.7 or v0.8.

For more information about the differences between the versions, refer to the specifications for [ERC-4337 v0.6.0](https://github.com/eth-infinitism/account-abstraction/blob/v0.6.0/eip/EIPS/eip-4337.md), [ERC-4337 v0.7.0](https://github.com/eth-infinitism/account-abstraction/blob/v0.7.0/erc/ERCS/erc-4337.md), and [ERC-4337 v0.8.0](https://github.com/eth-infinitism/account-abstraction/blob/v0.8.0/erc/ERCS/erc-4337.md), particularly the description of the user operation fields.
For more information about the differences between the versions, refer to the specifications for [ERC-4337 v0.6.0](https://github.com/eth-infinitism/account-abstraction/blob/v0.6.0/eip/EIPS/eip-4337.md), [ERC-4337 v0.7.0](https://github.com/eth-infinitism/account-abstraction/blob/v0.7.0/erc/ERCS/erc-4337.md), and [ERC-4337 v0.8.0](https://github.com/eth-infinitism/account-abstraction/blob/v0.8.0/erc/ERCS/erc-4337.md), particularly the description of the user operation fields.

### EntryPoint contract addresses (v0.6, v0.7, v0.8)

Expand Down
43 changes: 35 additions & 8 deletions content/wallets/pages/bundler-api/bundler-sponsored-operations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ slug: reference/bundler-sponsored-operations

Bundler sponsorship is a beta feature that allows the bundler to sponsor gas fees for user operations directly, eliminating the need for an onchain paymaster contract. This approach provides a streamlined way to abstract gas costs from your users while reducing the complexity and overhead associated with deploying and managing paymaster contracts.

<Tip title="Automatic retries built in">
With bundler sponsorship, you set a **max spend limit** per user operation and the bundler handles fee estimation, gas pricing, and automatic retries internally. You don't need to calculate `maxFeePerGas` or apply priority fee buffers yourself. [Learn more below](#automatic-retries-and-fee-management).
</Tip>

## How it differs from paymaster sponsorship

Traditional gas sponsorship in ERC-4337 relies on paymaster contracts deployed onchain. These contracts:
Expand All @@ -25,13 +29,32 @@ Bundler sponsorship, in contrast:
* Uses your Gas Manager policy to control spending
* Reduces gas overhead by eliminating paymaster contract calls
* Simplifies multi-chain deployments
* **Handles fee estimation and retries automatically** — you set a max spend limit and the bundler does the rest

<Info>
Bundler sponsorship is currently in **beta**. While it's production-ready, features and pricing may evolve based on user feedback.

For beta access, please reach out to [account-abstraction@alchemy.com](mailto:account-abstraction@alchemy.com).
</Info>

## Automatic retries and fee management

One of the most significant benefits of bundler sponsorship is that the bundler manages fee estimation and transaction submission on your behalf, including automatic retries.

### How it works

When you submit a user operation with bundler sponsorship:

1. **You set gas fees to zero** — pass `maxFeePerGas: "0x0"` and `maxPriorityFeePerGas: "0x0"` in your request. The bundler interprets this as "sponsor and manage fees for me."
2. **The bundler estimates fees** — it reads current network conditions (base fee, priority fee, congestion) and selects appropriate gas pricing.
3. **The bundler submits the transaction** — your user operation is included in a bundle and submitted to the network.
4. **If the transaction doesn't land, the bundler retries** — the bundler monitors the transaction and, if it remains pending due to fee changes or network congestion, resubmits with updated fee parameters.
5. **Costs stay within your policy limit** — the total gas cost is capped by the **Max Spend Per UO** you configure in your Gas Manager policy.

<Note>
While the bundler handles retries and fee adjustments automatically, there is no guarantee that every operation will land. In cases of extreme congestion or sustained fee spikes beyond your configured max spend limit, an operation may not be included. Set your Max Spend Per UO with sufficient headroom for your target networks.
</Note>

## Policy setup

To use bundler sponsorship, create a Gas Manager policy of type **Bundler Sponsored Operations** in your dashboard.
Expand Down Expand Up @@ -62,7 +85,7 @@ To enable bundler sponsorship, you need to:

1. **Create a Bundler Sponsored Operations policy** in your dashboard with the required Max Spend Per UO configuration
2. **Include the policy ID** in your requests via the `x-alchemy-policy-id` header
3. **Set gas fees to zero** in your user operation overrides
3. **Set gas fees to zero** in your user operation overrides — the bundler handles fee estimation and retries from there

### Example implementation

Expand Down Expand Up @@ -101,7 +124,8 @@ const PRIVATE_KEY = process.env.PRIVATE_KEY!;
signer,
});

// Send user operation with bundler sponsorship
// Send user operation with bundler sponsorship.
// Gas fees are set to zero — the bundler estimates fees and retries automatically.
const uo = await client.sendUserOperation({
overrides: {
maxFeePerGas: "0x0",
Expand Down Expand Up @@ -131,7 +155,7 @@ const PRIVATE_KEY = process.env.PRIVATE_KEY!;

2. **Transport Configuration**: The `x-alchemy-policy-id` header must be included in the transport configuration's `fetchOptions.headers`.

3. **Gas Fee Overrides**: Set both `maxFeePerGas` and `maxPriorityFeePerGas` to `"0x0"` to indicate that the bundler should sponsor all gas costs.
3. **Gas Fee Overrides**: Set both `maxFeePerGas` and `maxPriorityFeePerGas` to `"0x0"` to indicate that the bundler should sponsor all gas costs. The bundler selects fees and retries if needed — you don't need to estimate or buffer fees yourself.

## Requirements

Expand All @@ -145,11 +169,13 @@ const PRIVATE_KEY = process.env.PRIVATE_KEY!;

## Benefits

* **Simplified Architecture**: No need to deploy or manage paymaster contracts
* **Lower Onchain Gas Costs**: Eliminates the gas overhead of paymaster verification and contract calls
* **Reduced Latency**: Fewer network calls and onchain interactions result in faster user operation processing
* **Easier Multi-Chain Support**: Use the same policy type across multiple chains
* **Centralized Policy Management**: Control spending limits and rules from the dashboard
* **No fee estimation required**: Set gas fees to zero and let the bundler handle fee calculation and optimization.
* **Automatic retries**: The bundler monitors pending transactions and resubmits with updated fees if needed, though inclusion is not guaranteed in all network conditions.
* **Simplified Architecture**: No need to deploy or manage paymaster contracts.
* **Lower Onchain Gas Costs**: Eliminates the gas overhead of paymaster verification and contract calls.
* **Reduced Latency**: Fewer network calls and onchain interactions result in faster user operation processing.
* **Easier Multi-Chain Support**: Use the same policy type across multiple chains without managing per-chain fee strategies.
* **Centralized Policy Management**: Control spending limits and rules from the dashboard.

## Limitations (beta)

Expand All @@ -163,6 +189,7 @@ As this feature is currently in beta, be aware of:
## Related documentation

* [Bundler API Quickstart](/docs/reference/bundler-api-quickstart)
* [Bundler API Fee Logic](/docs/reference/bundler-api-fee-logic)
* [Gas Manager Admin API](/docs/wallets/api-reference/gas-manager-admin-api/admin-api-endpoints/get-policy)
* [Compute Unit Costs](/docs/reference/compute-unit-costs)
* [Smart Wallets documentation](/docs/wallets)
Loading