crumb-alpha-sdk 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> crumb-alpha-sdk@0.1.0 build /Users/taylorferran/Desktop/dev/crumb-sdk/packages/sdk
+> tsc
+

package/.turbo/turbo-test.log

@@ -0,0 +1,32 @@
+
+
+> @crumb/sdk@0.1.0 test /Users/taylorferran/Desktop/dev/crumb-sdk/packages/sdk
+> vitest run
+
+[?25l
+ RUN  v4.0.18 /Users/taylorferran/Desktop/dev/crumb-sdk/packages/sdk
+
+[?2026h
+ ❯ test/provider.test.ts [queued]
+
+ Test Files 0 passed (3)
+      Tests 0 passed (0)
+   Start at 11:08:54
+   Duration 101ms
+[?2026l[?2026h ✓ test/middleware.test.ts (4 tests) 2ms
+ ✓ test/provider.test.ts (6 tests) 3ms
+
+ ❯ test/client.test.ts 0/15
+
+ Test Files 2 passed (3)
+      Tests 10 passed (25)
+   Start at 11:08:54
+   Duration 302ms
+[?2026l ✓ test/client.test.ts (15 tests) 25ms
+
+ Test Files  3 passed (3)
+      Tests  25 passed (25)
+   Start at  11:08:54
+   Duration  400ms (transform 129ms, setup 0ms, import 354ms, tests 31ms, environment 0ms)
+
+[?25h

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { GatewayClient } from 'crumb-alpha-core';
+import type { FetchOptions, FetchResult, SupportedChainName, Balances } from 'crumb-alpha-core';
+export declare class Crumb {
+    private wallet;
+    private gateway;
+    private chain;
+    private lowBalanceHook?;
+    private lowBalanceThreshold;
+    constructor(config: {
+        privateKey: string;
+        chain?: SupportedChainName;
+        rpcUrl?: string;
+        lowBalanceThreshold?: number;
+        onLowBalance?: (balance: string) => void;
+    });
+    get address(): string;
+    /**
+     * Pay for an x402-protected resource. Handles the full 402 flow automatically.
+     */
+    fetch<T = unknown>(url: string, options?: FetchOptions): Promise<FetchResult<T>>;
+    /**
+     * Deposit USDC into Gateway for gasless payments.
+     */
+    deposit(amount: string): Promise<import("@circle-fin/x402-batching/client").DepositResult>;
+    /**
+     * Withdraw USDC from Gateway.
+     */
+    withdraw(amount: string, options?: {
+        chain?: SupportedChainName;
+        recipient?: string;
+    }): Promise<import("@circle-fin/x402-batching/client").WithdrawResult>;
+    /**
+     * Get all balances (wallet + gateway).
+     */
+    balances(): Promise<Balances>;
+    /**
+     * Get gateway available balance as a formatted string.
+     */
+    balance(): Promise<string>;
+    /**
+     * Check if a URL supports Gateway batching.
+     */
+    supports(url: string): Promise<import("@circle-fin/x402-batching/client").SupportsResult>;
+    onLowBalance(threshold: number, fn: (balance: string) => void): void;
+    /** Access the underlying GatewayClient for advanced operations. */
+    get client(): GatewayClient;
+    private checkLowBalance;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAKd,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAEV,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACT,MAAM,kBAAkB,CAAA;AAEzB,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,cAAc,CAAC,CAA2B;IAClD,OAAO,CAAC,mBAAmB,CAAc;gBAE7B,MAAM,EAAE;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,CAAC,EAAE,kBAAkB,CAAA;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,mBAAmB,CAAC,EAAE,MAAM,CAAA;QAC5B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KACzC;IAmBD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;OAEG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IA8B1F;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM;IAI5B;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QACvC,KAAK,CAAC,EAAE,kBAAkB,CAAA;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB;IAOD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IAWnC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAWhC;;OAEG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM;IAI1B,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAK7D,mEAAmE;IACnE,IAAI,MAAM,IAAI,aAAa,CAE1B;YAEa,eAAe;CAW9B"}

package/dist/client.js

@@ -0,0 +1,122 @@
+import { GatewayClient, checkPriceCeiling, deriveAddress, } from 'crumb-alpha-core';
+export class Crumb {
+    wallet;
+    gateway;
+    chain;
+    lowBalanceHook;
+    lowBalanceThreshold = 1.0;
+    constructor(config) {
+        this.chain = config.chain ?? 'arcTestnet';
+        this.wallet = {
+            address: deriveAddress(config.privateKey),
+            privateKey: config.privateKey,
+        };
+        this.gateway = new GatewayClient({
+            chain: this.chain,
+            privateKey: config.privateKey,
+            rpcUrl: config.rpcUrl,
+        });
+        if (config.lowBalanceThreshold !== undefined) {
+            this.lowBalanceThreshold = config.lowBalanceThreshold;
+        }
+        if (config.onLowBalance) {
+            this.lowBalanceHook = config.onLowBalance;
+        }
+    }
+    get address() {
+        return this.wallet.address;
+    }
+    /**
+     * Pay for an x402-protected resource. Handles the full 402 flow automatically.
+     */
+    async fetch(url, options = {}) {
+        if (options.maxPayment !== undefined) {
+            // Pre-check: probe the URL to see the price before paying
+            const supported = await this.gateway.supports(url);
+            if (supported.supported && supported.requirements) {
+                const amount = supported.requirements?.amount;
+                if (amount) {
+                    checkPriceCeiling(amount, options.maxPayment);
+                }
+            }
+        }
+        const result = await this.gateway.pay(url, {
+            method: options.method,
+            body: options.body,
+            headers: options.headers,
+        });
+        // Check low balance after payment
+        this.checkLowBalance();
+        return {
+            data: result.data,
+            amount: result.amount,
+            formattedAmount: result.formattedAmount,
+            txHash: result.transaction,
+            status: result.status,
+        };
+    }
+    /**
+     * Deposit USDC into Gateway for gasless payments.
+     */
+    async deposit(amount) {
+        return this.gateway.deposit(amount);
+    }
+    /**
+     * Withdraw USDC from Gateway.
+     */
+    async withdraw(amount, options) {
+        return this.gateway.withdraw(amount, {
+            chain: options?.chain,
+            recipient: options?.recipient,
+        });
+    }
+    /**
+     * Get all balances (wallet + gateway).
+     */
+    async balances() {
+        const result = await this.gateway.getBalances();
+        const available = result.gateway.formattedAvailable;
+        if (parseFloat(available) < this.lowBalanceThreshold) {
+            this.lowBalanceHook?.(available);
+        }
+        return result;
+    }
+    /**
+     * Get gateway available balance as a formatted string.
+     */
+    async balance() {
+        const result = await this.gateway.getBalances();
+        const available = result.gateway.formattedAvailable;
+        if (parseFloat(available) < this.lowBalanceThreshold) {
+            this.lowBalanceHook?.(available);
+        }
+        return available;
+    }
+    /**
+     * Check if a URL supports Gateway batching.
+     */
+    async supports(url) {
+        return this.gateway.supports(url);
+    }
+    onLowBalance(threshold, fn) {
+        this.lowBalanceThreshold = threshold;
+        this.lowBalanceHook = fn;
+    }
+    /** Access the underlying GatewayClient for advanced operations. */
+    get client() {
+        return this.gateway;
+    }
+    async checkLowBalance() {
+        try {
+            const result = await this.gateway.getBalances();
+            const available = parseFloat(result.gateway.formattedAvailable);
+            if (available < this.lowBalanceThreshold) {
+                this.lowBalanceHook?.(result.gateway.formattedAvailable);
+            }
+        }
+        catch {
+            // Don't fail the payment if balance check fails
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Crumb } from './client.js';
+export { createProvider } from './provider.js';
+export type { GatewayMiddleware, PaymentRequest } from './provider.js';
+export { crumbMiddleware } from './middleware/express.js';
+export type { CrumbWallet, SettlementResult, FetchOptions, FetchResult, MiddlewareConfig, SupportedChainName, Balances, PayResult, } from 'crumb-alpha-core';
+export { CrumbError, GatewayClient, CHAIN_CONFIGS, GATEWAY_DOMAINS, } from 'crumb-alpha-core';
+export type { CrumbErrorCode } from 'crumb-alpha-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGnC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGtE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAGzD,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,UAAU,EACV,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Agent-side
+export { Crumb } from './client.js';
+// Provider-side
+export { createProvider } from './provider.js';
+// Express middleware (convenience re-export)
+export { crumbMiddleware } from './middleware/express.js';
+export { CrumbError, GatewayClient, CHAIN_CONFIGS, GATEWAY_DOMAINS, } from 'crumb-alpha-core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAEnC,gBAAgB;AAChB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAG9C,6CAA6C;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAczD,OAAO,EACL,UAAU,EACV,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAA"}

package/dist/middleware/express.d.ts

@@ -0,0 +1,30 @@
+import type { MiddlewareConfig } from 'crumb-alpha-core';
+/**
+ * Express middleware that gates routes behind x402 payments via Circle Gateway.
+ *
+ * @example
+ * ```typescript
+ * import { crumbMiddleware } from 'crumb-alpha-sdk/middleware/express'
+ *
+ * const gateway = crumbMiddleware({ sellerAddress: '0x...' })
+ *
+ * app.get('/resource', gateway.require('$0.01'), (req, res) => {
+ *   console.log('Payer:', req.payment?.payer)
+ *   res.json({ data: 'paid content' })
+ * })
+ * ```
+ */
+export declare function crumbMiddleware(config: MiddlewareConfig): {
+    require: (price: string) => (req: import("@circle-fin/x402-batching/server").PaymentRequest, res: import("@circle-fin/x402-batching/server").PaymentResponse, next: (err?: unknown) => void) => void | Promise<void>;
+    verify: (payment: unknown) => Promise<{
+        valid: boolean;
+        payer?: string;
+        error?: string;
+    }>;
+    settle: (payment: unknown) => Promise<{
+        success: boolean;
+        transaction?: string;
+        error?: string;
+    }>;
+};
+//# sourceMappingURL=express.d.ts.map

package/dist/middleware/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB;qBASnC,MAAM;;;aAkBspO,CAAC;aAAuB,CAAC;;;;mBAA6J,CAAC;aAAuB,CAAC;;EAD/3O"}

package/dist/middleware/express.js

@@ -0,0 +1,43 @@
+import { createGatewayMiddleware } from '@circle-fin/x402-batching/server';
+/**
+ * Express middleware that gates routes behind x402 payments via Circle Gateway.
+ *
+ * @example
+ * ```typescript
+ * import { crumbMiddleware } from 'crumb-alpha-sdk/middleware/express'
+ *
+ * const gateway = crumbMiddleware({ sellerAddress: '0x...' })
+ *
+ * app.get('/resource', gateway.require('$0.01'), (req, res) => {
+ *   console.log('Payer:', req.payment?.payer)
+ *   res.json({ data: 'paid content' })
+ * })
+ * ```
+ */
+export function crumbMiddleware(config) {
+    const gateway = createGatewayMiddleware({
+        sellerAddress: config.sellerAddress,
+        networks: config.networks,
+        facilitatorUrl: config.facilitatorUrl,
+        description: config.description,
+    });
+    return {
+        require: (price) => {
+            const mw = gateway.require(price);
+            if (config.onPayment) {
+                return async (req, res, next) => {
+                    await mw(req, res, () => {
+                        if (req.payment) {
+                            config.onPayment(req.payment);
+                        }
+                        next();
+                    });
+                };
+            }
+            return mw;
+        },
+        verify: gateway.verify,
+        settle: gateway.settle,
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/middleware/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA;AAG1E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,MAAwB;IACtD,MAAM,OAAO,GAAG,uBAAuB,CAAC;QACtC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAA;IAEF,OAAO;QACL,OAAO,EAAE,CAAC,KAAa,EAAE,EAAE;YACzB,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YACjC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACrB,OAAO,KAAK,EAAE,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;oBAC7C,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;wBACtB,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;4BAChB,MAAM,CAAC,SAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;wBAChC,CAAC;wBACD,IAAI,EAAE,CAAA;oBACR,CAAC,CAAC,CAAA;gBACJ,CAAC,CAAA;YACH,CAAC;YACD,OAAO,EAAE,CAAA;QACX,CAAC;QACD,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAA;AACH,CAAC"}

package/dist/middleware/fastify.d.ts

@@ -0,0 +1,9 @@
+import type { MiddlewareConfig } from 'crumb-alpha-core';
+import type { FastifyPluginAsync } from 'fastify';
+declare module 'fastify' {
+    interface FastifyRequest {
+        crumbPayment?: import('crumb-alpha-core').SettlementResult;
+    }
+}
+export declare const crumbPlugin: FastifyPluginAsync<MiddlewareConfig>;
+//# sourceMappingURL=fastify.d.ts.map

package/dist/middleware/fastify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.d.ts","sourceRoot":"","sources":["../../src/middleware/fastify.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAKnD,OAAO,KAAK,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAA;AAE/E,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,YAAY,CAAC,EAAE,OAAO,aAAa,EAAE,gBAAgB,CAAA;KACtD;CACF;AAcD,eAAO,MAAM,WAAW,EAAE,kBAAkB,CAAC,gBAAgB,CAyC5D,CAAA"}

package/dist/middleware/fastify.js

@@ -0,0 +1,44 @@
+import { verifyAndSettle, CrumbError, BASE_SEPOLIA_NETWORK, BASE_SEPOLIA_USDC, } from '@crumb/core';
+import { decodePaymentSignatureHeader, encodePaymentRequiredHeader, } from '@x402/core/http';
+function buildRequirement(config) {
+    return {
+        scheme: 'exact',
+        network: config.network ?? BASE_SEPOLIA_NETWORK,
+        amount: config.price,
+        asset: config.asset ?? BASE_SEPOLIA_USDC,
+        payTo: config.address,
+        maxTimeoutSeconds: config.maxTimeoutSeconds ?? 300,
+        extra: {},
+    };
+}
+export const crumbPlugin = async (fastify, config) => {
+    const requirement = buildRequirement(config);
+    const paymentRequired = {
+        x402Version: 2,
+        accepts: [requirement],
+        resource: {},
+    };
+    fastify.addHook('preHandler', async (request, reply) => {
+        const paymentHeader = request.headers['x-payment'];
+        if (!paymentHeader) {
+            reply.header('X-Payment-Required', encodePaymentRequiredHeader(paymentRequired));
+            return reply.status(402).send(paymentRequired);
+        }
+        try {
+            const paymentPayload = decodePaymentSignatureHeader(paymentHeader);
+            const result = await verifyAndSettle(paymentPayload, requirement, config.facilitatorUrl);
+            request.crumbPayment = result;
+            config.onPayment?.(result);
+        }
+        catch (err) {
+            if (err instanceof CrumbError) {
+                return reply.status(402).send({
+                    error: err.code,
+                    detail: err.detail,
+                });
+            }
+            throw err;
+        }
+    });
+};
+//# sourceMappingURL=fastify.js.map

package/dist/middleware/fastify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.js","sourceRoot":"","sources":["../../src/middleware/fastify.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,UAAU,EACV,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA;AASxB,SAAS,gBAAgB,CAAC,MAAwB;IAChD,OAAO;QACL,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,oBAAoB;QAC/C,MAAM,EAAE,MAAM,CAAC,KAAK;QACpB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,iBAAiB;QACxC,KAAK,EAAE,MAAM,CAAC,OAAO;QACrB,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,GAAG;QAClD,KAAK,EAAE,EAAE;KACV,CAAA;AACH,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAyC,KAAK,EACpE,OAAO,EACP,MAAM,EACN,EAAE;IACF,MAAM,WAAW,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAC5C,MAAM,eAAe,GAAG;QACtB,WAAW,EAAE,CAAC;QACd,OAAO,EAAE,CAAC,WAAW,CAAC;QACtB,QAAQ,EAAE,EAAE;KACb,CAAA;IAED,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,OAAuB,EAAE,KAAmB,EAAE,EAAE;QACnF,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAuB,CAAA;QAExE,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,KAAK,CAAC,MAAM,CACV,oBAAoB,EACpB,2BAA2B,CAAC,eAAsB,CAAC,CACpD,CAAA;YACD,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;QAChD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,4BAA4B,CAAC,aAAa,CAAC,CAAA;YAClE,MAAM,MAAM,GAAG,MAAM,eAAe,CAClC,cAAc,EACd,WAAkB,EAClB,MAAM,CAAC,cAAc,CACtB,CAAA;YACD,OAAO,CAAC,YAAY,GAAG,MAAM,CAAA;YAC7B,MAAM,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAA;QAC5B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;gBAC9B,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBAC5B,KAAK,EAAE,GAAG,CAAC,IAAI;oBACf,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC,CAAA;YACJ,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/middleware/fetch.d.ts

@@ -0,0 +1,7 @@
+import type { MiddlewareConfig, SettlementResult } from 'crumb-alpha-core';
+export interface CrumbFetchHandlerResult {
+    paid: boolean;
+    payment?: SettlementResult;
+}
+export declare function createFetchHandler(config: MiddlewareConfig): (request: Request) => Promise<Response | CrumbFetchHandlerResult>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/middleware/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/middleware/fetch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAMrE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAcD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,IAQ3C,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,GAAG,uBAAuB,CAAC,CAsC7E"}

package/dist/middleware/fetch.js

@@ -0,0 +1,49 @@
+import { verifyAndSettle, CrumbError, BASE_SEPOLIA_NETWORK, BASE_SEPOLIA_USDC, } from '@crumb/core';
+import { decodePaymentSignatureHeader, encodePaymentRequiredHeader, } from '@x402/core/http';
+function buildRequirement(config) {
+    return {
+        scheme: 'exact',
+        network: config.network ?? BASE_SEPOLIA_NETWORK,
+        amount: config.price,
+        asset: config.asset ?? BASE_SEPOLIA_USDC,
+        payTo: config.address,
+        maxTimeoutSeconds: config.maxTimeoutSeconds ?? 300,
+        extra: {},
+    };
+}
+export function createFetchHandler(config) {
+    const requirement = buildRequirement(config);
+    const paymentRequired = {
+        x402Version: 2,
+        accepts: [requirement],
+        resource: {},
+    };
+    return async (request) => {
+        const paymentHeader = request.headers.get('x-payment');
+        if (!paymentHeader) {
+            return new Response(JSON.stringify(paymentRequired), {
+                status: 402,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Payment-Required': encodePaymentRequiredHeader(paymentRequired),
+                },
+            });
+        }
+        try {
+            const paymentPayload = decodePaymentSignatureHeader(paymentHeader);
+            const result = await verifyAndSettle(paymentPayload, requirement, config.facilitatorUrl);
+            config.onPayment?.(result);
+            return { paid: true, payment: result };
+        }
+        catch (err) {
+            if (err instanceof CrumbError) {
+                return new Response(JSON.stringify({ error: err.code, detail: err.detail }), {
+                    status: 402,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            throw err;
+        }
+    };
+}
+//# sourceMappingURL=fetch.js.map

package/dist/middleware/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/middleware/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,UAAU,EACV,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA;AAOxB,SAAS,gBAAgB,CAAC,MAAwB;IAChD,OAAO;QACL,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,oBAAoB;QAC/C,MAAM,EAAE,MAAM,CAAC,KAAK;QACpB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,iBAAiB;QACxC,KAAK,EAAE,MAAM,CAAC,OAAO;QACrB,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,GAAG;QAClD,KAAK,EAAE,EAAE;KACV,CAAA;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAwB;IACzD,MAAM,WAAW,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAC5C,MAAM,eAAe,GAAG;QACtB,WAAW,EAAE,CAAC;QACd,OAAO,EAAE,CAAC,WAAW,CAAC;QACtB,QAAQ,EAAE,EAAE;KACb,CAAA;IAED,OAAO,KAAK,EAAE,OAAgB,EAA+C,EAAE;QAC7E,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAEtD,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,EAC/B;gBACE,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,oBAAoB,EAAE,2BAA2B,CAAC,eAAsB,CAAC;iBAC1E;aACF,CACF,CAAA;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,4BAA4B,CAAC,aAAa,CAAC,CAAA;YAClE,MAAM,MAAM,GAAG,MAAM,eAAe,CAClC,cAAc,EACd,WAAkB,EAClB,MAAM,CAAC,cAAc,CACtB,CAAA;YACD,MAAM,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAA;YAC1B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;gBAC9B,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,EACvD;oBACE,MAAM,EAAE,GAAG;oBACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;iBAChD,CACF,CAAA;YACH,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,33 @@
+import type { MiddlewareConfig } from 'crumb-alpha-core';
+export type { GatewayMiddleware, PaymentRequest } from '@circle-fin/x402-batching/server';
+/**
+ * Create a CrumbProvider — wraps Circle's createGatewayMiddleware.
+ *
+ * @example
+ * ```typescript
+ * const gateway = createProvider({
+ *   sellerAddress: '0x...',
+ * })
+ *
+ * app.get('/resource', gateway.require('$0.01'), (req, res) => {
+ *   res.json({ data: 'paid content' })
+ * })
+ * ```
+ */
+export declare function createProvider(config: MiddlewareConfig): {
+    /** Require payment — returns Express middleware */
+    require: (price: string) => (req: import("@circle-fin/x402-batching/server").PaymentRequest, res: import("@circle-fin/x402-batching/server").PaymentResponse, next: (err?: unknown) => void) => void | Promise<void>;
+    /** Verify a payment without settling */
+    verify: (payment: unknown) => Promise<{
+        valid: boolean;
+        payer?: string;
+        error?: string;
+    }>;
+    /** Settle a verified payment */
+    settle: (payment: unknown) => Promise<{
+        success: boolean;
+        transaction?: string;
+        error?: string;
+    }>;
+};
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AAEzF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB;IASnD,mDAAmD;qBAClC,MAAM;IAevB,wCAAwC;;;aAM++N,CAAC;aAAuB,CAAC;;IAJhjO,gCAAgC;;;mBAI6qO,CAAC;aAAuB,CAAC;;EADzuO"}

package/dist/provider.js

@@ -0,0 +1,46 @@
+import { createGatewayMiddleware } from '@circle-fin/x402-batching/server';
+/**
+ * Create a CrumbProvider — wraps Circle's createGatewayMiddleware.
+ *
+ * @example
+ * ```typescript
+ * const gateway = createProvider({
+ *   sellerAddress: '0x...',
+ * })
+ *
+ * app.get('/resource', gateway.require('$0.01'), (req, res) => {
+ *   res.json({ data: 'paid content' })
+ * })
+ * ```
+ */
+export function createProvider(config) {
+    const middleware = createGatewayMiddleware({
+        sellerAddress: config.sellerAddress,
+        networks: config.networks,
+        facilitatorUrl: config.facilitatorUrl,
+        description: config.description,
+    });
+    return {
+        /** Require payment — returns Express middleware */
+        require: (price) => {
+            const mw = middleware.require(price);
+            // Wrap to call onPayment hook
+            if (config.onPayment) {
+                return async (req, res, next) => {
+                    await mw(req, res, () => {
+                        if (req.payment) {
+                            config.onPayment(req.payment);
+                        }
+                        next();
+                    });
+                };
+            }
+            return mw;
+        },
+        /** Verify a payment without settling */
+        verify: middleware.verify,
+        /** Settle a verified payment */
+        settle: middleware.settle,
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA;AAK1E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,MAAwB;IACrD,MAAM,UAAU,GAAG,uBAAuB,CAAC;QACzC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAA;IAEF,OAAO;QACL,mDAAmD;QACnD,OAAO,EAAE,CAAC,KAAa,EAAE,EAAE;YACzB,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YACpC,8BAA8B;YAC9B,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACrB,OAAO,KAAK,EAAE,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;oBAC7C,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;wBACtB,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;4BAChB,MAAM,CAAC,SAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;wBAChC,CAAC;wBACD,IAAI,EAAE,CAAA;oBACR,CAAC,CAAC,CAAA;gBACJ,CAAC,CAAA;YACH,CAAC;YACD,OAAO,EAAE,CAAA;QACX,CAAC;QACD,wCAAwC;QACxC,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,gCAAgC;QAChC,MAAM,EAAE,UAAU,CAAC,MAAM;KAC1B,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "crumb-alpha-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./middleware/express": {
+      "types": "./dist/middleware/express.d.ts",
+      "import": "./dist/middleware/express.js",
+      "default": "./dist/middleware/express.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@circle-fin/x402-batching": "^2.0.4",
+    "crumb-alpha-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,161 @@
+import {
+  GatewayClient,
+  getBalances,
+  checkPriceCeiling,
+  deriveAddress,
+  CrumbError,
+} from 'crumb-alpha-core'
+import type {
+  CrumbWallet,
+  FetchOptions,
+  FetchResult,
+  SupportedChainName,
+  Balances,
+} from 'crumb-alpha-core'
+
+export class Crumb {
+  private wallet: CrumbWallet
+  private gateway: GatewayClient
+  private chain: SupportedChainName
+  private lowBalanceHook?: (balance: string) => void
+  private lowBalanceThreshold: number = 1.0
+
+  constructor(config: {
+    privateKey: string
+    chain?: SupportedChainName
+    rpcUrl?: string
+    lowBalanceThreshold?: number
+    onLowBalance?: (balance: string) => void
+  }) {
+    this.chain = config.chain ?? 'arcTestnet'
+    this.wallet = {
+      address: deriveAddress(config.privateKey),
+      privateKey: config.privateKey,
+    }
+    this.gateway = new GatewayClient({
+      chain: this.chain,
+      privateKey: config.privateKey as `0x${string}`,
+      rpcUrl: config.rpcUrl,
+    })
+    if (config.lowBalanceThreshold !== undefined) {
+      this.lowBalanceThreshold = config.lowBalanceThreshold
+    }
+    if (config.onLowBalance) {
+      this.lowBalanceHook = config.onLowBalance
+    }
+  }
+
+  get address(): string {
+    return this.wallet.address
+  }
+
+  /**
+   * Pay for an x402-protected resource. Handles the full 402 flow automatically.
+   */
+  async fetch<T = unknown>(url: string, options: FetchOptions = {}): Promise<FetchResult<T>> {
+    if (options.maxPayment !== undefined) {
+      // Pre-check: probe the URL to see the price before paying
+      const supported = await this.gateway.supports(url)
+      if (supported.supported && supported.requirements) {
+        const amount = (supported.requirements as any)?.amount
+        if (amount) {
+          checkPriceCeiling(amount, options.maxPayment)
+        }
+      }
+    }
+
+    const result = await this.gateway.pay<T>(url, {
+      method: options.method,
+      body: options.body,
+      headers: options.headers,
+    })
+
+    // Check low balance after payment
+    this.checkLowBalance()
+
+    return {
+      data: result.data,
+      amount: result.amount,
+      formattedAmount: result.formattedAmount,
+      txHash: result.transaction,
+      status: result.status,
+    }
+  }
+
+  /**
+   * Deposit USDC into Gateway for gasless payments.
+   */
+  async deposit(amount: string) {
+    return this.gateway.deposit(amount)
+  }
+
+  /**
+   * Withdraw USDC from Gateway.
+   */
+  async withdraw(amount: string, options?: {
+    chain?: SupportedChainName
+    recipient?: string
+  }) {
+    return this.gateway.withdraw(amount, {
+      chain: options?.chain,
+      recipient: options?.recipient as `0x${string}`,
+    })
+  }
+
+  /**
+   * Get all balances (wallet + gateway).
+   */
+  async balances(): Promise<Balances> {
+    const result = await this.gateway.getBalances()
+
+    const available = result.gateway.formattedAvailable
+    if (parseFloat(available) < this.lowBalanceThreshold) {
+      this.lowBalanceHook?.(available)
+    }
+
+    return result
+  }
+
+  /**
+   * Get gateway available balance as a formatted string.
+   */
+  async balance(): Promise<string> {
+    const result = await this.gateway.getBalances()
+    const available = result.gateway.formattedAvailable
+
+    if (parseFloat(available) < this.lowBalanceThreshold) {
+      this.lowBalanceHook?.(available)
+    }
+
+    return available
+  }
+
+  /**
+   * Check if a URL supports Gateway batching.
+   */
+  async supports(url: string) {
+    return this.gateway.supports(url)
+  }
+
+  onLowBalance(threshold: number, fn: (balance: string) => void) {
+    this.lowBalanceThreshold = threshold
+    this.lowBalanceHook = fn
+  }
+
+  /** Access the underlying GatewayClient for advanced operations. */
+  get client(): GatewayClient {
+    return this.gateway
+  }
+
+  private async checkLowBalance() {
+    try {
+      const result = await this.gateway.getBalances()
+      const available = parseFloat(result.gateway.formattedAvailable)
+      if (available < this.lowBalanceThreshold) {
+        this.lowBalanceHook?.(result.gateway.formattedAvailable)
+      }
+    } catch {
+      // Don't fail the payment if balance check fails
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// Agent-side
+export { Crumb } from './client.js'
+
+// Provider-side
+export { createProvider } from './provider.js'
+export type { GatewayMiddleware, PaymentRequest } from './provider.js'
+
+// Express middleware (convenience re-export)
+export { crumbMiddleware } from './middleware/express.js'
+
+// Re-export core types for convenience
+export type {
+  CrumbWallet,
+  SettlementResult,
+  FetchOptions,
+  FetchResult,
+  MiddlewareConfig,
+  SupportedChainName,
+  Balances,
+  PayResult,
+} from 'crumb-alpha-core'
+
+export {
+  CrumbError,
+  GatewayClient,
+  CHAIN_CONFIGS,
+  GATEWAY_DOMAINS,
+} from 'crumb-alpha-core'
+export type { CrumbErrorCode } from 'crumb-alpha-core'

package/src/middleware/express.ts

@@ -0,0 +1,45 @@
+import { createGatewayMiddleware } from '@circle-fin/x402-batching/server'
+import type { MiddlewareConfig } from 'crumb-alpha-core'
+
+/**
+ * Express middleware that gates routes behind x402 payments via Circle Gateway.
+ *
+ * @example
+ * ```typescript
+ * import { crumbMiddleware } from 'crumb-alpha-sdk/middleware/express'
+ *
+ * const gateway = crumbMiddleware({ sellerAddress: '0x...' })
+ *
+ * app.get('/resource', gateway.require('$0.01'), (req, res) => {
+ *   console.log('Payer:', req.payment?.payer)
+ *   res.json({ data: 'paid content' })
+ * })
+ * ```
+ */
+export function crumbMiddleware(config: MiddlewareConfig) {
+  const gateway = createGatewayMiddleware({
+    sellerAddress: config.sellerAddress,
+    networks: config.networks,
+    facilitatorUrl: config.facilitatorUrl,
+    description: config.description,
+  })
+
+  return {
+    require: (price: string) => {
+      const mw = gateway.require(price)
+      if (config.onPayment) {
+        return async (req: any, res: any, next: any) => {
+          await mw(req, res, () => {
+            if (req.payment) {
+              config.onPayment!(req.payment)
+            }
+            next()
+          })
+        }
+      }
+      return mw
+    },
+    verify: gateway.verify,
+    settle: gateway.settle,
+  }
+}

package/src/provider.ts

@@ -0,0 +1,50 @@
+import { createGatewayMiddleware } from '@circle-fin/x402-batching/server'
+import type { MiddlewareConfig } from 'crumb-alpha-core'
+
+export type { GatewayMiddleware, PaymentRequest } from '@circle-fin/x402-batching/server'
+
+/**
+ * Create a CrumbProvider — wraps Circle's createGatewayMiddleware.
+ *
+ * @example
+ * ```typescript
+ * const gateway = createProvider({
+ *   sellerAddress: '0x...',
+ * })
+ *
+ * app.get('/resource', gateway.require('$0.01'), (req, res) => {
+ *   res.json({ data: 'paid content' })
+ * })
+ * ```
+ */
+export function createProvider(config: MiddlewareConfig) {
+  const middleware = createGatewayMiddleware({
+    sellerAddress: config.sellerAddress,
+    networks: config.networks,
+    facilitatorUrl: config.facilitatorUrl,
+    description: config.description,
+  })
+
+  return {
+    /** Require payment — returns Express middleware */
+    require: (price: string) => {
+      const mw = middleware.require(price)
+      // Wrap to call onPayment hook
+      if (config.onPayment) {
+        return async (req: any, res: any, next: any) => {
+          await mw(req, res, () => {
+            if (req.payment) {
+              config.onPayment!(req.payment)
+            }
+            next()
+          })
+        }
+      }
+      return mw
+    },
+    /** Verify a payment without settling */
+    verify: middleware.verify,
+    /** Settle a verified payment */
+    settle: middleware.settle,
+  }
+}

package/test/client.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const mockPay = vi.fn()
+const mockDeposit = vi.fn()
+const mockWithdraw = vi.fn()
+const mockGetBalances = vi.fn()
+const mockSupports = vi.fn()
+
+class MockGatewayClient {
+  pay = mockPay
+  deposit = mockDeposit
+  withdraw = mockWithdraw
+  getBalances = mockGetBalances
+  supports = mockSupports
+  constructor(_config: any) {}
+}
+
+vi.mock('@circle-fin/x402-batching/client', () => ({
+  GatewayClient: MockGatewayClient,
+}))
+
+vi.mock('crumb-alpha-core', async () => {
+  const actual = await vi.importActual<any>('crumb-alpha-core')
+  return {
+    ...actual,
+    GatewayClient: MockGatewayClient,
+  }
+})
+
+const { Crumb } = await import('../src/client.js')
+
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
+
+describe('Crumb', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetBalances.mockResolvedValue({
+      wallet: { formatted: '100.00' },
+      gateway: { formattedAvailable: '50.00', available: 50000000n },
+    })
+  })
+
+  describe('constructor', () => {
+    it('derives address from private key', () => {
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      expect(crumb.address).toBe('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266')
+    })
+
+    it('defaults chain to arcTestnet', () => {
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      expect(crumb).toBeDefined()
+    })
+
+    it('exposes the underlying GatewayClient', () => {
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      expect(crumb.client).toBeDefined()
+    })
+  })
+
+  describe('fetch', () => {
+    it('calls gateway.pay with url and options', async () => {
+      mockPay.mockResolvedValue({
+        data: { results: [] },
+        amount: 1000n,
+        formattedAmount: '0.001',
+        transaction: '0xtx123',
+        status: 200,
+      })
+      mockSupports.mockResolvedValue({ supported: false })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      const result = await crumb.fetch('http://localhost:3001/search', {
+        method: 'POST',
+        body: { query: 'test' },
+      })
+
+      expect(mockPay).toHaveBeenCalledWith('http://localhost:3001/search', {
+        method: 'POST',
+        body: { query: 'test' },
+        headers: undefined,
+      })
+      expect(result.data).toEqual({ results: [] })
+      expect(result.formattedAmount).toBe('0.001')
+      expect(result.txHash).toBe('0xtx123')
+      expect(result.status).toBe(200)
+    })
+
+    it('checks price ceiling when maxPayment is set', async () => {
+      mockSupports.mockResolvedValue({
+        supported: true,
+        requirements: { amount: '$0.05' },
+      })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+
+      await expect(
+        crumb.fetch('http://localhost:3001/search', { maxPayment: 0.01 }),
+      ).rejects.toThrow()
+    })
+
+    it('proceeds when price is within maxPayment', async () => {
+      mockSupports.mockResolvedValue({
+        supported: true,
+        requirements: { amount: '$0.001' },
+      })
+      mockPay.mockResolvedValue({
+        data: {},
+        amount: 1000n,
+        formattedAmount: '0.001',
+        transaction: '0xtx',
+        status: 200,
+      })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      const result = await crumb.fetch('http://localhost:3001/search', { maxPayment: 0.01 })
+      expect(result.formattedAmount).toBe('0.001')
+    })
+  })
+
+  describe('deposit', () => {
+    it('delegates to gateway.deposit', async () => {
+      mockDeposit.mockResolvedValue({ success: true })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      await crumb.deposit('10.0')
+
+      expect(mockDeposit).toHaveBeenCalledWith('10.0')
+    })
+  })
+
+  describe('withdraw', () => {
+    it('delegates to gateway.withdraw', async () => {
+      mockWithdraw.mockResolvedValue({ success: true })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      await crumb.withdraw('5.0')
+
+      expect(mockWithdraw).toHaveBeenCalledWith('5.0', {
+        chain: undefined,
+        recipient: undefined,
+      })
+    })
+
+    it('passes chain and recipient options', async () => {
+      mockWithdraw.mockResolvedValue({ success: true })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      await crumb.withdraw('5.0', { chain: 'arcTestnet', recipient: '0xrecipient' })
+
+      expect(mockWithdraw).toHaveBeenCalledWith('5.0', {
+        chain: 'arcTestnet',
+        recipient: '0xrecipient',
+      })
+    })
+  })
+
+  describe('balance / balances', () => {
+    it('returns formatted gateway balance', async () => {
+      mockGetBalances.mockResolvedValue({
+        wallet: { formatted: '100.00' },
+        gateway: { formattedAvailable: '42.50', available: 42500000n },
+      })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      const bal = await crumb.balance()
+      expect(bal).toBe('42.50')
+    })
+
+    it('returns full balances object', async () => {
+      const mockResult = {
+        wallet: { formatted: '100.00' },
+        gateway: { formattedAvailable: '42.50', available: 42500000n },
+      }
+      mockGetBalances.mockResolvedValue(mockResult)
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      const result = await crumb.balances()
+      expect(result).toEqual(mockResult)
+    })
+
+    it('triggers low balance hook when below threshold', async () => {
+      mockGetBalances.mockResolvedValue({
+        wallet: { formatted: '0.50' },
+        gateway: { formattedAvailable: '0.25', available: 250000n },
+      })
+
+      const hook = vi.fn()
+      const crumb = new Crumb({
+        privateKey: TEST_PRIVATE_KEY,
+        lowBalanceThreshold: 1.0,
+        onLowBalance: hook,
+      })
+
+      await crumb.balance()
+      expect(hook).toHaveBeenCalledWith('0.25')
+    })
+
+    it('does not trigger hook when above threshold', async () => {
+      mockGetBalances.mockResolvedValue({
+        wallet: { formatted: '100.00' },
+        gateway: { formattedAvailable: '50.00', available: 50000000n },
+      })
+
+      const hook = vi.fn()
+      const crumb = new Crumb({
+        privateKey: TEST_PRIVATE_KEY,
+        lowBalanceThreshold: 1.0,
+        onLowBalance: hook,
+      })
+
+      await crumb.balance()
+      expect(hook).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('supports', () => {
+    it('delegates to gateway.supports', async () => {
+      mockSupports.mockResolvedValue({ supported: true, requirements: {} })
+
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      const result = await crumb.supports('http://example.com/api')
+
+      expect(mockSupports).toHaveBeenCalledWith('http://example.com/api')
+      expect(result.supported).toBe(true)
+    })
+  })
+
+  describe('onLowBalance', () => {
+    it('updates threshold and hook', async () => {
+      mockGetBalances.mockResolvedValue({
+        wallet: { formatted: '5.00' },
+        gateway: { formattedAvailable: '3.00', available: 3000000n },
+      })
+
+      const hook = vi.fn()
+      const crumb = new Crumb({ privateKey: TEST_PRIVATE_KEY })
+      crumb.onLowBalance(5.0, hook)
+
+      await crumb.balance()
+      expect(hook).toHaveBeenCalledWith('3.00')
+    })
+  })
+})

package/test/middleware.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from 'vitest'
+
+const mockRequire = vi.fn().mockReturnValue(vi.fn())
+const mockVerify = vi.fn()
+const mockSettle = vi.fn()
+
+vi.mock('@circle-fin/x402-batching/server', () => ({
+  createGatewayMiddleware: vi.fn().mockImplementation(() => ({
+    require: mockRequire,
+    verify: mockVerify,
+    settle: mockSettle,
+  })),
+}))
+
+const { crumbMiddleware } = await import('../src/middleware/express.js')
+
+describe('crumbMiddleware', () => {
+  it('returns an object with require, verify, settle', () => {
+    const gateway = crumbMiddleware({ sellerAddress: '0xseller' })
+    expect(gateway).toHaveProperty('require')
+    expect(gateway).toHaveProperty('verify')
+    expect(gateway).toHaveProperty('settle')
+  })
+
+  it('require returns middleware', () => {
+    const gateway = crumbMiddleware({ sellerAddress: '0xseller' })
+    const mw = gateway.require('$0.01')
+    expect(mockRequire).toHaveBeenCalledWith('$0.01')
+    expect(mw).toBeDefined()
+  })
+
+  it('wraps middleware with onPayment hook', async () => {
+    const onPayment = vi.fn()
+    const innerMw = vi.fn().mockImplementation((_req: any, _res: any, next: () => void) => {
+      next()
+    })
+    mockRequire.mockReturnValue(innerMw)
+
+    const gateway = crumbMiddleware({
+      sellerAddress: '0xseller',
+      onPayment,
+    })
+
+    const mw = gateway.require('$0.01')
+    const req = { payment: { verified: true, payer: '0xpayer', amount: '0.01', network: 'arcTestnet' } }
+    const res = {}
+    const next = vi.fn()
+
+    await mw(req, res, next)
+
+    expect(onPayment).toHaveBeenCalledWith(req.payment)
+    expect(next).toHaveBeenCalled()
+  })
+
+  it('returns raw middleware when no onPayment', () => {
+    const innerMw = vi.fn()
+    mockRequire.mockReturnValue(innerMw)
+
+    const gateway = crumbMiddleware({ sellerAddress: '0xseller' })
+    const mw = gateway.require('$0.01')
+    expect(mw).toBe(innerMw)
+  })
+})

package/test/provider.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi } from 'vitest'
+
+const mockRequire = vi.fn().mockReturnValue(vi.fn())
+const mockVerify = vi.fn()
+const mockSettle = vi.fn()
+
+vi.mock('@circle-fin/x402-batching/server', () => ({
+  createGatewayMiddleware: vi.fn().mockImplementation(() => ({
+    require: mockRequire,
+    verify: mockVerify,
+    settle: mockSettle,
+  })),
+}))
+
+const { createProvider } = await import('../src/provider.js')
+
+describe('createProvider', () => {
+  it('returns an object with require, verify, settle', () => {
+    const provider = createProvider({ sellerAddress: '0xseller' })
+    expect(provider).toHaveProperty('require')
+    expect(provider).toHaveProperty('verify')
+    expect(provider).toHaveProperty('settle')
+  })
+
+  it('passes config to createGatewayMiddleware', async () => {
+    const { createGatewayMiddleware } = await import('@circle-fin/x402-batching/server')
+
+    createProvider({
+      sellerAddress: '0xseller',
+      description: 'Test provider',
+      networks: 'arcTestnet',
+    })
+
+    expect(createGatewayMiddleware).toHaveBeenCalledWith({
+      sellerAddress: '0xseller',
+      description: 'Test provider',
+      networks: 'arcTestnet',
+      facilitatorUrl: undefined,
+    })
+  })
+
+  it('require returns middleware from gateway', () => {
+    const provider = createProvider({ sellerAddress: '0xseller' })
+    const mw = provider.require('$0.01')
+    expect(mockRequire).toHaveBeenCalledWith('$0.01')
+    expect(mw).toBeDefined()
+  })
+
+  it('wraps middleware to call onPayment hook', async () => {
+    const onPayment = vi.fn()
+    const innerMw = vi.fn().mockImplementation((_req: any, _res: any, next: () => void) => {
+      next()
+    })
+    mockRequire.mockReturnValue(innerMw)
+
+    const provider = createProvider({
+      sellerAddress: '0xseller',
+      onPayment,
+    })
+
+    const mw = provider.require('$0.01')
+
+    const req = { payment: { verified: true, payer: '0xpayer', amount: '0.01', network: 'arcTestnet' } }
+    const res = {}
+    const next = vi.fn()
+
+    await mw(req, res, next)
+
+    expect(onPayment).toHaveBeenCalledWith(req.payment)
+    expect(next).toHaveBeenCalled()
+  })
+
+  it('does not wrap middleware when no onPayment hook', () => {
+    const innerMw = vi.fn()
+    mockRequire.mockReturnValue(innerMw)
+
+    const provider = createProvider({ sellerAddress: '0xseller' })
+    const mw = provider.require('$0.01')
+
+    // Without onPayment, it should return the raw middleware
+    expect(mw).toBe(innerMw)
+  })
+
+  it('exposes verify and settle from gateway', () => {
+    const provider = createProvider({ sellerAddress: '0xseller' })
+    expect(provider.verify).toBe(mockVerify)
+    expect(provider.settle).toBe(mockSettle)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}