# StablecoinX API

> Merchant API for StablecoinX: stablecoin payment sessions, webhooks, merchant account management, floYsh yield deployments and the managed ERC-4337 paymaster. This host serves JSON APIs only; the machine-readable contract is the OpenAPI spec.

## Specs

- [Integrator OpenAPI](https://api.harness.stablecoinx.com/openapi.json) ([YAML](https://api.harness.stablecoinx.com/openapi.yaml), Swagger UI at [/openapi](https://api.harness.stablecoinx.com/openapi)): health, payment sessions, paymaster JSON-RPC and the bundler proxy.
- [Full OpenAPI](https://api.harness.stablecoinx.com/docs/openapi.json) ([YAML](https://api.harness.stablecoinx.com/docs/openapi.yaml), Swagger UI at [/docs](https://api.harness.stablecoinx.com/docs)): adds merchant auth, dashboard routes, webhooks and paymaster management.

## Authentication

- `Authorization: Bearer sk_*` — server-to-server secret key; creates payment sessions and manages webhooks, nothing else. Minted at `POST /v1/merchants/me/api-keys` (merchant JWT) and returned once.
- `Authorization: Bearer <JWT>` — merchant session for the dashboard and paymaster management routes. Headless: `GET /v1/auth/login-payload?address=<wallet>`, 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.

## Managed paymaster

- `POST https://api.harness.stablecoinx.com/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.harness.stablecoinx.com/v1/paymaster/bundler/{chainId}` — ERC-4337 bundler JSON-RPC proxy.
- Networks, sponsorship rules and per-chain contract addresses: [paymaster llms.txt](https://paymaster-ui.harness.stablecoinx.com/llms.txt) and [llms-full.txt](https://paymaster-ui.harness.stablecoinx.com/llms-full.txt).

## Merchant dashboard

- [https://business.harness.stablecoinx.com](https://business.harness.stablecoinx.com/) — the UI over the same routes; see its [llms.txt](https://business.harness.stablecoinx.com/llms.txt).

## 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.harness.stablecoinx.com/) — 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.harness.stablecoinx.com/llms-full.txt) — product overview and navigation, including how to find a deployment's public site.
- [Merchant OpenAPI](https://api.harness.stablecoinx.com/docs#/yield-deployments) ([JSON](https://api.harness.stablecoinx.com/docs/openapi.json)) — configuration routes under `/v1/merchants/me/yield-deployments`, authenticated with a merchant JWT. 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.harness.stablecoinx.com/.well-known/security.txt) (RFC 9116).