HTTP API

The app runs on a JSON API that agents and integrations can use directly. The API builds transactions and follows them to finality; the caller's wallet always signs.

Conventions

• Every POST sends JSON, under 16 KiB, with an Origin header equal to the app's origin.
• Amounts are strings of USDC base units (millionths of a dollar): "1000000" is one dollar. Decimals and numbers above the u64 range are refused.
• Addresses are base58 Solana public keys.
• Errors come back as { "error": { "code", "message", "requestId" } } with a matching HTTP status.

Sign in

1. POST /api/auth/challenge with { "wallet": "<address>" } returns { id, message, expiresAt }.

2. Sign the exact UTF-8 message with the wallet's Ed25519 key.

3. POST /api/auth/verify with { "challengeId": "<id>", "signature": "<base64 signature>" } returns { wallet, token, expiresAt } and sets a session cookie.

Browsers use the cookie. Other clients send Authorization: Bearer <token> with the same Origin header. A session lasts twelve hours; POST /api/auth/logout ends it.

Read

Act

1. POST /api/transactions/prepare with { "idempotencyKey", "action" } returns a transaction intent with the unsigned transaction (base64) and its status.

2. Sign the transaction with the wallet. An issue transaction arrives already signed by its new mint account: add the wallet's signature beside it (with @solana/web3.js, partialSign; sign would drop the mint's signature).

3. POST /api/transactions/{id}/submit with { "signedTransaction": "<base64>" }. Scrip stores it, then sends it.

4. Poll GET /api/transactions/{id} until status is finalized or failed.

The idempotencyKey is 16 to 128 letters, digits, - or _. Repeating a request with the same key returns the original intent; the same key with a different action is refused with 409.

Actions

{ "kind": "mint", "scrip": "<Scrip account>", "amount": "1000000" }
{ "kind": "redeem", "scrip": "<Scrip account>", "amount": "1000000" }
{ "kind": "convert", "from": "<Scrip account>", "to": "<Scrip account>", "amount": "1000000" }
{ "kind": "issue", "name": "Your community", "ticker": "YOURUSD", "metadataUri": "https://example.com/scrip.json", "route": { … } }
{ "kind": "route", "scrip": "<Scrip account>", "route": { … } }
{ "kind": "applyRoute", "scrip": "<Scrip account>" }

A route object:

{
  "buybackBps": 5000,
  "holdersBps": 2500,
  "treasuryBps": 2500,
  "treasury": "<wallet>",
  "communityMint": "<mint>",
  "buybackDestination": "<wallet>",
  "burnBuyback": true,
  "priceFeed": "<price feed>",
  "maxSlippageBps": 100
}

Unused addresses take the system program's address, 11111111111111111111111111111111.

The reserve's admin and keeper have four more actions: setKeeper (keeper, paused, or both; a field left out keeps its recorded value), harvest (scrip), configureTreasury (treasuryMint, provider, oracleProgram, oracleFeed) and initialize (feeTreasury, feeBps, bufferBps, routeDelay, maxOracleAge).

Status codes worth handling