Protocol

API

The public HTTP API behind the app: reads, transaction builders and the relay.

The app runs entirely on a public HTTP API. You can use the same API to read Flume's state or to build your own client. Reads need no key. Writes return unsigned transactions for your own wallet to sign, so the API never holds a key of yours.

This site serves the API under /api/flume, so /api/flume/v1/network is the first route below. Amounts are strings of base units: micro-USDC, with six decimals, and lamports.

Reads

Route	Returns
`GET /v1/network`	The cluster and its genesis hash, the program, the vault, the USDC and share mints, the upgrade authority, the pricing model's parameters, and a readiness status
`GET /v1/vault`	Cash, shares outstanding, open streams and what was paid for them, the quote key, the admin and any admin it has named next, and whether the vault is open
`GET /v1/sources`	Every source on the vault with its latest stream, its status (`idle`, `active`, `capped` or `ended`) and whether it can be settled. Add `?creator=` to filter by creator
`GET /v1/sources/:source`	One source and its stream
`GET /v1/sources/:source/activity`	The source's events, newest first, and thirty UTC days of fees split into vault and creator parts
`GET /v1/sources/:source/preview`	What a quote would be right now, with each eligibility check and every limit. Takes `shareBps` and `termSeconds`; reserves nothing
`GET /v1/accounts/:owner`	A wallet's SOL, USDC and vault shares
`GET /v1/signatures/:signature`	A transaction's confirmation status

A preview for a source that isn't quotable yet says why, and when:

JSON

{
  "eligible": false,
  "checks": { "enabled": true, "model": true, "idle": true, "lenders": true,
              "indexer": true, "usdcAccount": true, "history": false,
              "feeDays": false, "limits": null },
  "shareBps": 3000,
  "termSeconds": 2592000,
  "terms": null,
  "history": { "coveredSince": "1790810188", "quotableFrom": "1791414988",
               "feeDays": 1, "requiredFeeDays": 4, "observed": "17655000000" }
}

Quotes

POST /v1/creator-quotes issues a firm quote to a creator. The body carries the request fields, the time it was issued, and the creator's signature over the request text described in Quote checks, base64-encoded:

JSON

{
  "source": "<source>",
  "creator": "<creator wallet>",
  "shareBps": 3000,
  "termSeconds": 2592000,
  "issuedAt": 1790841676,
  "signature": "<base64 ed25519 signature>"
}

The response holds the quote's terms under intent and the partly signed purchase in transaction, base64. It expires 120 seconds after issue.

Transactions

Each builder checks the chain first and refuses with a clear error when the transaction would fail. Every body has owner, the wallet that will sign. The response is the unsigned transaction, base64, with its lastValidBlockHeight and a short summary.

Route	Body, besides `owner`	Builds
`POST /v1/transactions/create-source`	`token`	Registers a token
`POST /v1/transactions/pay-usdc`	`source`, `amount`	Pays USDC into a source
`POST /v1/transactions/pay-sol`	`source`, `lamports`	Pays SOL into a source
`POST /v1/transactions/claim`	`source`	Claims the creator side
`POST /v1/transactions/settle`	`source`	Settles an ended stream
`POST /v1/transactions/deposit`	`amount`	Deposits USDC into the vault
`POST /v1/transactions/withdraw`	`shares`	Withdraws shares from the vault
`POST /v1/transactions/usdc-account`		Creates the owner's USDC account

Deposits and withdrawals carry a minimum for what comes back, 0.1% under the amount in the summary.

Governance

FLUME governance runs on SPL Governance. These routes read its realm, proposals and voters, and build its transactions the same way as above. Amounts of FLUME are base units, with six decimals.

Route	Returns
`GET /v1/governance`	The realm, the governance and the FLUME mint, the supply and FLUME deposited, the voting rules (what it takes to propose, how long a vote runs, the wait before a passed proposal runs, the votes it takes to pass), and whether governance holds the vault admin
`GET /v1/governance/proposals`	Every proposal, newest first: its state, votes for and against, when voting ends, and whether it can be closed or run now
`GET /v1/governance/proposals/:proposal`	One proposal and each step it will run, read back as vault actions
`GET /v1/governance/voters/:owner`	A wallet's FLUME, what it has deposited, its votes, and whether it can propose or withdraw

Route	Body, besides `owner`	Builds
`POST /v1/transactions/governance-deposit`	`amount`	Deposits FLUME into governance
`POST /v1/transactions/governance-withdraw`		Releases votes on finished proposals and withdraws all deposited FLUME
`POST /v1/transactions/governance-propose`	`name`, `description`, `action`, `key`, `modelVersion`, `modelHash`	Opens a proposal and starts its vote. `action` is `update-model`, `set-quote-key`, `accept-admin` or `transfer-admin`; fields the action doesn't use are empty strings
`POST /v1/transactions/governance-vote`	`proposal`, `support`	Votes `for` or `against` with everything deposited
`POST /v1/transactions/governance-finalize`	`proposal`	Closes a vote whose time is up
`POST /v1/transactions/governance-execute`	`proposal`	Runs a passed proposal's next step once its wait is over

Submitting

POST /v1/submit takes a fully signed transaction, base64, with its lastValidBlockHeight, sends it, and answers once it's confirmed. It only forwards transactions that call the Flume program, FLUME governance, SPL Token, the associated token account program, System or Compute Budget. You're free to send transactions through any RPC instead.

Errors

Every error has the same shape, with a stable code and a sentence a person can read:

JSON

{ "error": "INSUFFICIENT_HISTORY", "message": "Seven complete days of finalized history are required" }

The codes are listed in Errors.