ERC-4337 Error AA31: Paymaster Deposit Too Low in EntryPoint
ERC-4337 error AA31 "paymaster deposit too low" occurs when a paymaster contract has insufficient native cryptocurrency deposited inside the EntryPoint contract to cover the required prefund of the transaction. Before executing any UserOp, the EntryPoint locks maximum theoretical gas costs. If the paymaster deposit is below requiredPreFund, the transaction reverts. Deposit native tokens into EntryPoint via depositTo(paymasterAddress) to resolve, and lower excessively inflated verification gas limit parameters in your client SDK.
# Root Cause & Technical Architecture
The EntryPoint requires 100% prefunding before executing UserOperations. The required prefund is calculated as `requiredPreFund = (verificationGasLimit * 3 + callGasLimit + preVerificationGas) * maxFeePerGas`. The EntryPoint queries `deposits[paymaster]`. If `deposits[paymaster] < requiredPreFund`, the contract aborts with `revert("AA31 paymaster deposit too low")`. This occurs when sponsorship treasuries run dry during gas price spikes.
# 4-Step Actionable Diagnostic Protocol
Step-by-Step ResolutionCheck Paymaster Deposit Balance in EntryPoint
Call entryPoint.balanceOf(paymasterAddress) to inspect the active native token deposit held in escrow by the EntryPoint contract.
Refill Paymaster Escrow via depositTo Function
Send native currency (ETH/MATIC) to the EntryPoint by invoking entryPoint.depositTo(paymasterAddress, { value: amount }) from any wallet.
Lower Inflated UserOp Gas Limit Overestimations
Audit callGasLimit and verificationGasLimit. Overestimating gas limits artificially inflates the required prefund, depleting paymaster capacity.
Set Up Automated Balance Webhook Alerts
Configure monitoring on your paymaster service (e.g. Pimlico/Alchemy) to auto-refill or alert your team when deposits dip below 0.1 ETH.
# Diagnostic Verification Code / Command
solidity// Interface to refill Paymaster balance on EntryPoint
interface IEntryPoint {
function depositTo(address account) external payable;
function balanceOf(address account) external view returns (uint256);
}
// Anyone can top up a paymaster's gas deposit on-chain:
function topUpPaymaster(address entryPoint, address paymaster) external payable {
IEntryPoint(entryPoint).depositTo{value: msg.value}(paymaster);
}Launch ERC-4337 UserOp Decoder
Execute client-side cryptographic simulation and parameter checks safely in your browser via native WebCrypto without sending private keys or mnemonics over the wire.
Read Full Investigation & Recovery Workflow
Explore complete architectural diagrams, edge-case failure trees, and detailed post-mortem analysis in our verified deep guide.
# Related Diagnostic Codes in ERC-4337 & Safe
Related Hex StatusesERC-4337 Error AA10: Sender Already Constructed UserOp Fix
Fix ERC-4337 error AA10 sender already constructed. Resolve non-empty initCode sent for deployed smart accounts, bundler estimation, and counterfactuals.
ERC-4337 Error AA20: Account Not Deployed EntryPoint Revert
Fix ERC-4337 error AA20 account not deployed. Troubleshoot empty initCode for counterfactual smart accounts, factory calldata, and pre-deployment.
ERC-4337 Error AA24: Signature Error UserOp Validation Fix
Fix ERC-4337 error AA24 signature error. Resolve validateUserOp signature mismatch, userOpHash EIP-712 hashing errors, and signature aggregator faults.
# Frequently Asked Questions
FAQ SchemaDoes the paymaster need native tokens in its contract or in EntryPoint?
The tokens must be deposited inside the EntryPoint contract via depositTo(). Holding tokens in the paymaster contract wallet itself is not sufficient.
Is unused prefund refunded after transaction execution?
Yes. The EntryPoint locks the maximum possible gas prefund upfront, but only deducts actual gas used, leaving the remainder in the deposit pool.
Why does AA31 happen during gas price surges?
When gas prices spike, maxFeePerGas increases, multiplying the required prefund and exhausting paymaster deposits faster than normal.