Funding wallets for gas

Use this guide when your integration runs on a network where gas is not free and a transaction stops because the signing wallet cannot pay for it. Gas is the fee a network charges to run a transaction, paid in the network's own token. On networks that charge it, every transaction spends that token, so the wallet that signs the transaction must hold a balance first. The steps below show how to check gas readiness before you submit, fund the wallet that actually pays, and recover from a GAS_REQUIRED failure using the data the platform hands back.

Advanced accounts can sponsor a transaction's gas from a shared treasury, so the user's wallet pays nothing. The steps here apply to the other path: a wallet that pays its own gas. For sponsored gas, see Gas treasury runway and fee split.

When a wallet needs its own gas

Two things decide whether a wallet must hold gas: the network, and whether the operation is sponsored.

• The network. Some networks charge no gas. On a zero-gas network, no wallet needs a balance, and GAS_REQUIRED never fires. On a network where gas is not free, every transaction costs the gas token, and the signing wallet must hold enough to cover it.
• Sponsorship. With advanced accounts enabled, a paymaster can sponsor user operations from a funded treasury, so the user's own wallet spends no gas. Without sponsorship, or for a direct transaction that does not route through the paymaster, the signing wallet pays its own gas.

So a wallet needs its own funded balance when the network charges gas and the operation is not sponsored. Deployments and other direct on-chain writes from an unsponsored wallet are the common case.

Check gas readiness before you submit

Read a wallet's gas status before you queue a write, so you fund it ahead of time instead of after a failure.

curl --request GET \
  "https://your-platform.example.com/api/v2/smart-wallets/0x1234567890abcdef1234567890abcdef12345678/gas-status" \
  --header "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

{
  "data": {
    "hasPaymaster": false,
    "walletBalance": "5000000000000000",
    "chainZeroGas": false
  },
  "links": {
    "self": "/v2/smart-wallets/0x1234567890abcdef1234567890abcdef12345678/gas-status"
  }
}

The response reports three signals:

Read these together. If chainZeroGas is true, the wallet is ready. If the network charges gas and the operation is not sponsored, compare walletBalance against the cost of the operation you plan to submit and top up if it is short.

For a managed-custody wallet, read the native balance straight from the custody provider with GET /api/v2/smart-wallets/custody/gas-balance. It resolves the wallet from your authenticated session and reports balance, symbol, and decimals. This read works when the active signer is DFNS managed custody; for other signers it returns null.

Read a GAS_REQUIRED failure

When a wallet runs a transaction it cannot pay for, the platform returns a structured GAS_REQUIRED error (DALP-9087, status 422) instead of a generic failure string. The network rejects the transaction before it lands, so nothing executed and no gas was spent. The error carries everything you need to fund the wallet and try again.

{
  "code": "GAS_REQUIRED",
  "status": 422,
  "message": "The wallet balance is too low to cover this transaction's gas",
  "data": {
    "id": "DALP-9087",
    "shortfallWei": "3000000000000000",
    "recommendedTotalWei": "23000000000000000",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "chainId": 11155111,
    "tokenSymbol": "ETH",
    "walletRole": "transaction-signer",
    "retryableByFunding": true
  }
}

Fund the wallet and retry

1. Send the gas token. Transfer at least shortfallWei of tokenSymbol to address on the network identified by chainId. Sending recommendedTotalWei instead leaves a buffer for the next few operations, so you fund less often. The amount is sized against the network's live fee, so a small over-send is normal and harmless.
2. Confirm the balance landed. Read gas-status again and check that walletBalance now covers the operation.
3. Resubmit the same request. Once the wallet holds enough, send the original request again.

Keep wallets funded over time

A wallet that pays its own gas drifts toward empty as it transacts. To avoid hitting GAS_REQUIRED mid-flow, read gas-status on the wallets your integration drives and top them up before they run low, the same way you would watch any operational balance. When the cost matters more than per-wallet control, enabling sponsorship through advanced accounts moves gas onto a shared treasury, so individual wallets stop needing their own balance.

Related guides