# Spout Partner API

> Spout is a non-custodial protocol on Solana. Users borrow stablecoins at 0% interest against tokenized US
> equities, or lend stablecoins into a two-tranche pool funded by systematic covered call premium. This site is
> the developer surface for integrating either side.

Status: the API is not live. This is a design contract so partners can build before the backend ships. The
sandbox returns fictional data.

## The things an integration gets wrong

1. Write endpoints do not execute. They return an unsigned, base64 serialized Solana transaction plus a
   transaction id. The partner has the user sign it and submits it. A 200 means "here is a valid transaction",
   not "it happened". Nothing is real until it confirms on chain.
2. Built transactions expire. They carry a recent blockhash. Past `expires_at`, rebuild rather than retrying.
3. Health is per collateral position, never pooled. `GET /v1/borrow/health` returns an OBJECT with a
   `positions` array, one entry per collateral asset, not a bare array. Two positions in one wallet do not
   support each other: one can be liquidated while the other is comfortable. The `aggregate` block is display
   only and must not be used as a safety signal.
4. Amounts are decimal strings, never JSON numbers. Use a decimal library. Each amount is paired with an
   `asset`, and `decimals` sits on the asset object.
5. Interest is 0%, and `estimated_borrow_cost_apr` is a separate estimate of the upside given up when a written
   covered call finishes in the money. It is not charged and not deducted. Show it alongside the 0%, never
   instead of it.
6. Send `Idempotency-Key` on every POST, generated where the action is decided rather than inside an HTTP
   helper. Reusing a key with a different body returns 409.
7. Branch on `error.code`, never on `error.message`.
8. Pagination is cursor based: `starting_after`, `ending_before`, `limit` capped at 100. No offsets.
9. The junior tranche has no instant exit, and its queued exit carries a 45 day notice period against the
   senior tranche's 7. Preview a withdrawal before the user commits.
10. Webhooks are at least once and unordered. Deduplicate on the event's top-level `id` and verify
   `Spout-Signature`.

## Docs

- [Overview and quickstart](/index.html): the concepts, conventions and a runnable quickstart
- [API reference](/reference.html): every operation, parameter, schema and error
- [OpenAPI specification](/openapi.yaml): OpenAPI 3.1, the source of truth for everything else

## Optional

- Repository: github.com/SpoutFinance/spout-builders carries the sandbox, an annotated reference integration
  and an MCP server. It is private during the preview; email builders@spout.finance for access.
- MCP server: run `node mcp/server.js` from the repository to let a coding agent query the spec directly.
  Tools: integration_notes, list_endpoints, get_endpoint, get_schema, list_error_codes, search_spec