@bondedhq/sdk 0.1.4 → 0.1.5

package/dist/openai-agents.d.ts

@@ -0,0 +1,33 @@
+import { type GuardPaymentsOptions } from "./payments.js";
+export type { GuardPaymentsOptions } from "./payments.js";
+/**
+ * The part of an OpenAI Agents SDK function tool (`tool()` from `@openai/agents`) the guard needs.
+ * The SDK calls `invoke` with the run context and the model's arguments as a JSON string.
+ */
+export interface OpenAiAgentsFunctionTool {
+    type: "function";
+    name: string;
+    invoke: (runContext: never, input: string, details?: never) => Promise<unknown>;
+}
+/**
+ * Your own OpenAI Agents SDK pay tool, with every call checked against the payment mandate first
+ * (see `PaymentGuard`, or pass the hosted `PaymentGate` as `guard`). Same name, description,
+ * parameters, approval setting and guardrails. When the guard refuses (Enforce mode blocked it,
+ * the guard is frozen, the gate couldn't be reached, or it can't read the payment) your tool is not
+ * called and the model gets `Error: ...` naming the rules broken, so it can react. In Monitor mode
+ * a breaking payment goes through and the guard's `onBreach` reports it.
+ *
+ * ```ts
+ * import { Agent, tool } from "@openai/agents";
+ * import { guardOpenAiAgentsPayTool } from "@bondedhq/sdk/openai-agents";
+ *
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const agent = new Agent({ name: "AP clerk", tools: [...readOnlyTools, guardOpenAiAgentsPayTool(payInvoice, { guard })] });
+ * ```
+ *
+ * The payment is read from the tool's arguments: `{ account, amountUsd, invoiceReference }` unless
+ * you pass `toPayment`. If the tool needs a person's approval, the run stops for it before the
+ * guard is asked, so an approved payment can still be blocked.
+ */
+export declare function guardOpenAiAgentsPayTool<T extends OpenAiAgentsFunctionTool>(payTool: T, options: GuardPaymentsOptions<Record<string, unknown>>): T;
+//# sourceMappingURL=openai-agents.d.ts.map

package/dist/openai-agents.js

@@ -0,0 +1,52 @@
+import { BondedError } from "./errors.js";
+import { guardPayments, isPaymentRefusal } from "./payments.js";
+/**
+ * Your own OpenAI Agents SDK pay tool, with every call checked against the payment mandate first
+ * (see `PaymentGuard`, or pass the hosted `PaymentGate` as `guard`). Same name, description,
+ * parameters, approval setting and guardrails. When the guard refuses (Enforce mode blocked it,
+ * the guard is frozen, the gate couldn't be reached, or it can't read the payment) your tool is not
+ * called and the model gets `Error: ...` naming the rules broken, so it can react. In Monitor mode
+ * a breaking payment goes through and the guard's `onBreach` reports it.
+ *
+ * ```ts
+ * import { Agent, tool } from "@openai/agents";
+ * import { guardOpenAiAgentsPayTool } from "@bondedhq/sdk/openai-agents";
+ *
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const agent = new Agent({ name: "AP clerk", tools: [...readOnlyTools, guardOpenAiAgentsPayTool(payInvoice, { guard })] });
+ * ```
+ *
+ * The payment is read from the tool's arguments: `{ account, amountUsd, invoiceReference }` unless
+ * you pass `toPayment`. If the tool needs a person's approval, the run stops for it before the
+ * guard is asked, so an approved payment can still be blocked.
+ */
+export function guardOpenAiAgentsPayTool(payTool, options) {
+    if (payTool?.type !== "function" || typeof payTool.invoke !== "function")
+        throw new BondedError("CONFIG", "guardOpenAiAgentsPayTool needs a function tool");
+    const invoke = payTool.invoke.bind(payTool);
+    const guarded = guardPayments((_args, runContext, input, details) => invoke(runContext, input, details), options);
+    return {
+        ...payTool,
+        invoke: (async (runContext, input, details) => {
+            let args;
+            try {
+                args = JSON.parse(input || "{}");
+            }
+            catch {
+                return "Error: the payment's arguments are not valid JSON; no payment was made";
+            }
+            // A custom toPayment reads fields: null or an array would throw before the guard answers.
+            if (!args || typeof args !== "object" || Array.isArray(args))
+                return "Error: the payment's arguments must be an object; no payment was made";
+            try {
+                return await guarded(args, runContext, input, details);
+            }
+            catch (error) {
+                if (isPaymentRefusal(error))
+                    return `Error: ${error.message}`;
+                throw error;
+            }
+        }),
+    };
+}
+//# sourceMappingURL=openai-agents.js.map

package/dist/payments.d.ts

@@ -1,4 +1,5 @@
-import { type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentLimits, type PaymentRule, type SignedGateReceipt, type VerifiedChange } from "@bondedhq/shared";
+import { type BudgetTerms, type GateRule, type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentLimits, type SignedGateReceipt, type VerifiedChange } from "@bondedhq/shared";
+import { type BudgetRequest, type PaymentBudget } from "./budget.js";
 import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError } from "./errors.js";
 /** The off-chain payment mandate an agent's payments are checked against. */
 export interface PaymentMandate extends PaymentLimits {
@@ -6,6 +7,13 @@ export interface PaymentMandate extends PaymentLimits {
     mode: "monitor" | "enforce";
     /** After the first breach, refuse every payment until a person unfreezes the guard. */
     freezeOnBreach: boolean;
+    /**
+     * False when your payments have no invoices: a payment needs a vendor on the list and to stay
+     * within the limits, and its reference is optional. Refunds still need an approved refund.
+     */
+    invoiceMatching?: boolean;
+    /** Payments allowed in any hour, with invoice matching off. No limit unless set. */
+    maxPaymentsPerHour?: number;
 }
 /** A supplier as your vendor master holds it. Its account is one the agent may pay. */
 export interface PaymentVendor {
@@ -28,18 +36,32 @@ export interface PaymentGuardState {
      * `unknown_payee`.
      */
     unverifiedChanges: VerifiedChange[];
+    /**
+     * Open budgets (`budget()`): their terms and what was counted against them. Each one's whole
+     * amount is in `payments` until it closes. Absent in state saved before budgets existed.
+     */
+    budgets?: LocalBudgetState[];
+    /** When budget payments were made in the last hour (Unix milliseconds), for the hourly limit. */
+    budgetSpends?: number[];
+}
+/** An open local budget, as the guard's state keeps it. */
+export interface LocalBudgetState {
+    id: string;
+    terms: BudgetTerms;
+    spentMicros: number;
+    payments: number;
 }
 /** One payment (or bank change) that broke the mandate, as the guard reports it. */
 export interface PaymentBreach {
-    kind: "invoice" | "refund" | "vendor_change";
+    kind: "invoice" | "refund" | "vendor_change" | "budget";
     /** Every rule broken, most serious first. */
-    rules: PaymentRule[];
-    /** Each rule in plain words (`PAYMENT_RULE_WORDS`), in the same order. */
+    rules: GateRule[];
+    /** Each rule in plain words (`GATE_RULE_WORDS`), in the same order. */
     reasons: string[];
     /** Enforce mode stopped it: the pay function was not called. */
     blocked: boolean;
     account: string;
-    /** The invoice or refund reference; empty for a bank change. */
+    /** The invoice or refund reference; empty for a bank change or a budget. */
     reference: string;
     /** The vendor whose verified account this is (or, for a bank change, the vendor changed). */
     vendorId: string | null;
@@ -58,7 +80,7 @@ export interface PaymentBreach {
 /** The rule verdict for a payment, without making it. */
 export interface PaymentVerdict {
     /** Every rule the payment breaks, most serious first. Empty when it is allowed. */
-    rules: PaymentRule[];
+    rules: GateRule[];
     reasons: string[];
     amountUsd: number;
     reference: string;
@@ -134,6 +156,17 @@ export declare class PaymentGuard {
         vendorId: string;
         account: string;
     }, update: () => R | Promise<R>): Promise<R>;
+    /**
+     * Opens a budget: one check for many small payments to one payee (see `PaymentBudget`). Needs
+     * `invoiceMatching: false`. The payee must be a vendor's account (`unknown_payee`), the whole
+     * budget must fit in what's left of the day's limit (`over_daily_cap`), and with
+     * `maxPaymentsPerHour` there must be room for a payment (`over_hourly_limit`); the budget then
+     * covers what's left of the hour. Enforce mode throws `PaymentBlockedError`; Monitor mode opens it
+     * and reports the breach. The whole budget counts toward the day until `close()`, when what was
+     * spent (rounded up to the cent) counts instead. A budget past its end is closed the next time
+     * one is opened.
+     */
+    budget(request: BudgetRequest): Promise<PaymentBudget>;
 }
 /** A payment guard: see `PaymentGuard`. */
 export declare function paymentGuard(options: PaymentGuardOptions): PaymentGuard;

package/dist/payments.js

@@ -1,11 +1,16 @@
-import { checkInvoicePayment, checkRefundPayment, isVerifiedChange, normalAccount, PAYMENT_RULE_WORDS, utcDay, } from "@bondedhq/shared";
+import { checkBudget, checkGeneralPayment, checkInvoicePayment, checkRefundPayment, GATE_RULE_WORDS, isVerifiedChange, normalAccount, utcDay, usdToMicros, } from "@bondedhq/shared";
+import { BudgetBase } from "./budget.js";
 import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, } from "./errors.js";
 const read = async (source) => typeof source === "function" ? await source() : (source ?? []);
 const copy = (state) => ({
     payments: state.payments.map((p) => ({ ...p })),
     frozen: state.frozen,
     unverifiedChanges: state.unverifiedChanges.map((c) => ({ ...c })),
+    budgets: (state.budgets ?? []).map((b) => ({ ...b, terms: { ...b.terms } })),
+    budgetSpends: [...(state.budgetSpends ?? [])],
 });
+/** The reference a local budget's reservation is recorded under. */
+const budgetReference = (id) => `budget:${id}`;
 /**
  * The payment mandate, checked inside your own process: the same rules (`@bondedhq/shared`'s
  * payment mandate) the Arena rates agents against, with no network and no model. You give it the
@@ -73,7 +78,8 @@ export class PaymentGuard {
         return this.#exclusive(async () => {
             if (this.#state.frozen)
                 throw new PaymentFrozenError();
-            const day = utcDay(this.#now());
+            const now = this.#now();
+            const day = utcDay(now);
             const check = await this.#check(attempt, kind, day);
             if (check.rules.length > 0) {
                 await this.#breach({
@@ -98,6 +104,7 @@ export class PaymentGuard {
                 amountUsd: check.amountUsd,
                 invoiceReference: check.reference,
                 day,
+                ...(this.mandate.invoiceMatching === false ? { at: now.toISOString() } : {}),
                 ...(kind === "refund" ? { kind } : {}),
             });
             await this.#save();
@@ -142,6 +149,141 @@ export class PaymentGuard {
             return update();
         });
     }
+    /**
+     * Opens a budget: one check for many small payments to one payee (see `PaymentBudget`). Needs
+     * `invoiceMatching: false`. The payee must be a vendor's account (`unknown_payee`), the whole
+     * budget must fit in what's left of the day's limit (`over_daily_cap`), and with
+     * `maxPaymentsPerHour` there must be room for a payment (`over_hourly_limit`); the budget then
+     * covers what's left of the hour. Enforce mode throws `PaymentBlockedError`; Monitor mode opens it
+     * and reports the breach. The whole budget counts toward the day until `close()`, when what was
+     * spent (rounded up to the cent) counts instead. A budget past its end is closed the next time
+     * one is opened.
+     */
+    budget(request) {
+        return this.#exclusive(async () => {
+            if (this.#state.frozen)
+                throw new PaymentFrozenError();
+            if (this.mandate.invoiceMatching !== false)
+                throw new BondedError("CONFIG", "budgets need invoiceMatching: false on the mandate");
+            const now = this.#now();
+            const day = utcDay(now);
+            if (this.#settleExpired(now.getTime()))
+                await this.#save();
+            const ttlSeconds = request.ttlSeconds ?? 3600;
+            if (!Number.isInteger(ttlSeconds) || ttlSeconds < 60 || ttlSeconds > 3600)
+                throw new BondedError("INVALID_PAYMENT", "ttlSeconds must be a whole number from 60 to 3,600");
+            const maxAll = usdToMicros(this.mandate.maxPaymentUsd) ?? 0;
+            const asked = request.maxPaymentUsd === undefined ? maxAll : usdToMicros(request.maxPaymentUsd);
+            if (asked === undefined || asked <= 0)
+                throw new BondedError("INVALID_PAYMENT", "maxPaymentUsd must be positive, with at most six decimals");
+            const check = checkBudget({
+                limits: {
+                    ...this.mandate,
+                    maxPaymentsPerHour: this.mandate.maxPaymentsPerHour ?? null,
+                },
+                payees: await this.#payees(),
+                payments: this.#state.payments,
+                paymentsLastHour: this.#paymentsLastHour(),
+                reservedPayments: this.#reservedPayments(),
+                day,
+            }, { account: request.account, budgetUsd: request.amountUsd });
+            if (!check.ok)
+                throw new BondedError("INVALID_PAYMENT", check.error);
+            const id = `local-${crypto.randomUUID()}`;
+            if (check.rules.length > 0)
+                await this.#breach({
+                    kind: "budget",
+                    rules: check.rules,
+                    reasons: words(check.rules),
+                    blocked: this.mandate.mode === "enforce",
+                    account: request.account,
+                    reference: "",
+                    vendorId: check.vendorId,
+                    amountUsd: request.amountUsd,
+                    lossUsd: 0,
+                    overpaidUsd: 0,
+                    day,
+                });
+            const terms = {
+                account: normalAccount(request.account),
+                budgetMicros: Math.round(request.amountUsd * 100) * 10_000,
+                maxPaymentMicros: Math.min(asked, maxAll),
+                maxPayments: check.maxPayments,
+                startsAtMs: now.getTime(),
+                expiresAtMs: now.getTime() + ttlSeconds * 1000,
+            };
+            // The reservation: no time, so it doesn't count as a payment for the hourly limit.
+            this.#state.payments.push({
+                account: request.account,
+                vendorId: check.vendorId,
+                amountUsd: Math.round(request.amountUsd * 100) / 100,
+                invoiceReference: budgetReference(id),
+                day,
+            });
+            const kept = { id, terms, spentMicros: 0, payments: 0 };
+            this.#state.budgets = [...(this.#state.budgets ?? []), kept];
+            await this.#save();
+            return new LocalBudget(id, terms, this.mandate.mode, () => this.#now().getTime(), {
+                frozen: () => this.#state.frozen,
+                report: (breach) => this.#report(breach),
+                recorded: (spend) => this.#exclusive(async () => {
+                    const b = this.#state.budgets?.find((x) => x.id === id);
+                    if (b) {
+                        b.spentMicros += spend.amountMicros;
+                        b.payments += 1;
+                    }
+                    this.#state.budgetSpends = [...(this.#state.budgetSpends ?? []), spend.atMs];
+                    await this.#save();
+                }),
+                released: (spend) => void this.#exclusive(async () => {
+                    const b = this.#state.budgets?.find((x) => x.id === id);
+                    if (b) {
+                        b.spentMicros -= spend.amountMicros;
+                        b.payments -= 1;
+                    }
+                    const spends = this.#state.budgetSpends ?? [];
+                    const at = spends.lastIndexOf(spend.atMs);
+                    if (at >= 0)
+                        spends.splice(at, 1);
+                    await this.#save();
+                }),
+                close: () => this.#exclusive(async () => {
+                    if (this.#closeBudget(id))
+                        await this.#save();
+                }),
+            });
+        });
+    }
+    /** Payments open budgets may still make, for the hourly limit. A budget past its end makes none. */
+    #reservedPayments() {
+        const now = this.#now().getTime();
+        return (this.#state.budgets ?? []).reduce((sum, b) => b.terms.maxPayments === null || b.terms.expiresAtMs <= now
+            ? sum
+            : sum + Math.max(0, b.terms.maxPayments - b.payments), 0);
+    }
+    /** Closes budgets past their end. True when any closed. */
+    #settleExpired(nowMs) {
+        const expired = (this.#state.budgets ?? []).filter((b) => b.terms.expiresAtMs <= nowMs);
+        for (const b of expired)
+            this.#closeBudget(b.id);
+        return expired.length > 0;
+    }
+    /** The budget's reservation becomes what it spent, rounded up to the cent. */
+    #closeBudget(id) {
+        const budget = this.#state.budgets?.find((b) => b.id === id);
+        if (!budget)
+            return false;
+        this.#state.budgets = this.#state.budgets.filter((b) => b.id !== id);
+        const at = this.#state.payments.findIndex((p) => p.invoiceReference === budgetReference(id));
+        if (at >= 0) {
+            const cents = Math.ceil(budget.spentMicros / 10_000);
+            if (cents > 0)
+                this.#state.payments[at] = { ...this.#state.payments[at], amountUsd: cents / 100 };
+            else
+                this.#state.payments.splice(at, 1);
+        }
+        return true;
+    }
     /** Runs the shared rule check against the builder's data and the guard's payments. */
     async #check(attempt, kind, day) {
         const payees = await this.#payees();
@@ -149,11 +291,30 @@ export class PaymentGuard {
         const payments = this.#state.payments;
         const check = kind === "refund"
             ? checkRefundPayment({ limits, payees, refunds: await read(this.#options.refunds), payments, day }, attempt)
-            : checkInvoicePayment({ limits, payees, invoices: await read(this.#options.invoices), payments, day }, attempt);
+            : this.mandate.invoiceMatching === false
+                ? checkGeneralPayment({
+                    limits: { ...limits, maxPaymentsPerHour: limits.maxPaymentsPerHour ?? null },
+                    payees,
+                    payments,
+                    // Payments open budgets may still make count toward the hourly limit too.
+                    paymentsLastHour: this.#paymentsLastHour() + this.#reservedPayments(),
+                    day,
+                }, attempt)
+                : checkInvoicePayment({ limits, payees, invoices: await read(this.#options.invoices), payments, day }, attempt);
         if (!check.ok)
             throw new BondedError("INVALID_PAYMENT", check.error);
         return check;
     }
+    /**
+     * Payments in the last hour, budget payments included. One restored from before the guard kept
+     * times doesn't count.
+     */
+    #paymentsLastHour() {
+        const since = this.#now().getTime() - 3_600_000;
+        this.#state.budgetSpends = (this.#state.budgetSpends ?? []).filter((at) => at >= since);
+        return (this.#state.payments.filter((p) => p.at !== undefined && Date.parse(p.at) >= since).length +
+            this.#state.budgetSpends.length);
+    }
     /**
      * Known payees: each vendor's account on file, unless it got there through an unverified
      * change, and every account a verified ticket covers.
@@ -171,6 +332,12 @@ export class PaymentGuard {
     }
     /** Reports a breach, freezes if the mandate says so, and throws when Enforce mode blocks it. */
     async #breach(breach) {
+        await this.#report(breach);
+        if (breach.blocked)
+            throw new PaymentBlockedError(breach);
+    }
+    /** Freezes if the mandate says so, and tells `onBreach`. */
+    async #report(breach) {
         if (this.mandate.freezeOnBreach) {
             this.#state.frozen = true;
             await this.#save();
@@ -180,8 +347,6 @@ export class PaymentGuard {
             rules: [...breach.rules],
             reasons: [...breach.reasons],
         });
-        if (breach.blocked)
-            throw new PaymentBlockedError(breach);
     }
     async #save() {
         await this.#options.onStateChange?.(this.state());
@@ -193,7 +358,36 @@ export class PaymentGuard {
         return next;
     }
 }
-const words = (rules) => rules.map((r) => PAYMENT_RULE_WORDS[r]);
+const words = (rules) => rules.map((r) => GATE_RULE_WORDS[r]);
+/** A budget the local guard opened: spends are counted in its state, nothing is sent anywhere. */
+class LocalBudget extends BudgetBase {
+    ledger;
+    constructor(id, terms, mode, now, ledger) {
+        super(id, terms, mode, now, (breach) => ledger.report(breach));
+        this.ledger = ledger;
+    }
+    spend(amountMicros, options) {
+        if (this.ledger.frozen())
+            return Promise.reject(new PaymentFrozenError());
+        return super.spend(amountMicros, options);
+    }
+    recorded(spend) {
+        return this.ledger.recorded(spend);
+    }
+    releasable() {
+        return !this.closed;
+    }
+    released(spend) {
+        this.ledger.released(spend);
+    }
+    flush() {
+        return Promise.resolve();
+    }
+    async close() {
+        this.markClosed();
+        await this.ledger.close();
+    }
+}
 /** A payment guard: see `PaymentGuard`. */
 export function paymentGuard(options) {
     return new PaymentGuard(options);
@@ -260,7 +454,12 @@ function defaultPayment(input) {
     return {
         account: field(args, "account"),
         amountUsd,
-        invoiceReference: field(args, "invoiceReference" in args ? "invoiceReference" : "reference"),
+        // Left out, it reaches the rules as empty: only invoice matching needs one.
+        ...("invoiceReference" in args || "reference" in args
+            ? {
+                invoiceReference: field(args, "invoiceReference" in args ? "invoiceReference" : "reference"),
+            }
+            : {}),
         ...(typeof args.requestId === "string" ? { requestId: args.requestId } : {}),
     };
 }

package/dist/x402.d.ts

@@ -0,0 +1,136 @@
+import type { BudgetRequest, PaymentBudget } from "./budget.js";
+/**
+ * One way to pay that an x402 server offers, as `@x402/core` gives it to client hooks. In x402
+ * version 2 the price is `amount`; version 1 called it `maxAmountRequired`. Both are in the
+ * asset's smallest unit (for USDC, millionths of a dollar).
+ */
+export interface X402Requirements {
+    scheme: string;
+    /** CAIP-2 in version 2 (`eip155:8453`, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`); a name in version 1 (`base`). */
+    network: string;
+    asset: string;
+    payTo: string;
+    amount?: string;
+    maxAmountRequired?: string;
+    resource?: string;
+    extra?: Record<string, unknown>;
+}
+/** What `x402Client.onBeforePaymentCreation` hooks are given. */
+export interface X402PaymentContext {
+    paymentRequired: {
+        x402Version: number;
+        resource?: {
+            url?: string;
+        };
+    };
+    selectedRequirements: X402Requirements;
+}
+/** A hook result that stops the payment: the x402 client signs nothing. */
+export type X402Abort = {
+    abort: true;
+    reason: string;
+};
+/** The `x402Client` hooks the guard registers (`@x402/core`'s client, or anything shaped like it). */
+export interface X402ClientHooks {
+    onBeforePaymentCreation(hook: (context: X402PaymentContext) => Promise<void | X402Abort>): unknown;
+    onAfterPaymentCreation?(hook: (context: X402PaymentContext & {
+        paymentPayload: object;
+    }) => Promise<void>): unknown;
+    onPaymentCreationFailure?(hook: (context: X402PaymentContext & {
+        error: Error;
+    }) => Promise<void>): unknown;
+    onPaymentResponse?(hook: (context: {
+        paymentPayload: object;
+        settleResponse?: {
+            success: boolean;
+            transaction?: string;
+        };
+        paymentRequired?: unknown;
+        error?: Error;
+    }) => Promise<void>): unknown;
+}
+/** A US dollar stablecoin the guard counts at one dollar per token. */
+export interface X402Asset {
+    /** CAIP-2 network id, or an x402 version 1 network name. */
+    network: string;
+    /** The token's contract or mint address. EVM addresses compare case-insensitively. */
+    asset: string;
+    decimals: number;
+}
+/**
+ * USDC on the networks x402 lists it for, by network id (and the version 1 name, where it has one).
+ * The guard only counts these (and any `assets` you add) as dollars; a price in anything else is
+ * refused.
+ */
+export declare const X402_USD_ASSETS: readonly X402Asset[];
+export interface X402GuardOptions {
+    /**
+     * A `PaymentGuard`, or the hosted `PaymentGate`: anything with `budget()`. Its mandate needs
+     * invoice matching off, and each service's `payTo` address on the vendor list, so the agent
+     * pays only services you listed.
+     */
+    guard: {
+        budget(request: BudgetRequest): Promise<PaymentBudget>;
+    };
+    /**
+     * The budget opened for each service: `amountUsd` (default $1, raised to fit a bigger price),
+     * `ttlSeconds` (default an hour) and `maxPaymentUsd` (default the mandate's per-payment limit).
+     */
+    budget?: {
+        amountUsd?: number;
+        ttlSeconds?: number;
+        maxPaymentUsd?: number;
+    };
+    /** More US dollar stablecoins to accept, beyond `X402_USD_ASSETS`. */
+    assets?: readonly X402Asset[];
+    /** Reads the payee and the exact price. Default: `payTo`, and the price in micro-dollars. */
+    toPayment?: (requirements: X402Requirements, context: X402PaymentContext) => {
+        account: string;
+        amountMicros: number;
+    };
+    /** Errors from closing a used-up budget in the background. Default: ignored. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Checks every x402 payment against a budget for its service before the x402 client signs it.
+ *
+ * The first payment to a service opens a budget for it (`guard.budget`): one check against the
+ * rules, and with the hosted gate a signed receipt. Every payment then checks against that budget
+ * in exact micro-dollars with no network call, so a $0.001 call is fast and counts as $0.001.
+ * When a budget is used up or ends, the next payment closes it and opens another.
+ *
+ * - A refused payment is never signed: the hook aborts and the request fails with the reason. In
+ *   Monitor mode a payment that breaks the budget is signed and `onBreach` reports it.
+ * - A payment the server turns down (it answers 402 again, or settlement fails) is taken back.
+ * - Call `close()` when the agent stops, so the unspent part of each budget stops counting toward
+ *   the day. Unclosed hosted budgets close themselves soon after they end.
+ */
+export declare class X402Guard {
+    #private;
+    constructor(options: X402GuardOptions);
+    /** Registers the guard's hooks on an x402 client and returns the client. */
+    register<C extends X402ClientHooks>(client: C): C;
+    /** The `onBeforePaymentCreation` hook: counts the payment against its service's budget. */
+    check(context: X402PaymentContext): Promise<void | X402Abort>;
+    /** The open budgets, one per service. */
+    budgets(): PaymentBudget[];
+    /** Closes every budget: sends what's left and stops the unspent part counting. */
+    close(): Promise<void>;
+}
+/** An x402 guard: see `X402Guard`. */
+export declare function x402Guard(options: X402GuardOptions): X402Guard;
+/**
+ * Registers a new `X402Guard` on an x402 client and returns the client, for when you never need
+ * to close its budgets yourself (hosted budgets close themselves after they end; local ones close
+ * when the next budget opens).
+ */
+export declare function guardX402Client<C extends X402ClientHooks>(client: C, options: X402GuardOptions): C;
+/**
+ * The payee and the exact price in micro-dollars, for a price in a dollar stablecoin the guard
+ * knows. Past six decimals it rounds up.
+ */
+export declare function x402Price(r: X402Requirements, assets?: readonly X402Asset[]): {
+    account: string;
+    amountMicros: number;
+};
+//# sourceMappingURL=x402.d.ts.map