A seller takes Alba by putting one middleware in front of a route. Requests without payment get a 402 with the price. Paid requests reach the handler after the payment has settled, and the price arrives in the asset you named.
What you need#
- A pay-to address. This guide uses a wallet address. To be paid into a private balance, see Receive privately.
- A token account for the asset at that wallet. The program pays into the wallet's associated token account and does not create it.
- The asset's mint, the network identifier and the facilitator's URL. Sell in the app shows all three inside a ready snippet, and
GET /v1/configon the facilitator returns them. The facilitator's URL can also come from theALBA_FACILITATOR_URLenvironment variable in place of thefacilitatorUrloption.
npm install @alba/sdkProtect a route#
import { Hono } from 'hono'
import { honoMiddleware } from '@alba/sdk/seller'
const app = new Hono()
const paid = honoMiddleware({
price: '10000',
asset: mint,
payTo,
network,
facilitatorUrl,
description: 'Search open research papers',
})
app.get('/v1/search', paid, (c) => c.json({ results: [] }))import express from 'express'
import { expressMiddleware } from '@alba/sdk/seller'
const app = express()
const paid = expressMiddleware({
price: '10000',
asset: mint,
payTo,
network,
facilitatorUrl,
description: 'Search open research papers',
})
app.get('/v1/search', paid, (req, res) => {
res.json({ results: [] })
})price is in raw units of the asset, as a string: 10000 is 0.01 USDC. Each route can have its own middleware with its own price.
What a buyer sees#
A request with no payment gets status 402, the header PAYMENT-REQUIRED and the same object as the JSON body:
| Field | Type | Meaning |
|---|---|---|
x402Version | number | 2. |
resource | object | The request's URL, your description and the media type application/json. |
accepts | object[] | One entry: the scheme alba, your network, amount, asset and payTo, maxTimeoutSeconds, and the facilitator. |
error | string | Present when a payment was just refused: the reason. |
An agent answers with a PAYMENT-SIGNATURE header. The middleware checks that the payment accepts exactly the requirements you issue, sends it to the facilitator to settle, and only then calls your handler. The response carries a PAYMENT-RESPONSE header with the settlement, including the transaction signature.
A payment the facilitator refuses gets a new 402 whose error says why. Your handler does not run.
Run it in production#
Keep receipts in your database. One settlement buys one response. By default the middleware remembers the settlements it has served in memory, which holds for one process. With several instances or across restarts, pass a receiptStore that records each one durably:
import type { SellerReceiptStore } from '@alba/sdk/seller'
const receiptStore: SellerReceiptStore = {
async claim(signature, resource) {
return await db.insertReceiptIfNew(signature, resource)
},
}claim returns true the first time it sees a transaction signature and false every time after. Make the insert atomic, for example a unique key on the signature. Pass the store as receiptStore in the middleware's options.
Settlement comes before your handler. If the handler then fails, the payment stays settled. Make the handler dependable, and send a refund yourself where one is due.
Set the timeout to your traffic. maxTimeoutSeconds is how long a buyer has to answer a 402. It defaults to 120.
Check what you were paid#
Sell lists the settlements to an address with their times in UTC, amounts and transactions. From code:
import { createClient } from '@alba/contract'
const api = createClient(facilitatorUrl)
const { items } = await api.settlements({ payTo })Each item has amount, protocolFee, relayFee, signature, slot and at. amount is your price in full. The two fees were charged to the buyer's grant on top of it.
On an explorer each payment is a transfer from the pool to your token account. Nothing in it identifies the buyer.
Other servers#
For a framework other than Hono or Express, build the requirements with paymentRequirements and settle a payment header with verifyAndSettle. Seller middleware documents both, with an example.