@buildersgarden/siwa 0.0.17 → 0.0.19

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './receipt.js';
 export * from './erc8128.js';
 export * from './nonce-store.js';
 export * from './tba.js';
+export * from './x402.js';

package/dist/index.js

@@ -9,3 +9,4 @@ export * from './receipt.js';
 export * from './erc8128.js';
 export * from './nonce-store.js';
 export * from './tba.js';
+export * from './x402.js';

package/dist/server-side-wrappers/express.d.ts

@@ -17,11 +17,13 @@
 import type { RequestHandler } from 'express';
 import { type SiwaAgent, type VerifyOptions } from '../erc8128.js';
 import type { SignerType } from '../signer/index.js';
+import { type X402Config, type X402Payment } from '../x402.js';
 export type { SiwaAgent };
 declare global {
     namespace Express {
         interface Request {
             agent?: SiwaAgent;
+            payment?: X402Payment;
             rawBody?: string;
         }
     }
@@ -37,6 +39,8 @@ export interface SiwaMiddlewareOptions {
     publicClient?: VerifyOptions['publicClient'];
     /** Allowed signer types. Omit to accept all. */
     allowedSignerTypes?: SignerType[];
+    /** Optional x402 payment gate. When set, both SIWA auth AND a valid payment are required. */
+    x402?: X402Config;
 }
 export interface SiwaCorsOptions {
     /** Allowed origin(s). Defaults to "*". */
@@ -45,10 +49,14 @@ export interface SiwaCorsOptions {
     methods?: string;
     /** Allowed headers. */
     headers?: string;
+    /** Include x402 payment headers in CORS. */
+    x402?: boolean;
 }
 /**
  * CORS middleware pre-configured with SIWA-specific headers.
  * Handles OPTIONS preflight automatically.
+ *
+ * When `x402: true` is set, also includes x402 payment headers.
  */
 export declare function siwaCors(options?: SiwaCorsOptions): RequestHandler;
 /**
@@ -56,9 +64,16 @@ export declare function siwaCors(options?: SiwaCorsOptions): RequestHandler;
  */
 export declare function siwaJsonParser(): RequestHandler;
 /**
- * Express middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
+ * Express middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt,
+ * with optional x402 payment gate.
+ *
+ * **Without x402** (SIWA only):
+ *   - Valid SIWA headers → `req.agent` → `next()`
+ *   - Missing/invalid → 401
  *
- * On success, sets `req.agent` with the verified agent identity.
- * On failure, responds with 401.
+ * **With x402** (SIWA + payment):
+ *   - SIWA must succeed → otherwise 401
+ *   - Payment must also succeed → otherwise 402 with payment requirements
+ *   - Both succeed → `req.agent` + `req.payment` → `next()`
  */
 export declare function siwaMiddleware(options?: SiwaMiddlewareOptions): RequestHandler;

package/dist/server-side-wrappers/express.js

@@ -16,22 +16,33 @@
  */
 import express from 'express';
 import { verifyAuthenticatedRequest, expressToFetchRequest, resolveReceiptSecret, } from '../erc8128.js';
+import { X402_HEADERS, encodeX402Header, decodeX402Header, processX402Payment, } from '../x402.js';
 // ---------------------------------------------------------------------------
 // CORS middleware
 // ---------------------------------------------------------------------------
 const DEFAULT_SIWA_HEADERS = 'Content-Type, X-SIWA-Receipt, Signature, Signature-Input, Content-Digest';
+const X402_CORS_HEADERS = `${X402_HEADERS.PAYMENT_SIGNATURE}, ${X402_HEADERS.PAYMENT_REQUIRED}`;
+const X402_EXPOSE_HEADERS = `${X402_HEADERS.PAYMENT_REQUIRED}, ${X402_HEADERS.PAYMENT_RESPONSE}`;
 /**
  * CORS middleware pre-configured with SIWA-specific headers.
  * Handles OPTIONS preflight automatically.
+ *
+ * When `x402: true` is set, also includes x402 payment headers.
  */
 export function siwaCors(options) {
     const origin = options?.origin ?? '*';
     const methods = options?.methods ?? 'GET, POST, OPTIONS';
-    const headers = options?.headers ?? DEFAULT_SIWA_HEADERS;
+    let headers = options?.headers ?? DEFAULT_SIWA_HEADERS;
+    if (options?.x402) {
+        headers = `${headers}, ${X402_CORS_HEADERS}`;
+    }
     return (req, res, next) => {
         res.header('Access-Control-Allow-Origin', origin);
         res.header('Access-Control-Allow-Methods', methods);
         res.header('Access-Control-Allow-Headers', headers);
+        if (options?.x402) {
+            res.header('Access-Control-Expose-Headers', X402_EXPOSE_HEADERS);
+        }
         if (req.method === 'OPTIONS') {
             res.sendStatus(204);
             return;
@@ -56,15 +67,25 @@ export function siwaJsonParser() {
 // Auth middleware
 // ---------------------------------------------------------------------------
 /**
- * Express middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
+ * Express middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt,
+ * with optional x402 payment gate.
+ *
+ * **Without x402** (SIWA only):
+ *   - Valid SIWA headers → `req.agent` → `next()`
+ *   - Missing/invalid → 401
  *
- * On success, sets `req.agent` with the verified agent identity.
- * On failure, responds with 401.
+ * **With x402** (SIWA + payment):
+ *   - SIWA must succeed → otherwise 401
+ *   - Payment must also succeed → otherwise 402 with payment requirements
+ *   - Both succeed → `req.agent` + `req.payment` → `next()`
  */
 export function siwaMiddleware(options) {
     return async (req, res, next) => {
-        const hasSignature = req.headers['signature'] && req.headers['x-siwa-receipt'];
-        if (!hasSignature) {
+        // -----------------------------------------------------------------------
+        // Step 1: SIWA ERC-8128 authentication (always required)
+        // -----------------------------------------------------------------------
+        const hasSiwaHeaders = req.headers['signature'] && req.headers['x-siwa-receipt'];
+        if (!hasSiwaHeaders) {
             res.status(401).json({
                 error: 'Unauthorized — provide ERC-8128 Signature + X-SIWA-Receipt headers',
             });
@@ -85,10 +106,64 @@ export function siwaMiddleware(options) {
                 return;
             }
             req.agent = result.agent;
-            next();
         }
         catch (err) {
             res.status(401).json({ error: `ERC-8128 auth failed: ${err.message}` });
+            return;
+        }
+        // -----------------------------------------------------------------------
+        // Step 2: x402 payment (required only when x402 is configured)
+        // -----------------------------------------------------------------------
+        if (options?.x402) {
+            const { x402 } = options;
+            const agentAddress = req.agent.address.toLowerCase();
+            // Step 2a: Check session store (SIWX pay-once mode)
+            if (x402.session) {
+                const existing = await x402.session.store.get(agentAddress, x402.resource.url);
+                if (existing) {
+                    // Active session — skip payment entirely
+                    next();
+                    return;
+                }
+            }
+            const paymentHeader = req.headers[X402_HEADERS.PAYMENT_SIGNATURE.toLowerCase()];
+            if (!paymentHeader) {
+                // No payment header — return 402 with requirements
+                const paymentRequired = {
+                    accepts: x402.accepts,
+                    resource: x402.resource,
+                };
+                res.setHeader(X402_HEADERS.PAYMENT_REQUIRED, encodeX402Header(paymentRequired));
+                res.status(402).json({
+                    error: 'Payment required',
+                    accepts: x402.accepts,
+                    resource: x402.resource,
+                });
+                return;
+            }
+            try {
+                const payload = decodeX402Header(paymentHeader);
+                const result = await processX402Payment(payload, x402.accepts, x402.facilitator);
+                if (!result.valid) {
+                    res.status(402).json({ error: result.error });
+                    return;
+                }
+                const responseHeader = encodeX402Header(result.payment);
+                res.setHeader(X402_HEADERS.PAYMENT_RESPONSE, responseHeader);
+                req.payment = result.payment;
+                // Step 2b: Store session after successful payment (SIWX)
+                if (x402.session) {
+                    await x402.session.store.set(agentAddress, x402.resource.url, { paidAt: Date.now(), txHash: result.payment.txHash }, x402.session.ttl);
+                }
+            }
+            catch (err) {
+                res.status(402).json({ error: `x402 payment processing failed: ${err.message}` });
+                return;
+            }
         }
+        // -----------------------------------------------------------------------
+        // Step 3: All checks passed
+        // -----------------------------------------------------------------------
+        next();
     };
 }

package/dist/server-side-wrappers/fastify.d.ts

@@ -20,10 +20,12 @@
 import type { FastifyPluginAsync, preHandlerHookHandler } from 'fastify';
 import { type SiwaAgent, type VerifyOptions } from '../erc8128.js';
 import type { SignerType } from '../signer/index.js';
-export type { SiwaAgent };
+import { type X402Config, type X402Payment } from '../x402.js';
+export type { SiwaAgent, X402Payment };
 declare module 'fastify' {
     interface FastifyRequest {
         agent?: SiwaAgent;
+        payment?: X402Payment;
     }
 }
 export interface SiwaAuthOptions {
@@ -37,12 +39,16 @@ export interface SiwaAuthOptions {
     publicClient?: VerifyOptions['publicClient'];
     /** Allowed signer types. Omit to accept all. */
     allowedSignerTypes?: SignerType[];
+    /** Optional x402 payment gate. When set, both SIWA auth AND a valid payment are required. */
+    x402?: X402Config;
 }
 export interface SiwaPluginOptions {
     /** CORS allowed origin(s). Defaults to true (reflect origin). */
     origin?: boolean | string | string[];
     /** Allowed headers including SIWA-specific ones. */
     allowedHeaders?: string[];
+    /** Include x402 payment headers in CORS. */
+    x402?: boolean;
 }
 /**
  * Fastify plugin that sets up CORS with SIWA-specific headers.
@@ -53,6 +59,7 @@ export declare const siwaPlugin: FastifyPluginAsync<SiwaPluginOptions>;
  * Fastify preHandler that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
  *
  * On success, sets `req.agent` with the verified agent identity.
- * On failure, responds with 401.
+ * When x402 is configured and payment succeeds, also sets `req.payment`.
+ * On failure, responds with 401 (auth) or 402 (payment).
  */
 export declare function siwaAuth(options?: SiwaAuthOptions): preHandlerHookHandler;

package/dist/server-side-wrappers/fastify.js

@@ -18,6 +18,7 @@
  * ```
  */
 import { verifyAuthenticatedRequest, resolveReceiptSecret, } from '../erc8128.js';
+import { X402_HEADERS, encodeX402Header, decodeX402Header, processX402Payment, } from '../x402.js';
 // ---------------------------------------------------------------------------
 // CORS headers
 // ---------------------------------------------------------------------------
@@ -28,6 +29,14 @@ const DEFAULT_SIWA_HEADERS = [
     'Signature-Input',
     'Content-Digest',
 ];
+const X402_CORS_ALLOW = [
+    X402_HEADERS.PAYMENT_SIGNATURE,
+    X402_HEADERS.PAYMENT_REQUIRED,
+];
+const X402_EXPOSE = [
+    X402_HEADERS.PAYMENT_REQUIRED,
+    X402_HEADERS.PAYMENT_RESPONSE,
+];
 // ---------------------------------------------------------------------------
 // Request conversion helper
 // ---------------------------------------------------------------------------
@@ -35,7 +44,8 @@ const DEFAULT_SIWA_HEADERS = [
  * Convert a Fastify request to a Fetch Request for verification.
  */
 function toFetchRequest(req) {
-    const url = `${req.protocol}://${req.hostname}${req.url}`;
+    // Use req.host (includes port) rather than req.hostname (strips port in Fastify v5)
+    const url = `${req.protocol}://${req.host}${req.url}`;
     return new Request(url, {
         method: req.method,
         headers: req.headers,
@@ -52,12 +62,18 @@ function toFetchRequest(req) {
  * Requires @fastify/cors to be installed.
  */
 export const siwaPlugin = async (fastify, options) => {
+    let allowedHeaders = options?.allowedHeaders ?? DEFAULT_SIWA_HEADERS;
+    if (options?.x402) {
+        allowedHeaders = [...allowedHeaders, ...X402_CORS_ALLOW];
+    }
+    const exposeHeaders = options?.x402 ? X402_EXPOSE : undefined;
     // Try to register @fastify/cors if available
     try {
         const cors = await import('@fastify/cors');
         await fastify.register(cors.default ?? cors, {
             origin: options?.origin ?? true,
-            allowedHeaders: options?.allowedHeaders ?? DEFAULT_SIWA_HEADERS,
+            allowedHeaders,
+            exposedHeaders: exposeHeaders,
         });
     }
     catch {
@@ -65,7 +81,10 @@ export const siwaPlugin = async (fastify, options) => {
         fastify.addHook('onSend', async (req, reply) => {
             reply.header('Access-Control-Allow-Origin', '*');
             reply.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-            reply.header('Access-Control-Allow-Headers', (options?.allowedHeaders ?? DEFAULT_SIWA_HEADERS).join(', '));
+            reply.header('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+            if (exposeHeaders) {
+                reply.header('Access-Control-Expose-Headers', exposeHeaders.join(', '));
+            }
         });
         // Handle OPTIONS preflight
         fastify.options('*', async (req, reply) => {
@@ -80,7 +99,8 @@ export const siwaPlugin = async (fastify, options) => {
  * Fastify preHandler that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
  *
  * On success, sets `req.agent` with the verified agent identity.
- * On failure, responds with 401.
+ * When x402 is configured and payment succeeds, also sets `req.payment`.
+ * On failure, responds with 401 (auth) or 402 (payment).
  */
 export function siwaAuth(options) {
     return async (req, reply) => {
@@ -107,5 +127,51 @@ export function siwaAuth(options) {
         catch (err) {
             return reply.status(401).send({ error: `ERC-8128 auth failed: ${err.message}` });
         }
+        // -----------------------------------------------------------------
+        // x402 payment gate
+        // -----------------------------------------------------------------
+        if (options?.x402) {
+            const { x402 } = options;
+            const agentAddress = req.agent.address.toLowerCase();
+            // Session check
+            if (x402.session) {
+                const existing = await x402.session.store.get(agentAddress, x402.resource.url);
+                if (existing) {
+                    // Active session — skip payment
+                    return;
+                }
+            }
+            // Payment header
+            const paymentHeader = req.headers[X402_HEADERS.PAYMENT_SIGNATURE.toLowerCase()];
+            if (!paymentHeader) {
+                const paymentRequired = {
+                    accepts: x402.accepts,
+                    resource: x402.resource,
+                };
+                reply.header(X402_HEADERS.PAYMENT_REQUIRED, encodeX402Header(paymentRequired));
+                return reply.status(402).send({
+                    error: 'Payment required',
+                    accepts: x402.accepts,
+                    resource: x402.resource,
+                });
+            }
+            // Process payment
+            try {
+                const payload = decodeX402Header(paymentHeader);
+                const payResult = await processX402Payment(payload, x402.accepts, x402.facilitator);
+                if (!payResult.valid) {
+                    return reply.status(402).send({ error: payResult.error });
+                }
+                reply.header(X402_HEADERS.PAYMENT_RESPONSE, encodeX402Header(payResult.payment));
+                req.payment = payResult.payment;
+                // Store session after successful payment
+                if (x402.session) {
+                    await x402.session.store.set(agentAddress, x402.resource.url, { paidAt: Date.now(), txHash: payResult.payment.txHash }, x402.session.ttl);
+                }
+            }
+            catch (err) {
+                return reply.status(402).send({ error: `x402 payment processing failed: ${err.message}` });
+            }
+        }
     };
 }

package/dist/server-side-wrappers/hono.d.ts

@@ -19,7 +19,8 @@
 import type { MiddlewareHandler } from 'hono';
 import { type SiwaAgent, type VerifyOptions } from '../erc8128.js';
 import type { SignerType } from '../signer/index.js';
-export type { SiwaAgent };
+import { type X402Config, type X402Payment } from '../x402.js';
+export type { SiwaAgent, X402Payment };
 export interface SiwaMiddlewareOptions {
     /** HMAC secret for receipt verification. Defaults to RECEIPT_SECRET or SIWA_SECRET env. */
     receiptSecret?: string;
@@ -31,6 +32,8 @@ export interface SiwaMiddlewareOptions {
     publicClient?: VerifyOptions['publicClient'];
     /** Allowed signer types. Omit to accept all. */
     allowedSignerTypes?: SignerType[];
+    /** Optional x402 payment gate. When set, both SIWA auth AND a valid payment are required. */
+    x402?: X402Config;
 }
 export interface SiwaCorsOptions {
     /** Allowed origin(s). Defaults to "*". */
@@ -39,6 +42,8 @@ export interface SiwaCorsOptions {
     methods?: string[];
     /** Allowed headers. */
     headers?: string[];
+    /** Include x402 payment headers in CORS. */
+    x402?: boolean;
 }
 /**
  * CORS middleware pre-configured with SIWA-specific headers.
@@ -49,6 +54,7 @@ export declare function siwaCors(options?: SiwaCorsOptions): MiddlewareHandler;
  * Hono middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
  *
  * On success, sets `c.set("agent", agent)` with the verified agent identity.
- * On failure, responds with 401.
+ * When x402 is configured and payment succeeds, also sets `c.set("payment", payment)`.
+ * On failure, responds with 401 (auth) or 402 (payment).
  */
 export declare function siwaMiddleware(options?: SiwaMiddlewareOptions): MiddlewareHandler;

package/dist/server-side-wrappers/hono.js

@@ -17,6 +17,7 @@
  * ```
  */
 import { verifyAuthenticatedRequest, resolveReceiptSecret, } from '../erc8128.js';
+import { X402_HEADERS, encodeX402Header, decodeX402Header, processX402Payment, } from '../x402.js';
 // ---------------------------------------------------------------------------
 // CORS middleware
 // ---------------------------------------------------------------------------
@@ -27,6 +28,14 @@ const DEFAULT_SIWA_HEADERS = [
     'Signature-Input',
     'Content-Digest',
 ];
+const X402_CORS_ALLOW = [
+    X402_HEADERS.PAYMENT_SIGNATURE,
+    X402_HEADERS.PAYMENT_REQUIRED,
+];
+const X402_EXPOSE = [
+    X402_HEADERS.PAYMENT_REQUIRED,
+    X402_HEADERS.PAYMENT_RESPONSE,
+];
 /**
  * CORS middleware pre-configured with SIWA-specific headers.
  * Handles OPTIONS preflight automatically.
@@ -34,11 +43,17 @@ const DEFAULT_SIWA_HEADERS = [
 export function siwaCors(options) {
     const origin = options?.origin ?? '*';
     const methods = options?.methods ?? ['GET', 'POST', 'OPTIONS'];
-    const headers = options?.headers ?? DEFAULT_SIWA_HEADERS;
+    let headers = options?.headers ?? DEFAULT_SIWA_HEADERS;
+    if (options?.x402) {
+        headers = [...headers, ...X402_CORS_ALLOW];
+    }
     return async (c, next) => {
         c.header('Access-Control-Allow-Origin', origin);
         c.header('Access-Control-Allow-Methods', methods.join(', '));
         c.header('Access-Control-Allow-Headers', headers.join(', '));
+        if (options?.x402) {
+            c.header('Access-Control-Expose-Headers', X402_EXPOSE.join(', '));
+        }
         if (c.req.method === 'OPTIONS') {
             return c.body(null, 204);
         }
@@ -52,7 +67,8 @@ export function siwaCors(options) {
  * Hono middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
  *
  * On success, sets `c.set("agent", agent)` with the verified agent identity.
- * On failure, responds with 401.
+ * When x402 is configured and payment succeeds, also sets `c.set("payment", payment)`.
+ * On failure, responds with 401 (auth) or 402 (payment).
  */
 export function siwaMiddleware(options) {
     return async (c, next) => {
@@ -60,6 +76,7 @@ export function siwaMiddleware(options) {
         if (!hasSignature) {
             return c.json({ error: 'Unauthorized — provide ERC-8128 Signature + X-SIWA-Receipt headers' }, 401);
         }
+        let agent;
         try {
             const secret = resolveReceiptSecret(options?.receiptSecret);
             const result = await verifyAuthenticatedRequest(c.req.raw, {
@@ -72,11 +89,56 @@ export function siwaMiddleware(options) {
             if (!result.valid) {
                 return c.json({ error: result.error }, 401);
             }
-            c.set('agent', result.agent);
-            await next();
+            agent = result.agent;
+            c.set('agent', agent);
         }
         catch (err) {
             return c.json({ error: `ERC-8128 auth failed: ${err.message}` }, 401);
         }
+        // -----------------------------------------------------------------
+        // x402 payment gate
+        // -----------------------------------------------------------------
+        if (options?.x402) {
+            const { x402 } = options;
+            const agentAddress = agent.address.toLowerCase();
+            // Session check
+            if (x402.session) {
+                const existing = await x402.session.store.get(agentAddress, x402.resource.url);
+                if (existing) {
+                    // Active session — skip payment
+                    await next();
+                    return;
+                }
+            }
+            // Payment header
+            const paymentHeader = c.req.header(X402_HEADERS.PAYMENT_SIGNATURE.toLowerCase())
+                ?? c.req.header(X402_HEADERS.PAYMENT_SIGNATURE);
+            if (!paymentHeader) {
+                const paymentRequired = {
+                    accepts: x402.accepts,
+                    resource: x402.resource,
+                };
+                c.header(X402_HEADERS.PAYMENT_REQUIRED, encodeX402Header(paymentRequired));
+                return c.json({ error: 'Payment required', accepts: x402.accepts, resource: x402.resource }, 402);
+            }
+            // Process payment
+            try {
+                const payload = decodeX402Header(paymentHeader);
+                const payResult = await processX402Payment(payload, x402.accepts, x402.facilitator);
+                if (!payResult.valid) {
+                    return c.json({ error: payResult.error }, 402);
+                }
+                c.header(X402_HEADERS.PAYMENT_RESPONSE, encodeX402Header(payResult.payment));
+                c.set('payment', payResult.payment);
+                // Store session after successful payment
+                if (x402.session) {
+                    await x402.session.store.set(agentAddress, x402.resource.url, { paidAt: Date.now(), txHash: payResult.payment.txHash }, x402.session.ttl);
+                }
+            }
+            catch (err) {
+                return c.json({ error: `x402 payment processing failed: ${err.message}` }, 402);
+            }
+        }
+        await next();
     };
 }

package/dist/server-side-wrappers/next.d.ts

@@ -18,7 +18,8 @@
  */
 import { type SiwaAgent } from '../erc8128.js';
 import type { SignerType } from '../signer/index.js';
-export type { SiwaAgent };
+import { type X402Config, type X402Payment } from '../x402.js';
+export type { SiwaAgent, X402Payment };
 export interface WithSiwaOptions {
     /** HMAC secret for receipt verification. Defaults to RECEIPT_SECRET or SIWA_SECRET env. */
     receiptSecret?: string;
@@ -28,16 +29,23 @@ export interface WithSiwaOptions {
     verifyOnchain?: boolean;
     /** Allowed signer types. Omit to accept all. */
     allowedSignerTypes?: SignerType[];
+    /** Optional x402 payment gate. When set, both SIWA auth AND a valid payment are required. */
+    x402?: X402Config;
+}
+export interface CorsOptions {
+    /** Include x402 payment headers in CORS. */
+    x402?: boolean;
 }
 /** CORS headers required by SIWA-authenticated requests. */
-export declare function corsHeaders(): Record<string, string>;
+export declare function corsHeaders(options?: CorsOptions): Record<string, string>;
 /** Return a JSON Response with CORS headers. */
 export declare function corsJson(data: unknown, init?: {
     status?: number;
-}): Response;
+    headers?: Record<string, string>;
+}, corsOpts?: CorsOptions): Response;
 /** Return a 204 OPTIONS response with CORS headers. */
-export declare function siwaOptions(): Response;
-type SiwaHandler = (agent: SiwaAgent, req: Request) => Promise<Record<string, unknown> | Response> | Record<string, unknown> | Response;
+export declare function siwaOptions(corsOpts?: CorsOptions): Response;
+type SiwaHandler = (agent: SiwaAgent, req: Request, payment?: X402Payment) => Promise<Record<string, unknown> | Response> | Record<string, unknown> | Response;
 /**
  * Wrap a Next.js route handler with SIWA ERC-8128 authentication.
  *
@@ -45,5 +53,6 @@ type SiwaHandler = (agent: SiwaAgent, req: Request) => Promise<Record<string, un
  * - Normalizes the request URL for reverse-proxy environments
  * - Returns 401 with CORS headers on auth failure
  * - If the handler returns a plain object, it is auto-wrapped in a JSON Response with CORS headers
+ * - When x402 is configured, requires payment after SIWA auth succeeds
  */
 export declare function withSiwa(handler: SiwaHandler, options?: WithSiwaOptions): (req: Request) => Promise<Response>;

package/dist/server-side-wrappers/next.js

@@ -17,30 +17,43 @@
  * ```
  */
 import { verifyAuthenticatedRequest, nextjsToFetchRequest, resolveReceiptSecret, } from '../erc8128.js';
+import { X402_HEADERS, encodeX402Header, decodeX402Header, processX402Payment, } from '../x402.js';
 // ---------------------------------------------------------------------------
 // CORS helpers
 // ---------------------------------------------------------------------------
+const DEFAULT_SIWA_HEADERS = 'Content-Type, X-SIWA-Receipt, Signature, Signature-Input, Content-Digest';
+const X402_CORS_HEADERS = `${X402_HEADERS.PAYMENT_SIGNATURE}, ${X402_HEADERS.PAYMENT_REQUIRED}`;
+const X402_EXPOSE_HEADERS = `${X402_HEADERS.PAYMENT_REQUIRED}, ${X402_HEADERS.PAYMENT_RESPONSE}`;
 /** CORS headers required by SIWA-authenticated requests. */
-export function corsHeaders() {
-    return {
+export function corsHeaders(options) {
+    let allowHeaders = DEFAULT_SIWA_HEADERS;
+    if (options?.x402) {
+        allowHeaders = `${allowHeaders}, ${X402_CORS_HEADERS}`;
+    }
+    const headers = {
         'Access-Control-Allow-Origin': '*',
         'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-        'Access-Control-Allow-Headers': 'Content-Type, X-SIWA-Receipt, Signature, Signature-Input, Content-Digest',
+        'Access-Control-Allow-Headers': allowHeaders,
     };
+    if (options?.x402) {
+        headers['Access-Control-Expose-Headers'] = X402_EXPOSE_HEADERS;
+    }
+    return headers;
 }
 /** Return a JSON Response with CORS headers. */
-export function corsJson(data, init) {
+export function corsJson(data, init, corsOpts) {
     return new Response(JSON.stringify(data), {
         status: init?.status ?? 200,
         headers: {
             'Content-Type': 'application/json',
-            ...corsHeaders(),
+            ...corsHeaders(corsOpts),
+            ...init?.headers,
         },
     });
 }
 /** Return a 204 OPTIONS response with CORS headers. */
-export function siwaOptions() {
-    return new Response(null, { status: 204, headers: corsHeaders() });
+export function siwaOptions(corsOpts) {
+    return new Response(null, { status: 204, headers: corsHeaders(corsOpts) });
 }
 /**
  * Wrap a Next.js route handler with SIWA ERC-8128 authentication.
@@ -49,8 +62,10 @@ export function siwaOptions() {
  * - Normalizes the request URL for reverse-proxy environments
  * - Returns 401 with CORS headers on auth failure
  * - If the handler returns a plain object, it is auto-wrapped in a JSON Response with CORS headers
+ * - When x402 is configured, requires payment after SIWA auth succeeds
  */
 export function withSiwa(handler, options) {
+    const corsOpts = options?.x402 ? { x402: true } : undefined;
     return async (req) => {
         const secret = resolveReceiptSecret(options?.receiptSecret);
         // Clone for body-consuming methods so handler can still read the body
@@ -64,21 +79,86 @@ export function withSiwa(handler, options) {
         };
         const result = await verifyAuthenticatedRequest(nextjsToFetchRequest(verifyReq), verifyOptions);
         if (!result.valid) {
-            return corsJson({ error: result.error }, { status: 401 });
+            return corsJson({ error: result.error }, { status: 401 }, corsOpts);
         }
-        const response = await handler(result.agent, req);
-        if (response instanceof Response) {
-            // Merge CORS headers into existing response
-            const headers = new Headers(response.headers);
-            for (const [k, v] of Object.entries(corsHeaders())) {
-                headers.set(k, v);
+        // -----------------------------------------------------------------
+        // x402 payment gate
+        // -----------------------------------------------------------------
+        let payment;
+        if (options?.x402) {
+            const { x402 } = options;
+            const agentAddress = result.agent.address.toLowerCase();
+            // Session check
+            if (x402.session) {
+                const existing = await x402.session.store.get(agentAddress, x402.resource.url);
+                if (existing) {
+                    // Active session — skip payment, call handler without payment arg
+                    const response = await handler(result.agent, req);
+                    return wrapResponse(response, corsOpts);
+                }
             }
-            return new Response(response.body, {
-                status: response.status,
-                statusText: response.statusText,
+            // Payment header
+            const paymentHeader = req.headers.get(X402_HEADERS.PAYMENT_SIGNATURE.toLowerCase())
+                ?? req.headers.get(X402_HEADERS.PAYMENT_SIGNATURE);
+            if (!paymentHeader) {
+                const paymentRequired = {
+                    accepts: x402.accepts,
+                    resource: x402.resource,
+                };
+                return corsJson({ error: 'Payment required', accepts: x402.accepts, resource: x402.resource }, {
+                    status: 402,
+                    headers: { [X402_HEADERS.PAYMENT_REQUIRED]: encodeX402Header(paymentRequired) },
+                }, corsOpts);
+            }
+            // Process payment
+            try {
+                const payload = decodeX402Header(paymentHeader);
+                const payResult = await processX402Payment(payload, x402.accepts, x402.facilitator);
+                if (!payResult.valid) {
+                    return corsJson({ error: payResult.error }, { status: 402 }, corsOpts);
+                }
+                payment = payResult.payment;
+                // Store session after successful payment
+                if (x402.session) {
+                    await x402.session.store.set(agentAddress, x402.resource.url, { paidAt: Date.now(), txHash: payResult.payment.txHash }, x402.session.ttl);
+                }
+            }
+            catch (err) {
+                return corsJson({ error: `x402 payment processing failed: ${err.message}` }, { status: 402 }, corsOpts);
+            }
+        }
+        // -----------------------------------------------------------------
+        // Call handler
+        // -----------------------------------------------------------------
+        const response = await handler(result.agent, req, payment);
+        const wrapped = wrapResponse(response, corsOpts);
+        // Add Payment-Response header if payment was processed
+        if (payment) {
+            const headers = new Headers(wrapped.headers);
+            headers.set(X402_HEADERS.PAYMENT_RESPONSE, encodeX402Header(payment));
+            return new Response(wrapped.body, {
+                status: wrapped.status,
+                statusText: wrapped.statusText,
                 headers,
             });
         }
-        return corsJson(response);
+        return wrapped;
     };
 }
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function wrapResponse(response, corsOpts) {
+    if (response instanceof Response) {
+        const headers = new Headers(response.headers);
+        for (const [k, v] of Object.entries(corsHeaders(corsOpts))) {
+            headers.set(k, v);
+        }
+        return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+        });
+    }
+    return corsJson(response, undefined, corsOpts);
+}

package/dist/x402.d.ts

@@ -0,0 +1,140 @@
+/**
+ * x402.ts
+ *
+ * Framework-agnostic x402 payment protocol integration.
+ *
+ * Provides types, header constants, base64 encode/decode helpers,
+ * a facilitator HTTP client, and a high-level processX402Payment function.
+ *
+ * No framework imports. No `@x402/*` dependency — the facilitator API
+ * is just 2 HTTP POSTs (verify + settle).
+ */
+export declare const X402_HEADERS: {
+    readonly PAYMENT_REQUIRED: "Payment-Required";
+    readonly PAYMENT_SIGNATURE: "Payment-Signature";
+    readonly PAYMENT_RESPONSE: "Payment-Response";
+};
+/** Network identifier (e.g. "eip155:84532") */
+export type Network = string;
+/** Resource being paid for */
+export interface ResourceInfo {
+    url: string;
+    description?: string;
+}
+/** A single payment option the server accepts */
+export interface PaymentRequirements {
+    scheme: string;
+    network: Network;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds?: number;
+}
+/** Full 402 response payload (base64-encoded in header) */
+export interface PaymentRequired {
+    accepts: PaymentRequirements[];
+    resource: ResourceInfo;
+}
+/** Client-side payment payload (base64-encoded in header) */
+export interface PaymentPayload {
+    signature: string;
+    payment: {
+        scheme: string;
+        network: Network;
+        amount: string;
+        asset: string;
+        payTo: string;
+        nonce?: string;
+    };
+    resource: ResourceInfo;
+}
+/** Facilitator verify response */
+export interface VerifyResponse {
+    valid: boolean;
+    reason?: string;
+}
+/** Facilitator settle response */
+export interface SettleResponse {
+    success: boolean;
+    txHash?: string;
+    reason?: string;
+}
+/** Result of processing an x402 payment */
+export type X402Result = {
+    valid: true;
+    payment: X402Payment;
+} | {
+    valid: false;
+    error: string;
+};
+/** Verified payment info attached to the request */
+export interface X402Payment {
+    scheme: string;
+    network: Network;
+    amount: string;
+    asset: string;
+    payTo: string;
+    txHash?: string;
+}
+/** Facilitator client with verify + settle methods */
+export interface FacilitatorClient {
+    verify(payload: PaymentPayload, requirements: PaymentRequirements[]): Promise<VerifyResponse>;
+    settle(payload: PaymentPayload, requirements: PaymentRequirements[]): Promise<SettleResponse>;
+}
+/** Stored session data for a paid agent */
+export interface X402Session {
+    paidAt: number;
+    txHash?: string;
+}
+/** Pluggable session store keyed by (address, resource) */
+export interface X402SessionStore {
+    get(address: string, resource: string): Promise<X402Session | null>;
+    set(address: string, resource: string, session: X402Session, ttlMs: number): Promise<void>;
+}
+/** Session configuration for SIWX pay-once mode */
+export interface X402SessionConfig {
+    store: X402SessionStore;
+    /** Session TTL in milliseconds */
+    ttl: number;
+}
+/** x402 configuration for middleware */
+export interface X402Config {
+    facilitator: FacilitatorClient;
+    resource: ResourceInfo;
+    accepts: PaymentRequirements[];
+    /** Enable SIWX pay-once sessions. When set, payment is only required on first request. */
+    session?: X402SessionConfig;
+}
+/**
+ * Encode data as a base64 JSON string for use in HTTP headers.
+ */
+export declare function encodeX402Header(data: unknown): string;
+/**
+ * Decode a base64 JSON header value.
+ */
+export declare function decodeX402Header<T = unknown>(header: string): T;
+/**
+ * Create a facilitator client that communicates via HTTP.
+ *
+ * The x402 facilitator exposes two endpoints:
+ *   - POST /verify — validates a payment signature
+ *   - POST /settle — settles the payment on-chain
+ */
+export declare function createFacilitatorClient(options: {
+    url: string;
+}): FacilitatorClient;
+/**
+ * In-memory X402 session store with TTL-based expiry.
+ *
+ * Suitable for single-process servers. For multi-instance deployments,
+ * implement X402SessionStore with a shared store (Redis, database, etc.).
+ */
+export declare function createMemoryX402SessionStore(): X402SessionStore;
+/**
+ * Verify and settle an x402 payment in one call.
+ *
+ * 1. Calls facilitator.verify() to validate the payment signature
+ * 2. If valid, calls facilitator.settle() to execute the on-chain transfer
+ * 3. Returns the payment details with transaction hash
+ */
+export declare function processX402Payment(payload: PaymentPayload, accepts: PaymentRequirements[], facilitator: FacilitatorClient): Promise<X402Result>;

package/dist/x402.js

@@ -0,0 +1,161 @@
+/**
+ * x402.ts
+ *
+ * Framework-agnostic x402 payment protocol integration.
+ *
+ * Provides types, header constants, base64 encode/decode helpers,
+ * a facilitator HTTP client, and a high-level processX402Payment function.
+ *
+ * No framework imports. No `@x402/*` dependency — the facilitator API
+ * is just 2 HTTP POSTs (verify + settle).
+ */
+// ---------------------------------------------------------------------------
+// Header constants
+// ---------------------------------------------------------------------------
+export const X402_HEADERS = {
+    PAYMENT_REQUIRED: 'Payment-Required',
+    PAYMENT_SIGNATURE: 'Payment-Signature',
+    PAYMENT_RESPONSE: 'Payment-Response',
+};
+// ---------------------------------------------------------------------------
+// Base64 JSON encode / decode
+// ---------------------------------------------------------------------------
+/**
+ * Encode data as a base64 JSON string for use in HTTP headers.
+ */
+export function encodeX402Header(data) {
+    const json = JSON.stringify(data);
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(json).toString('base64');
+    }
+    return btoa(json);
+}
+/**
+ * Decode a base64 JSON header value.
+ */
+export function decodeX402Header(header) {
+    let json;
+    if (typeof Buffer !== 'undefined') {
+        json = Buffer.from(header, 'base64').toString('utf-8');
+    }
+    else {
+        json = atob(header);
+    }
+    return JSON.parse(json);
+}
+// ---------------------------------------------------------------------------
+// Facilitator client
+// ---------------------------------------------------------------------------
+/**
+ * Create a facilitator client that communicates via HTTP.
+ *
+ * The x402 facilitator exposes two endpoints:
+ *   - POST /verify — validates a payment signature
+ *   - POST /settle — settles the payment on-chain
+ */
+export function createFacilitatorClient(options) {
+    const baseUrl = options.url.replace(/\/+$/, '');
+    return {
+        async verify(payload, requirements) {
+            const res = await fetch(`${baseUrl}/verify`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ payload, requirements }),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => res.statusText);
+                throw new Error(`Facilitator verify failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        async settle(payload, requirements) {
+            const res = await fetch(`${baseUrl}/settle`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ payload, requirements }),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => res.statusText);
+                throw new Error(`Facilitator settle failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Session store — in-memory
+// ---------------------------------------------------------------------------
+/**
+ * In-memory X402 session store with TTL-based expiry.
+ *
+ * Suitable for single-process servers. For multi-instance deployments,
+ * implement X402SessionStore with a shared store (Redis, database, etc.).
+ */
+export function createMemoryX402SessionStore() {
+    const sessions = new Map();
+    function cleanup() {
+        const now = Date.now();
+        for (const [k, v] of sessions) {
+            if (v.expiry < now)
+                sessions.delete(k);
+        }
+    }
+    return {
+        async get(address, resource) {
+            cleanup();
+            const key = `${address}:${resource}`;
+            const entry = sessions.get(key);
+            if (!entry)
+                return null;
+            if (entry.expiry < Date.now()) {
+                sessions.delete(key);
+                return null;
+            }
+            return entry.session;
+        },
+        async set(address, resource, session, ttlMs) {
+            cleanup();
+            const key = `${address}:${resource}`;
+            sessions.set(key, { session, expiry: Date.now() + ttlMs });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Payment processing
+// ---------------------------------------------------------------------------
+/**
+ * Verify and settle an x402 payment in one call.
+ *
+ * 1. Calls facilitator.verify() to validate the payment signature
+ * 2. If valid, calls facilitator.settle() to execute the on-chain transfer
+ * 3. Returns the payment details with transaction hash
+ */
+export async function processX402Payment(payload, accepts, facilitator) {
+    // 1. Verify the payment signature
+    const verifyResult = await facilitator.verify(payload, accepts);
+    if (!verifyResult.valid) {
+        return {
+            valid: false,
+            error: `Payment verification failed: ${verifyResult.reason ?? 'unknown'}`,
+        };
+    }
+    // 2. Settle the payment on-chain
+    const settleResult = await facilitator.settle(payload, accepts);
+    if (!settleResult.success) {
+        return {
+            valid: false,
+            error: `Payment settlement failed: ${settleResult.reason ?? 'unknown'}`,
+        };
+    }
+    return {
+        valid: true,
+        payment: {
+            scheme: payload.payment.scheme,
+            network: payload.payment.network,
+            amount: payload.payment.amount,
+            asset: payload.payment.asset,
+            payTo: payload.payment.payTo,
+            txHash: settleResult.txHash,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildersgarden/siwa",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "exports": {
     ".": {
@@ -66,6 +66,10 @@
     "./tba": {
       "types": "./dist/tba.d.ts",
       "default": "./dist/tba.js"
+    },
+    "./x402": {
+      "types": "./dist/x402.d.ts",
+      "default": "./dist/x402.js"
     }
   },
   "main": "./dist/index.js",