# How gas is paid and funded

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding
What happens to a write when the paying wallet runs out of gas, how the gas payer models differ, and the Platform API routes behind Transaction funding.

The platform sends the organisation's transactions from paying wallets, and the organisation or the user keeps those wallets funded with the network's fee, called gas. When a wallet runs short on a network that charges gas, the platform pauses the write and records a funding requirement that names the wallet and the amount. It resumes the write if the wallet is funded within the funding window. The Console shows a funding requirement as a funding request. The Console side of this, where an operator reads who pays, tops up a wallet and changes the gas payer, is [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding).

## When a wallet runs out of gas [#when-a-wallet-runs-out-of-gas]

The platform pauses a write for funding only after the network refuses it because the paying wallet cannot cover its gas. A forecast of the gas need sizes the amount but never starts a pause. The one exception is when the platform sets up or repairs an organisation's bundler wallet: it checks the balance and raises a requirement without a refused write. The refused wallet can be a user's signing wallet, a smart wallet, the relayer wallet, the bundler wallet, or the paymaster deposit.

The platform then records a funding requirement for that wallet on that network. It holds the minimum amount the wallet needs, a larger recommended amount that also covers fee changes and the next operations, and the balance the platform saw. Only one requirement is active per organisation, network and wallet, so a second write that runs short on the same wallet joins it. While a write waits, its transaction request keeps its state and its status names the requirement. A smart-wallet operation that the bundler finds short when it builds a bundle waits the same way and joins the next bundle once its smart wallet or the paymaster deposit is funded. [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) covers how to read an operation's status.

[Figure] How a write paused for gas ends. The network refuses a sent write for gas, so the platform pauses it under an active funding requirement. A top-up resolves the requirement and the write resumes. If the funding window closes first, the requirement expires and the write fails with DALP-9087. One top-up releases every write waiting on the same wallet. Labels: Write sent; queued transaction; Network refuses; not enough gas; Paused; requirement active; Resumes; top-up observed,; requirement resolved; Fails, DALP-9087; window closed,; requirement expired; One top-up releases every write waiting on the same wallet.

A paused write ends in one of two ways: a top-up resolves its requirement, or the funding window closes.

A requirement has one of three statuses:

| Status | Meaning | Waiting writes |
| --- | --- | --- |
| `active` | The wallet is short. A notice shows at the top of Transaction funding. | Wait. |
| `resolved` | The platform observed enough funds on the wallet. | Resume, all of them, on one top-up. |
| `expired` | The funding window closed first. | Fail with the gas required error, `DALP-9087`. |

The funding window is a gas setting of each network, 30 minutes unless a platform administrator sets another value from 60 seconds to 7 days. [Gas settings](https://docs.settlemint.com/docs/deployment/gas-settings) covers it and the settle delay: when a wallet shows enough funds but the node still refuses the write, the platform waits that delay, 2 minutes by default, and sends again up to five times.

Some writes do not pause:

- On a network that charges no gas, a write never pauses for funds.
- A caller can decline the pause and get a fast failure instead, as [Fund through the API](#fund-through-the-api) shows.
- A smart-wallet write that needs more than one signer to approve fails on a shortfall instead of pausing.

The person who must fund a wallet hears about it by email. A user's own wallet emails each person who holds it, and a wallet with no person holder emails the organisation's owners. The email names the network, the wallet address and the minimum balance the wallet needs. A request for the relayer wallet, the bundler wallet or the paymaster deposit sends no email: those show as notices on [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) and on the home dashboard.

A user can cancel a write paused on their own EOA wallet while it waits. [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle) covers cancellation in other states.

## Choose a gas payer [#choose-a-gas-payer]

Two settings decide who pays gas when a user of the organisation signs a transaction. They change which wallet pays the fee and what you keep funded, and the fee itself stays the same. [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) explains how each choice reaches the network.

- **Wallet type**, one choice for the whole organisation, between EOA wallets and [smart wallets](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) with approvals and recovery. The move from EOA wallets to smart wallets is permanent, and is made in the "Wallet type" row of [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-wallet-type).
- **Gas payer**, one choice per network. With EOA wallets, each user pays under "Self-pay" or the organisation's relayer pays under "Relayer-paid". With smart wallets, each smart wallet pays under "Self-pay" or the organisation's paymaster pays under "Paymaster-paid".

The organisation picks its wallet type and a preferred gas payer during [onboarding](https://docs.settlemint.com/docs/getting-started/onboarding). The first network takes that payer. When the deployment sets up a network's paymaster without a ready sponsorship signing key, sponsorship stays off there until an operator turns it on. Each network added later starts on Self-pay, and after a move to smart wallets every network starts on Self-pay. You change the gas payer one network at a time with [Change gas payer](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-gas-payer).

| Wallet type and gas payer | Who pays gas | What you keep funded | Can you leave it |
| --- | --- | --- | --- |
| EOA wallets, Self-pay | Each user's own wallet | Each signer's wallet that runs short | Yes, per network |
| EOA wallets, Relayer-paid | The relayer wallet on that network | The relayer wallet | Yes, per network |
| Smart wallets, Self-pay | Each smart wallet, which repays the bundler | The bundler wallet and each smart wallet | Per network, not back to EOA |
| Smart wallets, Paymaster-paid | The paymaster deposit, which repays it | The bundler wallet and the paymaster deposit | Per network, not back to EOA |

[Figure] How a write reaches the network for each gas payer. EOA wallets with Self-pay: the EOA wallet signs, submits and pays. Relayer-paid: the EOA wallet signs, and the relayer wallet submits and pays through the forwarder contract. Smart wallets: the smart wallet signs, and the bundler submits through the EntryPoint and fronts the gas. Under Self-pay the smart wallet pays the bundler back, under Paymaster-paid the paymaster deposit does. Labels: EOA, Self-pay; EOA wallet signs, submits and pays, then target contract; EOA, Relayer-paid; EOA wallet signs, relayer wallet submits and pays,; forwarder contract, then target contract; Smart, Self-pay; Smart wallet signs, bundler fronts the gas, EntryPoint,; target contract, then the smart wallet pays the bundler back; Smart, Paymaster-paid; Smart wallet signs, bundler fronts the gas, EntryPoint,; target contract, then the paymaster deposit pays it back.

On a network that charges no gas, the same route runs and no fee is paid.

**Self-pay** suits users who already hold the network's currency, and networks that charge no gas, where the other payers only add a step. With EOA wallets, nothing on the organisation's side needs funding, but a signer who runs short waits until someone funds that signer.

**Relayer-paid** suits users who keep EOA wallets and should never hold gas. The organisation funds one wallet per network instead of one per user. The user's wallet signs a request, called a meta transaction. The relayer wallet sends it to the platform's forwarder contract and pays the fee, and the target contract records the user as the sender. The relayer cannot alter a signed request, because the forwarder rejects one whose signature does not match. It can delay sending it.

**Paymaster-paid** suits smart-wallet users who should never hold gas. The bundler wallet submits each operation and fronts the gas, and the paymaster's deposit at the EntryPoint contract pays it back in the same transaction. Both must stay funded. Choosing Paymaster-paid turns sponsorship on for that network, and choosing Self-pay turns it off. The paymaster contract stays deployed while sponsorship is off, and turning it off does not refund the deposit.

### What Relayer-paid does not cover [#what-relayer-paid-does-not-cover]

The relayer pays only for transactions it can relay:

- The forwarder accepts signatures from EOA wallets only, so a transaction from a smart-wallet sender fails at once.
- When the target contract does not accept the forwarder, the user's own wallet pays for that transaction, as with Self-pay.
- The relayer does not fund native currency that a call sends with it, so such a transaction fails at once.
- When the user's custody provider cannot sign the request, the transaction fails with an error that names the provider.

The platform sends one relayed transaction per user wallet per network at a time, because the forwarder runs each user's requests in a fixed order. The next one from the same wallet waits, for at most one hour, until the previous one completes. Transactions from different users do not wait for each other.

A relayed transaction can be cancelled until it is confirmed: the relayer then sends an empty transaction in its place.

### Changing who pays [#changing-who-pays]

A switch changes how new transactions on that network are paid. A transaction the platform already prepared for the relayer still goes through the relayer. Users keep the same wallet addresses, so a switch moves no assets and changes no user's permissions. It changes the address that sends new transactions. The transactions that deploy the organisation are paid by the deploying wallet, whatever you choose.

Switching a network to Relayer-paid creates a relayer wallet on that network. Until the relayer holds enough, user transactions on that network wait for funding. Switching back to Self-pay stops the relayer paying, and the relayer keeps its balance. It shows as "Idle" in the **Wallets** table, where a Permission manager can [withdraw](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#withdraw-from-an-idle-wallet) it. Switching that network back to Relayer-paid later reuses the same relayer wallet and its balance.

## Fund through the API [#fund-through-the-api]

The Platform API reads and changes the same funding state. A system route acts on the organisation's default network unless the request sends `X-Chain-Id` with another chain ID. Amounts are decimal strings in wei, the currency's smallest unit.

| Task | Route |
| --- | --- |
| List funding requirements | `GET /api/v2/organizations/funding-requirements` |
| Read whether a write waits for funds | `GET /api/v2/transaction-requests/{transactionId}` |
| Follow a write as it pauses and resumes | `GET /api/v2/transaction-requests/{transactionId}/stream` |
| Read the bundler wallet's balance | `GET /api/v2/system/bundler/balance` |
| Read a paymaster deposit | `GET /api/v2/system/paymasters/{address}/balance` |
| Deposit into the paymaster from your account | `POST /api/v2/system/paymasters/{address}/deposits` |
| Read how much a payer wallet can withdraw | `GET /api/v2/system/payers/{address}/withdrawable` |
| Withdraw from a payer wallet or paymaster deposit | `POST /api/v2/system/payers/{address}/withdrawals` |
| Change the gas payer with EOA wallets | `PUT /api/v2/organizations/networks/gas-payer` |
| Turn sponsorship on or off with smart wallets | `PUT /api/v2/system/paymasters/config` |

The request and response fields of each route are in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2), under Transaction funding, Transactions and Organisation deployment.

**Funding requirements.** The list returns only `active` requirements, newest first, unless you send `filter[status]=resolved` or `filter[status]=expired`. It also filters by `chainId`, `subjectAddress`, `subjectKind`, `expiresAt`, `lastRefusalAt` and `createdAt`. `subjectKind` is `eoa`, `smart-account` or `paymaster-deposit`. Each row carries the minimum as `requiredWei`, the recommended amount as `advisoryTotalWei`, the balance seen as `observedWei`, and `status`, `expiresAt` and `resolvedAt`. When the refusing check measured the balance, the requirement opens with that balance, and each later read that sees it change replaces it. The Permission manager, Gas manager and System manager roles see every row in full. Other callers see the address and amounts only for their own wallets and the organisation's wallets.

**A paused write.** A write is paused while its status read carries `activeRequirement`. The request keeps its state, for example `SIGNING`. `activeRequirement` holds the requirement `id`, the refused wallet's `address` and `role`, `subjectOwner`, which is `caller`, `organisation` or `platform`, `chainId` and `nativeCurrency`. A caller whose wallet signed the request, or who is an organisation owner or a platform administrator, also gets `shortfall` and `recommendedTotal`. `activeRequirementUnavailable: true` means the requirement could not be read, so read the status again. To see when the window closes, list requirements filtered by `subjectAddress` and read `expiresAt`. The status stream sends an event when a write starts or stops waiting on a requirement, and closes 180 seconds after it opens while the write is in flight, so reopen it to keep following. When the funding window closes, the request fails with the gas required error, `DALP-9087`.

**Decline the pause.** Send `Prefer: dalp-no-funding-pause`, alone or with a wait, as in `Prefer: wait=30, dalp-no-funding-pause`. A write the network then refuses for gas fails at once with `DALP-9087` and raises no requirement. Without a wait, the route answers HTTP 202 and the transaction request records the failure with the shortfall and the wallet address. A route that lists `DALP-14062` among its errors in the API reference can answer HTTP 400 with it, `TRANSACTION_QUEUE_FUNDING_REQUIRED`, instead, with `data.transactionId` naming the transaction request when the queue recorded one. The header can decline a pause but cannot force one.

**Top up.** No route moves funds into a wallet from outside the platform. Send the network's currency to the requirement's `subjectAddress` from your own wallet or service. The paymaster deposit is the exception: `POST /api/v2/system/paymasters/{address}/deposits` takes `amount` in wei, needs the Permission manager, Gas manager or System manager role and wallet verification, and pays from the account the request runs as.

**Withdraw.** Read the limit first. The Permission manager, Gas manager, System manager and Auditor roles can read it, and `destination` prices the reserve for that address.

- `balance` is the wallet's balance at the latest block, so a top-up shows on the first read after it confirms. For the paymaster, it is the EntryPoint deposit the indexer last observed.
- `reserve` is what the withdrawal itself costs, including a replacement at a raised fee. The platform prices it for a one-wei transfer and for sending the whole `withdrawable` amount to `destination`, and keeps the higher of the two.
- `inFlightReserve` is what the wallet's own writes on the network hold: the worst-case cost of its signed writes that have not settled and, for the bundler wallet, the bundles in flight.
- `withdrawable` is `balance` minus `reserve` and `inFlightReserve`, or 0 when those two take the whole balance.

The withdrawal applies the same rule when it is sent. It accepts the `withdrawable` amount the read showed unless the latest balance, the fee or the wallet's own writes changed since. For the paymaster, it also refuses that amount when the EntryPoint deposit on the network is lower than the indexed one the read showed. A `DALP-14027` refusal carries the figures it used: `balanceWei`, `reserveWei`, `inFlightReserveWei` and `withdrawableWei`.

The platform counts only the writes it sent itself. The network can also hold a spend from the wallet that the platform did not send, for example from the wallet's key used outside the platform. When that spend leaves less than the withdrawal, the withdrawal answers `DALP-12104` and sends nothing. Retry once the spend confirms. When it leaves the amount but uses part of `reserve`, the withdrawal is sent and the network can refuse it. The transaction request then fails and no funds move.

The withdrawal takes `destination`, `amount` in wei or `all`, and wallet verification, and only the Permission manager role can send it. A paymaster withdrawal also needs the System manager role on the signing account. It answers HTTP 200 with the amount moved once the transfer settles, or HTTP 202 with the transaction request to follow.

| Code | The route refuses |
| --- | --- |
| `DALP-14025` | A wallet that is not one of the organisation's payer wallets on the network. |
| `DALP-14027` | An amount over the current limit. |
| `DALP-14028` | A destination that cannot receive the transfer. |
| `DALP-12104` | A withdrawal while the network holds a spend the platform did not send. Retry it. |

**Change who pays.** With EOA wallets, send `chainId`, `gasPayer` as `self` or `relayer`, and an optional `reason`. An organisation owner or a platform administrator can call it or make the same change in the Console. A smart-wallet organisation is refused with `gas-payer-unavailable`. With smart wallets, send `enabled: true` for Paymaster-paid or `false` for Self-pay to the paymaster configuration route on the network. The Permission manager, Gas manager or System manager role can call it.

## Related pages [#related-pages]

Read [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) for how a sponsored operation reaches the network, [Operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet) for how the platform watches the balances of the wallets it sends from, and [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) for the Console screen.