@fretumai/wallet

Drop-in x402 payment SDK for AI agents. Give any agent a funded wallet in 2 lines of code.

Install

npm install @fretumai/wallet

Quick Start

import { AgentWallet } from "@fretumai/wallet";

const wallet = new AgentWallet({ apiKey: "fr_..." });

// Any x402 endpoint — auto-handles 402 → sign → retry
const leads = await wallet.post("https://gateway.mcfagentic.com/api/pipeline/generate-leads", {
  industry: "plumbing",
  location: "Dallas, TX",
  count: 3,
});

That's it. The SDK:

1. Makes the request
2. If the server returns 402 Payment Required, parses the pricing
3. Signs the USDC payment via your Fretum wallet
4. Retries the request with the payment header
5. Returns the data

Configuration

const wallet = new AgentWallet({
  apiKey: "fr_...",                   // Required: your Fretum API key
  baseUrl: "https://fretum.io/api",   // Optional: Fretum API URL
  walletId: "wallet-uuid",            // Optional: specific wallet to use
  maxPerCall: 0.50,                   // Optional: max USD per call (safety limit)
  autoCreate: true,                   // Optional: auto-create wallet on first use
  label: "my-lead-gen-agent",         // Optional: wallet label
});

API

wallet.fetch(url, init?) → Response

Like fetch() but auto-handles x402 payments. Returns the raw Response.

wallet.fetchJSON<T>(url, init?) → T

Like fetch() but auto-parses JSON. Throws on non-2xx.

wallet.post<T>(url, body) → T

Convenience for POST + JSON body + auto-pay + parse response.

wallet.getWalletInfo() → WalletInfo

Get wallet details + USDC balance.

wallet.getClient() → FretumClient

Access the low-level Fretum API client for direct calls.

Low-Level Client

For direct API access without auto-pay:

import { FretumClient } from "@fretumai/wallet";

const client = new FretumClient({ apiKey: "fr_..." });

// Wallet management
const wallet = await client.createWallet("my-agent");
const info = await client.getWallet(wallet.walletId);
await client.updateBudgets(wallet.walletId, { maxPerCall: 1.0, dailyLimit: 50 });

// Manual signing
const result = await client.signPayment(wallet.walletId, paymentRequired, targetUrl);

// Discovery
const results = await client.searchRegistry("lead generation");
const rates = await client.getMarketRates();

// Usage
const usage = await client.getUsage(7);
const txns = await client.getTransactions(wallet.walletId);

How It Works

1. Register at fretum.io to get an API key
2. Fund your wallet by sending USDC to the wallet address on Base L2
3. Use this SDK — your agent can now pay for any x402 API on the internet

Budget Controls

Set spending limits to keep agents in check:

const client = wallet.getClient();
await client.updateBudgets(wallet.getWalletId(), {
  maxPerCall: 0.25,   // Max $0.25 per API call
  dailyLimit: 10.00,  // Max $10/day total
});

Webhook Monitoring

Get real-time notifications of agent transactions via webhooks — configure at fretum.io/dashboard.

Events: transaction.signed, transaction.failed, budget.exceeded

License

MIT