An Alba address receives payments as notes inside the pool. No tokens leave the vault, no recipient appears on chain, and what you earn sits in a private balance that you spend, grant to your own agents, or withdraw. This guide is for a seller, and for an agent or a person who is paid by another Alba user.
Get your Alba address#
Open your balance in the app. The address under the Balance heading, starting alba:, is yours. On Sell, Alba address fills it in for you.
In code it is the address of the opened balance:
import { connectBalance } from '@alba/sdk'
const owner = await connectBalance((message) => wallet.signMessage(message), { facilitatorUrl })
owner.address // 'alba:…'The address is safe to publish. It lets others pay you and shows nothing of what you hold.
Be paid by another owner#
Give the payer your address. They send from their own balance:
await payer.transfer({ mint, amount: '250000', recipient: 'alba:…' })The payment arrives as a note in your balance at the next scan.
Use it as a seller's pay-to#
A seller's server needs the receiving balance open, because the middleware checks that each payment's note really arrived before it serves. Open it in the server process from the key that owns it. The balance's key comes from an Ed25519 signature of Alba's fixed message, so a server signs that message with its own key:
import { ed25519 } from '@noble/curves/ed25519.js'
import { openBalance, openBalanceMessage } from '@alba/sdk'
const signature = ed25519.sign(openBalanceMessage(), secretKey)
const owner = openBalance(signature, { facilitatorUrl })secretKey is the 32-byte Ed25519 secret key of the server's wallet. The same wallet, connected in the app, opens the same balance, since both produce the same signature.
Then pass the address as payTo and the balance as privateOwner:
import { Hono } from 'hono'
import { honoMiddleware } from '@alba/sdk/seller'
const app = new Hono()
const paid = honoMiddleware({
price: '10000',
asset: mint,
payTo: owner.address,
privateOwner: owner,
nonceSecret,
network,
facilitatorUrl,
})
app.get('/v1/search', paid, (c) => c.json({ results: [] }))Everything else is as in Accept Alba on an API.
What changes on the wire#
Each 402 for an Alba address carries a fresh nonce, and the payment must answer with that nonce. The middleware signs each nonce with nonceSecret and gives it an expiry of maxTimeoutSeconds, so any instance holding the secret accepts a nonce another instance issued. Give every instance of your server the same nonceSecret, a long random string from your secret store. Without it each process makes its own, which serves a single instance.
After settlement the middleware scans your balance for the new note. It serves the request once the note is found with the right amount. If the note cannot be opened with your key, the buyer gets a 402 with the reason private_note_unavailable and your handler does not run.
See what arrived#
In the app, Sell lists the payments under Into your private balance, and under Balance each one is a note of the kind Received.
In code, scan and read the notes:
const balance = await owner.scan()
const received = balance.notes.filter((note) => note.kind === 'received')Each note has its amount in raw units. balance.assets gives the totals per asset.
What anyone else sees#
| Anyone | The owner | |
|---|---|---|
| That a payment was made | yes, with its amount | yes |
| Recipient | sealed | your Alba address |
| Your balance | sealed | every note |
Use what you earned#
Received notes are ordinary notes in your balance. Fund a grant for your own agent from them, send them to another Alba address, or withdraw to a public wallet.