# StablecoinX Treasury

> Non-custodial on-chain treasury dashboard for stablecoin holders. Aggregates wallet balances and yield positions across EVM chains, surfaces P&L history, and executes deposits/withdrawals into yield-bearing stablecoin vaults via account-abstraction smart accounts with sponsored gas.

The machine interface to this dashboard's data is the Treasury API OpenAPI spec linked below. For programmatic control of a StablecoinX merchant account (payment sessions, API keys, paymaster clients/allowlist, webhooks), 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`.

## Surfaces

- [Dashboard](https://treasury.harness.stablecoinx.com/): aggregated treasury view, yield positions, P&L history, deposit (put-to-work) and withdraw (cash-out) flows.

## APIs

- **Treasury API** — `https://treasury-api.harness.stablecoinx.com`
  - OpenAPI 3.x spec: [/openapi.json](https://treasury-api.harness.stablecoinx.com/openapi.json), [/openapi.yaml](https://treasury-api.harness.stablecoinx.com/openapi.yaml)
  - Interactive Swagger UI: [/openapi](https://treasury-api.harness.stablecoinx.com/openapi)
  - REST under `/v1/treasury/*` (wallet registration, snapshot-backed aggregate read with ETag, sync status) and `/v1/dashboard/*` (history, P&L, put-to-work / cash-out quotes, redeem calldata, config).
  - Health: `GET /health` → `{"status":"ok"}`
- **Smart-account gas sponsorship** — `https://paymaster.harness.stablecoinx.com` (ERC-4337 paymaster RPC, used here via EntryPoint v0.7). See [paymaster-ui llms.txt](https://paymaster-ui.harness.stablecoinx.com/llms.txt).

## Auth & limits

- **Public — no authentication required.** All endpoints are read-only or operate on user-supplied wallet addresses (no private data).
- **Global rate limit:** 120 req/min/IP (NestJS `ThrottlerGuard`).
- **`POST /v1/treasury/wallets`** tightened to 30 req/min/IP (each call may trigger a 90-day multi-chain HyperSync backfill).
- **Errors:** standard NestJS HTTP envelope — `{"statusCode":N,"message":"...","error":"..."}`.
- **Idempotency:** all `POST` endpoints are naturally idempotent — the API never mutates external state directly. `/v1/treasury/wallets` does `getOrCreate` (re-adding an onboarded wallet returns `status:"ready"`). `/v1/treasury/wallets/{address}/refresh` is a no-op during the 60s cooldown. `/v1/treasury/aggregated` is a read despite the POST verb (POST is used so the request body can carry a wallet-address array). `/v1/dashboard/{history,pnl}` are pure reads. `/v1/dashboard/{put-to-work,cash-out,redeem-*}` return EVM calldata only — on-chain side effects happen when the user signs and submits the returned tx, not when the API is called. Safe to retry any of these on network failure.

## Yield protocol coverage

Yield positions and deposit/withdraw flows are sourced from LI.FI's vault catalog (any EVM stablecoin vault LI.FI lists is discoverable — e.g. Aave V3, Compound V3, Morpho vaults when present), plus dedicated adapters:

- **Ethena sUSDe** — `redeem-direct` for instant ERC-4626 redeem, plus two-phase `cooldownShares` → `unstake` flow for the Ethena cooldown queue.
- **floYSH (Easeflow YSH vault)** — live APY feed from the ysh-web Hasura indexer; deep-link CTA from the dashboard.

## Architecture

- Frontend: React SPA (Vite), thirdweb in-app wallet, viem.
- Smart account: ERC-4337 sponsored UserOps on EntryPoint v0.7 via StablecoinX's SingletonPaymasterV7 peer. Falls back to thirdweb's default sponsorship on chains where our V7 peer isn't deployed yet.
- Supported chains for sponsored ops (mainnet): Ethereum, Base, Arbitrum. Read-side aggregation covers any chain the wallet holds positions on.

## Methodology

- **Balances** come from `wallet_holdings`, refreshed by `TransferSyncService` (HyperSync indexer) plus an inline `quickRefresh` (balanceOf multicall) every 10 seconds on each `/v1/treasury/aggregated` poll.
- **USD valuations** use the price oracle feed embedded in the aggregate snapshot. Momentary divergence from live AMM prices is possible.
- **Yield APYs** are surfaced from each protocol's published feed (e.g. the floYSH Hasura indexer for the YSH vault). Not independently audited by StablecoinX.
- **P&L over long windows** uses linear approximation; drift vs proper compounding is under 0.5% over 90 days.
- **Vault coverage** is driven by LI.FI's vault catalog plus dedicated readers for Ethena sUSDe and floYSH. When a vault implements EIP-4626 but LI.FI doesn't catalog it, the `/v1/dashboard/redeem-direct` fallback path still works.

## Privacy

- Non-custodial. The dashboard never holds user funds; every state-changing action is signed by the user's smart-account wallet.
- The backend stores only on-chain-derived state (wallet address, observed balances and positions). No off-chain identifiers, no email, no IP-linked records, no cookies beyond what the SPA uses for session state and theme preference.
- Wallet addresses are user-supplied; anyone can query any address (this is on-chain public data).

## Security

- Vulnerability disclosure: `tech@e2xlabs.com`. Machine-readable contact at [/.well-known/security.txt](https://treasury.harness.stablecoinx.com/.well-known/security.txt) (RFC 9116).
- See [llms-full.txt](https://treasury.harness.stablecoinx.com/llms-full.txt) for the extended endpoint-by-endpoint reference.