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.

paymasterOptions is the App SDK’s hook into the ERC-4337 paymaster layer. Use it whenever you ship a standalone dApp that needs to sponsor gas, or when you need finer-grained control than the default flow gives you. For the high-level model of who pays in which context, see Gas sponsorship. This page is the deep dive: what the paymaster service looks like on the wire, what paymasterOptions injects into requests, and how to choose between SCS-hosted and self-hosted services.

​
Two valid backends

BackendWhen to pick itSetup time
SCS Managed paymasterYou want SCS to settle gas in fiat on a monthly cycle.Minutes (provision in the SCS Portal).
SCS Self-funded paymasterYou want a hard ETH cap on sponsorship and prefer crypto settlement.Minutes plus an ETH top-up.
Self-hosted ERC-7677 serviceYou need custom logic the Portal cannot express (per-tenant rules, signed allowlists, off-platform settlement).Hours to days, depending on your sponsorship rules.
The App SDK call site is identical for all three. The difference is in what you point paymasterOptions[chainId].url at.

​
Configure

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.my-app.com/sponsor',
      id: 'pm_live_my_paymaster_id',
    },
  },
})
FieldTypeNotes
urlstringThe paymaster JSON-RPC endpoint. SCS-hosted: https://paymaster.scs.startale.com/v1?apikey=YOUR_API_KEY. Self-hosted: whatever you deploy.
idstringThe value forwarded as paymasterId in the paymasterContext of every paymaster RPC call.
Internally, the SDK uses paymasterOptions to populate the paymasterService field of the EIP-5792 capabilities attached to wallet_sendCalls. From there the bundler routes paymaster requests to your URL with the id in context.

​
ERC-7677 paymaster service surface

A custom paymaster service must implement the two methods defined by ERC-7677: pm_getPaymasterStubData and pm_getPaymasterData. Both run against the same JSON-RPC endpoint.

​
pm_getPaymasterStubData

Called during gas estimation. Return a stub paymaster signature that lets the bundler estimate gas without committing to a real signature. Request 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "pm_getPaymasterStubData",
  "params": [
    {
      "sender": "0x...",
      "nonce": "0x0",
      "callData": "0x...",
      "callGasLimit": "0x...",
      "verificationGasLimit": "0x...",
      "preVerificationGas": "0x...",
      "maxFeePerGas": "0x...",
      "maxPriorityFeePerGas": "0x..."
    },
    "0x...EntryPoint",
    "0x...chainId",
    {
      "id": "pm_live_my_paymaster_id"
    }
  ]
}
Response (EntryPoint v0.7) 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "paymaster": "0x...PaymasterAddress",
    "paymasterData": "0x...stubBytes",
    "paymasterVerificationGasLimit": "0x...",
    "paymasterPostOpGasLimit": "0x..."
  }
}

​
pm_getPaymasterData

Called after gas estimation. Return the real paymaster signature for the now-finalised UserOperation. The request shape is identical; the response is the same as above but with a real paymasterData instead of a stub.

​
What goes in the context object

paymasterOptions[chainId].id becomes paymasterContext.id in the request payload. SCS paymasters expect this to be the paymasterId issued by the Portal. Self-hosted services can interpret it however they like; many use it as a tenant key to look up a sponsorship policy.

​
Picking the right path

Use SCS Managed

SCS pays gas, bills you in fiat. Fastest to ship; no infrastructure to operate.

Use SCS Self-funded

You top up an ETH balance on the paymaster contract. Hard cap; crypto settlement.

Self-host ERC-7677

Run your own service when you need policies the Portal cannot express. You implement pm_getPaymasterStubData and pm_getPaymasterData.

No paymaster

Skip paymasterOptions and let users pay gas from their smart account’s ETH balance.

​
Operational guidance

API keys. SCS paymaster URLs include an apikey query parameter. If you embed the URL in client code, scope the key tightly with SCS Portal gas policies. For self-hosted services, terminate authentication on your own gateway.
ConcernRecommendation
Per-chain rulesConfigure paymasterOptions per chain id; omit chains where users should pay.
Per-user policyEncode user identity into id, or run a self-hosted ERC-7677 service that resolves policy from the sender field.
Spend capsUse SCS Portal gas policies for managed and self-funded; enforce caps yourself for self-hosted.
AuditingLog every pm_getPaymasterData call alongside the resulting UserOperation hash; reconcile against the bundler receipts.

App SDK gasless flows

The three runtime flows (Mini App, configured, user-pays) explained at the SDK call site.

AA SDK Portal setup

Mint and tune SCS paymasters. Same Portal whether you consume them via the App SDK or the AA SDK.

Sponsored paymaster (AA)

The AA SDK call site. Useful for backend services or framework-free integrations.

ERC-20 paymaster

Charge gas in a token instead of ETH.