Spending Limits

createBudgetAccount wraps fetch with a total budget, a per-request limit, an hourly limit, and an optional domain allowlist. Its ledger lives in one account instance's memory. Restarting the process, creating another instance, or calling reset() starts new accounting.

Use one instance and await each request before starting the next. The account does not coordinate concurrent requests or enforce a wallet-wide limit across processes. For delegated authority with a seller-bound cap and expiry, see Tabs.

Configure the Account

Use Node.js 22 or newer. Install @dexterai/x402@6.0.0, its peer @dexterai/vault@0.43.4, and viem@2. Fund a wallet using the Node guide, then reuse its .dexter-wallet.json file and set PAID_API_URL to your paid endpoint.

import { readFileSync } from 'node:fs';
import { createBudgetAccount, X402Error } from '@dexterai/x402/client';

const walletPrivateKey = readFileSync('.dexter-wallet.json', 'utf8');
const url = process.env.PAID_API_URL;
if (!url) {
  throw new Error('Set PAID_API_URL to your paid endpoint.');
}

const account = createBudgetAccount({
  walletPrivateKey,
  budget: {
    total: '5.00',
    perRequest: '0.01',
    perHour: '1.00',
  },
  allowedDomains: [new URL(url).hostname],
});

try {
  const response = await account.fetch(url);
  console.log('HTTP status:', response.status);
  console.log(await response.text());
  console.log('Recorded spend:', account.spent);
  console.log('Remaining budget:', account.remaining);
} catch (error) {
  if (error instanceof X402Error && error.code === 'amount_exceeds_max') {
    console.error('Cap reached:', error.message);
  } else if (error instanceof X402Error && error.code === 'payment_rejected') {
    console.error('Payment blocked:', error.message);
  } else {
    // Payment may have been dispatched. Reconcile before another attempt.
    throw error;
  }
}

export PAID_API_URL='https://your-api.example.com/paid/route'
node budget.mjs

The first request may pay up to 0.01 USDC. If a successful call costs 0.002, the ledger records that amount. The formatted spent and remaining strings round to cents; use spentAmount when inspecting smaller payments.

Limit Scope

Budget amounts are dollar-denominated strings. For Solana USDC, '0.01' means one cent. Restrict the assets and networks used by your application before treating these values as a common dollar budget.

The allowlist checks the request URL's hostname. If you require an exact-origin policy, also validate the scheme, port, and redirect behavior in your application.

Inspect Recorded Spend

for (const payment of account.ledger) {
  console.log(payment.amount, payment.domain, payment.network, payment.timestamp);
}

Ledger entries are added when the wrapped payment request returns. A connection failure after submission can leave a payment absent from this ledger. Reconcile uncertain attempts against payment evidence before continuing or restarting the process.

Cap Errors

A cap check throws X402Error with code amount_exceeds_max before signing the proposed payment. A disallowed hostname throws payment_rejected. Inspect the message to distinguish the rejected condition.

Other failures can happen after signing or dispatch. The browser hook and budget wrapper throw errors; payAndFetch returns a PayResult. Keep those interfaces distinct when adding retry handling. See Errors and Retries.