@bondedhq/sdk 0.1.5 → 0.1.6

package/README.md

@@ -299,6 +299,21 @@ await x402.close();
 - `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/payments.d.ts

@@ -221,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,4 +1,5 @@
 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 ?? []);
@@ -422,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];

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

package/dist/x402.d.ts

@@ -133,4 +133,5 @@ export declare function x402Price(r: X402Requirements, assets?: readonly X402Ass
     account: string;
     amountMicros: number;
 };
+export { remoteX402Signer, X402_SIGNER_ERROR_CODES, X402_SIGNER_PATHS, type RemoteX402Signer, type RemoteX402SignerOptions, type X402SignerInfo, type X402SignerProblem, type X402SignRequest, type X402SignResponse, type X402TypedData, } from "./x402-remote.js";
 //# sourceMappingURL=x402.d.ts.map

package/dist/x402.js

@@ -179,4 +179,5 @@ export function x402Price(r, assets = X402_USD_ASSETS) {
         throw new BondedError("INVALID_PAYMENT", "the x402 price is too large");
     return { account: r.payTo, amountMicros: Number(micros) };
 }
+export { remoteX402Signer, X402_SIGNER_ERROR_CODES, X402_SIGNER_PATHS, } from "./x402-remote.js";
 //# sourceMappingURL=x402.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bondedhq/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Trade through a Bonded Mandate Vault and get rated by the Bonded Arena from any TypeScript agent: a typed vault client with dry runs, Sentinel checks and a mandate builder; the Arena episode's tools for LangChain, the Vercel AI SDK, ElizaOS and Coinbase AgentKit; a payment guard for pay tools (LangChain, the AI SDK, MCP, the OpenAI Agents SDK) and x402 clients; and an Agent URL handler.",
   "license": "MIT",
   "keywords": [