@agent-budget/sdk

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

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. Create the budget client
const budget = await AgentBudgetClient.create({
  appId: 758859031n,           // your deployed AgentBudget app ID
  mnemonic: "your 25-word ...", // agent's mnemonic
});

// 2. Check status
const status = await budget.getBudgetStatus();
console.log(`Remaining: ${status.remaining} µALGO`);

// 3. Wrap x402 fetch with budget enforcement
const avmSigner = toClientAvmSigner(secretKey);
const client = new x402Client().register("algorand:*", new ExactAvmScheme(avmSigner));
const budgetFetch = makeBudgetWrappedFetch({ budget, client });

// 4. Use like normal fetch — budget checks happen automatically
const res = await budgetFetch("https://x402.goplausible.xyz/examples/weather");

API

AgentBudgetClient.create(opts)

| Option | Type | Description | |--------|------|-------------| | appId | bigint | Deployed AgentBudget application ID | | mnemonic | string | 25-word Algorand mnemonic | | algorand? | AlgorandClient | Optional custom AlgorandClient |

Client Methods

| Method | Description | |--------|-------------| | checkAndRecordSpend(amount, server) | Check policy + record spend atomically | | getBudgetStatus() | Get daily limit, spent, remaining, per-tx limit, paused | | getLifetimeStats() | Get total spent, approved count, rejected count | | isWhitelisted(server) | Check if a server is whitelisted | | addWhitelist(server) | Add server to whitelist (owner-only) | | removeWhitelist(server) | Remove server from whitelist (owner-only) | | updateDailyLimit(limit) | Update daily cap (owner-only) | | updatePerTxLimit(limit) | Update per-tx cap (owner-only) | | pause() / unpause() | Emergency pause/unpause (owner-only) |

makeBudgetWrappedFetch(opts)

Returns a fetch-compatible function that automatically:

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

BudgetRejectedError

Thrown when the contract rejects a spend. Properties:

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

Deploy Your Own Contract

cd agent-sdk
cp .env.example .env
# Set AVM_MNEMONIC to your 25-word testnet mnemonic

pnpm install
pnpm run deploy    # deploys contract + sets limits + whitelists host
pnpm run demo      # runs 3-scenario e2e test

License

MIT