One line for an agent to pay, one line for a seller to be paid
The agent’s whole surface is alba.fetch(url). It behaves like fetch, and when a seller answers 402 it proves a payment inside the grant and retries.
Pay from an agent
Install @alba/sdk, put the grant credential in the agent’s environment and call alba.fetch(url) wherever the agent fetched before. Requests that need no payment pass straight through.
import { alba } from '@alba/sdk'
// The grant credential is read from ALBA_GRANT.
const res = await alba.fetch('https://api.example/v1/search?q=lithium')
const results = await res.json()import { alba } from '@alba/sdk'
// Or bind a credential yourself, one agent per grant.
const agent = alba.with(process.env.RESEARCH_GRANT!)
const res = await agent.fetch('https://api.example/v1/search?q=lithium')
const grant = await agent.grantStatus() // remaining, terms, statePay from an MCP client
Agents that take tools get the same through alba-mcp, which ships with the SDK. It gives the agent two tools: fetch_paid to call a paid URL and grant_status to read what is left.
{
"mcpServers": {
"alba": {
"command": "npx",
"args": ["-y", "--package", "@alba/sdk", "alba-mcp"],
"env": { "ALBA_GRANT": "alba_grant_…" }
}
}
}What the agent holds
One string, the grant credential. It carries what the agent needs to prove payments from one grant:
- The grant’s seed
- The agent’s key for this grant
- The terms: cap per payment, expiry, sellers
- The asset and the facilitator’s address
What it never holds
Nothing in the credential opens anything else of yours:
- Your keysealed
- Your balancesealed
- Your other grantssealed
- This grant’s terms, to change themsealed
Accept Alba on an API
Add the middleware to a route with a price and a pay-to address. A request without payment gets the 402; a paid request reaches your handler after the payment has settled. Use a public address, or an Alba address to receive into a private balance.
Quickstart: accept Albaimport { Hono } from 'hono'
import { honoMiddleware } from '@alba/sdk/seller'
const app = new Hono()
app.get(
'/v1/search',
honoMiddleware({ price: '4000', asset: USDC, payTo: PAY_TO, network: NETWORK, facilitatorUrl: FACILITATOR }),
(c) => c.json(search(c.req.query('q'))),
)import express from 'express'
import { expressMiddleware } from '@alba/sdk/seller'
const app = express()
app.get(
'/v1/search',
expressMiddleware({ price: '4000', asset: USDC, payTo: PAY_TO, network: NETWORK, facilitatorUrl: FACILITATOR }),
(req, res) => res.json(search(req.query.q)),
)price is in the asset’s smallest unit: 4000 is 0.004 USDC. The same page of the app that shows your settlements writes this snippet with your address in it. Sell