Swap API

Swap stablecoins without holding gas. The user signs; a solver pays the gas and delivers the output from its own inventory.

The distinguishing property is par pricing. When both sides of a swap are Brale-issued tokens tracking the same peg (SBC, cfUSD), they fill at true par: 1:1, 0 bps, zero slippage. Not "low fee". The solver earns nothing on the swap itself; the only cost is gas, which the solver absorbs. 1 cfUSD on Solana becomes exactly 1 SBC on Base.

What you can do

Redemption is the one non-par flow. Exiting a Brale stable to USDC routes through a DEX anchor pool, so the output reflects real pool depth for the size. Everything else is par.

Every path on these pages is relative to https://swap.stablecoin.xyz, which serves Base mainnet (chain 8453) and Solana mainnet. Examples below are written as .../api/... — substitute that host.

All endpoints return JSON. Successful and error responses include the header X-Swap-API-Version: 1. Money-moving routes also require an x-api-key header — see Authentication.

Errors look like:

{ "error": "owner required", "code": "BAD_REQUEST" }

Codes in use today: BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, INVENTORY_SHORT, CAP_EXCEEDED, FLOW_DISABLED, RATE_LIMITED, INTERNAL.

Amounts described as ...Base or ...Raw are integer strings in the token's smallest units. uiAmount fields are human decimals — send a string (preferred) or a number.

Machine-readable contract: OpenAPI (repo) — partner routes only. Human walkthroughs are the pages below.

How a swap executes

Every swap follows the same three beats, whether it's same-chain or cross-chain:

1. Quote. Ask the API what you'd receive. For par routes this is deterministic; for redemption it's a live DEX quote with a signed proceeds floor.
2. Sign. The user signs an EIP-712 order that binds the terms (tokens, amounts, solver, deadline, nonce) plus a token permit. Nothing is submitted from the user's wallet, so no gas is needed.
3. Submit. You POST the signed order. The solver verifies it against its own view, then relays it on-chain and pays the gas.

Because the user signs the terms rather than a transaction, a relaying solver cannot alter what was agreed. The order struct is checked on-chain at execution.

Same-chain swaps settle atomically in a single transaction. Cross-chain swaps lock the input in escrow, and the solver delivers on the destination before claiming, with an M-of-N attestor quorum gating the claim and a permissionless refund if the order expires unfilled. Integrators poll status; they do not call settle or refund.

Access control

Money-moving routes are authenticated with a partner API key — a sbc-… key you create yourself at dashboard.stablecoin.xyz, sent as an x-api-key header. Read-only discovery routes (health, capabilities, info, balance) stay open.

Enforcement is in soft launch: a protected request without a valid key is still served today and the failed check only logged, but it will return 401 once enforcement is switched on. Add your key now and the flip is a non-event for you. See Authentication for how to get one, which routes need it, and how rotation propagates.

Size limits apply independently of your key. For redemption they come back on the quote (maxUsd, hardMaxUsd); for par routes the binding constraint is the solver's live inventory in the output token, reported by /api/base/info. Read them rather than assuming a value.

Who should call what

Next steps

• Authentication: get a partner key and send it
• Quotes and token info: read endpoints, balances, redemption pricing
• Same-chain swaps: the sign-and-relay flow on Base and Solana
• Cross-chain swaps: Base ↔ Solana intents and status polling