Skip to content
StablecoinX StablecoinX

Paymaster

The Stablecoin Harness Paymaster lets your users transact without holding the chain’s native token. Register your dApp with a publishable client key, allowlist the contracts you’re willing to back, and every sponsored UserOperation is attributed to your merchant account.

How it works

Section titled “How it works”
dApp ─► /v1/paymaster/rpc ─► Bundler ─► EntryPoint ─► Paymaster Contract
        (X-Client-Id + Origin)                         (sponsors the UserOp)
  • Smart Account. An ERC-4337 smart account (in-app wallet with sponsored gas), or your own implementation.
  • Bundler. Any compliant ERC-4337 bundler.
  • Paymaster contract. ERC-4337 paymasters are deployed per chain for both EntryPoint versions: a v0.8 contract — what the managed proxy targets — and a v0.7 peer, used by smart-account SDKs that can’t yet speak EntryPoint v0.8.
  • Paymaster API. The managed proxy at api.harness.stablecoinx.com authenticates your client key, checks the contract allowlist, signs, and records the operation.

Modes

Section titled “Modes”

The paymaster contract supports two modes, selected per UserOp by the request context:

ModeWho paysWhen
Sponsor (0)Your project’s paymaster depositDefault — the platform’s verifying mode.
ERC-20 / user-pays (1)The user, in a supported stablecoinSelected when the request context names a sponsorship token (e.g. USDe).

The mode is encoded into paymasterData; the platform picks it based on whether a sponsorship token is requested and signs accordingly. Supported sponsorship tokens are configured per chain.

Credentials

Section titled “Credentials”

Two lists per merchant, both managed from the dashboard or the Paymaster API:

  • Publishable clients — pmc_live_* keys safe to ship in your frontend bundle. Sent as X-Client-Id on every JSON-RPC call. Security is a strict per-key allowedOrigins[] + allowedChainIds[] whitelist, not secrecy. Server keys (sk_*) are not valid here.
  • Contract allowlist — (chainId, contractAddress) tuples you’re willing to back. The paymaster only signs UserOps whose decoded target is in this list. By default no contract is allowed.

Integrate

Section titled “Integrate”

Point your smart-account SDK’s paymaster at the managed RPC endpoint and set your client ID:

RPC:    https://api.harness.stablecoinx.com/v1/paymaster/rpc
Header: X-Client-Id: pmc_live_...

The SDK calls pm_getPaymasterStubData / pm_getPaymasterData (ERC-7677); the platform decodes the UserOp target, checks your allowlist, and signs. No other credentials are required — strict Origin matching does the security work. See the Paymaster API reference for the JSON-RPC shapes.

Attribution

Section titled “Attribution”

Every signed or denied operation produces a SponsorshipUsage record visible under Paymaster → Activity, moving through:

denied_target / denied_upstream            (pre-sign denials)
submitted ─► onchain_success / onchain_reverted / dropped

Each finalised row carries actualGasCost, actualGasUsed, txHash, and a Chainlink ETH/USD snapshot (so historical USD figures don’t drift). The platform runs a single shared EntryPoint deposit; per-merchant billing and spend caps are not part of this layer.

Supported chains

Section titled “Supported chains”
ChainEntryPoint
Basev0.7 + v0.8
Arbitrumv0.7 + v0.8
Ethereumv0.7 + v0.8

Testnets (Base Sepolia, Arbitrum Sepolia, Ethereum Sepolia) are available for testing.

Section titled “Related”