Put Spout inside your product

Read this first

The API builds transactions. It does not execute them.

Spout is a non-custodial protocol on Solana. The API never moves user funds and never holds a private key. If you have integrated a custodial fintech API before, this is the one structural difference that shapes your whole integration, so it is worth understanding before you read anything else.

Every write endpoint that builds a transaction also returns a simulation block: a plain-language summary and a list of before and after effects. Render that as your confirmation screen. Users who cannot read what they are signing do not sign.

Quickstart

Running in about a minute

The sandbox is served from the specification itself, so it validates your requests the same way the live API will and returns the shapes the spec promises. During the preview any bearer token is accepted, but the header itself is still required: send it and a missing-key bug shows up now rather than on launch day.

Call the hosted sandbox

# protocol state, a good call to make on app boot
$ curl -H "Authorization: Bearer sk_test_anything" \
     https://sandbox.api.spout.finance/v1/protocol/stats

# what a partner sees before building a borrow screen
$ curl -H "Authorization: Bearer sk_test_anything" \
     "https://sandbox.api.spout.finance/v1/assets?limit=5"

Or run the whole thing locally

The repository carries the same sandbox, an annotated reference integration and an MCP server. It is private during the preview, so ask us for access and we will add you.

$ git clone https://github.com/SpoutFinance/spout-builders
$ cd spout-builders
$ npm install

$ npm run mock        # terminal 1: the sandbox on 127.0.0.1:4010
$ npm run example     # terminal 2: an annotated borrow flow against it

The example walks the full flow and prints what a real integration would do at each step, including the parts it cannot do without a wallet. It is written to be read as much as run.

Test your error paths early

Most integrations that fail in production fail because nobody exercised the error branches, and those are the ones a user hits at the worst moment. The sandbox honours the Prefer header so you can force any status or named example on demand.

$ curl -H "Authorization: Bearer sk_test_anything" \
     -H "Prefer: code=422, example=protocol_paused" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: manual-test-1" \
     -d '{"wallet":"7Np41oe...","asset":"AAPL","collateral_amount":"10","borrow_amount":"1000"}' \
     https://sandbox.api.spout.finance/v1/borrow/loans

Named examples available on the 422: exceeds_max_ltv, insufficient_collateral, asset_not_accepting_deposits, protocol_paused, stale_price_feed.

Concepts

Three things partners get wrong

None of these are API quirks. They are product facts that your UI has to reflect honestly, and each one has bitten someone.

Interest is 0%, and there is still a cost

The 0% is not promotional. Lender yield comes from covered calls written against the collateral, not from the borrower. But when a written call finishes in the money, the upside above the strike is given up, and that is a real cost to the borrower.

estimated_borrow_cost_apr on the asset object is our estimate of that cost, annualised from historical cycles. It is an estimate, it is not charged, and it is not deducted from the balance. Show it next to the 0% rate, never instead of it. Presenting 0% alone is misleading; presenting the cost alone is also misleading.

Health is per position, never pooled

Every partner arrives assuming one account-wide number. There is one health factor per loan, and liquidation reads only the loan that crossed its own 1.00. Drag the AAPL price and watch the NVDA rail stay exactly where it is.

This differs from Aave, Compound and every margin account your users have used, which is exactly why GET /v1/borrow/health returns an object with a positions array, one entry per collateral asset. There is also an aggregate block for a summary line and it is documented as display only. If you compute a single portfolio health number and present it as a safety signal, your users will be liquidated while your UI says they are fine.

The lending pool has two tranches with different exits

Junior absorbs losses before senior and is compensated for it. There is no instant exit from junior. Call POST /v1/lend/withdrawals with preview: true and show the user the haircut or the estimated wait before they commit to anything. A lender who discovers a notice period after clicking withdraw is a support ticket and a complaint.

APY figures are estimates from trailing realised cycles. Label them as estimates in your UI. They are not guarantees and they will move.

Conventions

How the API behaves

{
  "error": {
    "type": "invalid_request_error",
    "code": "exceeds_max_ltv",
    "message": "Requested borrow of 6000.00 USDC exceeds the maximum of 5277.75 at 50% LTV for AAPL.",
    "param": "borrow_amount",
    "doc_url": "https://spout.finance/docs/errors#exceeds_max_ltv",
    "request_id": "req_9xKq2mB"
  }
}

Webhooks

Events, and the one to wire first

Wire loan.at_risk before anything else. It is the event that keeps your users from being surprised, and it is the difference between a product that warns people and one that does not.

AI agents

Point your coding agent at the spec

If you build with Claude Code, Cursor or anything else that speaks MCP, run our MCP server locally and the agent can query the specification while it writes your integration. That beats pasting the spec into a prompt: the agent pulls only the endpoint it is working on, and it cannot work from a stale copy.

{
  "mcpServers": {
    "spout": {
      "command": "node",
      "args": ["/absolute/path/to/spout-builders/mcp/server.js"]
    }
  }
}

Agents that prefer documents to tools can read llms.txt or fetch openapi.yaml directly.

Next

Where to go from here