Reference

The alba x402 scheme

Payment requirements, the payment payload, verification and settlement, field by field.

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#

NameValue
Schemealba
x402 version2
extra.assetTransferMethodgroth16
extra.paymentFlowupfront
Mainnet networksolana: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.

HeaderSent byCarries
PAYMENT-REQUIREDseller, with HTTP 402PaymentRequired
PAYMENT-SIGNATUREagent, on the retryPaymentPayload
PAYMENT-RESPONSEseller, with the resourcethe 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.

  1. The agent requests the resource

    The seller answers HTTP 402 with PaymentRequired in PAYMENT-REQUIRED. The JSON response body may repeat the object.

  2. The agent selects an alba entry and proves the payment

    It picks an entry of accepts whose scheme is alba, whose assetTransferMethod and paymentFlow are the two values above, and whose asset and network match the grant. amount is the seller's price. The protocol fee and the relay fee are charged to the grant on top of it.

  3. The agent retries with the payment

    The same request, with PaymentPayload in PAYMENT-SIGNATURE.

  4. 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 has success: true.

  5. 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.

FieldTypeMeaning
x402Versionrequirednumber2.
resourcerequiredResourceInfoThe resource being sold. See below.
acceptsrequiredPaymentRequirements[]The ways to pay. A seller may list other schemes beside alba.
errorstringWhy the previous attempt was refused, when there was one.
extensionsRecord<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#

FieldTypeMeaning
urlrequiredstringThe resource's absolute HTTP or HTTPS URL.
descriptionstringWhat the resource is.
mimeTypestringThe response's media type.
serviceNamestringThe seller's name, at most 32 characters.
tagsstring[]At most 5 tags of at most 32 characters each.
iconUrlstringAn absolute HTTP or HTTPS URL.

PaymentRequirements#

One entry of accepts. The facilitator parses it strictly: an unknown key is a validation error.

FieldTypeMeaning
schemerequired'alba'The scheme name.
networkrequiredstringsolana: and 1 to 32 base58 characters of the genesis hash.
amountrequiredstringThe price in raw units, a positive u64.
assetrequiredstringThe token mint, base58. It names the pool the payment comes from.
payTorequiredstringWhere the price goes: a base58 wallet address, or an Alba address (alba: and base58, at most 95 characters).
maxTimeoutSecondsrequirednumberA positive integer: how long the seller holds these requirements open.
extra.facilitatorrequiredstringThe facilitator's absolute HTTP or HTTPS base URL.
extra.assetTransferMethodrequired'groth16'The transfer method.
extra.paymentFlowrequired'upfront'The flow.
extra.noncestringA 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.

FieldTypeMeaning
x402Versionrequired2The protocol version.
acceptedrequiredPaymentRequirementsThe entry the agent selected, unchanged, nonce included.
payloadrequiredobjectproof, publicInputs and extData, defined below.
resourceResourceInfoOptional. 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.
extensionsRecord<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:

BytesContent
0 to 63-A: x, then y, 32 bytes each, big-endian
64 to 191B: x.c1, x.c0, y.c1, y.c0, 32 bytes each, big-endian
192 to 255C: 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.

InputType
root, tag0, tag1, out0, out1field element
publicIn, publicOut, fee, payAmountu64
recipientHi, recipientLounsigned integer below 2^128
payTagfield element
expiryBoundu64, Unix seconds
extDataHashfield 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.

FieldTypeMeaning
versionrequired1The external-data version.
mintrequiredstringThe pool's mint. Equal to the requirements' asset.
relayerrequiredstringThe facilitator's signer, which submits the transaction and receives the relay fee. Listed by GET /supported and GET /v1/config.
recipientTokenAccountrequiredstring | nullThe seller's token account for a wallet pay-to. null exactly when publicOut is 0.
relayFeerequiredstringThe 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.
memorequiredstringBase64 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:

modeByteCiphertext
none0Empty. 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.
x255191A note's opening, encrypted to its recipient's X25519 key. Used for the seller's note when pay-to is an Alba address.
grant2A 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:

text
"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) || memo

What the payload binds#

RequirementBound by
amountpayAmount
assetextData.mint, through extDataHash
payTo, a walletrecipientHi, recipientLo, and extData.recipientTokenAccount through extDataHash
payTo, an Alba addresspayTag, with extra.nonce
the encrypted notes and the memoextDataHash
the relayer and the relay feeextDataHash

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:

FieldTypeMeaning
x402Versionrequired2The protocol version.
paymentPayloadrequiredPaymentPayloadThe decoded PAYMENT-SIGNATURE header.
paymentRequirementsrequiredPaymentRequirementsThe 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.

FieldTypeMeaning
isValidrequiredbooleanWhether the payment passes every check now.
invalidReasonstringA reason string, when isValid is false.
payerstringNever present. An Alba proof has no public payer.
extensionsRecord<string, unknown>x402 extensions.
extraRecord<string, unknown>Reserved by x402.

Settle response#

POST /settle returns success: true only after the transaction reaches the facilitator's settlement commitment.

FieldTypeMeaning
successrequiredbooleanWhether the payment settled.
transactionrequiredstringThe transaction signature. Empty when the payment was refused before broadcast.
networkrequiredstringThe network identifier.
amountstringThe settled price in raw units.
errorReasonstringA reason string, when success is false.
payerstringNever present.
extensionsRecord<string, unknown>x402 extensions.
OutcomesuccesstransactionerrorReason
Settledtruethe signatureabsent
Refused before broadcastfalseemptythe reason
Broadcast, outcome not yet knownfalsethe submitted signaturesettlement_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#

ReasonRaised when
proof_refusedThe proof does not verify against the public inputs, or a binding to the requirements does not hold.
unknown_rootroot is not among the pool's 64 most recent roots. The agent syncs and proves again.
spent_tagA spend tag is already recorded. The grant's note was spent by another payment, a top-up or a revoke.
grant_expiredThe cluster's clock is past expiryBound.
seller_not_allowedThe pay-to address is not in the grant's seller list.
amount_over_capThe price is above the grant's cap per payment.
insufficient_grant_balanceThe grant holds less than the price plus the fees.
fee_mismatchfee or extData.relayFee differs from the current rates. The agent reads GET /v1/fees and proves again.
waiting_for_programThe facilitator cannot reach the Alba program on this network.
settlement_pendingThe transaction is broadcast and its outcome is not known yet.
transaction_failedThe 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.

FieldTypeMeaning
kindsrequiredobject[]Each { x402Version, scheme, network, extra? }. An Alba kind has scheme: "alba" and an extra with assetTransferMethod: "groth16" and paymentFlow: "upfront".
extensionsrequiredstring[]The extension names the facilitator supports.
signersrequiredRecord<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 receiptStore whose claim(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 privateOwner for 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.