Reference

Facilitator API

Every route of the facilitator: requests, responses, paging and errors.

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.

Base URL
https://alba-api-production.up.railway.app

The 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 as limit, revision and 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 status or 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.

ts
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:

OptionTypeMeaning
fetchtypeof fetchThe transport. Defaults to the global fetch.
headersRecord<string, string>Headers sent with every request.
credentialsRequestCredentialsThe fetch credentials mode.

Every method takes a last argument call?: { signal?: AbortSignal; headers?: Record<string, string> }.

A failed call throws ApiClientError:

PropertyTypeMeaning
statusnumberThe HTTP status.
codestringThe error code, the same value as body.error.code.
body{ error: ... }The whole error envelope.
messagestringbody.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 pathClient methodReturns
GET /v1/healthhealth()Readiness
GET /v1/configconfig()Program, network, relayer, limits, fees
GET /v1/feesfees()The protocol fee and each mint's relay fee
GET /v1/poolspools()Figures for every pool
GET /v1/pools/:mintpool(mint)Figures for one pool
GET /v1/settlementssettlements(query)Payments settled to a pay-to address
GET /v1/sync/leavesleaves(query)The note tree's leaves
GET /v1/sync/outputsoutputs(query)New notes with their encrypted openings
GET /v1/sync/tagstags(query)Recorded spend tags
GET /v1/sync/rootsroots(query)The tree's roots
POST /v1/grants/chaingrantChain(body)The spends behind a grant's tags
GET /v1/grant-recordsgrantRecords(query?)Encrypted grant records
GET /v1/grant-records/:locatorgrantRecord(locator)One encrypted grant record
PUT /v1/grant-records/:locatorputGrantRecord(locator, body)The stored record
POST /v1/deposits/buildbuildDeposit(body)An unsigned deposit transaction
POST /v1/transactions/submitsubmitTransaction(body)The transaction's state
POST /v1/transactions/observeobserveTransaction(body)The transaction's state
POST /v1/spends/relayrelaySpend(body)The transaction's state
GET /v1/transactions/:idtransaction(id)The transaction's state
GET /v1/artifactsartifacts()The circuit's artifact manifest
GET /v1/artifacts/v1/:nameartifactUrl(name)One artifact's bytes
POST /verifyverify(body)An x402 verify response
POST /settlesettle(body)An x402 settle response
GET /supportedsupported()The x402 kinds and signers
GET /v1/openapi.jsonopenApiUrl()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.

QueryTypeMeaning
cursorstringWhere the page starts. Pass page.nextCursor from the previous page and nothing else. Omit it for the first page.
limitnumberItems per page, 1 to 100. Defaults to 24.
FieldTypeMeaning
itemsrequiredT[]The rows, oldest first.
page.nextCursorrequiredstring | nullThe cursor of the next page, or null on the last one.
page.hasMorerequiredbooleanWhether a next page exists now.
asOfrequiredstringWhen 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#

FieldTypeMeaning
statusrequiredstringready, or waiting while the facilitator cannot reach the Alba program. The route still answers HTTP 200.
moderequiredstringThe mode the facilitator runs in.
versionrequiredstringThe contract version it serves.
reasonrequiredstring | nullWhy 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.

FieldTypeMeaning
statusrequiredstringThe facilitator's state, as in /v1/health.
moderequiredstringThe mode the facilitator runs in.
programIdrequiredstringThe Alba program's address.
networkrequiredstring | nullThe x402 network identifier of the cluster it settles on.
facilitatorUrlrequiredstringIts own base URL, the value sellers put in extra.facilitator.
relayerrequiredstring | nullThe signer that submits transactions and receives relay fees. A proof names it in extData.relayer.
treeDepthrequirednumberThe depth of each pool's note tree.
sellerListDepthrequirednumberThe depth of a grant's seller tree. A grant lists at most 2 to that power sellers.
feesrequiredFeesThe object GET /v1/fees returns.
artifactManifestUrlrequiredstringThe URL of GET /v1/artifacts.
limits.maxMemoBytesrequirednumber | nullThe largest encrypted memo a spend may carry, in bytes: 240.
limits.maxEncryptedOutputBytesrequirednumber | nullThe largest ciphertext one new note may carry, in bytes: 218.
limits.transactionBytesrequirednumberThe size limit of a Solana transaction: 1232. A payment with a 240-byte memo to an Alba address is exactly that size.
limits.measuredrequiredbooleanWhether the two byte limits above are set from a measured transaction.
token.mintrequiredstring | nullThe ALBA mint.
token.venuerequiredstring | nullWhere ALBA trades.
token.developerAllocationBpsrequirednumber | nullThe 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.

FieldTypeMeaning
statusrequiredstringThe state of the fee configuration.
localOnlyrequiredbooleantrue when the rates apply to a local cluster only.
protocolFeeBpsrequirednumber | nullThe protocol fee in basis points of the price, 0 to 10000.
feeRecipientrequiredstring | nullThe wallet the protocol fee is paid to.
mintsrequiredMintFee[]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.
missingrequiredstring[]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#

FieldTypeMeaning
statusrequiredstringready when the figures are current, waiting while the facilitator waits for the program.
poolsrequiredPool[]One entry for each open pool.
asOfrequiredstringWhen the figures were read.

GET /v1/pools/:mint#

mint is the pool's token mint. The response is one Pool:

FieldTypeMeaning
mintrequiredstringThe token mint.
symbolrequiredstringThe mint's symbol.
decimalsrequirednumberThe mint's decimals.
depositsHeldrequiredstringWhat the vault holds, in raw units.
paymentsSettledrequiredstringHow many payments from grants the pool has settled, a count as a decimal string.
sellersPaidrequiredstringHow many sellers the pool has paid, a count as a decimal string.
nextLeafIndexrequirednumberThe index the next note takes in the tree.
rootrequiredstringThe tree's current root.
statusrequiredstringThe pool's state.

GET /v1/settlements#

The payments settled to one pay-to address, for a seller checking what arrived. Paged.

QueryTypeMeaning
payTorequiredstringA wallet address or an Alba address.
mintstringOnly this pool.
cursor, limitpagingSee Paging.

Each item is a Settlement:

FieldTypeMeaning
idrequiredstringThe settlement's identifier.
mintrequiredstringThe pool's mint.
payTorequiredstringThe address that was paid.
payTagrequiredstringThe proof's payTag: 0 for a wallet pay-to, the nonce binding for an Alba address.
amountrequiredstringThe price paid, in raw units.
protocolFeerequiredstringThe protocol fee charged to the grant.
relayFeerequiredstringThe relay fee charged to the grant.
signaturerequiredstringThe transaction.
slotrequiredstringThe slot it landed in.
atrequiredstringThe block time.
statusrequiredstringsettled 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.

QueryTypeMeaning
mintrequiredstringThe pool to read.
cursor, limitpagingSee Paging.

GET /v1/sync/leaves#

Every leaf of the note tree in tree order, dummy leaves included.

FieldTypeMeaning
mintrequiredstringThe pool's mint.
indexrequirednumberThe leaf's position in the tree.
commitmentrequiredstringThe note commitment.
signaturerequiredstringThe transaction that inserted it.
slotrequiredstringThat 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:

FieldTypeMeaning
outputIndexrequirednumber0 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.
payAmountstringThe 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#

FieldTypeMeaning
mintrequiredstringThe pool's mint.
tagrequiredstringA recorded spend tag.
signaturerequiredstringThe transaction that spent the note.
slotrequiredstringThat transaction's slot.

GET /v1/sync/roots#

FieldTypeMeaning
mintrequiredstringThe pool's mint.
rootrequiredstringThe tree's root after an instruction's two insertions.
nextLeafIndexrequirednumberThe tree's size at that root.
signaturerequiredstringThe transaction that produced it.
slotrequiredstringThat transaction's slot.
recentrequiredbooleanWhether 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.

BodyTypeMeaning
mintrequiredstringThe grant's pool.
tagsrequiredstring[]1 to 100 spend tags, each a nonzero field element.
FieldTypeMeaning
itemsrequiredSpend[]The indexed spends that recorded one of the tags.
unspentTagsrequiredstring[]The tags with no indexed spend. The program's own record decides whether a tag is spent when a proof executes.
asOfrequiredstringWhen the index was read.

A Spend:

FieldTypeMeaning
idrequiredstringThe spend's identifier.
mintrequiredstringThe pool's mint.
signaturerequiredstringThe transaction.
slotrequiredstringIts slot.
atrequiredstringThe block time.
publicInputsrequiredPublicInputsThe proof's fourteen public inputs, as in the circuit reference.
extDatarequiredExtDataThe external data, with the encrypted memo.
leafIndexesrequired[number, number]Where out0 and out1 sit in the tree.
rootAfterrequiredstringThe 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:

FieldTypeMeaning
locatorrequiredstringWhere the record lives.
ciphertextrequiredstringThe encrypted record, base64.
revisionrequirednumber0 for the first write, one more for each replacement.
updatedAtrequiredstringWhen 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.

BodyTypeMeaning
writeTokenrequiredstring64 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.
ciphertextrequiredstringThe encrypted record: 4 to 32768 base64 characters.
expectedRevisionrequirednumber | nullnull 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#

BodyTypeMeaning
proofrequiredstringThe Groth16 proof, base64 of 256 bytes.
publicInputsrequiredPublicInputsThe fourteen public inputs, with publicIn equal to the deposit.
extDatarequiredExtDataThe external data, with the new note's opening encrypted to the owner, relayer set to the depositor and relayFee set to 0.
depositorrequiredstringThe wallet that signs.
depositorTokenAccountrequiredstringThe wallet's token account the deposit comes from.

It returns a TransactionBuild:

FieldTypeMeaning
idrequiredstringThe build's identifier, used by the two routes below.
transactionBase64requiredstringThe unsigned version 0 transaction.
blockhashrequiredstringThe blockhash it was built on.
lastValidBlockHeightrequiredstringThe last block height at which it can land.
contextSlotrequiredstringThe slot the build was simulated at.
expiresAtrequiredstringWhen the build expires.
feerequiredstringThe 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.

BodyTypeMeaning
idrequiredstringThe build's id, 1 to 128 characters.
signedTransactionBase64requiredstringThe 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.

BodyTypeMeaning
idrequiredstringThe build's id.
signaturerequiredstringThe 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.

BodyTypeMeaning
proofrequiredstringThe Groth16 proof, base64 of 256 bytes.
publicInputsrequiredPublicInputsThe fourteen public inputs, with publicIn equal to 0.
extDatarequiredExtDataThe 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:

FieldTypeMeaning
idrequiredstringThe transaction's identifier.
statusrequiredstringbuilt before it is signed, submitted while it is in flight, settled once it is final, failed when it was refused.
signaturerequiredstring | nullThe transaction signature, once there is one.
slotrequiredstring | nullThe slot it landed in.
errorrequired{ code, message } | nullWhy 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.

FieldTypeMeaning
statusrequiredstringwaiting while the artifacts are not published.
circuitrequiredstringThe circuit's name, spend.
versionrequiredstringThe artifacts' version, v1.
publicInputOrderrequiredstring[]The fourteen public input names in verifier order.
artifactsrequiredArtifact[]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:

NameContent
spend.wasmThe witness generator
spend.zkeyThe proving key
verification_key.jsonThe verifying key. verification-key.json names the same file.
QueryTypeMeaning
sha256string64 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:

ts
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
  }
}
FieldTypeMeaning
coderequiredstringA stable code from the table below. Branch on this.
messagerequiredstringA sentence a person can read.
retryablerequiredbooleanWhether the same request can succeed later.
stagerequiredstringThe step that failed: validation, auth, read, upload, build, wallet, co_sign, simulation, send, confirmation or proving.
fieldErrorsRecord<string, string[]>For VALIDATION_ERROR: each refused field with its messages.
programErrorobjectFor a refusal by a program: its address, the error's name and its number.
retryAfterSecondsnumberHow long to wait before trying again.
requestIdstringThe request's identifier in the facilitator's logs.

A body that parses as this envelope is an error whatever the HTTP status.

Error codes#

CodeHTTPRaised when
VALIDATION_ERROR400A query, parameter or body does not match its schema. fieldErrors names the fields.
INVALID_CREDENTIAL400A value is not a valid version 1 grant credential.
INVALID_ALBA_ADDRESS400A value is not a valid version 1 Alba address.
UNAUTHORIZED401A grant record's write token does not match its locator.
ORIGIN_NOT_ALLOWED403A browser request comes from an origin the facilitator does not allow.
NOT_FOUND404No route or transaction exists at this path.
PROGRAM_UNAVAILABLE409The facilitator cannot read the program.
CONFIGURATION_REQUIRED409A fee setting has no value. GET /v1/fees lists which in missing.
IDEMPOTENCY_CONFLICT409A grant record's stored revision is not the expectedRevision sent.
TRANSACTION_EXPIRED409A built transaction's blockhash expired before it landed. Build again.
UNKNOWN_ROOT409A proof's root is not among the pool's 64 most recent roots. Sync and prove again.
SPENT_TAG409A proof spends a note that is already spent.
GRANT_EXPIRED409A payment's expiryBound is behind the cluster's clock.
WAITING_FOR_PROGRAM409The Alba program is not reachable on this network yet. Retryable.
ARTIFACTS_UNAVAILABLE409The circuit artifacts are not published yet. Retryable.
SETTLEMENT_PENDING409The transaction is broadcast and its outcome is not known yet. Follow it by its id.
PAYLOAD_TOO_LARGE413The request body is over the size limit.
UNSUPPORTED_MEDIA_TYPE415A body is not application/json.
SIMULATION_FAILED422The transaction failed when simulated. programError names the refusal.
CHAIN_REFUSED422The cluster refused the transaction.
PROOF_REFUSED422The proof does not verify against its public inputs.
SELLER_NOT_ALLOWED422The pay-to address is not in the grant's seller list.
AMOUNT_OVER_CAP422The price is above the grant's cap per payment.
INSUFFICIENT_GRANT_BALANCE422The grant holds less than the price plus the fees.
INSUFFICIENT_BALANCE422The owner's notes hold less than the amount plus the fee.
UNSUPPORTED_NETWORK422The network identifier is not the facilitator's cluster.
FEE_MISMATCH422A proof's fee differs from the current rates. Read GET /v1/fees and prove again.
RATE_LIMITED429Too many requests. retryAfterSeconds says when to return.
INTERNAL_ERROR500The facilitator failed. Retryable.
UPSTREAM_UNAVAILABLE502The 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.