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.

Quickstart: fund an agent
agent.ts
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()
several grants
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, state

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

Use Alba from an MCP client
MCP server config
{
  "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 Alba
server.ts
import { 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'))),
)

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

Solana program 49hapF2ZzcSCmVDqT56QTFb3UDW28HaSDqaLSjqW5YvV@usealbalive on XEvery time on this site is UTC.