How to fetch UserOperations (UserOps) for a smart account
List the ERC-4337 UserOperations a smart account sent, decode gas and paymaster, and monitor a paymaster's spend and EntryPoint deposit with the GoldRush API.
On this page
An ERC-4337 smart account doesn't send ordinary transactions. Its owner signs a UserOperation (UserOp), a bundler packs it with others into one transaction to the EntryPoint contract, and the EntryPoint runs it. On a block explorer the transaction is from the bundler to the EntryPoint, so the account's activity is hard to find. What the EntryPoint does leave is one UserOperationEvent log per UserOp, with the smart account in it as an indexed topic. This guide reads those logs with the GoldRush Foundational API to list one account's UserOps, then uses the same method to monitor a paymaster.
Where a UserOperation shows up onchain
The EntryPoint emits this event for every UserOperation it executes, whether it succeeded or not:
event UserOperationEvent( bytes32 indexed userOpHash, address indexed sender, address indexed paymaster, uint256 nonce, bool success, uint256 actualGasCost, uint256 actualGasUsed);Its three indexed fields become log topics, after the event's own topic hash:
| Topic | Holds |
|---|---|
| 0 | The event's topic hash, 0x49628fd1471006c1482da88028e9ce4dbb080b815c9b0344d39e5a8e6ec1419f |
| 1 | userOpHash, the UserOp's unique ID |
| 2 | sender, the smart account, left-padded to 32 bytes |
| 3 | paymaster, left-padded, or the zero address when the account paid its own gas |
nonce, success, actualGasCost (in wei) and actualGasUsed are in the log's data. So "the UserOps of wallet X" is "every UserOperationEvent whose topic 2 is X", and "what paymaster Y paid for" is "every UserOperationEvent whose topic 3 is Y".
Which EntryPoint
Each EntryPoint version is a separate contract, and a smart account is built for one of them. The event signature, and so its topic hash, is the same in all three, so you filter by the contract that emitted the log:
| EntryPoint | Address |
|---|---|
| v0.6 | 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 |
| v0.7 | 0x0000000071727De22E5E9d8BAf0edAc6f37da032 |
| v0.8 | 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108 |
These are the addresses in viem's viem/account-abstraction constants. If you don't know which one an account uses, leave out the EntryPoint check below: the log's sender_address tells you which contract emitted it. Our guide to ERC-4337 account abstraction SDKs shows which SDKs support which version.
What you need
- A GoldRush API key. Sign up for the free trial.
- The smart account's address and the chain it's on, such as
base-mainnetoreth-mainnet. - A block range. Event queries are scoped by
starting-blockandending-block.
Step 1: Query the UserOperationEvent by topic
The log events by topic hash endpoint returns every log with a given topic hash on a chain, decoded. Its secondary-topics parameter narrows that to logs that also carry another topic, and it takes a plain address as well as a padded one. Put the smart account there:
API=https://api.covalenthq.com/v1USER_OPERATION_EVENT=0x49628fd1471006c1482da88028e9ce4dbb080b815c9b0344d39e5a8e6ec1419fACCOUNT=0x6897a6523119f1221e70e6afb9ec5483d091852b curl "$API/base-mainnet/events/topics/$USER_OPERATION_EVENT/?starting-block=59700000&ending-block=59700030&secondary-topics=$ACCOUNT" \ -H "Authorization: Bearer $GOLDRUSH_API_KEY"On 21 November 2026 that returned five UserOps from this account in those 31 Base blocks, all through EntryPoint v0.7 and all sponsored by the same paymaster. Here is the first one, abridged:
{ "block_signed_at": "2026-11-19T23:19:39.000Z", "block_height": 59700017, "tx_hash": "0xbaa546534c60e85b7a9763a9bc092e9b92399138678aaa5b4b20c283871967db", "raw_log_topics": [ "0x49628fd1471006c1482da88028e9ce4dbb080b815c9b0344d39e5a8e6ec1419f", "0x3fb272f6f69a4c990061fb36c1fe87f9875a780d62248a9d72f7e99a85002da2", "0x0000000000000000000000006897a6523119f1221e70e6afb9ec5483d091852b", "0x000000000000000000000000777777777777aec03fd955926dbf81597e66834c" ], "sender_address": "0x0000000071727de22e5e9d8baf0edac6f37da032", "raw_log_data": "0x00000000000000007cb406dac8ca40ad95c7c40fc43540c2000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000012c260e6e4e000000000000000000000000000000000000000000000000000000000002fd27", "decoded": { "name": "UserOperationEvent", "params": [ { "name": "userOpHash", "type": "bytes32", "value": "P7Jy9vaaTJkAYfs2wf6H+YdaeA1iJIqdcvfpmoUALaI=" }, { "name": "sender", "type": "address", "value": "0x6897a6523119f1221e70e6afb9ec5483d091852b" }, { "name": "paymaster", "type": "address", "value": "0x777777777777aec03fd955926dbf81597e66834c" }, { "name": "nonce", "type": "uint256", "value": "3057714292532845161992322850932438626725411477048155701248" }, { "name": "success", "type": "bool", "value": true }, { "name": "actualGasCost", "type": "uint256", "value": "1289128668750" }, { "name": "actualGasUsed", "type": "uint256", "value": "195879" } ] }}Three things to read correctly:
sender_addressis the EntryPoint, the contract that emitted the log, not the smart account. The smart account is thesenderparam, topic 2.- The decoded
userOpHashis base64. Useraw_log_topics[1]for the hex hash that bundlers, explorers andeth_getUserOperationByHashuse. Here,P7Jy…LaI=is0x3fb272f6…85002da2. actualGasCostis in wei of the chain's native token. It is what the EntryPoint charged the paymaster's deposit, or the account's own deposit when there was no paymaster.
Step 2: Decode, filter and page through the results
secondary-topics matches the address in any topic, so an account that is also a paymaster, or a contract on another EntryPoint, can show up too. The code below keeps only logs from the EntryPoint you name where the address is topic 2, follows pagination.has_more through every page, and turns each log into a row. It reads the indexed fields from raw_log_topics and the rest from the 32-byte words of raw_log_data, so it doesn't depend on the decoder's parameter names.
const API = "https://api.covalenthq.com/v1";const USER_OPERATION_EVENT = "0x49628fd1471006c1482da88028e9ce4dbb080b815c9b0344d39e5a8e6ec1419f";const headers = { Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}` }; // An address as a 32-byte log topic: lowercase, left-padded with zeros.const asTopic = (address) => "0x" + address.toLowerCase().slice(2).padStart(64, "0"); // Every log with this event topic and `address` among its other topics, across all pages.async function* logsByTopic(chain, eventTopic, address, startBlock, endBlock) { for (let page = 0; ; page++) { const query = new URLSearchParams({ "starting-block": String(startBlock), "ending-block": String(endBlock), "secondary-topics": address, "page-number": String(page), }); const res = await fetch(`${API}/${chain}/events/topics/${eventTopic}/?${query}`, { headers }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); const { data } = await res.json(); yield* data.items; if (!data.pagination.has_more) return; }} // One UserOperationEvent as a row. Indexed fields are topics; the rest are 32-byte words of raw_log_data.function toUserOp(log) { const word = (i) => BigInt("0x" + log.raw_log_data.slice(2 + 64 * i, 66 + 64 * i)); const paymaster = "0x" + log.raw_log_topics[3].slice(26); return { block: log.block_height, time: log.block_signed_at, txHash: log.tx_hash, userOpHash: log.raw_log_topics[1], sender: "0x" + log.raw_log_topics[2].slice(26), paymaster: /^0x0+$/.test(paymaster) ? null : paymaster, nonce: word(0), success: word(1) === 1n, actualGasCost: word(2), // wei, paid by the paymaster's deposit or the account's actualGasUsed: word(3), };} // The UserOperations one smart account sent through one EntryPoint in a block range.async function getUserOps(chain, entryPoint, account, startBlock, endBlock) { const ops = []; for await (const log of logsByTopic(chain, USER_OPERATION_EVENT, account, startBlock, endBlock)) { if (log.sender_address !== entryPoint.toLowerCase()) continue; // emitted by another EntryPoint if (log.raw_log_topics[2] !== asTopic(account)) continue; // the address matched as paymaster, not sender ops.push(toUserOp(log)); } return ops;} const ENTRYPOINT_V07 = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";const ops = await getUserOps( "base-mainnet", ENTRYPOINT_V07, "0x6897a6523119f1221e70e6afb9ec5483d091852b", 59700000, 59700030);console.table(ops);Run against the responses for the request in Step 1, fetched three to a page, it makes two requests (page-number=0, then 1) and prints the five UserOps: all success: true, actualGasUsed between 178,900 and 195,934, and 6,218,340,196,526 wei of gas between them.
Block ranges and pagination
- Pages. Results come 100 to a page by default (
page-sizechanges it).page-numberis zero-based; keep going whilepagination.has_moreistrue.total_countcan benull, so don't rely on it. - Ranges.
starting-blockandending-blockalso takelatest, sostarting-block=<last block you saw>&ending-block=latestpicks up new UserOps on a schedule. For a long history, walk the range in slices and store the last block you processed. A request that would take too long returns a 406; narrow the range. - Account creation. If you don't know where to start, the account's first UserOp is the one that deployed it, which also emits an
AccountDeployedevent from the EntryPoint with the account as topic 2. - Failed UserOps still emit
UserOperationEvent, withsuccessfalse, and the account or paymaster still pays for the gas. The EntryPoint also emits aUserOperationRevertReasonevent with the revert data.
Get the full transaction behind a UserOp
A UserOperationEvent is one log in a bundle transaction. For everything else that UserOp did, such as the token transfers it made, fetch the transaction by the row's txHash with the get a transaction endpoint, which returns all of its decoded logs. A bundle can hold several accounts' UserOps, and the EntryPoint runs them in order, emitting each one's UserOperationEvent after its execution. So this UserOp's logs are the ones after the previous UserOperationEvent (or after BeforeExecution, for the first) up to and including its own.
To start from the account instead, its wallet transaction history lists transactions that involve the address, with their logs. In those results, logs whose sender_address is an EntryPoint are the account-abstraction activity.
Monitor a paymaster
A paymaster pays gas for the UserOps it sponsors, and when its funds run out, those UserOps fail validation. Monitoring one means watching where the money is and how fast it goes.
Where a paymaster's gas money lives
- The EntryPoint deposit. The paymaster deposits native tokens into the EntryPoint with
depositTo. This is the gas tank: after each sponsored UserOp the EntryPoint takesactualGasCostfrom the deposit. Its live value isEntryPoint.balanceOf(paymaster), a contract read over RPC. - A reserve wallet. The paymaster contract's own balance isn't spent on gas. Many operators keep a separate wallet that tops up the deposit. Its balance is the reserve, not the tank.
Watching only the reserve wallet misses the deposit draining; watching only the deposit misses that there is nothing left to refill it with. Watch both.
Spend: what the paymaster sponsored, and for whom
The paymaster is topic 3 of every UserOp it paid for, so the Step 2 code works with the paymaster's address in secondary-topics and a check on topic 3 instead of topic 2. Summing actualGasCost per day and per account shows the spend rate, when it spikes, and which smart accounts consume the sponsorship:
// What a paymaster sponsored in a block range: spend per UTC day and per smart account.async function paymasterSpend(chain, entryPoint, paymaster, startBlock, endBlock) { const byDay = new Map(); const bySender = new Map(); let ops = 0; for await (const log of logsByTopic(chain, USER_OPERATION_EVENT, paymaster, startBlock, endBlock)) { if (log.sender_address !== entryPoint.toLowerCase()) continue; if (log.raw_log_topics[3] !== asTopic(paymaster)) continue; // keep only ops this paymaster paid for const op = toUserOp(log); const day = op.time.slice(0, 10); byDay.set(day, (byDay.get(day) ?? 0n) + op.actualGasCost); bySender.set(op.sender, (bySender.get(op.sender) ?? 0n) + op.actualGasCost); ops++; } const topSenders = [...bySender].sort((a, b) => (b[1] > a[1] ? 1 : b[1] < a[1] ? -1 : 0)).slice(0, 10); return { ops, byDay, topSenders };} const spend = await paymasterSpend( "base-mainnet", ENTRYPOINT_V07, "0x777777777777aec03fd955926dbf81597e66834c", 59700000, 59700030);console.log(spend);For the paymaster in the sample, those 31 blocks held the same five UserOps: one account, 6,218,340,196,526 wei. Over a day or a week, the same call gives you the burn rate and the accounts behind it. One account taking most of the spend, or a jump in UserOps per hour, is the pattern to alert on.
Refills and withdrawals
The EntryPoint also logs changes to a deposit: Deposited(address indexed account, uint256 totalDeposit) when it is topped up, and Withdrawn(address indexed account, address withdrawAddress, uint256 amount) when the owner takes funds out. The account, here the paymaster, is topic 1 in both. Deposited carries the deposit's new total, so each one is a reading of the tank right after a refill.
const DEPOSITED = "0x2da466a7b24304f47e87fa2e1e5a81b9831ce54fec19055ce277ca2f39ba42c4"; // Deposited(address,uint256)const WITHDRAWN = "0xd1c19fbcd4551a5edfb66d43d2e337c04837afda3482b42bdf569a8fccdae5fb"; // Withdrawn(address,address,uint256) // Top-ups and withdrawals of a paymaster's EntryPoint deposit, oldest first.async function depositHistory(chain, entryPoint, paymaster, startBlock, endBlock) { const rows = []; for (const [kind, eventTopic] of [ ["deposited", DEPOSITED], ["withdrawn", WITHDRAWN], ]) { for await (const log of logsByTopic(chain, eventTopic, paymaster, startBlock, endBlock)) { if (log.sender_address !== entryPoint.toLowerCase()) continue; if (log.raw_log_topics[1] !== asTopic(paymaster)) continue; const data = log.raw_log_data.slice(2); rows.push({ kind, block: log.block_height, txHash: log.tx_hash, // Deposited carries the deposit's new total; Withdrawn carries (withdrawAddress, amount). wei: BigInt("0x" + (kind === "deposited" ? data.slice(0, 64) : data.slice(64, 128))), }); } } return rows.sort((a, b) => a.block - b.block);}GoldRush decodes Deposited with its own parameter names (user, amount), and the value is the new total, not the amount added, which is another reason the code reads the raw topics and data.
A low-balance alert
Put the pieces together: read the live deposit over RPC, read the reserve wallet's native balance with the native token balance endpoint, and compare them to the spend rate from paymasterSpend:
const RPC_URL = process.env.RPC_URL; // any JSON-RPC endpoint for the same chain // The live EntryPoint deposit: EntryPoint.balanceOf(paymaster), selector 0x70a08231.async function entryPointDeposit(entryPoint, paymaster) { const res = await fetch(RPC_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to: entryPoint, data: "0x70a08231" + asTopic(paymaster).slice(2) }, "latest"], }), }); const { result, error } = await res.json(); if (error) throw new Error(error.message); return BigInt(result);} // The reserve wallet's native balance, from GoldRush.async function reserveBalance(chain, wallet) { const res = await fetch(`${API}/${chain}/address/${wallet}/balances_native/`, { headers }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); const { data } = await res.json(); return BigInt(data.items[0].balance);} // Alert when the deposit would last less than `minDays` at the last day's spend, or the reserve can't refill it.async function checkPaymaster({ chain, entryPoint, paymaster, reserve, dailySpendWei, refillWei, minDays = 3 }) { const deposit = await entryPointDeposit(entryPoint, paymaster); const inReserve = await reserveBalance(chain, reserve); const daysLeft = dailySpendWei > 0n ? Number(deposit / dailySpendWei) : Infinity; const alerts = []; if (daysLeft < minDays) alerts.push(`deposit covers ~${daysLeft} day(s) of spend`); if (inReserve < refillWei) alerts.push("reserve wallet can't cover the next refill"); return { deposit, inReserve, daysLeft, alerts };}Run it on a schedule, once per chain where you sponsor gas, and send alerts to wherever your team is paged. Thresholds in days of runway, rather than a fixed amount of ETH, keep working as traffic grows.
What it costs
Each call is billed in GoldRush credits:
- Log events by topic hash: 0.01 per item, so 1,000 UserOps cost 10 credits.
- Native token balance: 0.5 per call.
- Get a transaction: 0.1 per call.
Narrow block ranges and secondary-topics keep the item count, and the bill, to the logs you need.
Frequently asked questions
Why can't I find a smart account's UserOps in its normal transaction list?
A UserOp isn't a transaction from the account. The bundler sends the transaction to the EntryPoint, so the account is neither its from nor its to, and an explorer's list of transactions sent from the address leaves it out. The account appears in the UserOperationEvent log the EntryPoint emits, as indexed topic 2, which is why querying that event by topic finds each UserOp, with its own gas cost and paymaster, even when one bundle holds several accounts' operations.
How do I get the userOpHash in hex?
Use raw_log_topics[1] from the log. The decoded userOpHash parameter is the same 32 bytes in base64. The hex form is what bundler APIs such as eth_getUserOperationByHash and block explorers take.
Does this work for EntryPoint v0.6, v0.7 and v0.8?
Yes. UserOperationEvent has the same signature, and so the same topic hash, in all three. Each version is a different contract, so filter on sender_address for the EntryPoint your accounts use, or check sender_address to see which version each UserOp went through.
How do I tell whether a paymaster sponsored a UserOp?
Look at topic 3. A zero address means no paymaster: the account paid its own gas from its EntryPoint deposit. Any other address is the paymaster that paid actualGasCost.
How do I monitor a paymaster's balance?
Read its EntryPoint deposit with EntryPoint.balanceOf(paymaster) over RPC: that is the balance gas comes out of. Track spend by querying UserOperationEvent with the paymaster as topic 3 and summing actualGasCost, track refills with the EntryPoint's Deposited and Withdrawn events, and check the reserve wallet that refills it with the native token balance endpoint.
Which chains does this work on?
Any EVM chain that GoldRush indexes and where an ERC-4337 EntryPoint is deployed. Pass the chain name, such as base-mainnet or arbitrum-mainnet, in the URL.
Next steps
- Try the log events by topic hash endpoint in the API reference with your own account.
- Compare ERC-4337 account abstraction SDKs, and list every UserOp an EntryPoint handled with log events by contract address.
- See everything else the GoldRush Foundational API covers, from balances to transactions.