Concepts

Private payments

One payment from the 402 to the settled transfer, and what each party learns from it.

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#

  1. The agent asks

    The agent calls alba.fetch(url). The first request goes out with no payment attached.

  2. The seller answers 402

    The response carries a PAYMENT-REQUIRED header: the payment requirements. They name the scheme alba, the network, the asset (a mint), the amount, the pay-to address and the facilitator.

  3. The SDK proves the payment

    The SDK picks the alba entry 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.

  4. The agent retries

    The same request goes out again with the proof in a PAYMENT-SIGNATURE header.

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

  6. The seller serves

    Once the transaction is settled the seller runs its handler and returns the response with a PAYMENT-RESPONSE header carrying the transaction signature. alba.fetch resolves 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 valueWhat it says
a tree rootthe note being spent is somewhere in the pool
a spend tagthis note has not been spent before
two new commitmentsthe notes this payment creates
the amount paid and the feewhat leaves the grant
the recipientthe seller's wallet, for a public pay-to
a pay tagbinds the payment to the seller's request, for a private pay-to
a deadlinethe payment is valid until this second
a hash of the attached datathe 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-toAlba address pay-to
The sellerThe request, and that the pool paid its price.The request, and that a note for its price arrived.
The facilitatorThe requirements and the proof. It is not sent the URL the agent asked for.The same.
Anyone reading the chainThe pool paid this address this amount at this time.A payment of this amount was made inside the pool at this time.
The ownerEverything: 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.

ReasonCause
amount_over_capThe price is above the grant's cap per payment.
seller_not_allowedThe pay-to address is not on the grant's seller list.
grant_expiredThe grant's expiry has passed.
insufficient_grant_balanceThe grant cannot cover the price and the fees.
spent_tagThe grant's note was already spent: by a revoke, a top-up or another payment.
unknown_rootThe proof names a tree root the pool no longer keeps. The pool keeps its last 64.
fee_mismatchThe fee rates changed after the proof was made.
proof_refusedThe proof does not verify against the values sent with it.
waiting_for_programThe facilitator is not connected to the program.
settlement_pendingThe transaction was sent and has not settled yet. The facilitator keeps following the same transaction.
transaction_failedThe transaction was sent and the chain refused it.
private_note_unavailableSet 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.