@bondedhq/sdk 0.1.4 → 0.1.6

package/README.md

@@ -182,6 +182,11 @@ The six rules: pay only a vendor's account on file or one a verified ticket cove
 limits (`over_payment_cap`, `over_daily_cap`; days are UTC). `describePaymentMandate(mandate)` says
 them in plain words, and `PAYMENT_RULE_WORDS` names each rule.
 
+Payments with no invoices: set `invoiceMatching: false` on the mandate, and optionally
+`maxPaymentsPerHour`. A payment then needs a listed vendor and to stay within the limits, and
+`invoiceReference` is optional. `GATE_RULE_WORDS` adds the hourly rule's words. The hosted gate
+reads the same setting from your account, so your code doesn't change.
+
 - **Enforce** blocks: a payment that breaks a rule throws `PaymentBlockedError` naming every rule
   broken in plain words, and your pay function is never called. **Monitor** calls it anyway and
   reports the breach to `onBreach`. A bank change no ticket covers that Monitor lets through is
@@ -211,10 +216,104 @@ const lcTools = [...readOnlyTools, guardLangChainPayTool(payInvoiceTool, { guard
 server.registerTool("pay_invoice", config, guardMcpPayHandler(payInvoiceHandler, { guard }));
 ```
 
+The OpenAI Agents SDK works the same way, and the model gets `Error: ...` text back:
+
+```ts
+import { Agent } from "@openai/agents";
+import { guardOpenAiAgentsPayTool } from "@bondedhq/sdk/openai-agents";
+
+const agent = new Agent({
+  name: "AP clerk",
+  tools: [...readOnlyTools, guardOpenAiAgentsPayTool(payInvoiceTool, { guard })],
+});
+```
+
+If the tool needs a person's approval (`needsApproval`), the run stops for that first. The guard
+still checks the payment once it is approved.
+
 What it doesn't do: it is a local check, so code that calls your pay function directly skips it.
 Keep the unwrapped function out of the agent's reach. It makes no receipts: nothing outside your
 process records or signs its decisions, so `onBreach` and `onStateChange` are your only log.
 
+### Budgets
+
+For many small payments to one payee, such as an API that charges $0.001 a call, ask for a budget
+and check each payment against it. The budget is checked once against the rules; each payment is
+checked against the budget with no rule check and no network call, in exact micro-dollars
+(millionths of a dollar), so $0.001 counts as $0.001. Budgets need `invoiceMatching: false`.
+
+```ts
+const budget = await guard.budget({ account: "0x1111111111111111111111111111111111111111", amountUsd: 1 });
+
+await budget.spend(1_000); // $0.001: throws PaymentBlockedError in Enforce mode if it doesn't fit
+await budget.close(); // the unspent part stops counting toward the day
+```
+
+- **The check:** the payee must be a vendor's account (`unknown_payee`), the whole budget must fit
+  in what's left of the day (`over_daily_cap`), and with `maxPaymentsPerHour` there must be room
+  for a payment (`over_hourly_limit`). Enforce throws `PaymentBlockedError`; Monitor opens it and
+  reports the breach.
+- **The terms** (`budget.terms`): the payee, the budget, the most one payment may be
+  (`maxPaymentUsd`, default the mandate's per-payment limit), how many payments it covers (what's
+  left of the hour, with an hourly limit) and its end (`ttlSeconds`, an hour at most).
+- **Each payment:** `spend(amountMicros)` checks it against the terms. One that doesn't fit breaks
+  `over_budget`: Enforce throws and doesn't count it; Monitor counts it and reports it. Spend
+  before you pay. `release(id)` takes back one the payee turned down.
+- **The day:** the whole budget counts toward the daily limit until `close()`; then what was spent,
+  rounded up to the cent. A budget past its end is closed the next time one is opened.
+- **The hosted gate:** `gate.budget(...)` is the same, with a signed receipt whose input commits to
+  the terms; the SDK checks the receipt, recomputes the input's hash and reruns its rules. Payments
+  go to the gate in the background and on `close()`, whose receipt commits to every one. Unclosed
+  budgets close themselves soon after they end.
+
+### x402
+
+For an agent that pays for APIs with [x402](https://x402.org): check each payment before the x402
+client signs it. Turn invoice matching off, and put each service's `payTo` address on the vendor
+list, so the agent pays only services you chose:
+
+```ts
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { x402Guard } from "@bondedhq/sdk/x402";
+
+const guard = paymentGate({ apiKey: process.env.BONDED_GATE_KEY! }); // or a local paymentGuard
+const x402 = x402Guard({ guard, budget: { amountUsd: 1 } });
+const client = x402.register(new x402Client().register("eip155:*", new ExactEvmScheme(signer)));
+const paidFetch = wrapFetchWithPayment(fetch, client);
+
+// ...and when the agent stops:
+await x402.close();
+```
+
+- The first payment to a service opens a budget for it (`budget.amountUsd`, default $1, raised to
+  fit a bigger price). Each payment then checks against that budget, exact to the micro-dollar.
+  When it's used up or ends, the next payment closes it and opens another.
+- A refused payment is never signed: the request fails with the reason. Monitor mode signs it and
+  reports the breach.
+- A payment the server turns down (it answers 402 again, or settlement fails) is taken back. One
+  that settles is reported with its transaction hash.
+- Prices count only in USDC on the networks x402 lists it for (Base, Ethereum, Arbitrum, Polygon,
+  Avalanche and Solana, plus Base Sepolia and Solana devnet). A price in any other token is
+  refused; add your own dollar stablecoins with `assets`.
+- `guardX402Client(client, { guard })` registers a guard and returns the client, if you never close
+  budgets yourself. `x402Price(requirements)` gives the payee and exact price it reads.
+
+The guard runs in the agent's process, so code that holds the wallet key can still sign without
+it. To stop that, keep the key out of the agent: run [`@bondedhq/signer`](../signer/README.md) on
+your own server, with the key in your KMS, and give the agent `remoteX402Signer` in place of a
+wallet. The signer runs the same budgets and signs only payments that fit:
+
+```ts
+import { remoteX402Signer } from "@bondedhq/sdk/x402";
+
+const signer = await remoteX402Signer({ url: "http://bonded-signer:8402", token });
+const client = new x402Client().register("eip155:*", new ExactEvmScheme(signer));
+```
+
+A payment the signer won't sign fails with a `BondedError` (`SIGNER_REFUSED`, `SIGNER_UNAVAILABLE`,
+`SIGNER_UNAUTHORIZED` or `INVALID_PAYMENT`); `isPaymentRefusal` recognizes each.
+
 ## Hosted payment gate (off chain)
 
 The same rules as the guard, run by Bonded instead of inside your process. Your vendors, approved

package/dist/budget.d.ts

@@ -0,0 +1,97 @@
+import { type BudgetTerms } from "@bondedhq/shared";
+import type { PaymentBreach } from "./payments.js";
+/**
+ * A budget: one check for many small payments to one payee (an x402 API, say). Ask for one with
+ * `guard.budget(...)` on the local `PaymentGuard` or the hosted `PaymentGate`; then check each
+ * payment with `spend` before making it. `spend` needs no network: it checks the payment against
+ * the budget's terms (the payee, the per-payment limit, how many payments it covers, its end, and
+ * what's left) in exact micro-dollars, so a $0.001 call counts as $0.001.
+ *
+ * In Enforce mode a payment that breaks the terms throws `PaymentBlockedError` and isn't counted;
+ * in Monitor mode it is counted and reported to `onBreach`. A hosted budget sends its payments to
+ * the gate in the background and on `close()`; closing it gets a receipt that commits to every one.
+ */
+export interface PaymentBudget {
+    /** The budget's id: the hosted gate's decision id, or a local one. */
+    readonly id: string;
+    /** What it allows: payee, budget, per-payment limit, payment count and end. */
+    readonly terms: Readonly<BudgetTerms>;
+    readonly mode: "monitor" | "enforce";
+    /** Micro-dollars counted so far, released payments left out. */
+    readonly spentMicros: number;
+    /** Payments counted so far. */
+    readonly payments: number;
+    /** Closed, or past its end. */
+    readonly closed: boolean;
+    /** What a payment of this size would break, in plain words; undefined when it fits. */
+    problem(amountMicros: number): string | undefined;
+    /** Check a payment against the terms and count it. See the interface's description. */
+    spend(amountMicros: number, options?: {
+        id?: string;
+        reference?: string;
+    }): Promise<BudgetSpend>;
+    /**
+     * Take back a payment that never went out (the payee turned it down). Only before it was sent to
+     * the gate; returns whether it was taken back.
+     */
+    release(spendId: string): boolean;
+    /** Attach what the payment settled as (an x402 transaction hash) before it is sent. */
+    settle(spendId: string, reference: string): void;
+    /** Send payments to the gate now (hosted budgets; nothing to do locally). */
+    flush(): Promise<void>;
+    /** Send what's left and close: the unspent part stops counting toward the day's limit. */
+    close(): Promise<void>;
+}
+/** A payment counted against a budget. */
+export interface BudgetSpend {
+    id: string;
+    amountMicros: number;
+    reference: string;
+    /** Unix milliseconds. */
+    atMs: number;
+}
+/** What `guard.budget(...)` takes. */
+export interface BudgetRequest {
+    /** The one account it pays: an x402 service's `payTo` address, say. */
+    account: string;
+    /** The budget, in US dollars with at most two decimals. */
+    amountUsd: number;
+    /** The most one payment may be, up to six decimals. Default: the mandate's per-payment limit. */
+    maxPaymentUsd?: number;
+    /** How long it lasts, 60 to 3,600 seconds (the default). */
+    ttlSeconds?: number;
+    /** Hosted gate: the same id again gives back the first budget instead of a second one. */
+    requestId?: string;
+}
+/** The bookkeeping both kinds of budget share: the terms check and the running totals. */
+export declare abstract class BudgetBase implements PaymentBudget {
+    #private;
+    readonly id: string;
+    readonly terms: Readonly<BudgetTerms>;
+    readonly mode: "monitor" | "enforce";
+    protected readonly now: () => number;
+    protected readonly onBreach?: ((breach: PaymentBreach) => void | Promise<void>) | undefined;
+    protected readonly counted: Map<string, BudgetSpend>;
+    constructor(id: string, terms: Readonly<BudgetTerms>, mode: "monitor" | "enforce", now: () => number, onBreach?: ((breach: PaymentBreach) => void | Promise<void>) | undefined);
+    get spentMicros(): number;
+    get payments(): number;
+    get closed(): boolean;
+    protected markClosed(): void;
+    problem(amountMicros: number): string | undefined;
+    spend(amountMicros: number, options?: {
+        id?: string;
+        reference?: string;
+    }): Promise<BudgetSpend>;
+    release(spendId: string): boolean;
+    settle(spendId: string, reference: string): void;
+    /** The spend was counted. */
+    protected abstract recorded(spend: BudgetSpend): Promise<void>;
+    /** Whether a counted spend can still be taken back. */
+    protected abstract releasable(spend: BudgetSpend): boolean;
+    /** The spend was taken back. */
+    protected abstract released(spend: BudgetSpend): void;
+    abstract flush(): Promise<void>;
+    abstract close(): Promise<void>;
+    private breachOf;
+}
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.js

@@ -0,0 +1,98 @@
+import { budgetSpendProblem, GATE_RULE_WORDS, MICROS_PER_USD, utcDay, } from "@bondedhq/shared";
+import { BondedError, PaymentBlockedError } from "./errors.js";
+/** Spends are refused this long before the budget's end, so they reach the gate inside it. */
+const END_MARGIN_MS = 5_000;
+/** The bookkeeping both kinds of budget share: the terms check and the running totals. */
+export class BudgetBase {
+    id;
+    terms;
+    mode;
+    now;
+    onBreach;
+    #spentMicros = 0;
+    #payments = 0;
+    #closed = false;
+    counted = new Map();
+    constructor(id, terms, mode, now, onBreach) {
+        this.id = id;
+        this.terms = terms;
+        this.mode = mode;
+        this.now = now;
+        this.onBreach = onBreach;
+    }
+    get spentMicros() {
+        return this.#spentMicros;
+    }
+    get payments() {
+        return this.#payments;
+    }
+    get closed() {
+        return this.#closed || this.now() >= this.terms.expiresAtMs - END_MARGIN_MS;
+    }
+    markClosed() {
+        this.#closed = true;
+    }
+    problem(amountMicros) {
+        if (this.#closed)
+            return "the budget is closed";
+        const atMs = this.now();
+        if (atMs >= this.terms.expiresAtMs - END_MARGIN_MS)
+            return "it was paid after the budget expired";
+        return budgetSpendProblem(this.terms, { spentMicros: this.#spentMicros, payments: this.#payments }, { amountMicros, atMs });
+    }
+    async spend(amountMicros, options = {}) {
+        if (!Number.isSafeInteger(amountMicros) || amountMicros <= 0)
+            throw new BondedError("INVALID_PAYMENT", "amountMicros must be a positive whole number");
+        const problem = this.problem(amountMicros);
+        const spend = {
+            id: options.id ?? crypto.randomUUID(),
+            amountMicros,
+            reference: options.reference ?? "",
+            atMs: this.now(),
+        };
+        if (problem) {
+            const breach = this.breachOf(spend, problem);
+            await this.onBreach?.(breach);
+            if (breach.blocked)
+                throw new PaymentBlockedError(breach);
+        }
+        this.#spentMicros += amountMicros;
+        this.#payments += 1;
+        this.counted.set(spend.id, spend);
+        await this.recorded(spend);
+        return spend;
+    }
+    release(spendId) {
+        const spend = this.counted.get(spendId);
+        if (!spend || !this.releasable(spend))
+            return false;
+        this.counted.delete(spendId);
+        this.#spentMicros -= spend.amountMicros;
+        this.#payments -= 1;
+        this.released(spend);
+        return true;
+    }
+    settle(spendId, reference) {
+        const spend = this.counted.get(spendId);
+        if (spend)
+            spend.reference = reference.slice(0, 200);
+    }
+    breachOf(spend, problem) {
+        const rules = ["over_budget"];
+        return {
+            kind: "budget",
+            rules,
+            reasons: [`${GATE_RULE_WORDS.over_budget}: ${problem}`],
+            blocked: this.mode === "enforce",
+            account: this.terms.account,
+            reference: spend.reference,
+            vendorId: null,
+            amountUsd: spend.amountMicros / MICROS_PER_USD,
+            lossUsd: 0,
+            overpaidUsd: 0,
+            day: utcDay(new Date(spend.atMs)),
+            decisionId: this.id,
+        };
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/gate.d.ts

@@ -1,6 +1,7 @@
-import { type GateInput, type GateLogProof, type PaymentAttempt, type PaymentRule, type SignedGateReceipt } from "@bondedhq/shared";
+import { type GateInput, type GateLogProof, type GateRule, type PaymentAttempt, type SignedGateReceipt } from "@bondedhq/shared";
 import { type Address, type Hex } from "viem";
 import type { PaymentBreach } from "./payments.js";
+import { type BudgetRequest, type PaymentBudget } from "./budget.js";
 /** Bonded's hosted API. */
 export declare const BONDED_API_URL = "https://api-production-ba50.up.railway.app";
 /** A payment for the gate. Pass the same `requestId` to retry one: see `PaymentGate.pay`. */
@@ -23,16 +24,19 @@ export type GateCheck = (GatePayment & {
 /** A decision, as the gate's log keeps it. */
 export interface GateDecision {
     id: string;
-    kind: "invoice" | "refund" | "bank_change" | "card";
+    kind: "invoice" | "refund" | "bank_change" | "card" | "payment" | "budget" | "budget_close";
     decision: "pass" | "breach" | "frozen";
     result: "allowed" | "blocked" | "refused";
     allowed: boolean;
     message: string;
     mode: "monitor" | "enforce";
     /** Every rule broken, most serious first. */
-    rules: PaymentRule[];
+    rules: GateRule[];
     /** Each rule in plain words, in the same order. */
-    reasons: string[];
+    reasons: {
+        rule: GateRule;
+        words: string;
+    }[];
     amountUsd: number;
     lossUsd: number;
     overpaidUsd: number;
@@ -120,6 +124,21 @@ export declare class PaymentGate {
     pay<R>(attempt: GatePayment, pay: () => R | Promise<R>, kind?: "invoice" | "refund"): Promise<R>;
     /** The same for a vendor bank change: `update` runs only if the gate allows the change. */
     changeVendorAccount<R>(request: GateVendorChange, update: () => R | Promise<R>): Promise<R>;
+    /**
+     * Opens a budget: one check for many small payments to one payee (see `PaymentBudget`). The gate
+     * checks it against the general rules (the account needs invoice matching off), reserves the
+     * whole budget against the day's limit and signs a receipt whose input commits to the terms;
+     * this checks the receipt, then recomputes the input's hash and reruns its rules. Each `spend`
+     * is checked here with no network call; payments go to the gate in the background (every
+     * `flushMs`, 5 seconds by default, once `holdMs` has passed so a turned-down payment can be taken
+     * back) and on `close()`, whose receipt commits to every one. Throws `PaymentBlockedError`
+     * (Enforce), `PaymentFrozenError` or `PaymentGateError` without opening one.
+     */
+    budget(request: BudgetRequest, options?: {
+        flushMs?: number;
+        holdMs?: number;
+        onError?: (error: unknown) => void;
+    }): Promise<PaymentBudget>;
     /** The gate account's decisions, newest first. Pass `next` back as `before` for older ones. */
     decisions(query?: {
         limit?: number;

package/dist/gate.js

@@ -1,6 +1,7 @@
-import { normalAccount, verifyGateReceipt, } from "@bondedhq/shared";
+import { budgetCloseCents, evaluateGateInput, gateInputHash, normalAccount, verifyGateReceipt, } from "@bondedhq/shared";
 import { isAddress } from "viem";
 import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, } from "./errors.js";
+import { BudgetBase } from "./budget.js";
 /** Bonded's hosted API. */
 export const BONDED_API_URL = "https://api-production-ba50.up.railway.app";
 /** One retry of a check the gate may not have answered: its request id makes that safe. */
@@ -42,7 +43,7 @@ export class PaymentGate {
                 kind: check.kind ?? "invoice",
                 account: check.account,
                 amountUsd: check.amountUsd,
-                invoiceReference: check.invoiceReference,
+                ...(check.invoiceReference?.trim() ? { invoiceReference: check.invoiceReference } : {}),
                 requestId,
             };
         let last;
@@ -81,6 +82,66 @@ export class PaymentGate {
         await this.#settle(await this.check({ ...request, kind: "bank_change" }));
         return update();
     }
+    /**
+     * Opens a budget: one check for many small payments to one payee (see `PaymentBudget`). The gate
+     * checks it against the general rules (the account needs invoice matching off), reserves the
+     * whole budget against the day's limit and signs a receipt whose input commits to the terms;
+     * this checks the receipt, then recomputes the input's hash and reruns its rules. Each `spend`
+     * is checked here with no network call; payments go to the gate in the background (every
+     * `flushMs`, 5 seconds by default, once `holdMs` has passed so a turned-down payment can be taken
+     * back) and on `close()`, whose receipt commits to every one. Throws `PaymentBlockedError`
+     * (Enforce), `PaymentFrozenError` or `PaymentGateError` without opening one.
+     */
+    async budget(request, options = {}) {
+        const body = {
+            account: request.account,
+            amountUsd: request.amountUsd,
+            ...(request.maxPaymentUsd === undefined ? {} : { maxPaymentUsd: request.maxPaymentUsd }),
+            ...(request.ttlSeconds === undefined ? {} : { ttlSeconds: request.ttlSeconds }),
+            requestId: request.requestId ?? crypto.randomUUID(),
+        };
+        let answer;
+        let last;
+        for (let attempt = 0; attempt < TRIES && !answer; attempt++) {
+            try {
+                answer = await this.#request("/payments/budgets", {
+                    method: "POST",
+                    body: JSON.stringify(body),
+                });
+            }
+            catch (error) {
+                last = error;
+                const unanswered = error instanceof PaymentGateError && (!error.status || error.status >= 500);
+                if (!unanswered)
+                    throw error;
+            }
+        }
+        if (!answer)
+            throw last;
+        const terms = await this.#verifyBudget(answer, body);
+        await this.#settle(answer);
+        return new HostedBudget(answer.id, terms, answer.mode, Date.now, this.#options.onBreach, {
+            flushMs: options.flushMs ?? 5_000,
+            holdMs: options.holdMs ?? 10_000,
+            onError: options.onError ?? (() => undefined),
+            send: (spends) => this.#request(`/payments/budgets/${encodeURIComponent(answer.id)}/spends`, {
+                method: "POST",
+                body: JSON.stringify({
+                    spends: spends.map((s) => ({
+                        id: s.id,
+                        amountMicros: s.amountMicros,
+                        reference: s.reference,
+                        at: new Date(s.atMs).toISOString(),
+                    })),
+                }),
+            }),
+            close: async () => {
+                const closed = await this.#request(`/payments/budgets/${encodeURIComponent(answer.id)}/close`, { method: "POST" });
+                await this.#verifyClose(closed, answer.id);
+                return closed;
+            },
+        });
+    }
     /** The gate account's decisions, newest first. Pass `next` back as `before` for older ones. */
     decisions(query = {}) {
         const params = new URLSearchParams();
@@ -127,12 +188,84 @@ export class PaymentGate {
             r.payee === normalAccount(asked.account) &&
             (asked.kind === "bank_change"
                 ? r.kind === "bank_change"
-                : r.kind === (asked.kind ?? "invoice") &&
-                    r.amountCents === Math.round(asked.amountUsd * 100) &&
-                    r.reference === asked.invoiceReference.trim());
+                : // An account with invoice matching off answers an invoice check as kind "payment".
+                    (r.kind === (asked.kind ?? "invoice") ||
+                        (r.kind === "payment" && (asked.kind ?? "invoice") === "invoice")) &&
+                        r.amountCents === Math.round(asked.amountUsd * 100) &&
+                        r.reference === (asked.invoiceReference ?? "").trim());
         if (!matches)
             throw wrong("its receipt is for a different decision or payment");
     }
+    /** The budget answer's receipt and input check out; returns the terms it grants. */
+    async #verifyBudget(answer, asked) {
+        const wrong = (what) => new PaymentGateError(`the gate's budget can't be trusted: ${what}`, undefined, {
+            receipt: true,
+        });
+        const signed = answer.receipt;
+        if (!signed?.receipt)
+            throw wrong("it has no receipt");
+        if (this.#options.verifyReceipts !== false) {
+            const signer = await this.#receiptSigner();
+            if (!(await verifyGateReceipt(signed, signer).catch(() => false)))
+                throw wrong("its receipt isn't signed by Bonded's receipt key");
+        }
+        const r = signed.receipt;
+        const input = answer.input;
+        if (r.kind !== "budget" ||
+            r.decisionId !== answer.id ||
+            r.decision !== answer.decision ||
+            r.result !== answer.result ||
+            answer.allowed !== (r.result === "allowed") ||
+            r.payee !== normalAccount(asked.account) ||
+            r.amountCents !== Math.round(asked.amountUsd * 100))
+            throw wrong("its receipt is for a different budget");
+        if (!input || input.kind !== "budget" || gateInputHash(input) !== r.inputHash)
+            throw wrong("its input doesn't match the receipt");
+        if (r.decision !== "frozen") {
+            const verdict = evaluateGateInput(input);
+            if (!verdict.ok || verdict.rules.join() !== r.rules.join())
+                throw wrong("its rules don't follow from its input");
+        }
+        const t = input.terms;
+        const ttlMs = (asked.ttlSeconds ?? 3600) * 1000;
+        const maxAsked = asked.maxPaymentUsd === undefined ? Infinity : Math.round(asked.maxPaymentUsd * 1e6);
+        if (t.account !== r.payee ||
+            t.budgetMicros !== r.amountCents * 10_000 ||
+            t.expiresAtMs - t.startsAtMs !== ttlMs ||
+            t.maxPaymentMicros > maxAsked)
+            throw wrong("its terms aren't the ones asked for");
+        return t;
+    }
+    /** A budget close's receipt checks out and commits to its input. */
+    async #verifyClose(answer, budgetId) {
+        if (this.#options.verifyReceipts === false)
+            return;
+        const wrong = (what) => new PaymentGateError(`the gate's budget close can't be trusted: ${what}`, undefined, {
+            receipt: true,
+        });
+        const signed = answer.receipt;
+        if (!signed?.receipt)
+            throw wrong("it has no receipt");
+        const signer = await this.#receiptSigner();
+        if (!(await verifyGateReceipt(signed, signer).catch(() => false)))
+            throw wrong("its receipt isn't signed by Bonded's receipt key");
+        const r = signed.receipt;
+        if (r.kind !== "budget_close" || r.reference !== budgetId || r.decisionId !== answer.id)
+            throw wrong("its receipt is for a different budget");
+        const input = answer.input;
+        // A close given back again has no input to check beyond its signed receipt.
+        if (!input)
+            return;
+        if (input.kind !== "budget_close" ||
+            input.budgetId !== budgetId ||
+            gateInputHash(input) !== r.inputHash)
+            throw wrong("its input doesn't match the receipt");
+        const verdict = evaluateGateInput(input);
+        if (!verdict.ok ||
+            verdict.rules.join() !== r.rules.join() ||
+            r.amountCents !== budgetCloseCents(input))
+            throw wrong("its rules or amount don't follow from its input");
+    }
     #receiptSigner() {
         if (this.#options.receiptKey)
             return Promise.resolve(this.#options.receiptKey);
@@ -180,15 +313,94 @@ export class PaymentGate {
 export function paymentGate(options) {
     return new PaymentGate(options);
 }
+/**
+ * A budget the hosted gate opened. Spends wait `holdMs` (so one the payee turned down can be taken
+ * back), then go to the gate every `flushMs`; `close()` sends the rest and closes it.
+ */
+class HostedBudget extends BudgetBase {
+    link;
+    #pending = [];
+    /** Spends on their way to the gate: too late to take back. */
+    #inFlight = new Set();
+    #sending;
+    #timer;
+    #closing;
+    constructor(id, terms, mode, now, onBreach, link) {
+        super(id, terms, mode, now, onBreach);
+        this.link = link;
+    }
+    /** The close decision, once closed. */
+    closeDecision;
+    recorded(spend) {
+        this.#pending.push(spend);
+        if (!this.#timer) {
+            this.#timer = setInterval(() => {
+                this.#send(false).catch(this.link.onError);
+            }, this.link.flushMs);
+            this.#timer.unref?.();
+        }
+        return Promise.resolve();
+    }
+    releasable(spend) {
+        return this.#pending.includes(spend) && !this.#inFlight.has(spend);
+    }
+    released(spend) {
+        this.#pending = this.#pending.filter((s) => s !== spend);
+    }
+    flush() {
+        return this.#send(true);
+    }
+    close() {
+        this.#closing ??= (async () => {
+            this.markClosed();
+            if (this.#timer)
+                clearInterval(this.#timer);
+            while (this.#pending.length > 0 || this.#sending)
+                await this.#send(true);
+            this.closeDecision = await this.link.close();
+        })().catch((error) => {
+            // Nothing is lost: what wasn't sent is still pending, so closing again tries again.
+            this.#closing = undefined;
+            throw error;
+        });
+        return this.#closing;
+    }
+    /** Sends what's due (everything when `all`), 500 at a time, one send at a time. */
+    async #send(all) {
+        while (this.#sending)
+            await this.#sending;
+        const cutoff = this.now() - this.link.holdMs;
+        const due = this.#pending.filter((s) => all || s.atMs <= cutoff).slice(0, 500);
+        if (due.length === 0)
+            return;
+        for (const s of due)
+            this.#inFlight.add(s);
+        this.#sending = (async () => {
+            const answer = await this.link.send(due);
+            this.#pending = this.#pending.filter((s) => !due.includes(s));
+            if (answer.frozen)
+                this.markClosed();
+        })().finally(() => {
+            for (const s of due)
+                this.#inFlight.delete(s);
+            this.#sending = undefined;
+        });
+        await this.#sending;
+        if (all && this.#pending.length > 0)
+            await this.#send(true);
+    }
+}
 function breachOf(answer) {
     return {
         kind: answer.kind === "bank_change"
             ? "vendor_change"
             : answer.kind === "refund"
                 ? "refund"
-                : "invoice",
+                : answer.kind === "budget"
+                    ? "budget"
+                    : "invoice",
         rules: answer.rules,
-        reasons: answer.reasons,
+        reasons: answer.reasons.map((r) => (typeof r === "string" ? r : r.words)),
         blocked: !answer.allowed,
         account: answer.payee,
         reference: answer.reference,

package/dist/index.d.ts

@@ -7,8 +7,10 @@
  * `@bondedhq/sdk/mcp`, and the Agent URL handler in `@bondedhq/sdk/agent-url`.
  *
  * Off chain, `paymentGuard` and `guardPayments` check an agent's payments against the payment
- * mandate inside your own process (no network, no receipts); the framework subpaths wrap a pay
- * tool with it.
+ * mandate inside your own process (no network, no receipts), and `paymentGate` asks Bonded's
+ * hosted gate instead. The framework subpaths wrap a pay tool with either, `@bondedhq/sdk/openai-agents`
+ * does the same for the OpenAI Agents SDK, and `@bondedhq/sdk/x402` checks x402 payments before
+ * the client signs them.
  */
 export { BondedVault, type ActionResult, type BondedVaultConfig, type VaultStatus, } from "./vault.js";
 export { demoRouter, describeAction, type ApproveParams, type CallParams, type SwapParams, type SwapRouter, type TransferParams, type VaultAction, type VaultCall, } from "./actions.js";
@@ -20,7 +22,7 @@ export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, P
 export type { BreachType } from "@bondedhq/shared";
 export { BONDED_API_URL, PaymentGate, paymentGate, type GateAnswer, type GateCheck, type GateDecision, type GatePayment, type GateReceiptProof, type GateVendorChange, type PaymentGateOptions, } from "./gate.js";
 export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, type GuardPaymentsOptions, type GuardVendorChangesOptions, type PaymentBreach, type PaymentGuardOptions, type PaymentGuardState, type PaymentMandate, type PaymentSource, type PaymentVendor, type PaymentVerdict, } from "./payments.js";
-export { describePaymentMandate, PAYMENT_RULE_WORDS, PAYMENT_RULES, type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentRule, type VerifiedChange, } from "@bondedhq/shared";
+export { describePaymentMandate, GATE_RULE_WORDS, GATE_RULES, PAYMENT_RULE_WORDS, PAYMENT_RULES, type GateRule, type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentRule, type VerifiedChange, } from "@bondedhq/shared";
 export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, type BondedVaultTool, type BondedVaultToolName, type BondedVaultToolsOptions, } from "./vault-tools.js";
 export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, type BondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, type AllowanceCheck, type AllowanceFinding, type TokenRef, installMandateModule, type InstallMandateModuleInput, type ModuleAccountType, type ModuleInstallPlan, } from "./module.js";