alba is a payment scheme for x402 version 2 on Solana. The buyer is an agent holding a grant credential. It pays with a Groth16 proof that the payment is inside the grant's terms, and the facilitator settles that proof against the pool before the seller serves the resource. This page defines every object the scheme puts on the wire. The SDK's seller middleware and alba.fetch implement both sides of it.
Every amount, field element, slot and counter on this page is a canonical decimal string: digits only, no leading zeros, no sign. Amounts are in the mint's raw units, so 10000 of a 6-decimal mint is 0.01.
Scheme identifiers#
| Name | Value |
|---|---|
| Scheme | alba |
| x402 version | 2 |
extra.assetTransferMethod | groth16 |
extra.paymentFlow | upfront |
| Mainnet network | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp |
A network identifier is solana: followed by the first 32 characters of the cluster's base58 genesis hash. A local validator uses its own genesis hash in the same form.
Headers#
Each header carries one JSON object, UTF-8 encoded and then base64 encoded. Header names are case-insensitive. The scheme does not read X-PAYMENT.
| Header | Sent by | Carries |
|---|---|---|
PAYMENT-REQUIRED | seller, with HTTP 402 | PaymentRequired |
PAYMENT-SIGNATURE | agent, on the retry | PaymentPayload |
PAYMENT-RESPONSE | seller, with the resource | the settle response |
A grant credential, an owner key and a decrypted memo never go into a header or a facilitator request.
Payment flow#
The only flow is upfront: the payment settles, then the seller runs the handler, then it responds.
The agent requests the resource
The seller answers HTTP 402 with
PaymentRequiredinPAYMENT-REQUIRED. The JSON response body may repeat the object.The agent selects an alba entry and proves the payment
It picks an entry of
acceptswhoseschemeisalba, whoseassetTransferMethodandpaymentFloware the two values above, and whoseassetandnetworkmatch the grant.amountis the seller's price. The protocol fee and the relay fee are charged to the grant on top of it.The agent retries with the payment
The same request, with
PaymentPayloadinPAYMENT-SIGNATURE.The seller settles
The seller sends the payload and its own retained requirements to the facilitator's
POST /settle. The paid handler does not run until the response hassuccess: true.The seller serves
The resource goes back with the settle response in
PAYMENT-RESPONSE.
POST /verify checks a payment without settling it. The flow does not need it, because /settle runs every check before it commits. A handler that fails after settlement leaves the payment settled, and a refund is a separate payment from the seller.
PaymentRequired#
The object a seller returns with a 402.
| Field | Type | Meaning |
|---|---|---|
x402Versionrequired | number | 2. |
resourcerequired | ResourceInfo | The resource being sold. See below. |
acceptsrequired | PaymentRequirements[] | The ways to pay. A seller may list other schemes beside alba. |
error | string | Why the previous attempt was refused, when there was one. |
extensions | Record<string, unknown> | x402 extensions. The Alba facilitator advertises none. |
A client parses entries of other schemes without failing and pays only an entry whose scheme, transfer method and flow it recognizes.
ResourceInfo#
| Field | Type | Meaning |
|---|---|---|
urlrequired | string | The resource's absolute HTTP or HTTPS URL. |
description | string | What the resource is. |
mimeType | string | The response's media type. |
serviceName | string | The seller's name, at most 32 characters. |
tags | string[] | At most 5 tags of at most 32 characters each. |
iconUrl | string | An absolute HTTP or HTTPS URL. |
PaymentRequirements#
One entry of accepts. The facilitator parses it strictly: an unknown key is a validation error.
| Field | Type | Meaning |
|---|---|---|
schemerequired | 'alba' | The scheme name. |
networkrequired | string | solana: and 1 to 32 base58 characters of the genesis hash. |
amountrequired | string | The price in raw units, a positive u64. |
assetrequired | string | The token mint, base58. It names the pool the payment comes from. |
payTorequired | string | Where the price goes: a base58 wallet address, or an Alba address (alba: and base58, at most 95 characters). |
maxTimeoutSecondsrequired | number | A positive integer: how long the seller holds these requirements open. |
extra.facilitatorrequired | string | The facilitator's absolute HTTP or HTTPS base URL. |
extra.assetTransferMethodrequired | 'groth16' | The transfer method. |
extra.paymentFlowrequired | 'upfront' | The flow. |
extra.nonce | string | A nonzero BN254 scalar field element. Required when payTo is an Alba address. |
Pay-to as a wallet address#
The program pays the price from the pool's vault to the wallet's token account for the mint. The proof carries the wallet address as two 128-bit limbs, and the payload's extData.recipientTokenAccount names the token account. The program checks that the account belongs to that wallet and that mint.
Pay-to as an Alba address#
The price becomes a note in the same pool, owned by the address's key and encrypted to it. Nothing leaves the vault. See Receive privately.
The seller issues a fresh nonzero nonce, a field element, for every 402, and has to recognize it as its own on the retry until the requirements expire. It may keep the nonce with the requirements, or make the nonce verifiable by itself, as the SDK's middleware does: its nonce is 5 bytes of expiry, 10 random bytes and a 16-byte HMAC-SHA256 under the seller's secret. The agent's proof carries payTag = Poseidon(recipientPk, nonce), where recipientPk is the key inside the Alba address. On the retry the seller validates against the requirements it issued, nonce included, and never issues a new challenge in their place. The facilitator refuses requirements with an Alba address and a missing or zero nonce.
PaymentPayload#
The object in PAYMENT-SIGNATURE. Every level is parsed strictly.
| Field | Type | Meaning |
|---|---|---|
x402Versionrequired | 2 | The protocol version. |
acceptedrequired | PaymentRequirements | The entry the agent selected, unchanged, nonce included. |
payloadrequired | object | proof, publicInputs and extData, defined below. |
resource | ResourceInfo | Optional. The SDK leaves it out, so the facilitator is not sent the resource's URL. The method and URL the agent requested go in the encrypted memo. |
extensions | Record<string, unknown> | x402 extensions, echoed under the version 2 rules when one is negotiated. |
payload.proof#
Base64 of exactly 256 bytes (344 characters), a Groth16 proof over BN254 laid out for Solana's alt_bn128 pairing syscall:
| Bytes | Content |
|---|---|
| 0 to 63 | -A: x, then y, 32 bytes each, big-endian |
| 64 to 191 | B: x.c1, x.c0, y.c1, y.c0, 32 bytes each, big-endian |
| 192 to 255 | C: x, then y, 32 bytes each, big-endian |
A is negated once, by negating its y coordinate modulo the BN254 base field. The G2 coordinates are in c1, c0 order, the reverse of snarkjs output. Invalid points and the point at infinity are refused.
payload.publicInputs#
The spend circuit's fourteen public inputs, by name. The object is strict, and the order below is the order the verifier takes them in. Circuit defines each one.
| Input | Type |
|---|---|
root, tag0, tag1, out0, out1 | field element |
publicIn, publicOut, fee, payAmount | u64 |
recipientHi, recipientLo | unsigned integer below 2^128 |
payTag | field element |
expiryBound | u64, Unix seconds |
extDataHash | field element |
A field element is below the BN254 scalar field modulus 21888242871839275222246405745257275088548364400416034343698204186575808495617. A value at or above it is refused, never reduced.
In a grant payment publicIn is 0, payAmount equals the requirements' amount, and fee is the protocol fee plus the relay fee. For a wallet pay-to, publicOut equals payAmount, the two recipient limbs hold the wallet address and payTag is 0. For an Alba address pay-to, publicOut and both limbs are 0 and payTag is the value above.
expiryBound is the payment's deadline, and the program refuses the payment once the cluster's clock is past it. The SDK sets it to now plus maxTimeoutSeconds, at most 120 seconds ahead, and never later than the grant's expiry.
payload.extData#
The data the proof commits to through extDataHash and the program reads directly.
| Field | Type | Meaning |
|---|---|---|
versionrequired | 1 | The external-data version. |
mintrequired | string | The pool's mint. Equal to the requirements' asset. |
relayerrequired | string | The facilitator's signer, which submits the transaction and receives the relay fee. Listed by GET /supported and GET /v1/config. |
recipientTokenAccountrequired | string | null | The seller's token account for a wallet pay-to. null exactly when publicOut is 0. |
relayFeerequired | string | The relay fee for this mint in raw units, as GET /v1/fees reports it. |
encryptedOutputsrequired | [EncryptedOutput, EncryptedOutput] | One entry for each new note, in the order of out0 and out1. |
memorequired | string | Base64 of the memo, encrypted to the owner's encryption key from the grant credential. It names the HTTP method and URL the agent requested. |
An EncryptedOutput is { mode, ciphertext }, with ciphertext in padded base64:
mode | Byte | Ciphertext |
|---|---|---|
none | 0 | Empty. Used for a dummy output and for a grant's next note after a payment, which the owner and the agent both derive from the note before it. |
x25519 | 1 | A note's opening, encrypted to its recipient's X25519 key. Used for the seller's note when pay-to is an Alba address. |
grant | 2 | A grant note's opening under the grant's own key. Used when a grant is created or topped up. |
A memo is at most 240 bytes and a ciphertext at most 218 bytes, before base64. The program enforces both, and GET /v1/config reports them as limits.maxMemoBytes and limits.maxEncryptedOutputBytes. A memo holds a GET URL of up to 158 bytes for a wallet pay-to and 93 bytes for an Alba address pay-to. A longer URL is stored cut short and ending in an ellipsis. Notes and memos are encrypted with X25519, HKDF-SHA256 and XChaCha20-Poly1305.
extDataHash is SHA-256 of the following bytes, read as a big-endian integer and reduced modulo the scalar field:
"alba:v1:ext-data" || 0x00 || u8(1)
|| mint[32] || relayer[32]
|| recipientTokenAccount[32] (32 zero bytes when null)
|| u64le(relayFee)
|| u8(output0.mode) || u32le(len) || output0.ciphertext
|| u8(output1.mode) || u32le(len) || output1.ciphertext
|| u32le(len) || memoWhat the payload binds#
| Requirement | Bound by |
|---|---|
amount | payAmount |
asset | extData.mint, through extDataHash |
payTo, a wallet | recipientHi, recipientLo, and extData.recipientTokenAccount through extDataHash |
payTo, an Alba address | payTag, with extra.nonce |
| the encrypted notes and the memo | extDataHash |
| the relayer and the relay fee | extDataHash |
A proof copied into another payload cannot change the recipient, the price, the relayer or either fee.
Verify and settle#
Both routes are on the facilitator named in extra.facilitator, and both take the same body:
| Field | Type | Meaning |
|---|---|---|
x402Versionrequired | 2 | The protocol version. |
paymentPayloadrequired | PaymentPayload | The decoded PAYMENT-SIGNATURE header. |
paymentRequirementsrequired | PaymentRequirements | The seller's own retained requirements for this challenge. |
The facilitator checks in this order: the structure of the body; that accepted equals paymentRequirements and that network and mint match; that payAmount, the recipient, the nonce and the deadline are bound as above; extDataHash; the fee against the current rates; that root is a recent root of the pool and both tags are unspent; the proof. /settle then builds and simulates the transaction, records the signed bytes, broadcasts it and follows it. The program repeats the money checks when it executes.
A refused payment is a normal response of the shapes below with HTTP 200. A body that fails structural parsing, and any transport failure, uses the error envelope of the facilitator API.
Verify response#
POST /verify reads state and changes none. A valid result reserves nothing: a revoke or another payment from the same grant can still settle first.
| Field | Type | Meaning |
|---|---|---|
isValidrequired | boolean | Whether the payment passes every check now. |
invalidReason | string | A reason string, when isValid is false. |
payer | string | Never present. An Alba proof has no public payer. |
extensions | Record<string, unknown> | x402 extensions. |
extra | Record<string, unknown> | Reserved by x402. |
Settle response#
POST /settle returns success: true only after the transaction reaches the facilitator's settlement commitment.
| Field | Type | Meaning |
|---|---|---|
successrequired | boolean | Whether the payment settled. |
transactionrequired | string | The transaction signature. Empty when the payment was refused before broadcast. |
networkrequired | string | The network identifier. |
amount | string | The settled price in raw units. |
errorReason | string | A reason string, when success is false. |
payer | string | Never present. |
extensions | Record<string, unknown> | x402 extensions. |
| Outcome | success | transaction | errorReason |
|---|---|---|---|
| Settled | true | the signature | absent |
| Refused before broadcast | false | empty | the reason |
| Broadcast, outcome not yet known | false | the submitted signature | settlement_pending |
After settlement_pending the seller sends the same request again. The facilitator follows the transaction it already submitted and answers with that signature once it settles.
Reason strings#
| Reason | Raised when |
|---|---|
proof_refused | The proof does not verify against the public inputs, or a binding to the requirements does not hold. |
unknown_root | root is not among the pool's 64 most recent roots. The agent syncs and proves again. |
spent_tag | A spend tag is already recorded. The grant's note was spent by another payment, a top-up or a revoke. |
grant_expired | The cluster's clock is past expiryBound. |
seller_not_allowed | The pay-to address is not in the grant's seller list. |
amount_over_cap | The price is above the grant's cap per payment. |
insufficient_grant_balance | The grant holds less than the price plus the fees. |
fee_mismatch | fee or extData.relayFee differs from the current rates. The agent reads GET /v1/fees and proves again. |
waiting_for_program | The facilitator cannot reach the Alba program on this network. |
settlement_pending | The transaction is broadcast and its outcome is not known yet. |
transaction_failed | The transaction was broadcast and the cluster refused it. transaction holds its signature. |
The seller middleware adds one reason of its own. For an Alba address pay-to it scans the seller's balance after a successful settlement, and when it does not find a note with the payment's out1 commitment and the price it returns the settle response with success: false, errorReason: "private_note_unavailable" and the settled signature. The payment is settled, so the agent does not pay again.
A consumer keeps a reason it does not recognize as the string it received.
Supported#
GET /supported is the x402 version 2 discovery route.
| Field | Type | Meaning |
|---|---|---|
kindsrequired | object[] | Each { x402Version, scheme, network, extra? }. An Alba kind has scheme: "alba" and an extra with assetTransferMethod: "groth16" and paymentFlow: "upfront". |
extensionsrequired | string[] | The extension names the facilitator supports. |
signersrequired | Record<string, string[]> | A network identifier, or a pattern such as solana:*, mapped to the facilitator's signer addresses. A signer is the relayer in extData.relayer. |
kinds is empty while the facilitator waits for the program. GET /v1/health and GET /v1/config report its readiness.
Replay and delivery#
The program refuses a nonzero spend tag it has already recorded, so a proof settles once. The facilitator records each settlement under a fingerprint of its fourteen public inputs and its external data, and records the signed transaction before it broadcasts. The same settle request sent again returns the existing signature. A request that spends the same tag with different data is refused. The facilitator never builds a second transaction while the first one's outcome is unknown.
A seller holds to three rules:
- One settlement buys one response. The seller keeps a record of each settlement it has served. The middleware keeps that record in memory, and takes a
receiptStorewhoseclaim(signature, resource)keeps it in the seller's database across restarts. A settle response it has already served against is never a second purchase and never pays for another route. A retry of the same request may get the original response again under the seller's own idempotency policy. - For an Alba address pay-to, a nonce is accepted only with the requirements it was issued for, and only until they expire.
- For an Alba address pay-to, the seller opens the incoming note before it serves. The proof binds the ciphertext's bytes, and the seller's own decryption is what shows the note is there for it to spend. The middleware takes the seller's opened balance as
privateOwnerfor this.
An agent runtime sends one payment at a time from one grant. Two processes holding the same grant credential can prove against the same note, and one of them settles. After spent_tag the agent syncs the grant before it proves again, and it never turns a payment whose outcome is unknown into a new payment.