Gas Model

Two ways to pay for gas. Knowing which applies to which call is the difference between "this transaction worked" and "out of funds."

Mode	Who pays	When it applies	Service fee
Agent pays	The sub-wallet's own native balance (ETH, BNB, MATIC, …).	send_transaction and any direct call you make through POST /api/tx/send.	None.
ShredPay sponsors	ShredPay's gas wallet on the target chain.	execute_swap, defi_deposit, defi_withdraw, gas_swap — all flows that go through the Router contract.	A small fee on the input amount, in the same token.

Why two modes

Agents need to be able to call arbitrary contracts (paying their own gas keeps the model simple and uncensorable). But the most common operations — swaps, deposits, withdrawals — go through ShredPay's Router contract, which can batch token approvals and the actual call into a single sponsored transaction. That's faster, cheaper, and avoids the "agent has USDC but no ETH for gas" footgun.

When you must hold native gas

Any time you call send_transaction. Typical examples:

• ERC-20 transfers to addresses outside the Router.

• Direct calls to a third-party protocol that ShredPay does not have a Router pathway for.

• Any custom calldata.

If your sub-wallet runs out of native gas mid-flow, use gas_swap — it converts USDC to ETH through the Router with ShredPay paying gas, so the agent doesn't need ETH to obtain ETH. This is how an agent funded only in USDC bootstraps itself.

Today gas_swap is supported on Base only. Plan accordingly if your agent operates on other chains — pre-fund native gas or hold the agent on Base.

When ShredPay sponsors

Any time you call:

• execute_swap — swap one token for another.

• defi_deposit / defi_withdraw — vault interactions in the curated DeFi catalog.

• gas_swap — bootstrap native gas from USDC.

These calls only succeed on chains where the Router contract is deployed. Check has_router in GET /api/wallet/chains:

{
  "chains": [
    { "id": 1,     "name": "Ethereum", "has_router": false },
    { "id": 8453,  "name": "Base",     "has_router": true  },
    { "id": 42161, "name": "Arbitrum", "has_router": false }
  ]
}

A sponsored call on a chain without Router returns 400 ROUTER_NOT_AVAILABLE.

Service fees

Sponsored flows charge a small fee (basis points on the input amount, taken in the same token). Fees are returned in every quote — they are never a surprise:

{
  "amount_in": "100000000",
  "amount_out": "0.0473...",
  "fee_amount": "100000",
  "fee_token": "USDC",
  "gas_sponsored": true
}

For exact current fee schedules, check the response body of POST /api/swap/quote — they are sourced live, not from documentation.

Gas estimation

GET /api/gas/estimate?chain_id=8453

{
  "chain_id": 8453,
  "gas_price_wei": "1000000",
  "recommended_eth_for_5_txs": "0.0005",
  "native_balance_wei": "120000000000000"
}

Use this to decide whether the wallet has enough headroom for the next few transactions, or whether to swap up first.

Related

• Manage Gas guide — how to keep the wallet topped up

• Multi-chain — which chains have Router