Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.startale.com/llms.txt

Use this file to discover all available pages before exploring further.

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

FlowWho paysWhat you configure
Mini AppStartale hostnothing
Standalone dApp with paymasterYou (or your sponsor wallet)paymasterOptions on createStartaleAccountSDK or startaleConnector
Standalone dApp without paymasterThe end user, in ETH from their smart accountnothing, 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.
MethodSponsored by host
eth_sendTransactionyes
wallet_sendCallsyes
personal_signno gas, signature only
eth_signTypedData_v4no 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',
    },
  },
})
FieldTypeNotes
paymasterOptions[chainId].urlstringThe paymaster RPC URL. SCS-hosted paymasters live at https://paymaster.scs.startale.com/v1; self-hosted services use whatever URL you deploy.
paymasterOptions[chainId].idstringThe 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

SymptomLikely causeFix
paymaster declined to sponsorPolicy hit (rate limit, allowlist) on your paymaster.Inspect the paymaster’s policies in the SCS Portal or your service logs.
insufficient funds for gasUser-pays flow with an empty smart account.Top up the smart account, or configure paymasterOptions.
paymaster context invalidpaymasterOptions[chainId].id is wrong or missing.Re-copy the paymasterId from the SCS Portal or check your service config.
Sponsorship works on one chain onlypaymasterOptions 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.