A private payment is an x402 payment whose payer is the pool. The seller is paid the price it asked, in the asset it asked for, before it serves the request. This page follows one payment from the 402 to the settled transfer.
The steps#
The agent asks
The agent calls
alba.fetch(url). The first request goes out with no payment attached.The seller answers 402
The response carries a
PAYMENT-REQUIREDheader: the payment requirements. They name the schemealba, the network, the asset (a mint), the amount, the pay-to address and the facilitator.The SDK proves the payment
The SDK picks the
albaentry whose asset is the grant's mint and whose facilitator is the grant's, checks the price, the seller and the expiry against the grant's terms, then builds a zero-knowledge proof that spends the grant's current note: the price to the seller, the fees, and the remainder into the grant's next note. It encrypts a memo for the owner naming the request's method and URL. The payment names a deadline of its own: the seller's timeout, at most 120 seconds from now, and never later than the grant's expiry.The agent retries
The same request goes out again with the proof in a
PAYMENT-SIGNATUREheader.The seller settles
The seller's middleware passes the payment and its own requirements to the facilitator. The facilitator checks the proof and submits the transaction. The program verifies the proof, records the spend tag, adds the grant's next note to the tree, pays the seller from the vault and takes the fees.
The seller serves
Once the transaction is settled the seller runs its handler and returns the response with a
PAYMENT-RESPONSEheader carrying the transaction signature.alba.fetchresolves with that response.
Nothing is spent until the program accepts the proof. A 402 the agent does not answer and a proof the facilitator refuses leave the grant exactly as it was.
A 402 with no alba entry for the grant's mint and facilitator is returned to the caller as it came, unpaid.
What the proof shows#
The proof comes with fourteen public values, and they are all a verifier sees. In words:
| Public value | What it says |
|---|---|
| a tree root | the note being spent is somewhere in the pool |
| a spend tag | this note has not been spent before |
| two new commitments | the notes this payment creates |
| the amount paid and the fee | what leaves the grant |
| the recipient | the seller's wallet, for a public pay-to |
| a pay tag | binds the payment to the seller's request, for a private pay-to |
| a deadline | the payment is valid until this second |
| a hash of the attached data | the memo, the encrypted openings, the relayer and the mint cannot be swapped |
Behind those values the proof establishes that the payer holds the agent key of a grant note under that root, that the amount is within the grant's cap, that the deadline is within its expiry, that the recipient is on its seller list, and that the remainder went into a note with the same terms. It reveals none of them: not the grant, its amount, its terms, its owner or which leaf of the tree it is.
Circuit lists the public values in order and every constraint.
Paying a public address#
When pay-to is a wallet address, the program transfers the price from the vault to that wallet's token account for the mint. On an explorer the payment is a token transfer from the pool to the seller.
Paying an Alba address#
When pay-to is an Alba address, no tokens leave the vault. The payment creates a note for the seller inside the pool, with its opening encrypted to the seller's address, and the seller finds it by scanning. The transaction shows the amount and no recipient.
The seller's middleware holds the seller's opened balance. After settlement it scans for the new note and serves only once it has found a note with that commitment and the price.
So the seller can tell which payment answers which request, each 402 for a private pay-to carries a fresh nonce signed by the seller, and the proof publishes a pay tag derived from the seller's key and that nonce. Only the seller can match the tag to the request.
What each party learns#
| Public pay-to | Alba address pay-to | |
|---|---|---|
| The seller | The request, and that the pool paid its price. | The request, and that a note for its price arrived. |
| The facilitator | The requirements and the proof. It is not sent the URL the agent asked for. | The same. |
| Anyone reading the chain | The pool paid this address this amount at this time. | A payment of this amount was made inside the pool at this time. |
| The owner | Everything: which grant, which seller, the amount, the fees, the resource. | The same. |
Nothing in a payment says which grant paid, who owns it, what it has left, or which other payments came from the same grant.
The fee payer#
The facilitator's relayer signs and pays for every transaction, and is repaid by the relay fee inside the proof. Neither the owner's wallet nor any wallet of the agent appears in a payment.
When a payment is refused#
alba.fetch checks a payment against the grant before it proves. When the payment cannot be made it throws an AlbaSdkError with one of these codes: AMOUNT_OVER_CAP, SELLER_NOT_ALLOWED, GRANT_EXPIRED, GRANT_REVOKED, INSUFFICIENT_GRANT_BALANCE, or INVALID_ARGUMENT when the seller is on another network.
A payment that reaches the facilitator and is refused comes back with a reason. The seller answers the retry with another 402 that carries the reason in its error field, and alba.fetch resolves with that response.
| Reason | Cause |
|---|---|
amount_over_cap | The price is above the grant's cap per payment. |
seller_not_allowed | The pay-to address is not on the grant's seller list. |
grant_expired | The grant's expiry has passed. |
insufficient_grant_balance | The grant cannot cover the price and the fees. |
spent_tag | The grant's note was already spent: by a revoke, a top-up or another payment. |
unknown_root | The proof names a tree root the pool no longer keeps. The pool keeps its last 64. |
fee_mismatch | The fee rates changed after the proof was made. |
proof_refused | The proof does not verify against the values sent with it. |
waiting_for_program | The facilitator is not connected to the program. |
settlement_pending | The transaction was sent and has not settled yet. The facilitator keeps following the same transaction. |
transaction_failed | The transaction was sent and the chain refused it. |
private_note_unavailable | Set by the seller's middleware, for an Alba address pay-to: the payment settled and the seller's scan did not find the note. The response carries the settled signature, and the agent does not pay again. |
The alba x402 scheme has each message field by field.