Paymaster

The Stablecoin Harness Paymaster lets your users transact without holding the chain’s native token. Choose whether your project pays gas (sponsor mode) or the user pays in stablecoins (user-pays mode) — both run from the same contract, switchable per transaction.

Modes

Mode	Who pays	When to use
Sponsor (0)	Your project’s ETH deposit	Welcome flows, fee-free product UX, acquisition campaigns
User pays USDe (1)	The user, in USDe	Default for paid transactions where you don’t want to subsidize gas

The mode is one byte in paymasterData. The Paymaster API picks the mode based on your project policy and signs accordingly.

Architecture

User wallet ─► Your app ─► Paymaster API ─► Bundler ─► EntryPoint ─► Paymaster Contract
                          (signs paymasterData)                       (charges chosen mode)

Smart Account. ERC-4337 v0.8 SimpleAccount (or your own implementation).
Bundler. Any compliant ERC-4337 bundler.
Paymaster contract. SingletonPaymasterV8 — one contract, both modes.
Paymaster API. Hosted by StablecoinX; signs paymasterData for your UserOps.

Integrate

Request paymaster data

curl -X POST https://api.stablecoinx.com/v1/paymaster/sign \
  -H "Authorization: Bearer $STABLECOINX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userOp": { /* unsigned UserOperation */ },
    "mode": "sponsor",
    "chain": "base"
  }'

Response:

{
  "paymasterAndData": "0x...",
  "preVerificationGas": "0x...",
  "verificationGasLimit": "0x...",
  "callGasLimit": "0x..."
}

TypeScript

import { signPaymasterData } from "@stablecoinx/sdk";

const { paymasterAndData } = await signPaymasterData({
  userOp,
  mode: "user_pays",     // or "sponsor"
  chain: "base",
});

// merge paymasterAndData into your UserOp, then send via your bundler

Project policy

Configure your default mode and overrides from the dashboard:

Default mode — what every UserOp uses unless overridden.
Sponsor budget — daily and monthly ceilings on sponsored gas.
Per-sender policy — allowlist, ratelimit, and sponsorship caps per smart account.
Token allowlist — which stablecoins are accepted in user-pays mode.

Supported chains

Chain	EntryPoint	Paymaster
Base	v0.8	GA
Arbitrum	v0.8	GA
Optimism	v0.8	GA
Ethereum	v0.8	GA
Base Sepolia	v0.8	Sandbox

Paymaster API reference — full endpoint and JSON-RPC surface.
Session Payment — pair gas sponsorship with stablecoin checkout.