agent-budget-sdk

On-chain spending policy SDK for AI agents on Algorand x402.

One shared contract, many cards. Each card is a capped spending key: it can only call check_and_record_spend, and the contract just-in-time funds the card exactly the approved amount on each spend — so a compromised card key can never overspend. Live singleton: 764186085 (testnet).

Install

npm install agent-budget-sdk algosdk

Quick Start

import { AgentBudgetClient, makeBudgetWrappedFetch } from "agent-budget-sdk";
import { x402Client } from "@x402-avm/core/client";
import { ExactAvmScheme } from "@x402-avm/avm/exact/client";
import { toClientAvmSigner } from "@x402-avm/avm";

// 1. Construct the client with the CARD key (the spender)
const budget = await AgentBudgetClient.create({
  appId: 764186085n,
  signerMnemonic: process.env.AGENT_MNEMONIC!, // the card's 25-word mnemonic
});

// 2. Read live policy state
const status = await budget.getCardStatus();
console.log(`Remaining today: ${status.remaining} µALGO · balance: ${status.balance}`);

// 3. Wrap x402 fetch — budget checks happen on-chain before any payment is signed
const secretKey = /* base64 ed25519 secret for the card */;
const client = new x402Client().register("algorand:*", new ExactAvmScheme(toClientAvmSigner(secretKey)));
const budgetFetch = makeBudgetWrappedFetch({ budget, client });

try {
  const res = await budgetFetch("https://x402.goplausible.xyz/examples/weather");
} catch (e) {
  if (e instanceof BudgetRejectedError) console.log(`Blocked: ${e.reason}`);
}

API

AgentBudgetClient.create(opts)

| Option | Type | Description | |--------|------|-------------| | appId | bigint | The AgentBudget singleton app ID | | signerMnemonic | string | Mnemonic that signs — the card key to spend | | cardAddress? | string | Card to target for reads (defaults to the signer's address) | | algodServer? / algodPort? / algodToken? | — | Optional algod config (defaults to Nodely testnet) |

Client methods

| Method | Description | |--------|-------------| | checkAndRecordSpend(amount, server) | Card-signed: check policy, record spend, get JIT-funded. Returns true/false. | | getCardStatus() | { dailyLimit, spentToday, remaining, perTxLimit, balance, isPaused } | | getLifetimeStats() | { totalSpent, txCount, rejectedCount } | | isWhitelisted(server) | Whether a server is whitelisted for this card | | cardExists() | Whether the card exists on-chain |

Owner admin (create/deposit/withdraw/pause/limits/merchants) is done from the owner wallet — see scripts/onboard.ts for the create-card flow, or use the dashboard.

makeBudgetWrappedFetch(opts)

Returns a fetch-compatible function that:

1. Preflights the URL for x402 pricing
2. Calls checkAndRecordSpend on-chain
3. Signs the x402 payment only if approved
4. Throws BudgetRejectedError if rejected

BudgetRejectedError

• reason — REJECTED:PAUSED, REJECTED:NOT_WHITELISTED, REJECTED:EXCEEDS_TX_LIMIT, REJECTED:EXCEEDS_DAILY_LIMIT, REJECTED:INSUFFICIENT_BALANCE
• url, amount, server

Onboard a card + run the demo

cd agent-sdk
cp .env.example .env          # set AVM_MNEMONIC (owner, >=1 ALGO) + ALGORAND_TESTNET_APP_ID
pnpm install
pnpm run onboard              # owner creates a card + whitelists a host + funds the agent (one signature)
pnpm run demo                 # spends with the card key: approved, exhaust budget, rejected

License

MIT