The facilitator is the service between Alba's users and the program. It settles alba payments for sellers, relays owners' proofs so that no user wallet pays a transaction fee, and serves the public data every client scans: pool figures, settlements, and the feeds of notes and spend tags. It holds no keys of an owner or an agent and returns no decrypted balance, label, grant credential or ledger. Those are computed in the SDK from the public feeds.
https://alba-api-production.up.railway.appThe same routes are described as OpenAPI 3.1 at GET /v1/openapi.json.
Conventions#
- Integers. Amounts, field elements, slots and counters are canonical decimal strings: digits only, no leading zeros. Amounts are in the mint's raw units. Do arithmetic on them in
BigInt. Small counts such aslimit,revisionand leaf indexes are JSON numbers. - Addresses and signatures. Base58. An address decodes to 32 bytes, a signature to 64.
- Bytes. Padded standard base64. Locators and write tokens are 64 lowercase hex characters.
- Field elements. Below the BN254 scalar field modulus. A value at or above it is refused.
- Times. ISO 8601 date-times in UTC.
- Requests are strict. An unknown key in a query or a body is a
VALIDATION_ERROR. - Responses are open. A response can gain keys, and a
statusor a code can take a value this page does not list. Keep an unrecognized string as it is and handle it as an unknown state.
The typed client#
@alba/contract exports a client with one method per route. It parses every response with the schema the facilitator validated it with, and it runs in a browser, a server and a script.
import { createClient, ApiClientError } from '@alba/contract'
const api = createClient(facilitatorUrl)
try {
const fees = await api.fees()
} catch (e) {
if (e instanceof ApiClientError) console.error(e.status, e.code, e.body.error.message)
}createClient(baseUrl, options?) takes these options:
| Option | Type | Meaning |
|---|---|---|
fetch | typeof fetch | The transport. Defaults to the global fetch. |
headers | Record<string, string> | Headers sent with every request. |
credentials | RequestCredentials | The fetch credentials mode. |
Every method takes a last argument call?: { signal?: AbortSignal; headers?: Record<string, string> }.
A failed call throws ApiClientError:
| Property | Type | Meaning |
|---|---|---|
status | number | The HTTP status. |
code | string | The error code, the same value as body.error.code. |
body | { error: ... } | The whole error envelope. |
message | string | body.error.message. |
A response that is not JSON becomes an envelope with code UPSTREAM_UNAVAILABLE for a status of 500 or above and INTERNAL_ERROR below it.
Routes#
| Method and path | Client method | Returns |
|---|---|---|
GET /v1/health | health() | Readiness |
GET /v1/config | config() | Program, network, relayer, limits, fees |
GET /v1/fees | fees() | The protocol fee and each mint's relay fee |
GET /v1/pools | pools() | Figures for every pool |
GET /v1/pools/:mint | pool(mint) | Figures for one pool |
GET /v1/settlements | settlements(query) | Payments settled to a pay-to address |
GET /v1/sync/leaves | leaves(query) | The note tree's leaves |
GET /v1/sync/outputs | outputs(query) | New notes with their encrypted openings |
GET /v1/sync/tags | tags(query) | Recorded spend tags |
GET /v1/sync/roots | roots(query) | The tree's roots |
POST /v1/grants/chain | grantChain(body) | The spends behind a grant's tags |
GET /v1/grant-records | grantRecords(query?) | Encrypted grant records |
GET /v1/grant-records/:locator | grantRecord(locator) | One encrypted grant record |
PUT /v1/grant-records/:locator | putGrantRecord(locator, body) | The stored record |
POST /v1/deposits/build | buildDeposit(body) | An unsigned deposit transaction |
POST /v1/transactions/submit | submitTransaction(body) | The transaction's state |
POST /v1/transactions/observe | observeTransaction(body) | The transaction's state |
POST /v1/spends/relay | relaySpend(body) | The transaction's state |
GET /v1/transactions/:id | transaction(id) | The transaction's state |
GET /v1/artifacts | artifacts() | The circuit's artifact manifest |
GET /v1/artifacts/v1/:name | artifactUrl(name) | One artifact's bytes |
POST /verify | verify(body) | An x402 verify response |
POST /settle | settle(body) | An x402 settle response |
GET /supported | supported() | The x402 kinds and signers |
GET /v1/openapi.json | openApiUrl() | This API as OpenAPI 3.1 |
artifactUrl and openApiUrl return the URL as a string and make no request.
Paging#
Every list route takes the same two query parameters and returns the same page shape.
| Query | Type | Meaning |
|---|---|---|
cursor | string | Where the page starts. Pass page.nextCursor from the previous page and nothing else. Omit it for the first page. |
limit | number | Items per page, 1 to 100. Defaults to 24. |
| Field | Type | Meaning |
|---|---|---|
itemsrequired | T[] | The rows, oldest first. |
page.nextCursorrequired | string | null | The cursor of the next page, or null on the last one. |
page.hasMorerequired | boolean | Whether a next page exists now. |
asOfrequired | string | When the page was read. |
The feeds are append-only, so a client keeps its last cursor and asks again from there to get what arrived since.
Readiness and configuration#
GET /v1/health#
| Field | Type | Meaning |
|---|---|---|
statusrequired | string | ready, or waiting while the facilitator cannot reach the Alba program. The route still answers HTTP 200. |
moderequired | string | The mode the facilitator runs in. |
versionrequired | string | The contract version it serves. |
reasonrequired | string | null | Why it is waiting, for example waiting_for_program. null when it is ready. |
GET /v1/config#
What a client needs before it proves or pays.
| Field | Type | Meaning |
|---|---|---|
statusrequired | string | The facilitator's state, as in /v1/health. |
moderequired | string | The mode the facilitator runs in. |
programIdrequired | string | The Alba program's address. |
networkrequired | string | null | The x402 network identifier of the cluster it settles on. |
facilitatorUrlrequired | string | Its own base URL, the value sellers put in extra.facilitator. |
relayerrequired | string | null | The signer that submits transactions and receives relay fees. A proof names it in extData.relayer. |
treeDepthrequired | number | The depth of each pool's note tree. |
sellerListDepthrequired | number | The depth of a grant's seller tree. A grant lists at most 2 to that power sellers. |
feesrequired | Fees | The object GET /v1/fees returns. |
artifactManifestUrlrequired | string | The URL of GET /v1/artifacts. |
limits.maxMemoBytesrequired | number | null | The largest encrypted memo a spend may carry, in bytes: 240. |
limits.maxEncryptedOutputBytesrequired | number | null | The largest ciphertext one new note may carry, in bytes: 218. |
limits.transactionBytesrequired | number | The size limit of a Solana transaction: 1232. A payment with a 240-byte memo to an Alba address is exactly that size. |
limits.measuredrequired | boolean | Whether the two byte limits above are set from a measured transaction. |
token.mintrequired | string | null | The ALBA mint. |
token.venuerequired | string | null | Where ALBA trades. |
token.developerAllocationBpsrequired | number | null | The developer's first buy as a share of supply, in basis points. |
GET /v1/fees#
The rates the program charges now. Fees and the ALBA token says what each fee is for.
| Field | Type | Meaning |
|---|---|---|
statusrequired | string | The state of the fee configuration. |
localOnlyrequired | boolean | true when the rates apply to a local cluster only. |
protocolFeeBpsrequired | number | null | The protocol fee in basis points of the price, 0 to 10000. |
feeRecipientrequired | string | null | The wallet the protocol fee is paid to. |
mintsrequired | MintFee[] | One entry for each pool: mint, symbol, decimals and relayFee, the flat relay fee in that mint's raw units. The program holds one relay fee amount and charges it in every pool. |
missingrequired | string[] | The fee settings that have no value. Routes that build or relay a spend answer CONFIGURATION_REQUIRED while this list has entries. |
For a payment of price p, the grant is charged p + floor(p * protocolFeeBps / 10000) + relayFee.
Pools and settlements#
GET /v1/pools#
| Field | Type | Meaning |
|---|---|---|
statusrequired | string | ready when the figures are current, waiting while the facilitator waits for the program. |
poolsrequired | Pool[] | One entry for each open pool. |
asOfrequired | string | When the figures were read. |
GET /v1/pools/:mint#
mint is the pool's token mint. The response is one Pool:
| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The token mint. |
symbolrequired | string | The mint's symbol. |
decimalsrequired | number | The mint's decimals. |
depositsHeldrequired | string | What the vault holds, in raw units. |
paymentsSettledrequired | string | How many payments from grants the pool has settled, a count as a decimal string. |
sellersPaidrequired | string | How many sellers the pool has paid, a count as a decimal string. |
nextLeafIndexrequired | number | The index the next note takes in the tree. |
rootrequired | string | The tree's current root. |
statusrequired | string | The pool's state. |
GET /v1/settlements#
The payments settled to one pay-to address, for a seller checking what arrived. Paged.
| Query | Type | Meaning |
|---|---|---|
payTorequired | string | A wallet address or an Alba address. |
mint | string | Only this pool. |
cursor, limit | paging | See Paging. |
Each item is a Settlement:
| Field | Type | Meaning |
|---|---|---|
idrequired | string | The settlement's identifier. |
mintrequired | string | The pool's mint. |
payTorequired | string | The address that was paid. |
payTagrequired | string | The proof's payTag: 0 for a wallet pay-to, the nonce binding for an Alba address. |
amountrequired | string | The price paid, in raw units. |
protocolFeerequired | string | The protocol fee charged to the grant. |
relayFeerequired | string | The relay fee charged to the grant. |
signaturerequired | string | The transaction. |
slotrequired | string | The slot it landed in. |
atrequired | string | The block time. |
statusrequired | string | settled once the payment is final. |
Scanning feeds#
A client rebuilds a balance from four public feeds: it downloads them, tries to decrypt each new note's opening with its own key, and computes its own spend tags to see which notes are spent. The facilitator has no route that looks up one note or one tag, so it never learns which notes a client cares about. All four are paged and take the same query.
| Query | Type | Meaning |
|---|---|---|
mintrequired | string | The pool to read. |
cursor, limit | paging | See Paging. |
GET /v1/sync/leaves#
Every leaf of the note tree in tree order, dummy leaves included.
| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The pool's mint. |
indexrequired | number | The leaf's position in the tree. |
commitmentrequired | string | The note commitment. |
signaturerequired | string | The transaction that inserted it. |
slotrequired | string | That transaction's slot. |
GET /v1/sync/outputs#
The same leaves with what a client needs to open them. An item has the five Leaf fields and:
| Field | Type | Meaning |
|---|---|---|
outputIndexrequired | number | 0 or 1: which of the instruction's two outputs this is. |
encryptedOutputrequired | { mode, ciphertext } | The note's encrypted opening. mode is none, x25519 or grant, and ciphertext is base64, empty for none. The scheme reference defines the modes. |
payAmount | string | The price of the grant payment that created this output, when it came from one. A scan uses it to mark a note as received. |
GET /v1/sync/tags#
| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The pool's mint. |
tagrequired | string | A recorded spend tag. |
signaturerequired | string | The transaction that spent the note. |
slotrequired | string | That transaction's slot. |
GET /v1/sync/roots#
| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The pool's mint. |
rootrequired | string | The tree's root after an instruction's two insertions. |
nextLeafIndexrequired | number | The tree's size at that root. |
signaturerequired | string | The transaction that produced it. |
slotrequired | string | That transaction's slot. |
recentrequired | boolean | Whether the program still accepts a proof against this root. It accepts the 64 most recent. |
Grants#
POST /v1/grants/chain#
Whoever holds a grant's seed, the owner or the agent, derives the grant's spend tags in order and asks for the spends behind them. This is how the SDK reads a grant's remaining amount and how the owner's app fills the ledger.
| Body | Type | Meaning |
|---|---|---|
mintrequired | string | The grant's pool. |
tagsrequired | string[] | 1 to 100 spend tags, each a nonzero field element. |
| Field | Type | Meaning |
|---|---|---|
itemsrequired | Spend[] | The indexed spends that recorded one of the tags. |
unspentTagsrequired | string[] | The tags with no indexed spend. The program's own record decides whether a tag is spent when a proof executes. |
asOfrequired | string | When the index was read. |
A Spend:
| Field | Type | Meaning |
|---|---|---|
idrequired | string | The spend's identifier. |
mintrequired | string | The pool's mint. |
signaturerequired | string | The transaction. |
slotrequired | string | Its slot. |
atrequired | string | The block time. |
publicInputsrequired | PublicInputs | The proof's fourteen public inputs, as in the circuit reference. |
extDatarequired | ExtData | The external data, with the encrypted memo. |
leafIndexesrequired | [number, number] | Where out0 and out1 sit in the tree. |
rootAfterrequired | string | The tree's root after the spend. |
Grant records#
A grant record is the owner's encrypted backup of one grant: its index, terms, label and facilitator URL. With the records and the feeds, the owner's app rebuilds every grant on a new device from the wallet signature alone. The facilitator stores ciphertext and can read none of it.
Each record lives at a locator, 64 hex characters derived from the grant's seed. The owner starts at grant index 0 and reads locators in order until one answers null.
A record:
| Field | Type | Meaning |
|---|---|---|
locatorrequired | string | Where the record lives. |
ciphertextrequired | string | The encrypted record, base64. |
revisionrequired | number | 0 for the first write, one more for each replacement. |
updatedAtrequired | string | When it was last written. |
GET /v1/grant-records#
Every stored record, paged with cursor and limit.
GET /v1/grant-records/:locator#
One record. When nothing is stored at the locator the response is HTTP 200 with the JSON body null, and grantRecord(locator) resolves to null.
PUT /v1/grant-records/:locator#
Creates the record or replaces it.
| Body | Type | Meaning |
|---|---|---|
writeTokenrequired | string | 64 hex characters derived from the grant's seed. The facilitator accepts the write when SHA-256("alba:v1:grant-record-locator" || 0x00 || writeToken) equals the locator, and it stores no token. |
ciphertextrequired | string | The encrypted record: 4 to 32768 base64 characters. |
expectedRevisionrequired | number | null | null to create the record. To replace it, the revision the caller last read. |
It returns the stored record. UNAUTHORIZED means the write token does not match the locator. IDEMPOTENCY_CONFLICT means the stored revision is not expectedRevision: read the record again and decide from what is there.
Deposits#
A deposit is the one action an owner's wallet signs as a transaction, because the tokens come from the wallet. The SDK proves the deposit, the facilitator builds the transaction, the wallet signs it.
POST /v1/deposits/build#
| Body | Type | Meaning |
|---|---|---|
proofrequired | string | The Groth16 proof, base64 of 256 bytes. |
publicInputsrequired | PublicInputs | The fourteen public inputs, with publicIn equal to the deposit. |
extDatarequired | ExtData | The external data, with the new note's opening encrypted to the owner, relayer set to the depositor and relayFee set to 0. |
depositorrequired | string | The wallet that signs. |
depositorTokenAccountrequired | string | The wallet's token account the deposit comes from. |
It returns a TransactionBuild:
| Field | Type | Meaning |
|---|---|---|
idrequired | string | The build's identifier, used by the two routes below. |
transactionBase64required | string | The unsigned version 0 transaction. |
blockhashrequired | string | The blockhash it was built on. |
lastValidBlockHeightrequired | string | The last block height at which it can land. |
contextSlotrequired | string | The slot the build was simulated at. |
expiresAtrequired | string | When the build expires. |
feerequired | string | The network fee in lamports, paid by the wallet as the transaction's fee payer. |
POST /v1/transactions/submit#
For a wallet that signs and hands the transaction back. The facilitator broadcasts it and follows it.
| Body | Type | Meaning |
|---|---|---|
idrequired | string | The build's id, 1 to 128 characters. |
signedTransactionBase64required | string | The signed transaction, 4 to 4096 base64 characters. |
POST /v1/transactions/observe#
For a wallet that signs and sends the transaction itself. The facilitator follows the signature.
| Body | Type | Meaning |
|---|---|---|
idrequired | string | The build's id. |
signaturerequired | string | The signature the wallet returned. |
Both return a Transaction.
Relayed spends#
POST /v1/spends/relay#
Every owner action after the deposit is a proof the facilitator submits: creating a grant, topping it up, revoking it, a transfer to an Alba address and a withdrawal. The owner's wallet signs nothing and appears nowhere in the transaction.
| Body | Type | Meaning |
|---|---|---|
proofrequired | string | The Groth16 proof, base64 of 256 bytes. |
publicInputsrequired | PublicInputs | The fourteen public inputs, with publicIn equal to 0. |
extDatarequired | ExtData | The external data. relayer and relayFee are the values in /v1/config and /v1/fees. |
It returns a Transaction. The three objects have the shapes the scheme reference gives them. An agent's payment does not use this route: it reaches the facilitator through the seller, on /settle.
Transaction state#
GET /v1/transactions/:id#
id is 1 to 128 characters of letters, digits, _ and -. The response is a Transaction, the same object the submit, observe and relay routes return:
| Field | Type | Meaning |
|---|---|---|
idrequired | string | The transaction's identifier. |
statusrequired | string | built before it is signed, submitted while it is in flight, settled once it is final, failed when it was refused. |
signaturerequired | string | null | The transaction signature, once there is one. |
slotrequired | string | null | The slot it landed in. |
errorrequired | { code, message } | null | Why it failed: an error code and a sentence. |
Poll this route with the same id to follow a transaction. Asking again never submits a second one.
Circuit artifacts#
GET /v1/artifacts#
The manifest of the files a prover and a verifier load.
| Field | Type | Meaning |
|---|---|---|
statusrequired | string | waiting while the artifacts are not published. |
circuitrequired | string | The circuit's name, spend. |
versionrequired | string | The artifacts' version, v1. |
publicInputOrderrequired | string[] | The fourteen public input names in verifier order. |
artifactsrequired | Artifact[] | Each { name, url, sha256, bytes, contentType }. sha256 is 64 hex characters and bytes the file's length as a decimal string. Each url carries the digest as a sha256 query parameter. Check both after downloading. |
GET /v1/artifacts/v1/:name#
The bytes of one artifact. name is one of:
| Name | Content |
|---|---|
spend.wasm | The witness generator |
spend.zkey | The proving key |
verification_key.json | The verifying key. verification-key.json names the same file. |
| Query | Type | Meaning |
|---|---|---|
sha256 | string | 64 hex characters: the digest of the file the caller expects. |
A request with sha256 is served with Cache-Control: public, max-age=31536000, immutable, and answers ARTIFACTS_UNAVAILABLE when the facilitator no longer hosts a file with that digest. A request without it is served with Cache-Control: no-cache. The route also answers ARTIFACTS_UNAVAILABLE while the manifest's status is waiting.
x402 routes#
POST /verify, POST /settle and GET /supported follow x402 version 2. Their bodies, responses and reason strings are in the alba x402 scheme.
A payment the facilitator refuses on /verify or /settle comes back as an x402 result with HTTP 200 and a reason string. A body that fails parsing comes back as the error envelope below.
Errors#
Every other failure is one envelope:
type ErrorEnvelope = {
error: {
code: string
message: string
retryable: boolean
stage: string
fieldErrors?: Record<string, string[]>
programError?: { programId: string; name: string; number?: number }
retryAfterSeconds?: number
requestId?: string
}
}| Field | Type | Meaning |
|---|---|---|
coderequired | string | A stable code from the table below. Branch on this. |
messagerequired | string | A sentence a person can read. |
retryablerequired | boolean | Whether the same request can succeed later. |
stagerequired | string | The step that failed: validation, auth, read, upload, build, wallet, co_sign, simulation, send, confirmation or proving. |
fieldErrors | Record<string, string[]> | For VALIDATION_ERROR: each refused field with its messages. |
programError | object | For a refusal by a program: its address, the error's name and its number. |
retryAfterSeconds | number | How long to wait before trying again. |
requestId | string | The request's identifier in the facilitator's logs. |
A body that parses as this envelope is an error whatever the HTTP status.
Error codes#
| Code | HTTP | Raised when |
|---|---|---|
VALIDATION_ERROR | 400 | A query, parameter or body does not match its schema. fieldErrors names the fields. |
INVALID_CREDENTIAL | 400 | A value is not a valid version 1 grant credential. |
INVALID_ALBA_ADDRESS | 400 | A value is not a valid version 1 Alba address. |
UNAUTHORIZED | 401 | A grant record's write token does not match its locator. |
ORIGIN_NOT_ALLOWED | 403 | A browser request comes from an origin the facilitator does not allow. |
NOT_FOUND | 404 | No route or transaction exists at this path. |
PROGRAM_UNAVAILABLE | 409 | The facilitator cannot read the program. |
CONFIGURATION_REQUIRED | 409 | A fee setting has no value. GET /v1/fees lists which in missing. |
IDEMPOTENCY_CONFLICT | 409 | A grant record's stored revision is not the expectedRevision sent. |
TRANSACTION_EXPIRED | 409 | A built transaction's blockhash expired before it landed. Build again. |
UNKNOWN_ROOT | 409 | A proof's root is not among the pool's 64 most recent roots. Sync and prove again. |
SPENT_TAG | 409 | A proof spends a note that is already spent. |
GRANT_EXPIRED | 409 | A payment's expiryBound is behind the cluster's clock. |
WAITING_FOR_PROGRAM | 409 | The Alba program is not reachable on this network yet. Retryable. |
ARTIFACTS_UNAVAILABLE | 409 | The circuit artifacts are not published yet. Retryable. |
SETTLEMENT_PENDING | 409 | The transaction is broadcast and its outcome is not known yet. Follow it by its id. |
PAYLOAD_TOO_LARGE | 413 | The request body is over the size limit. |
UNSUPPORTED_MEDIA_TYPE | 415 | A body is not application/json. |
SIMULATION_FAILED | 422 | The transaction failed when simulated. programError names the refusal. |
CHAIN_REFUSED | 422 | The cluster refused the transaction. |
PROOF_REFUSED | 422 | The proof does not verify against its public inputs. |
SELLER_NOT_ALLOWED | 422 | The pay-to address is not in the grant's seller list. |
AMOUNT_OVER_CAP | 422 | The price is above the grant's cap per payment. |
INSUFFICIENT_GRANT_BALANCE | 422 | The grant holds less than the price plus the fees. |
INSUFFICIENT_BALANCE | 422 | The owner's notes hold less than the amount plus the fee. |
UNSUPPORTED_NETWORK | 422 | The network identifier is not the facilitator's cluster. |
FEE_MISMATCH | 422 | A proof's fee differs from the current rates. Read GET /v1/fees and prove again. |
RATE_LIMITED | 429 | Too many requests. retryAfterSeconds says when to return. |
INTERNAL_ERROR | 500 | The facilitator failed. Retryable. |
UPSTREAM_UNAVAILABLE | 502 | The facilitator could not reach the cluster's RPC. |
The x402 reason strings are these codes in lower case: SPENT_TAG is spent_tag on /settle. /settle has one more, transaction_failed, for a transaction the cluster refused after broadcast.