@bondedhq/sdk 0.1.4 → 0.1.6

package/dist/index.js

@@ -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, } from "./vault.js";
 export { demoRouter, describeAction, } from "./actions.js";
@@ -19,7 +21,7 @@ export { buildMandate, describeMandate, } from "./mandate.js";
 export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, PredictedBreachError, SentinelError, SentinelRefusedError, VaultFrozenError, } from "./errors.js";
 export { BONDED_API_URL, PaymentGate, paymentGate, } from "./gate.js";
 export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, } from "./payments.js";
-export { describePaymentMandate, PAYMENT_RULE_WORDS, PAYMENT_RULES, } from "@bondedhq/shared";
+export { describePaymentMandate, GATE_RULE_WORDS, GATE_RULES, PAYMENT_RULE_WORDS, PAYMENT_RULES, } from "@bondedhq/shared";
 export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, } from "./vault-tools.js";
 export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, installMandateModule, } from "./module.js";

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;
@@ -188,7 +221,7 @@ export interface GuardVendorChangesOptions<I> {
 export declare function guardVendorChanges<I, Rest extends unknown[], R>(update: (input: I, ...rest: Rest) => R | Promise<R>, options: GuardVendorChangesOptions<I>): (input: I, ...rest: Rest) => Promise<R>;
 /**
  * The payment guard or gate refused (blocked, frozen, arguments it can't check, or the gate gave no
- * answer to act on): no money moved.
+ * answer to act on), or a remote x402 signer didn't sign: no money moved.
  */
 export declare function isPaymentRefusal(error: unknown): error is PaymentBlockedError | PaymentFrozenError | PaymentGateError | BondedError;
 //# sourceMappingURL=payments.d.ts.map

package/dist/payments.js

@@ -1,11 +1,17 @@
-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 { X402_SIGNER_ERROR_CODES } from "./x402-remote.js";
+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 +79,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 +105,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 +150,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 +292,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 +333,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 +348,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 +359,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);
@@ -228,13 +423,15 @@ export function guardVendorChanges(update, options) {
 }
 /**
  * The payment guard or gate refused (blocked, frozen, arguments it can't check, or the gate gave no
- * answer to act on): no money moved.
+ * answer to act on), or a remote x402 signer didn't sign: no money moved.
  */
 export function isPaymentRefusal(error) {
     return (error instanceof PaymentBlockedError ||
         error instanceof PaymentFrozenError ||
         error instanceof PaymentGateError ||
-        (error instanceof BondedError && error.code === "INVALID_PAYMENT"));
+        (error instanceof BondedError &&
+            (error.code === "INVALID_PAYMENT" ||
+                X402_SIGNER_ERROR_CODES.includes(error.code))));
 }
 const field = (input, name) => {
     const value = input[name];
@@ -260,7 +457,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-remote.d.ts

@@ -0,0 +1,77 @@
+import type { Address, Hex } from "viem";
+/**
+ * The wire format between an agent and `@bondedhq/signer`, the x402 signer a business runs on its
+ * own server. The agent never holds the wallet key: it sends each x402 payment's EIP-712 request
+ * to the signer, which checks it against a budget and signs only if it fits.
+ */
+export declare const X402_SIGNER_PATHS: {
+    /** `GET`: the signer's address and the networks it pays on (`X402SignerInfo`). */
+    readonly info: "/v1/x402/signer";
+    /** `POST` an `X402SignRequest`; answers an `X402SignResponse`, or an `X402SignerProblem`. */
+    readonly sign: "/v1/x402/sign";
+};
+/** One EIP-712 request, as the x402 client builds it. Big numbers travel as decimal strings. */
+export interface X402TypedData {
+    domain: Record<string, unknown>;
+    types: Record<string, unknown>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+export interface X402SignRequest {
+    typedData: X402TypedData;
+}
+export interface X402SignResponse {
+    signature: Hex;
+}
+export interface X402SignerInfo {
+    address: Address;
+    /** CAIP-2 ids, such as `eip155:8453`. */
+    networks: string[];
+}
+/**
+ * Why the signer didn't sign. `refused`: the payment breaks the budget or the gate couldn't be
+ * reached (it fails closed). `invalid`: not an x402 USDC payment from this signer, or malformed.
+ * `unauthorized`: a missing or wrong token. `error`: something broke in the signer.
+ */
+export interface X402SignerProblem {
+    error: "refused" | "invalid" | "unauthorized" | "not_found" | "error";
+    reason: string;
+}
+/** The error codes `remoteX402Signer` throws; all of them mean nothing was signed. */
+export declare const X402_SIGNER_ERROR_CODES: readonly ["SIGNER_REFUSED", "SIGNER_UNAUTHORIZED", "SIGNER_UNAVAILABLE"];
+export interface RemoteX402SignerOptions {
+    /** Where the signer runs, such as `http://bonded-signer:8402`. */
+    url: string;
+    /** One of the signer's tokens. It can only ask for x402 payments, never move money itself. */
+    token: string;
+    /**
+     * How long to wait for each request, in milliseconds (default 35,000). The signer may need to
+     * open a budget with the gate (up to two tries of 10 seconds) and then wait for its KMS (up to
+     * 10 seconds); giving up sooner would make the agent retry a payment the signer still counts.
+     */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/** What an x402 client needs from a signer (`ClientEvmSigner` in `@x402/evm`). */
+export interface RemoteX402Signer {
+    readonly address: Address;
+    readonly networks: readonly string[];
+    signTypedData(typedData: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<Hex>;
+}
+/**
+ * An x402 signer whose key stays on a server the agent can't reach: `@bondedhq/signer`. Pass it to
+ * `ExactEvmScheme` in place of a local account. Each payment goes to the signer, which checks it
+ * against the gate's budget for its payee and signs only if it fits, so code in the agent's process
+ * can't pay without the check.
+ *
+ * Nothing is signed when the signer refuses, can't be reached or doesn't accept the token: the
+ * x402 client's request fails with a `BondedError` (`SIGNER_REFUSED`, `SIGNER_UNAVAILABLE`,
+ * `SIGNER_UNAUTHORIZED`, or `INVALID_PAYMENT`), which `isPaymentRefusal` recognizes.
+ */
+export declare function remoteX402Signer(options: RemoteX402SignerOptions): Promise<RemoteX402Signer>;
+//# sourceMappingURL=x402-remote.d.ts.map

package/dist/x402-remote.js

@@ -0,0 +1,88 @@
+import { BondedError } from "./errors.js";
+/**
+ * The wire format between an agent and `@bondedhq/signer`, the x402 signer a business runs on its
+ * own server. The agent never holds the wallet key: it sends each x402 payment's EIP-712 request
+ * to the signer, which checks it against a budget and signs only if it fits.
+ */
+export const X402_SIGNER_PATHS = {
+    /** `GET`: the signer's address and the networks it pays on (`X402SignerInfo`). */
+    info: "/v1/x402/signer",
+    /** `POST` an `X402SignRequest`; answers an `X402SignResponse`, or an `X402SignerProblem`. */
+    sign: "/v1/x402/sign",
+};
+/** The error codes `remoteX402Signer` throws; all of them mean nothing was signed. */
+export const X402_SIGNER_ERROR_CODES = [
+    "SIGNER_REFUSED",
+    "SIGNER_UNAUTHORIZED",
+    "SIGNER_UNAVAILABLE",
+];
+/**
+ * An x402 signer whose key stays on a server the agent can't reach: `@bondedhq/signer`. Pass it to
+ * `ExactEvmScheme` in place of a local account. Each payment goes to the signer, which checks it
+ * against the gate's budget for its payee and signs only if it fits, so code in the agent's process
+ * can't pay without the check.
+ *
+ * Nothing is signed when the signer refuses, can't be reached or doesn't accept the token: the
+ * x402 client's request fails with a `BondedError` (`SIGNER_REFUSED`, `SIGNER_UNAVAILABLE`,
+ * `SIGNER_UNAUTHORIZED`, or `INVALID_PAYMENT`), which `isPaymentRefusal` recognizes.
+ */
+export async function remoteX402Signer(options) {
+    const base = options.url.replace(/\/+$/, "");
+    const fetchFn = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 35_000;
+    async function call(path, init = {}) {
+        let response;
+        try {
+            response = await fetchFn(`${base}${path}`, {
+                ...init,
+                headers: {
+                    ...(init.body ? { "content-type": "application/json" } : {}),
+                    authorization: `Bearer ${options.token}`,
+                },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new BondedError("SIGNER_UNAVAILABLE", `the x402 signer can't be reached at ${base}`, {
+                cause: error,
+            });
+        }
+        const text = await response.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = undefined;
+        }
+        if (response.ok && body && typeof body === "object")
+            return body;
+        const problem = body;
+        const reason = typeof problem?.reason === "string" ? problem.reason : `HTTP ${response.status}`;
+        if (response.status === 401 || problem?.error === "unauthorized")
+            throw new BondedError("SIGNER_UNAUTHORIZED", `the x402 signer refused the token: ${reason}`);
+        if (problem?.error === "refused")
+            throw new BondedError("SIGNER_REFUSED", `the x402 signer refused the payment: ${reason}`);
+        if (problem?.error === "invalid")
+            throw new BondedError("INVALID_PAYMENT", `the x402 signer won't sign this: ${reason}`);
+        throw new BondedError("SIGNER_UNAVAILABLE", `the x402 signer failed: ${reason}`);
+    }
+    const info = await call(X402_SIGNER_PATHS.info);
+    if (typeof info.address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(info.address))
+        throw new BondedError("SIGNER_UNAVAILABLE", "the x402 signer sent no valid address");
+    return {
+        address: info.address,
+        networks: Array.isArray(info.networks) ? [...info.networks] : [],
+        async signTypedData(typedData) {
+            const request = { typedData };
+            const { signature } = await call(X402_SIGNER_PATHS.sign, {
+                method: "POST",
+                body: JSON.stringify(request, (_key, value) => typeof value === "bigint" ? value.toString() : value),
+            });
+            if (typeof signature !== "string" || !/^0x[0-9a-fA-F]+$/.test(signature))
+                throw new BondedError("SIGNER_UNAVAILABLE", "the x402 signer sent no valid signature");
+            return signature;
+        },
+    };
+}
+//# sourceMappingURL=x402-remote.js.map