# StablecoinX API > Merchant API for StablecoinX: stablecoin payment sessions, webhooks, merchant account management, floYsh yield deployments and the managed ERC-4337 paymaster. The machine-readable contract is the OpenAPI spec; human pages: Swagger UI and the webhook guide. ## Specs - [Integrator OpenAPI](https://api.dev.scx.easeflow.io/openapi.json) ([YAML](https://api.dev.scx.easeflow.io/openapi.yaml), Swagger UI at [/openapi](https://api.dev.scx.easeflow.io/openapi)): health, payment sessions, paymaster JSON-RPC and the bundler proxy. - [Full OpenAPI](https://api.dev.scx.easeflow.io/docs/openapi.json) ([YAML](https://api.dev.scx.easeflow.io/docs/openapi.yaml), Swagger UI at [/docs](https://api.dev.scx.easeflow.io/docs)): adds merchant auth, dashboard routes, webhooks and paymaster management. ## Guides - [Webhook guide](https://api.dev.scx.easeflow.io/guides/webhooks.md) ([HTML](https://api.dev.scx.easeflow.io/guides/webhooks)): registering an endpoint, the delivery format and headers, a signature verifier, retries and secret rotation. ## Authentication - `Authorization: Bearer sk_*` — server-to-server secret key. Creates payment sessions (`POST /v1/sessions`), manages webhook endpoints and reads their deliveries (`/v1/webhooks`) and a session's webhook delivery status, retries webhooks and forwarders, and reads the merchant's own data: profile, sessions, balance, charges and statements, paymaster usage, allowlist, limits, deny rules, activity and overview, and yield deployments. It cannot use the API key or paymaster client routes (create, list, update, revoke), update the profile, or change paymaster configuration, top-ups or yield deployments — those require the merchant JWT. Usage and activity rows carry the publishable `pmc_*` client id of each operation. Each OpenAPI operation lists the credentials it accepts. Minted at `POST /v1/merchants/me/api-keys` (merchant JWT) and returned once. - `Authorization: Bearer ` — merchant session for the dashboard and paymaster management routes. Headless: `GET /v1/auth/login-payload?address=`, sign the returned SIWE payload with that wallet, exchange it at `POST /v1/auth/verify`. The merchant account is keyed by the signing address, so a wallet of your own gets its own account; the dashboard's email login signs with a thirdweb in-app smart account, and the StablecoinX MCP server below reaches that same account with the same email one-time code. - `X-Client-Id: pmc_live_*` / `pmc_test_*` — publishable paymaster client id for `POST /v1/paymaster/rpc` and `POST /v1/paymaster/bundler/{chainId}`. Created at `POST /v1/paymaster/clients` (merchant JWT) or in the dashboard; `pmc_live_*` covers mainnets and `pmc_test_*` testnets. ## Rate limits Public endpoints are rate-limited at the edge (Cloud Armor), per source IP over a 60s window, by request category. Defaults, requests/min/IP: auth (`GET /v1/auth/login-payload`, `POST /v1/auth/verify`) 30; managed paymaster (`POST /v1/paymaster/rpc`, `POST /v1/paymaster/bundler/{chainId}`) 600; public polling (`GET /v1/sessions/*`, `GET /assets/*`) 240; server-to-server (`POST /v1/sessions*`, `POST /v1/webhooks*`) 300; everything else 300. Over-limit requests get `429`; an IP that keeps flooding past twice its category limit is banned for 10 minutes. Back off on `429` and retry; merchant backends behind a shared egress IP should pace concurrent workers so the whole fleet stays under the server-to-server budget. ## Managed paymaster - `POST https://api.dev.scx.easeflow.io/v1/paymaster/rpc` — `pm_getPaymasterStubData`, `pm_getPaymasterData`, `pm_sponsorUserOperation` with `params = [userOp, entryPoint, chainId, context?]`. The OpenAPI operation lists every error code and message. - `POST https://api.dev.scx.easeflow.io/v1/paymaster/bundler/{chainId}` — ERC-4337 bundler JSON-RPC proxy. - Networks, sponsorship rules and per-chain contract addresses: [paymaster llms.txt](https://paymaster-ui.dev.scx.easeflow.io/llms.txt) and [llms-full.txt](https://paymaster-ui.dev.scx.easeflow.io/llms-full.txt). ## Merchant dashboard - [https://business.dev.scx.easeflow.io](https://business.dev.scx.easeflow.io/) — the UI over the same routes; see its [llms.txt](https://business.dev.scx.easeflow.io/llms.txt). ## Webhook delivery Endpoints and delivery history are managed under `/v1/webhooks` with an `sk_*` secret key — see the [Webhooks routes](https://api.dev.scx.easeflow.io/docs#/Webhooks) in the full OpenAPI ([JSON](https://api.dev.scx.easeflow.io/docs/openapi.json)). - **At-least-once.** Every recorded event is delivered at least once to each endpoint that was subscribed when the event was recorded, as long as the endpoint answers 2xx within the automatic retry window. A delivery whose endpoint is disabled, or whose URL fails the dispatch-time check, is marked `failed` without retry; a DNS resolution failure or a signing secret that cannot be decrypted is a failed attempt and follows the automatic retry schedule; a manual resend (`POST /v1/sessions/{id}/retry-webhook` or the dashboard) reaches only the session's latest event, sent to the endpoints enabled and subscribed to its type at resend time — an endpoint added later can receive an older event, and `POST /v1/webhooks/{id}/deliveries/{deliveryId}/resend` replays any retained delivery, its stored payload unchanged, to its original endpoint, which must still be enabled and subscribed to the event type. The same event can arrive more than once: a 2xx that did not reach StablecoinX (timeout, dropped connection), a worker failure after your 2xx, or a manual resend, which sends the event again even after a successful delivery. - **No ordering guarantee.** Events of one session can arrive in any order — a retried `session.confirming` can arrive after `session.completed`. - **Session status and resend.** Both select the same latest event. Events co-produced by one payment share a timestamp; tied events prefer types subscribed to by an enabled endpoint, then descending event id. Selection never falls back to an earlier timestamp. Use delivery history to inspect or replay other retained events. - **Stable event id.** Every event has an id `evt_*` in the body's `id`, copied to the `X-StablecoinX-Event-Id` header. It is identical on every delivery of that event and on every endpoint the event is sent to. - **Dedupe on the body `id` after verifying the signature.** `X-StablecoinX-Signature` covers `{timestamp}.{rawBody}` only; the `X-StablecoinX-Event-Id` header is unsigned. - **Recommended handler:** verify the signature → in one database transaction insert the event id into a table with a UNIQUE constraint together with your own state change (or a job row) → commit → respond 2xx → run external side effects (emails, outbound calls) from the job, idempotently. On a unique-key conflict respond 2xx without re-running anything. When several endpoints share one store, key the table on the consuming system and the event id. Respond within 10 seconds: a slower response times out and is retried. - **Ordering:** treat an event as a signal, not as the state. From the job, not the request path, re-read the session with `GET /v1/merchants/me/sessions/{id}` (`sk_*`, full OpenAPI) and act on its current `status` and `amountReceivedByChain`; do not order events by their bodies or `createdAt`. Never move an order back from `completed`; `session.expired` can still be followed by `session.completed`. - **Retention:** keep processed event ids for as long as you need to suppress repeated side effects — any retained delivery, including a balance event, can be manually replayed at any time. ## floYsh / Yield as a Service floYsh is StablecoinX's Yield as a Service (YaaS): a branded stablecoin-yield site built around Ethena USDe/sUSDe vaults. Merchants manage the site's deployment, branding and domains in Business UI; customers use the public site to connect a wallet and access the vault. - [Business UI](https://business.dev.scx.easeflow.io/) — sign in, open **Deployments → Yield** (`/deployments/yield`), and choose **New deployment** (or **Create deployment** for the first one). Open a deployment to edit its branding, manage **Domains**, and inspect **Contracts**. - [Business UI guide](https://business.dev.scx.easeflow.io/llms-full.txt) — product overview and navigation, including how to find a deployment's public site. - [Merchant OpenAPI](https://api.dev.scx.easeflow.io/docs#/yield-deployments) ([JSON](https://api.dev.scx.easeflow.io/docs/openapi.json)) — configuration routes under `/v1/merchants/me/yield-deployments`, authenticated with a merchant JWT; the list and read routes also accept an `sk_*` secret key. These routes are in the full merchant spec, not the integrator spec at `/openapi`. The MCP server currently has no yield-deployment tools; guide users to Business UI for floYsh management. ## MCP server StablecoinX MCP server (local stdio, no hosted endpoint): source https://github.com/e2xlabs/stablecoinx-mcp, npm [`@stablecoinx/mcp`](https://www.npmjs.com/package/@stablecoinx/mcp), MCP Registry [`io.github.e2xlabs/stablecoinx-mcp`](https://registry.modelcontextprotocol.io/v0/servers/io.github.e2xlabs%2Fstablecoinx-mcp/versions/latest). Install with `npx @stablecoinx/mcp setup`. ## Security - Vulnerability disclosure: `tech@e2xlabs.com`, machine-readable at [/.well-known/security.txt](https://api.dev.scx.easeflow.io/.well-known/security.txt) (RFC 9116).