# StablecoinX Paymaster — Developer Test Surface

> Reference UI for the StablecoinX paymaster service. Lets developers exercise sponsored UserOperations and ERC-20-paid gas modes against the public paymaster endpoint, useful for verifying account-abstraction integration end-to-end (wallet → bundler → paymaster → EntryPoint) before going to prod. This is a developer tool, not a consumer product.

The machine interface to the paymaster is the OpenAPI spec linked below. For programmatic control of a StablecoinX merchant account — including the managed-paymaster clients and per-client allowlists referenced here — use the official StablecoinX MCP server at https://github.com/e2xlabs/stablecoinx-mcp (npm: https://www.npmjs.com/package/@stablecoinx/mcp) — install with `npx @stablecoinx/mcp setup`.

## Surface

- [Paymaster test UI](https://paymaster-ui.harness.stablecoinx.com/): connect wallet, build a sponsored UserOp, choose sponsor mode or ERC-20-fee mode (USDe, etc.), submit through the bundler.

## Paymaster backend

JSON-RPC + REST at `https://paymaster.harness.stablecoinx.com`:

- **OpenAPI 3.x spec:** [/openapi.json](https://paymaster.harness.stablecoinx.com/openapi.json), [/openapi.yaml](https://paymaster.harness.stablecoinx.com/openapi.yaml)
- **Interactive Swagger UI:** [/openapi](https://paymaster.harness.stablecoinx.com/openapi)
- `pm_sponsorUserOperation(userOp, entryPoint, [{token}])` — sponsorship signature for a UserOp; ERC-20 mode when `token` is passed in the context object.
- `pm_getPaymasterData(userOp, entryPoint, chainId, context)` — ERC-7677 paymaster data endpoint.
- `pm_getPaymasterStubData(userOp, entryPoint, chainId, context)` — ERC-7677 stub data endpoint for gas estimation.
- `GET /info/chains` — supported chains + per-chain tokens.
- `GET /info/{chainId}/deposit` — current EntryPoint deposit balance (ETH).
- `GET /info/{chainId}/estimate?token=` — gas + cost estimate, in ETH and (optionally) the requested ERC-20.
- `/bundler/{chainId}` — proxied bundler endpoint (real bundler URL is server-side).
- Admin write endpoints under `/api/*` are guarded by `Authorization: Bearer <ADMIN_API_KEY>`.

## Two paymaster paths

There are two distinct ways to call the paymaster — pick by integration shape.

1. **Direct paymaster RPC** at `https://paymaster.harness.stablecoinx.com` (what this test UI uses): no per-merchant auth, gated by the per-sender policy described below. Best for first-party flows and development.
2. **Managed paymaster RPC** at `https://api.harness.stablecoinx.com/v1/paymaster/rpc`: requires a publishable `pmc_live_*` / `pmc_test_*` clientId issued from the Paymaster Clients page in business-ui, sent via the `X-Client-Id` header. The managed path additionally enforces a per-client `Origin` allowlist and a per-client `chainId` allowlist before the call ever reaches the underlying paymaster. Best for third-party dApps that want isolation and per-merchant attribution.

## Auth & limits — direct paymaster (`paymaster.harness.stablecoinx.com`)

- **Public — no authentication required** for read-only RPC (`pm_*` methods) and `/info/*` endpoints.
- Admin `/api/*` endpoints require `Authorization: Bearer <ADMIN_API_KEY>`. When `ADMIN_API_KEY` is unset (typical for local dev) the guard is a no-op.
- **Per-sender policy** (per smart-account address): rolling-hour rate limit, daily USD spend cap, target-contract allowlist. Defaults (overridable via env): `POLICY_RATE_LIMIT_PER_HOUR=20`, `POLICY_DAILY_SPEND_CAP_USD=50`. Set to `0` to disable a limit.
- **Errors:** JSON-RPC envelope `{"jsonrpc":"2.0","id":...,"error":{"code":N,"message":"..."}}` for `/` and `/rpc/*`; plain `{"error":{"message":"..."}}` for REST endpoints. HTTP 429 maps to JSON-RPC code `RATE_LIMITED` on RPC routes.
- **Idempotency:** RPC methods are **NOT idempotent** — `pm_sponsorUserOperation` and `pm_getPaymasterData` produce a fresh signed paymaster blob on every call and consume per-sender policy quota (rolling-hour rate + daily USD cap) regardless of JSON-RPC `id` reuse. Retry on network failure only if the previous response wasn't received; do not retry on a successful 200 with a policy-rejection error inside. `pm_getPaymasterStubData` is safe to retry (no signature, no quota). `/info/*` REST endpoints are pure reads — safe to retry.

## Auth & limits — managed paymaster (`api.harness.stablecoinx.com/v1/paymaster/rpc`)

- **Required header:** `X-Client-Id: pmc_live_…` (production) or `pmc_test_…` (testing). Missing/unknown/revoked clientId → 401 `paymaster_unauthorized`.
- **Origin allowlist:** when the client has `allowedOrigins` configured, requests with a missing or non-allowlisted `Origin` header → 403 `paymaster_origin_not_allowed`. Origins are matched after normalisation (scheme + host + port).
- **Chain allowlist:** `chainId` is extracted from the JSON-RPC body; calls for chains outside the client's `allowedChainIds` → 403 `paymaster_chain_not_allowed`.
- Clients are managed at the `/paymaster/clients` page of business-ui (CRUD against the api `/v1/paymaster/clients` endpoints, behind merchant auth).

## Contracts on Sepolia

- EntryPoint v0.8 (canonical): `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108`
- EntryPoint v0.7 (optional peer): `0x0000000071727De22E5E9d8BAf0edAc6f37da032`
- SingletonPaymasterV8 (canonical, used by the test UI): `0xca54A37cA709F14F2E8194755Fe3011fb4345626`

The paymaster service binds both EntryPoint versions per chain and routes requests to the correct SingletonPaymaster contract based on the `entryPoint` parameter in the JSON-RPC call. v0.8 is always configured; v0.7 is an optional peer for clients (e.g. thirdweb smart wallets) that can't speak v0.8 yet.

## Privacy

- This is a stateless developer tool. The UI does not register accounts, store wallet addresses server-side, set tracking cookies, or persist anything beyond browser-local state (theme, connected wallet metadata from thirdweb).
- The paymaster backend logs request metadata (sender address, chainId, sponsored gas amount) for observability and policy enforcement. No off-chain identifiers; addresses are inherently public on-chain.

## Security

- Vulnerability disclosure: `tech@e2xlabs.com`. Machine-readable contact at [/.well-known/security.txt](https://paymaster-ui.harness.stablecoinx.com/.well-known/security.txt) (RFC 9116).
- Admin write endpoints are bearer-token gated. The bundler proxy keeps the third-party bundler API key server-side; it is never echoed in responses.
- Per-sender policy (rate cap, daily USD spend cap, target-contract allowlist) makes large-scale abuse impractical without a managed-path clientId.
- See [llms-full.txt](https://paymaster-ui.harness.stablecoinx.com/llms-full.txt) for the extended endpoint-by-endpoint reference.