Alba is where an agent's money lives on Solana. An owner keeps a private balance, gives each agent a grant it can spend inside limits the owner set, and reads everything the agent paid for. Nobody else can read any of it. Sellers are paid over x402 in the asset they priced in.
Three people use Alba, and each has a path through these docs: the owner who funds agents, the builder who wires an agent to pay, and the seller who gets paid.
The private balance#
An owner deposits from a wallet into a pool, the program's vault and note tree for one mint. The first pool holds USDC, because x402 sellers price in it. Inside the pool the owner's holdings are notes: private amounts only the owner can open. The key that opens them is derived from one wallet signature, so the wallet is the only thing to keep.
The private balance covers pools, notes, the key and scanning.
The grant#
A grant is a note an agent can spend. The owner sets its amount, a cap per payment, an expiry and the sellers it may pay, and hands the agent a grant credential, a string beginning alba_grant_. Every payment the agent makes carries a proof that it is inside those terms, and the program accepts no payment without one. The owner can top a grant up or revoke it at any time.
Grants covers the terms, the credential and a grant's states.
The payment#
The agent makes one call:
import { alba } from '@alba/sdk'
const res = await alba.fetch('https://api.example/v1/search?q=lithium')When the seller answers 402, the SDK proves a payment from the grant and retries. The facilitator checks the proof and submits it, the program pays the seller from the pool, and the seller serves the response. On chain the payment is a transfer from the pool to the seller:
| Anyone | The owner | |
|---|---|---|
| Payer | sealed | research-agent |
| Seller | 7Kq2…x4Pn | 7Kq2…x4Pn |
| Amount | 0.0100 USDC | 0.0100 USDC |
| Resource | sealed | GET /papers/search |
The rows are a sample. Private payments follows one payment from the 402 to the settled transfer.
The ledger#
The owner opens a grant and reads its ledger: each payment with its time in UTC, the seller, the amount, the fees and the resource the agent named. The ledger is rebuilt from the chain with the grant's seed, and the resource names decrypt with the owner's key alone.
The ledger and the owner's view covers how it is rebuilt.