@bondedhq/sdk 0.1.5 → 0.1.7

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
@@ -373,6 +388,27 @@ if (isBondedEpisode()) {
 `isBondedEpisode()` is true when the runner set valid `BONDED_*` variables. `fromBondedEnv` reads
 and checks them, naming every missing or malformed one (`BondedError`, code `EPISODE_ENV`).
 
+That is the vault world, where ratings run. An agent that trades through a broker can also be
+tested on the brokerage world (a simulated brokerage account, no vault; docs/BROKERAGE.md), with a
+runner started with `--world brokerage`. Its episode is read with `fromBondedBrokerageEnv()`, and
+`bondedEpisodeWorld()` says which world the runner set up:
+
+```ts
+import { bondedEpisodeWorld, fromBondedBrokerageEnv, fromBondedEnv } from "@bondedhq/sdk";
+
+const world = bondedEpisodeWorld(); // "vault", "brokerage", or undefined outside an episode
+if (world === "brokerage") {
+  const episode = fromBondedBrokerageEnv(); // { world, episodeId, task, mode: "tools", endpoints, deadlineMs }
+} else if (world === "vault") {
+  const episode = fromBondedEnv();
+}
+```
+
+`isBondedEpisode()` is true in both worlds, so an agent under test never falls through to its
+production tools. In a brokerage episode `fromBondedEnv` and the vault tool helpers throw
+`EPISODE_ENV` rather than guess. By Agent URL, `createBondedHandler` runs brokerage episodes with
+`onBrokerageEpisode` and refuses them (422) without it.
+
 The mode decides how the agent acts:
 
 - **tools**: reads and writes are tool calls; `swap`, `transfer` and `approve` are tools, and the

package/dist/agent-url.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { BondedEpisode } from "./episode.js";
+import type { BondedBrokerageEpisode, BondedEpisode } from "./episode.js";
 import type { EpisodeUsage } from "./mcp.js";
 /** For your own handler: the proof a verify answer carries, and the whole answer. */
 export { agentUrlVerifyProof, answerAgentUrlVerify } from "@bondedhq/shared/agent-url";
@@ -40,6 +40,14 @@ export interface BondedHandlerOptions {
     secret: string | string[];
     /** Runs one episode. Resolve when the agent is finished; the handler then posts `/done`. */
     onEpisode(episode: BondedEpisode, context: EpisodeContext): Promise<EpisodeOutcome | void> | EpisodeOutcome | void;
+    /**
+     * Runs one brokerage episode (a simulated brokerage account; docs/BROKERAGE.md). Without it, the
+     * handler refuses brokerage episodes with 422, so an agent built for the vault world never gets
+     * one by surprise. Errors are passed to `onBrokerageError` (default `console.error`).
+     */
+    onBrokerageEpisode?(episode: BondedBrokerageEpisode, context: EpisodeContext): Promise<EpisodeOutcome | void> | EpisodeOutcome | void;
+    /** Called when `onBrokerageEpisode` throws (default: `console.error`). `/done` is still posted. */
+    onBrokerageError?: (error: unknown, episode: BondedBrokerageEpisode) => void;
     /**
      * Your agent's version (a release tag, a git commit). Reported when Bonded verifies the URL;
      * it becomes the rating's code hash when you don't declare one.

package/dist/agent-url.js

@@ -32,17 +32,29 @@ export function createBondedHandler(options) {
     /** Signatures already accepted, until they fall out of the window: replays are refused. */
     const replay = new AgentUrlReplayGuard(tolerance);
     const running = new Map();
-    const run = async (episode, controller) => {
+    const onBrokerageError = options.onBrokerageError ??
+        ((error, episode) => console.error(`Bonded brokerage episode ${episode.episodeId} failed:`, error));
+    const run = async (episode, controller, work, reportError) => {
         const deadline = setTimeout(() => controller.abort(new Error("the episode's deadline passed")), episode.deadlineMs);
+        // A reporter that throws must not stop `/done` from being posted: the gateway would wait out
+        // the deadline for an episode that has already failed.
+        const report = (error) => {
+            try {
+                reportError(error, episode);
+            }
+            catch (reporterError) {
+                console.error(`Bonded episode ${episode.episodeId}: the error reporter threw:`, reporterError);
+            }
+        };
         let outcome;
         let failed = false;
         try {
-            outcome = await options.onEpisode(episode, { signal: controller.signal });
+            outcome = await work(episode, { signal: controller.signal });
         }
         catch (error) {
             failed = true;
             if (!controller.signal.aborted)
-                onError(error, episode);
+                report(error);
             outcome = {
                 finalMessage: `the agent failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 4_000),
             };
@@ -64,7 +76,7 @@ export function createBondedHandler(options) {
         }
         catch (error) {
             if (!failed)
-                onError(error, episode);
+                report(error);
         }
     };
     return async (request, context) => {
@@ -92,20 +104,25 @@ export function createBondedHandler(options) {
             controller?.abort(new Error("Bonded cancelled the episode"));
             return json(200, { ok: true, cancelled: controller !== undefined });
         }
-        const episode = toEpisode(message);
-        if (running.has(episode.episodeId))
-            return json(200, { ok: true, episodeId: episode.episodeId, alreadyRunning: true });
+        if (message.world === "brokerage" && !options.onBrokerageEpisode)
+            return json(422, {
+                error: "this agent doesn't take brokerage episodes (no onBrokerageEpisode)",
+            });
+        if (running.has(message.episodeId))
+            return json(200, { ok: true, episodeId: message.episodeId, alreadyRunning: true });
         if (running.size >= maxConcurrent)
             return json(429, { error: `already running ${running.size} episodes` });
         const controller = new AbortController();
-        running.set(episode.episodeId, controller);
-        const work = run(episode, controller);
+        running.set(message.episodeId, controller);
+        const work = message.world === "brokerage"
+            ? run(toBrokerageEpisode(message), controller, (e, c) => options.onBrokerageEpisode(e, c), onBrokerageError)
+            : run(toEpisode(message), controller, (e, c) => options.onEpisode(e, c), onError);
         // Called as a method: Cloudflare's ctx.waitUntil needs its `this`.
         if (context?.waitUntil)
             context.waitUntil(work);
         else
             options.waitUntil?.(work);
-        return json(202, { ok: true, episodeId: episode.episodeId });
+        return json(202, { ok: true, episodeId: message.episodeId });
     };
 }
 /**
@@ -122,6 +139,17 @@ async function signingSecret(secrets, body, headers, nowMs, toleranceSeconds) {
     }
     return secrets[0];
 }
+/** A brokerage episode as the agent sees it (the same shape `fromBondedBrokerageEnv` returns). */
+function toBrokerageEpisode(message) {
+    return {
+        world: "brokerage",
+        episodeId: message.episodeId,
+        task: message.task,
+        mode: "tools",
+        endpoints: message.endpoints,
+        deadlineMs: message.deadlineMs,
+    };
+}
 /** The episode as the agent sees it (the same shape `fromBondedEnv` returns). */
 function toEpisode(message) {
     // The runner protocol's message, minus `type`, `nonce` and `teeKeyId` (TEE-bound agents use

package/dist/episode.d.ts

@@ -41,6 +41,7 @@ export interface BondedEpisode {
  * next to `episodeEnv` that writes them, so the runner, the gateway and the SDK can't drift.
  */
 export declare const bondedEpisodeEnv: import("zod").ZodObject<{
+    BONDED_WORLD: import("zod").ZodOptional<import("zod").ZodLiteral<"vault">>;
     BONDED_EPISODE_ID: import("zod").ZodString;
     BONDED_MODE: import("zod").ZodEnum<{
         tools: "tools";
@@ -57,6 +58,7 @@ export declare const bondedEpisodeEnv: import("zod").ZodObject<{
             approvalAllowlist: import("zod").ZodArray<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<`0x${string}`, string>>>;
         }, import("zod/v4/core").$strip>>;
         maxSteps: import("zod").ZodNumber;
+        tools: import("zod").ZodOptional<import("zod").ZodReadonly<import("zod").ZodArray<import("zod").ZodString>>>;
     }, import("zod/v4/core").$strip>>;
     BONDED_MCP_URL: import("zod").ZodURL;
     BONDED_TOOLS_URL: import("zod").ZodURL;
@@ -84,6 +86,11 @@ export declare const bondedEpisodeEnv: import("zod").ZodObject<{
  * ```ts
  * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
  * ```
+ *
+ * True in every world, so an agent under test never falls through to its production tools. In a
+ * world the agent wasn't built for, the helpers then fail loudly: in a brokerage episode
+ * `fromBondedEnv` and the vault tool helpers throw `EPISODE_ENV`. `bondedEpisodeWorld()` says
+ * which world it is.
  */
 export declare function isBondedEpisode(env?: Record<string, string | undefined>): boolean;
 /**
@@ -105,4 +112,48 @@ export declare function fromBondedEnv(env?: Record<string, string | undefined>):
  * or when the key is held by a TEE (no session key): use your own signer there.
  */
 export declare function episodeVault(episode: BondedEpisode): BondedVault;
+/**
+ * A brokerage episode: the agent manages a simulated brokerage account (stocks, filings, orders,
+ * cash withdrawals) through the episode's tools. There is no chain, vault or key: every read and
+ * write is a tool call, and the Arena judges it by the brokerage ledger. Needs runner protocol 2
+ * (`@bondedhq/runner` 0.1.4 or later), started with `--world brokerage`.
+ */
+export interface BondedBrokerageEpisode {
+    world: "brokerage";
+    episodeId: string;
+    task: AgentTask;
+    mode: "tools";
+    endpoints: {
+        /** MCP over streamable HTTP. */
+        mcp: string;
+        /** Plain HTTP: `GET {tools}` lists them, `POST {tools}/{name}` with JSON args calls one. */
+        tools: string;
+        openapi: string;
+        /** `POST` here when finished (`{ finalMessage? }`). */
+        done: string;
+    };
+    /** How long the agent has, in milliseconds from when it starts. */
+    deadlineMs: number;
+}
+/**
+ * Which world the runner's episode is for: `vault` (on-chain trading from a Mandate Vault, read
+ * with `fromBondedEnv`), `brokerage` (read with `fromBondedBrokerageEnv`), or undefined when this
+ * process isn't running a Bonded episode.
+ *
+ * ```ts
+ * const world = bondedEpisodeWorld();
+ * const tools =
+ *   world === "brokerage"
+ *     ? await myBrokerageTools(fromBondedBrokerageEnv())
+ *     : world === "vault"
+ *       ? await bondedLangChainTools()
+ *       : productionTools;
+ * ```
+ */
+export declare function bondedEpisodeWorld(env?: Record<string, string | undefined>): "vault" | "brokerage" | undefined;
+/**
+ * Reads a brokerage episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ */
+export declare function fromBondedBrokerageEnv(env?: Record<string, string | undefined>): BondedBrokerageEpisode;
 //# sourceMappingURL=episode.d.ts.map

package/dist/episode.js

@@ -1,4 +1,4 @@
-import { EpisodeEnv, parseEpisodeEnv } from "@bondedhq/shared";
+import { EpisodeEnv, parseBrokerageEpisodeEnv, parseEpisodeEnv, } from "@bondedhq/shared";
 import { defineChain } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { BondedError } from "./errors.js";
@@ -15,9 +15,14 @@ export const bondedEpisodeEnv = EpisodeEnv;
  * ```ts
  * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
  * ```
+ *
+ * True in every world, so an agent under test never falls through to its production tools. In a
+ * world the agent wasn't built for, the helpers then fail loudly: in a brokerage episode
+ * `fromBondedEnv` and the vault tool helpers throw `EPISODE_ENV`. `bondedEpisodeWorld()` says
+ * which world it is.
  */
 export function isBondedEpisode(env = typeof process === "undefined" ? {} : process.env) {
-    return parseEpisodeEnv(env).ok;
+    return bondedEpisodeWorld(env) !== undefined;
 }
 /**
  * Reads the episode the Bonded runner set up from the environment. Throws `BondedError`
@@ -62,4 +67,37 @@ export function episodeVault(episode) {
         router: episode.contracts.exchange,
     });
 }
+/**
+ * Which world the runner's episode is for: `vault` (on-chain trading from a Mandate Vault, read
+ * with `fromBondedEnv`), `brokerage` (read with `fromBondedBrokerageEnv`), or undefined when this
+ * process isn't running a Bonded episode.
+ *
+ * ```ts
+ * const world = bondedEpisodeWorld();
+ * const tools =
+ *   world === "brokerage"
+ *     ? await myBrokerageTools(fromBondedBrokerageEnv())
+ *     : world === "vault"
+ *       ? await bondedLangChainTools()
+ *       : productionTools;
+ * ```
+ */
+export function bondedEpisodeWorld(env = typeof process === "undefined" ? {} : process.env) {
+    // Fails closed: once the runner has named the brokerage world for an episode, that is the
+    // answer even if another variable is malformed. `fromBondedBrokerageEnv` then names the bad
+    // variable, where "not an episode" would send the agent to its production tools.
+    if (env.BONDED_WORLD === "brokerage" && env.BONDED_EPISODE_ID?.trim())
+        return "brokerage";
+    return parseEpisodeEnv(env).ok ? "vault" : undefined;
+}
+/**
+ * Reads a brokerage episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ */
+export function fromBondedBrokerageEnv(env = process.env) {
+    const parsed = parseBrokerageEpisodeEnv(env);
+    if (!parsed.ok)
+        throw new BondedError("EPISODE_ENV", `not a valid Bonded brokerage episode environment: ${parsed.problems.join("; ")}`);
+    return parsed.episode;
+}
 //# sourceMappingURL=episode.js.map

package/dist/index.d.ts

@@ -24,6 +24,6 @@ export { BONDED_API_URL, PaymentGate, paymentGate, type GateAnswer, type GateChe
 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, 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 { bondedEpisodeEnv, bondedEpisodeWorld, episodeVault, fromBondedBrokerageEnv, fromBondedEnv, isBondedEpisode, type BondedBrokerageEpisode, 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -23,6 +23,6 @@ export { BONDED_API_URL, PaymentGate, paymentGate, } from "./gate.js";
 export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, } from "./payments.js";
 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 { bondedEpisodeEnv, bondedEpisodeWorld, episodeVault, fromBondedBrokerageEnv, fromBondedEnv, isBondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, installMandateModule, } from "./module.js";
 //# sourceMappingURL=index.js.map

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.7",
   "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": [
@@ -94,7 +94,7 @@
     "@modelcontextprotocol/sdk": "1.30.1",
     "viem": "^2.56.9",
     "zod": "^4.6.5",
-    "@bondedhq/shared": "^0.1.5"
+    "@bondedhq/shared": "^0.1.6"
   },
   "devDependencies": {
     "@coinbase/agentkit": "0.10.4",