@hpp-io/x402-mcp-bridge 0.0.3 → 0.1.0

package/dist/sellerTools.js

@@ -0,0 +1,202 @@
+/**
+ * Seller building-block tools (A2 Phase 1) — let an agent that already receives
+ * requests (its own HTTP/A2A server) charge for them over x402.
+ *
+ * Five stateless tools mirroring Polygon's seller set, but covering all three
+ * HPP schemes (exact / upto / batch-settlement), not just exact:
+ *   - seller_create_requirements  build a PaymentRequirements (local)
+ *   - seller_generate_402         build the HTTP 402 body from accepts[] (local)
+ *   - seller_decode_payment       decode the X-PAYMENT header + payer (local)
+ *   - seller_verify               facilitator /verify   (does the buyer's sig hold?)
+ *   - seller_settle               facilitator /settle   (move the funds on-chain)
+ *
+ * verify/settle are thin wrappers over the same HTTPFacilitatorClient the
+ * resource server uses; the tools never hold funds or keys. The agent's own
+ * server orchestrates: 402 → decode → verify → do the work → settle.
+ */
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { log } from "./log.js";
+function decodeHeader(header) {
+    try {
+        const json = Buffer.from(header, "base64").toString("utf-8");
+        const parsed = JSON.parse(json);
+        if (!parsed || !parsed.payload)
+            return null;
+        const payer = parsed.payload.authorization?.from ??
+            parsed.payload.channelConfig?.payer ??
+            parsed.payload.permit2Authorization?.from ??
+            null;
+        return { payload: parsed, payer };
+    }
+    catch {
+        return null;
+    }
+}
+function ok(obj) {
+    return { content: [{ type: "text", text: JSON.stringify(obj) }] };
+}
+function err(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+// ── tool defs ───────────────────────────────────────────────────────────
+export const SELLER_CREATE_REQUIREMENTS_TOOL = {
+    name: "seller_create_requirements",
+    description: "Build an x402 PaymentRequirements object for a resource you sell. Returns " +
+        "the requirements to advertise in a 402 (see seller_generate_402). Scheme " +
+        "defaults to 'exact'; use 'upto' or 'batch-settlement' with scheme-specific " +
+        "fields in `extra`.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            amount: { type: "string", description: "Price in atomic units (e.g. '10000' = 0.01 USDC.e)." },
+            payTo: { type: "string", description: "Your wallet address (receives payment)." },
+            asset: { type: "string", description: "Token address (USDC.e on HPP)." },
+            network: { type: "string", description: "CAIP-2 network; defaults to the bridge network." },
+            scheme: { type: "string", enum: ["exact", "upto", "batch-settlement"], description: "Payment scheme (default exact)." },
+            maxTimeoutSeconds: { type: "number", description: "Payment validity window (default 600)." },
+            extra: { type: "object", description: "Scheme-specific extras (EIP-712 domain, Permit2 proxy, channel info)." },
+        },
+        required: ["amount", "payTo", "asset"],
+        additionalProperties: false,
+    },
+};
+export const SELLER_GENERATE_402_TOOL = {
+    name: "seller_generate_402",
+    description: "Build the HTTP 402 Payment Required response body from one or more " +
+        "PaymentRequirements (from seller_create_requirements). Return this when a " +
+        "request arrives with no payment header.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            accepts: { type: "array", description: "PaymentRequirements[] the buyer may choose from.", items: { type: "object" } },
+            resource: { type: "string", description: "The resource URL being protected." },
+            error: { type: "string", description: "Optional human-readable reason." },
+        },
+        required: ["accepts"],
+        additionalProperties: false,
+    },
+};
+export const SELLER_DECODE_PAYMENT_TOOL = {
+    name: "seller_decode_payment",
+    description: "Decode a buyer's base64 X-PAYMENT / Payment-Signature header locally (no " +
+        "facilitator call) to inspect the payload and extract the payer address. " +
+        "Supports exact / upto / batch-settlement.",
+    inputSchema: {
+        type: "object",
+        properties: { paymentHeader: { type: "string", description: "The base64 X-PAYMENT header value." } },
+        required: ["paymentHeader"],
+        additionalProperties: false,
+    },
+};
+export const SELLER_VERIFY_TOOL = {
+    name: "seller_verify",
+    description: "Verify a buyer's payment against the facilitator BEFORE doing the work. " +
+        "Pass the X-PAYMENT header + the PaymentRequirements you advertised. Returns " +
+        "{ isValid, payer, invalidReason }.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            paymentHeader: { type: "string", description: "The base64 X-PAYMENT header." },
+            paymentRequirements: { type: "object", description: "The requirements you advertised for this resource." },
+        },
+        required: ["paymentHeader", "paymentRequirements"],
+        additionalProperties: false,
+    },
+};
+export const SELLER_SETTLE_TOOL = {
+    name: "seller_settle",
+    description: "Settle a verified payment on-chain AFTER the work succeeded (serve-then-" +
+        "settle). Pass the same X-PAYMENT header + PaymentRequirements. Returns " +
+        "{ success, transaction }.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            paymentHeader: { type: "string", description: "The base64 X-PAYMENT header." },
+            paymentRequirements: { type: "object", description: "The requirements you advertised for this resource." },
+        },
+        required: ["paymentHeader", "paymentRequirements"],
+        additionalProperties: false,
+    },
+};
+export const SELLER_TOOLS = [
+    SELLER_CREATE_REQUIREMENTS_TOOL,
+    SELLER_GENERATE_402_TOOL,
+    SELLER_DECODE_PAYMENT_TOOL,
+    SELLER_VERIFY_TOOL,
+    SELLER_SETTLE_TOOL,
+];
+// ── handlers ──────────────────────────────────────────────────────────────
+export function sellerCreateRequirements(deps, a) {
+    if (!a.amount || !a.payTo || !a.asset)
+        return err("amount, payTo, asset are required");
+    const req = {
+        scheme: a.scheme ?? "exact",
+        network: (a.network ?? deps.network),
+        asset: a.asset,
+        amount: String(a.amount),
+        payTo: a.payTo,
+        maxTimeoutSeconds: a.maxTimeoutSeconds ?? 600,
+        extra: a.extra ?? {},
+    };
+    return ok({ requirements: req });
+}
+export function sellerGenerate402(a) {
+    const accepts = a.accepts;
+    if (!Array.isArray(accepts) || accepts.length === 0)
+        return err("accepts[] required");
+    const body = {
+        x402Version: 2,
+        error: a.error ?? "payment required",
+        ...(a.resource ? { resource: a.resource } : {}),
+        accepts,
+    };
+    return ok({
+        response: { statusCode: 402, headers: { "Content-Type": "application/json" }, body },
+    });
+}
+export function sellerDecodePayment(a) {
+    const header = a.paymentHeader;
+    if (!header || typeof header !== "string")
+        return err("paymentHeader required");
+    const decoded = decodeHeader(header);
+    if (!decoded)
+        return err("could not decode payment header (base64 JSON expected)");
+    return ok({ scheme: decoded.payload.scheme, payer: decoded.payer, payload: decoded.payload });
+}
+export async function sellerVerify(deps, a) {
+    const header = a.paymentHeader;
+    const requirements = a.paymentRequirements;
+    if (!header || !requirements)
+        return err("paymentHeader and paymentRequirements required");
+    const decoded = decodeHeader(header);
+    if (!decoded)
+        return err("could not decode payment header");
+    try {
+        const client = new HTTPFacilitatorClient({ url: deps.facilitatorUrl });
+        const res = await client.verify(decoded.payload, requirements);
+        log.info("seller_verify", { isValid: res.isValid, payer: res.payer });
+        return ok({ isValid: res.isValid, payer: res.payer, invalidReason: res.invalidReason });
+    }
+    catch (e) {
+        return err(`verify failed: ${e.message}`);
+    }
+}
+export async function sellerSettle(deps, a) {
+    const header = a.paymentHeader;
+    const requirements = a.paymentRequirements;
+    if (!header || !requirements)
+        return err("paymentHeader and paymentRequirements required");
+    const decoded = decodeHeader(header);
+    if (!decoded)
+        return err("could not decode payment header");
+    try {
+        const client = new HTTPFacilitatorClient({ url: deps.facilitatorUrl });
+        const res = await client.settle(decoded.payload, requirements);
+        log.info("seller_settle", { success: res.success, tx: res.transaction });
+        return ok({ success: res.success, transaction: res.transaction });
+    }
+    catch (e) {
+        return err(`settle failed: ${e.message}`);
+    }
+}
+//# sourceMappingURL=sellerTools.js.map

package/dist/sellerTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sellerTools.js","sourceRoot":"","sources":["../src/sellerTools.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import type { UpstreamClient } from "./client.js";
 import type { DiscoveryClient } from "./discovery.js";
+import { type SellerDeps } from "./sellerTools.js";
 import type { RawEoaSigner } from "./signers/raw-eoa.js";
 import type { Funds } from "./funds.js";
 import type { Network } from "@x402/core/types";
@@ -14,6 +15,8 @@ export interface BridgeServerOptions {
     funds?: Funds;
     /** Curated-discovery client. Present = register hpp_discover / hpp_call. */
     discovery?: DiscoveryClient;
+    /** Seller deps. Present = register seller_* tools. */
+    seller?: SellerDeps;
     /**
      * Per-request timeout for the A2A JSON-RPC calls in `pay_a2a_agent`.
      * Surfaced via env `HPP_X402_A2A_RPC_TIMEOUT_MS` (set at CLI entry);

package/dist/server.js

@@ -17,15 +17,58 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { PAY_A2A_TOOL, payA2aAgent } from "./a2a.js";
 import { X402_HTTP_TOOL, x402HttpCall } from "./httpX402.js";
 import { HPP_DISCOVER_TOOL, HPP_CALL_TOOL, hppDiscover, hppCall, } from "./discoveryTools.js";
+import { SELLER_TOOLS, SELLER_CREATE_REQUIREMENTS_TOOL, SELLER_GENERATE_402_TOOL, SELLER_DECODE_PAYMENT_TOOL, SELLER_VERIFY_TOOL, SELLER_SETTLE_TOOL, sellerCreateRequirements, sellerGenerate402, sellerDecodePayment, sellerVerify, sellerSettle, } from "./sellerTools.js";
+import { walletSpendStatus, setWalletLimits } from "./spendGuard.js";
 import { log } from "./log.js";
+const WALLET_GET_LIMITS_TOOL = {
+    name: "wallet_get_limits",
+    description: "Show the wallet's spend limits (per-call + per-day in atomic USDC.e units) " +
+        "and how much has been spent today. Empty limits = uncapped.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
+const WALLET_SET_LIMIT_TOOL = {
+    name: "wallet_set_limit",
+    description: "Set the wallet's spend guard: a per-call cap and/or a per-day cap in atomic " +
+        "USDC.e units (e.g. '10000' = 0.01 USDC.e). These bind across ALL payment " +
+        "tools and are enforced locally before signing (complements the Safe's " +
+        "on-chain cap). Omit a field to leave it unchanged.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            maxPerCallAtomic: { type: "string", description: "Max atomic units per single payment." },
+            maxPerDayAtomic: { type: "string", description: "Max atomic units per UTC day (all tools combined)." },
+        },
+        additionalProperties: false,
+    },
+};
+const WALLET_BALANCE_TOOL = {
+    name: "wallet_balance",
+    description: "Show the wallet's current USDC.e balance — what it can spend right now. In " +
+        "Safe mode this is the delegate's immediately-spendable balance (the Safe " +
+        "tops up more on demand).",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
+const WALLET_ADDRESS_TOOL = {
+    name: "wallet_address",
+    description: "Return this agent's own wallet address (to receive/fund USDC.e) and its " +
+        "network. Use when the user asks 'what's my address' or where to send funds.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
 export async function startBridgeServer(opts) {
     const server = new Server({ name: opts.name, version: opts.version }, { capabilities: { tools: {} } });
     // ---- listTools — upstream tools (if any) + local tools --------------
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         const upstreamTools = opts.upstream ? await opts.upstream.base.listTools() : { tools: [] };
-        const localTools = opts.discovery
-            ? [PAY_A2A_TOOL, X402_HTTP_TOOL, HPP_DISCOVER_TOOL, HPP_CALL_TOOL]
-            : [PAY_A2A_TOOL, X402_HTTP_TOOL];
+        const localTools = [
+            WALLET_ADDRESS_TOOL,
+            WALLET_BALANCE_TOOL,
+            WALLET_GET_LIMITS_TOOL,
+            WALLET_SET_LIMIT_TOOL,
+            PAY_A2A_TOOL,
+            X402_HTTP_TOOL,
+            ...(opts.discovery ? [HPP_DISCOVER_TOOL, HPP_CALL_TOOL] : []),
+            ...(opts.seller ? SELLER_TOOLS : []),
+        ];
         log.debug("listTools", { count: upstreamTools.tools.length + localTools.length });
         return { tools: [...upstreamTools.tools, ...localTools] };
     });
@@ -46,6 +89,74 @@ export async function startBridgeServer(opts) {
     server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
         const { name, arguments: args } = req.params;
         log.info("callTool.start", { name });
+        // Local tool: report our own wallet address (for funding).
+        if (name === WALLET_ADDRESS_TOOL.name) {
+            const address = opts.signer.address;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            address,
+                            network: opts.network,
+                            fund: `Send USDC.e to ${address} on ${opts.network} — no native gas needed (gasless settlement).`,
+                        }),
+                    },
+                ],
+            };
+        }
+        // Local tool: read the wallet's current USDC.e balance.
+        if (name === WALLET_BALANCE_TOOL.name) {
+            if (!opts.funds) {
+                return { content: [{ type: "text", text: "no funds source configured" }], isError: true };
+            }
+            try {
+                const atomic = await opts.funds.balance();
+                const s = atomic.toString().padStart(7, "0");
+                const usdce = `${s.slice(0, -6)}.${s.slice(-6)}`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                address: opts.signer.address,
+                                balanceAtomic: atomic.toString(),
+                                balanceUsdce: usdce,
+                                network: opts.network,
+                            }),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { content: [{ type: "text", text: `wallet_balance error: ${msg}` }], isError: true };
+            }
+        }
+        // Local tool: read the wallet's spend limits + today's usage.
+        if (name === WALLET_GET_LIMITS_TOOL.name) {
+            return { content: [{ type: "text", text: JSON.stringify(walletSpendStatus()) }] };
+        }
+        // Local tool: set the wallet's per-call / per-day spend caps.
+        if (name === WALLET_SET_LIMIT_TOOL.name) {
+            const a = (args ?? {});
+            const DIGITS = /^\d+$/;
+            const next = {};
+            for (const k of ["maxPerCallAtomic", "maxPerDayAtomic"]) {
+                const v = a[k];
+                if (v === undefined)
+                    continue;
+                if (typeof v !== "string" || !DIGITS.test(v)) {
+                    return { content: [{ type: "text", text: `${k} must be a decimal atomic-units string` }], isError: true };
+                }
+                next[k] = v;
+            }
+            if (next.maxPerCallAtomic === undefined && next.maxPerDayAtomic === undefined) {
+                return { content: [{ type: "text", text: "provide maxPerCallAtomic and/or maxPerDayAtomic" }], isError: true };
+            }
+            setWalletLimits(next);
+            return { content: [{ type: "text", text: JSON.stringify({ updated: true, ...walletSpendStatus() }) }] };
+        }
         // Local tool: pay an external A2A agent (not an upstream MCP tool).
         if (name === PAY_A2A_TOOL.name) {
             try {
@@ -101,6 +212,30 @@ export async function startBridgeServer(opts) {
                 return { content: [{ type: "text", text: `hpp_call error: ${msg}` }], isError: true };
             }
         }
+        // Local tools: seller building blocks (charge others over x402).
+        if (opts.seller && name.startsWith("seller_")) {
+            const s = opts.seller;
+            const a = (args ?? {});
+            try {
+                switch (name) {
+                    case SELLER_CREATE_REQUIREMENTS_TOOL.name:
+                        return sellerCreateRequirements(s, a);
+                    case SELLER_GENERATE_402_TOOL.name:
+                        return sellerGenerate402(a);
+                    case SELLER_DECODE_PAYMENT_TOOL.name:
+                        return sellerDecodePayment(a);
+                    case SELLER_VERIFY_TOOL.name:
+                        return await sellerVerify(s, a);
+                    case SELLER_SETTLE_TOOL.name:
+                        return await sellerSettle(s, a);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.error(`${name}.failed`, { err: msg });
+                return { content: [{ type: "text", text: `${name} error: ${msg}` }], isError: true };
+            }
+        }
         // Beyond the local tools above, everything is an upstream resource-server
         // tool. In local-tools-only mode there's no upstream to forward to.
         if (!opts.upstream) {

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/spendGuard.d.ts

@@ -0,0 +1,24 @@
+/** Wallet-wide atomic units spent so far today (UTC). */
+export declare function spentToday(): bigint;
+/**
+ * Returns a human-readable deny reason if paying `amount` would breach the
+ * wallet-wide per-call or per-day cap, else null. No-op (null) when no caps set.
+ */
+export declare function checkWalletSpend(amount: bigint): string | null;
+/** Record a *successful* payment against today's wallet-wide total. */
+export declare function recordWalletSpend(amount: bigint): void;
+/**
+ * Set the wallet-wide spend limits (persisted to policy._defaults.limits), so
+ * the guard enforces them. Omitted fields are left unchanged. Atomic strings.
+ */
+export declare function setWalletLimits(next: {
+    maxPerCallAtomic?: string;
+    maxPerDayAtomic?: string;
+}): void;
+/** Current limits + today's usage, for `wallet_get_limits` / `status`. */
+export declare function walletSpendStatus(): {
+    spentTodayAtomic: string;
+    maxPerCallAtomic?: string;
+    maxPerDayAtomic?: string;
+    remainingTodayAtomic?: string;
+};

package/dist/spendGuard.js

@@ -0,0 +1,124 @@
+/**
+ * Wallet-wide spend guard — the runaway-agent brake.
+ *
+ * Enforces two caps *uniformly across every payment path* (x402_http_call,
+ * hpp_call, pay_a2a_agent), so no single tool can bypass them:
+ *   - per-call:  a single payment may not exceed `maxPerCallAtomic`
+ *   - per-day:   the wallet's total spend in a UTC day may not exceed
+ *                `maxPerDayAtomic`  (this is the daily "ledger" that policy.ts
+ *                declared as a follow-up — now implemented)
+ *
+ * Limits are read from `policy._defaults.limits` (wallet-wide). When unset the
+ * guard is a no-op, so existing setups are unaffected — the caps only bite once
+ * a user sets them (via `wallet_set_limit` / `hpp-x402 policy defaults`).
+ *
+ * This is a *soft* guard the bridge enforces before signing: it protects
+ * against the agent overspending (misbehaviour / prompt injection), NOT against
+ * an attacker with machine access (that's the Safe's on-chain cap). Two
+ * complementary layers.
+ *
+ * The daily ledger lives at `${HPP_X402_HOME|~/.hpp-x402}/ledger.json` and only
+ * keeps today + yesterday (rolling).
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve as pathResolve } from "node:path";
+import { loadPolicy, savePolicy } from "./policy.js";
+import { log } from "./log.js";
+function home() {
+    return process.env.HPP_X402_HOME ?? pathResolve(homedir(), ".hpp-x402");
+}
+function ledgerPath() {
+    return pathResolve(home(), "ledger.json");
+}
+function dayKey(offsetDays = 0) {
+    const d = new Date();
+    d.setUTCDate(d.getUTCDate() + offsetDays);
+    return d.toISOString().slice(0, 10); // UTC yyyy-mm-dd
+}
+function loadLedger() {
+    try {
+        return JSON.parse(readFileSync(ledgerPath(), "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function saveLedger(l) {
+    const keep = new Set([dayKey(0), dayKey(-1)]);
+    for (const k of Object.keys(l))
+        if (!keep.has(k))
+            delete l[k];
+    try {
+        mkdirSync(home(), { recursive: true });
+        writeFileSync(ledgerPath(), JSON.stringify(l), { mode: 0o600 });
+    }
+    catch (err) {
+        log.debug("spendGuard.saveFailed", { err: err.message });
+    }
+}
+function walletLimits() {
+    const d = loadPolicy()._defaults?.limits ?? {};
+    return {
+        maxPerCall: d.maxPerCallAtomic != null ? BigInt(d.maxPerCallAtomic) : undefined,
+        maxPerDay: d.maxPerDayAtomic != null ? BigInt(d.maxPerDayAtomic) : undefined,
+    };
+}
+/** Wallet-wide atomic units spent so far today (UTC). */
+export function spentToday() {
+    return BigInt(loadLedger()[dayKey(0)] ?? "0");
+}
+/**
+ * Returns a human-readable deny reason if paying `amount` would breach the
+ * wallet-wide per-call or per-day cap, else null. No-op (null) when no caps set.
+ */
+export function checkWalletSpend(amount) {
+    const { maxPerCall, maxPerDay } = walletLimits();
+    if (maxPerCall != null && amount > maxPerCall) {
+        return `wallet per-call cap exceeded: ${amount} > ${maxPerCall} atomic. Raise it with wallet_set_limit (or hpp-x402 policy defaults --max-per-call).`;
+    }
+    if (maxPerDay != null) {
+        const after = spentToday() + amount;
+        if (after > maxPerDay) {
+            return `wallet daily cap exceeded: ${spentToday()} spent + ${amount} = ${after} > ${maxPerDay} atomic today. Resets at UTC midnight; raise with wallet_set_limit.`;
+        }
+    }
+    return null;
+}
+/** Record a *successful* payment against today's wallet-wide total. */
+export function recordWalletSpend(amount) {
+    if (amount <= 0n)
+        return;
+    const l = loadLedger();
+    l[dayKey(0)] = (BigInt(l[dayKey(0)] ?? "0") + amount).toString();
+    saveLedger(l);
+    log.debug("spendGuard.recorded", { amount: amount.toString(), spentToday: l[dayKey(0)] });
+}
+/**
+ * Set the wallet-wide spend limits (persisted to policy._defaults.limits), so
+ * the guard enforces them. Omitted fields are left unchanged. Atomic strings.
+ */
+export function setWalletLimits(next) {
+    const policy = loadPolicy();
+    const defaults = policy._defaults ?? {};
+    const limits = { ...(defaults.limits ?? {}) };
+    if (next.maxPerCallAtomic !== undefined)
+        limits.maxPerCallAtomic = next.maxPerCallAtomic;
+    if (next.maxPerDayAtomic !== undefined)
+        limits.maxPerDayAtomic = next.maxPerDayAtomic;
+    policy._defaults = { ...defaults, limits };
+    savePolicy(policy);
+    log.info("spendGuard.limitsUpdated", { ...limits });
+}
+/** Current limits + today's usage, for `wallet_get_limits` / `status`. */
+export function walletSpendStatus() {
+    const { maxPerCall, maxPerDay } = walletLimits();
+    const spent = spentToday();
+    return {
+        spentTodayAtomic: spent.toString(),
+        maxPerCallAtomic: maxPerCall?.toString(),
+        maxPerDayAtomic: maxPerDay?.toString(),
+        remainingTodayAtomic: maxPerDay != null ? (maxPerDay > spent ? (maxPerDay - spent).toString() : "0") : undefined,
+    };
+}
+//# sourceMappingURL=spendGuard.js.map

package/dist/spendGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spendGuard.js","sourceRoot":"","sources":["../src/spendGuard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hpp-io/x402-mcp-bridge",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "MCP stdio bridge that lets Claude Desktop / OpenClaw / other MCP hosts make x402 payments on HPP — autoTopup from a Safe via AllowanceModule, signs EIP-3009 with a delegate EOA.",
   "license": "Apache-2.0",
   "type": "module",
@@ -23,6 +23,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "postinstall": "patch-package || true",
     "prepublishOnly": "npm run typecheck && npm run build"
@@ -35,15 +36,19 @@
     "@napi-rs/keyring": "^1.3.0",
     "@x402/core": "^2.14.0",
     "@x402/evm": "^2.14.0",
+    "@x402/express": "^2.17.0",
     "@x402/mcp": "^2.14.0",
     "commander": "^12.1.0",
+    "express": "^4.22.2",
     "viem": "^2.21.54",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@types/express": "^4.17.25",
     "@types/node": "^20.0.0",
     "patch-package": "^8.0.1",
     "tsx": "^4.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.10"
   }
 }