Gas sponsorship in the App SDK

The App SDK does not pay for gas itself. It builds an ERC-4337 UserOperation, attaches a paymaster signature if one is configured, and submits the operation through the bundler. The result is one of three flows depending on context.

For the conceptual overview of who pays gas and why, see Gas sponsorship. This page covers the App SDK call sites.

Three flows, one SDK

Flow	Who pays	What you configure
Mini App	Startale host	nothing
Standalone dApp with paymaster	You (or your sponsor wallet)	`paymasterOptions` on `createStartaleAccountSDK` or `startaleConnector`
Standalone dApp without paymaster	The end user, in ETH from their smart account	nothing, but the user must hold ETH

Mini Apps: nothing to do

Inside the Startale App, gas is sponsored by the host paymaster. Your code calls eth_sendTransaction, wallet_sendCalls, useSendTransaction, or useWriteContract exactly as it would against any wagmi-compatible wallet. The host attaches the paymaster signature before the UserOperation reaches the bundler.

Method	Sponsored by host
`eth_sendTransaction`	yes
`wallet_sendCalls`	yes
`personal_sign`	no gas, signature only
`eth_signTypedData_v4`	no gas, signature only

If the user has just enough ETH to cover gas, that does not change anything either; the host paymaster pays first.

Standalone dApps: configure a paymaster

Standalone dApps do not get free gas. Pass paymasterOptions to either createStartaleAccountSDK or startaleConnector. The map is keyed by chain id.

import { createStartaleAccountSDK } from '@startale/app-sdk'

const sdk = createStartaleAccountSDK({
  appName: 'My App',
  appChainIds: [1868],
  paymasterOptions: {
    1868: {
      url: 'https://paymaster.scs.startale.com/v1?apikey=YOUR_API_KEY',
      id: 'pm_live_my_paymaster_id',
    },
  },
})

import { startaleConnector } from '@startale/app-sdk'

startaleConnector({
  appName: 'My App',
  paymasterOptions: {
    1868: {
      url: 'https://paymaster.scs.startale.com/v1?apikey=YOUR_API_KEY',
      id: 'pm_live_my_paymaster_id',
    },
  },
})

Field	Type	Notes
`paymasterOptions[chainId].url`	`string`	The paymaster RPC URL. SCS-hosted paymasters live at `https://paymaster.scs.startale.com/v1`; self-hosted services use whatever URL you deploy.
`paymasterOptions[chainId].id`	`string`	The `paymasterId` injected into the paymaster request context. SCS-issued for managed and self-funded paymasters; service-defined for self-hosted ERC-7677 services.

The SDK packs { url, id } into the EIP-5792 capabilities sent with wallet_sendCalls, so every batched call on that chain is routed through your paymaster.

The fastest way to get a working (url, id) pair is to provision an SCS paymaster from the SCS Portal. You get the same managed or self-funded modes the AA SDK uses, with no extra service to deploy.

Standalone dApps without `paymasterOptions`

If you do not configure a paymaster, UserOperations are still built and submitted, but the user pays gas from their smart account’s ETH balance. The user therefore needs:

An ETH balance on the smart account address (not the EOA).
A way to top up that balance (bridge, faucet on testnet, in-app purchase).

This flow is appropriate for testing, internal tooling, or apps where users are expected to fund their own activity. Document the funding requirement in your UX, otherwise users hit “insufficient funds for gas” failures with no recourse.

Per-chain configuration

paymasterOptions is a map per chain id. You can sponsor on one chain and ask the user to pay on another:

paymasterOptions: {
  1868: { // Soneium Mainnet, sponsored
    url: 'https://paymaster.scs.startale.com/v1?apikey=YOUR_API_KEY',
    id: 'pm_live_my_paymaster_id',
  },
  // No entry for 1946 means users pay gas on Soneium Minato.
}

Failure modes

Symptom	Likely cause	Fix
`paymaster declined to sponsor`	Policy hit (rate limit, allowlist) on your paymaster.	Inspect the paymaster’s policies in the SCS Portal or your service logs.
`insufficient funds for gas`	User-pays flow with an empty smart account.	Top up the smart account, or configure `paymasterOptions`.
`paymaster context invalid`	`paymasterOptions[chainId].id` is wrong or missing.	Re-copy the `paymasterId` from the SCS Portal or check your service config.
Sponsorship works on one chain only	`paymasterOptions` is missing the other chain’s entry.	Add the chain id to the map.

Custom paymaster reference

Full ERC-7677 paymaster service shape and integration patterns.

Provision an SCS paymaster

Mint a paymaster URL and paymasterId in the Portal.

Concept: gas sponsorship

The two-tier model and where it is going.

Batched calls

Atomic multi-call UserOperations work the same way regardless of who pays.

Setup

Wallet

Payments

Account abstraction

Three flows, one SDK

Mini Apps: nothing to do

Standalone dApps: configure a paymaster

Standalone dApps without `paymasterOptions`

Per-chain configuration

Failure modes

Custom paymaster reference

Provision an SCS paymaster

Concept: gas sponsorship

Batched calls

​Three flows, one SDK

​Mini Apps: nothing to do

​Standalone dApps: configure a paymaster

​Standalone dApps without paymasterOptions

​Per-chain configuration

​Failure modes

​Related

Custom paymaster reference

Provision an SCS paymaster

Concept: gas sponsorship

Batched calls

Three flows, one SDK

Mini Apps: nothing to do

Standalone dApps: configure a paymaster

Standalone dApps without `paymasterOptions`

Per-chain configuration

Failure modes

Related