Guides

Give an agent a grant

Open the balance, deposit, create a grant and hand its credential to an agent.

This guide goes from a wallet to a grant credential in an agent's configuration: open the balance, deposit, create the grant, hand the credential over. Each step is shown in the app and in code.

Open the balance#

In the app, connect a wallet and press Open balance. The wallet signs one fixed message, the app derives your Alba key from the signature, and the scan begins. The page shows your notes as it finds them.

In code, pass the wallet's signMessage:

ts
import { connectBalance } from '@alba/sdk'

const owner = await connectBalance((message) => wallet.signMessage(message), { facilitatorUrl })
const balance = await owner.scan()

balance.assets has one entry per pool with available, granted and total, in raw units.

Deposit#

Under Balance, choose Deposit, enter an amount and press Deposit. Your wallet signs one token transfer into the pool. A deposit pays no Alba fee.

In code a deposit has two halves, because the wallet signs the transaction itself:

ts
const build = await owner.deposit({ mint, amount: '5000000', depositor: wallet.address })

const signedTransactionBase64 = await wallet.signTransaction(build.transactionBase64)

const deposit = await owner.submitDeposit({ buildId: build.id, signedTransactionBase64 })

build.transactionBase64 is an unsigned version 0 transaction in base64. wallet.signTransaction stands for your wallet adapter: it signs those bytes and gives them back in base64.

amount is in raw units: 5000000 is 5 USDC. The tokens come from the depositor's associated token account unless you pass depositorTokenAccount. submitDeposit resolves when the transaction has settled, and the next scan finds the new note.

Choose the terms#

Press New grant. The form asks for the five terms.

FieldWhat to enter
AmountWhat the agent may spend in total, fees included. The form shows how much of your balance is available.
Cap per paymentThe most one request may cost. Set it just above the highest price you expect the agent to meet.
Expiry1, 7, 30 or 90 days from now. From code, any future second.
SellersAny seller, or Listed addresses: up to 32 pay-to addresses, one per line, each a Solana address or an Alba address.
LabelYour own name for the grant. Only you see it.

The panel beside the form shows the relay fee for creating the grant, the protocol fee each payment will carry, and what stays in your balance.

Terms are fixed once the grant exists. An amount can be raised later with a top-up. Grants explains how each term is enforced.

Create the grant#

Press Create grant. The browser builds the proof and the facilitator relays the transaction. Your wallet signs nothing, and no wallet of yours appears on chain.

In code:

ts
const week = 7 * 24 * 60 * 60

const { grant, credential } = await owner.createGrant({
  mint,
  amount: '1000000',
  terms: {
    cap: '50000',
    expiry: String(Math.floor(Date.now() / 1000) + week),
    sellers: [],
  },
  label: 'research-agent',
})

Amounts are raw units and expiry is Unix seconds, both as strings. An empty sellers list means any seller. The call resolves when the grant has settled, with the grant as the app shows it and the credential.

The grant is funded from at most two of your notes, which together must cover the amount and the relay fee. If they cannot, createGrant throws INSUFFICIENT_BALANCE.

Hand over the credential#

The app shows the credential once the grant is created, with Copy credential. Give it to the agent the way you give it any secret: as an environment variable from your secret store.

bash
ALBA_GRANT=alba_grant_…

The SDK and the MCP server both read ALBA_GRANT. An agent that holds several grants passes each one in code with alba.with(credential).

Whoever holds the credential can spend this grant inside its terms and can do nothing else with your balance. If it leaks, revoke the grant and what is left returns to you.

Show the credential again#

Open the grant from Grants: its page shows the credential again. In code:

ts
const credential = await owner.showCredential(grant.id)

The credential is rebuilt from your key each time, so there is no copy to lose.