@4mica/x402 0.1.0 → 1.0.1

package/demo/README.md

@@ -32,7 +32,7 @@ cp .env.example .env
 
 Required variables:
 - `PRIVATE_KEY`: Your Ethereum private key (with 0x prefix) for Sepolia testnet
-- `PAY_TO_ADDRESS`: Address that will receive payments (optional, defaults to a test address)
+- `PAY_TO_ADDRESS`: Address that will receive payments
 
 ## Running the Demo
 
@@ -54,7 +54,7 @@ You should see:
 ```
 x402 Demo Server running on http://localhost:3000
 Protected endpoint: http://localhost:3000/api/premium-data
-Payment required: $0.05 (4mica credit on Sepolia)
+Payment required: $0.01 (4mica credit on Sepolia)
 ```
 
 ### Terminal 2: Run the client
@@ -82,7 +82,7 @@ PRIVATE_KEY=0xYourPrivateKey yarn client
 ## What Happens
 
 1. **Server** starts with one protected endpoint: `GET /api/premium-data`
-   - Requires a payment of $0.05 in 4mica credits on Sepolia
+   - Requires a payment of $0.01 in 4mica credits on Sepolia
    - Uses x402 payment protocol
 
 2. **Client** makes a request to the protected endpoint:

package/demo/package.json

@@ -10,7 +10,7 @@
     "dev": "tsx watch src/server.ts"
   },
   "dependencies": {
-    "@4mica/sdk": "file:../../../../../ts-sdk-4mica",
+    "@4mica/sdk": "^0.5.3",
     "@4mica/x402": "file:..",
     "@x402/fetch": "^2.2.0",
     "dotenv": "^16.4.7",

package/demo/src/deposit.ts

@@ -2,8 +2,6 @@ import 'dotenv/config'
 import { privateKeyToAccount } from 'viem/accounts'
 import { Client, ConfigBuilder } from '@4mica/sdk'
 
-const USDC_ADDRESS = '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238'
-
 async function main() {
   const privateKey = process.env.PRIVATE_KEY
   if (!privateKey || !privateKey.startsWith('0x')) {

package/dist/client/scheme.js

@@ -49,9 +49,21 @@ export class FourMicaEvmScheme {
             };
         }
         else if (x402Version === 2) {
+            const resourcePayload = paymentRequirements.extra &&
+                typeof paymentRequirements.extra === 'object' &&
+                'resource' in paymentRequirements.extra &&
+                typeof paymentRequirements.extra.resource === 'object' &&
+                paymentRequirements.extra.resource !== null
+                ? paymentRequirements.extra.resource
+                : {};
+            const resource = {
+                url: String(resourcePayload.url ?? ''),
+                description: String(resourcePayload.description ?? ''),
+                mimeType: String(resourcePayload.mimeType ?? ''),
+            };
             const paymentRequired = {
                 x402Version: 2,
-                resource: { url: '', description: '', mimeType: '' },
+                resource,
                 accepts: [paymentRequirements],
             };
             const signed = await x402Flow.signPaymentV2(paymentRequired, paymentRequirements, this.signer.address);

package/dist/server/express/index.js

@@ -2,11 +2,14 @@ import { x402HTTPResourceServer, x402ResourceServer, } from '@x402/core/server';
 import { ExpressAdapter } from './adapter.js';
 import { FourMicaEvmScheme, SUPPORTED_NETWORKS } from '../scheme.js';
 import { FourMicaFacilitatorClient } from '../facilitator.js';
+function getHTTPServerInternals(httpServer) {
+    return httpServer;
+}
 function registerNetworkServers(httpServer, tabEndpoint) {
     const schemeServer = new FourMicaEvmScheme(tabEndpoint);
+    const server = getHTTPServerInternals(httpServer);
     SUPPORTED_NETWORKS.forEach((network) => {
-        ;
-        httpServer.ResourceServer.register(network, schemeServer);
+        server.ResourceServer.register(network, schemeServer);
     });
 }
 function checkIfBazaarNeeded(routes) {
@@ -17,6 +20,13 @@ function checkIfBazaarNeeded(routes) {
         return !!(routeConfig.extensions && 'bazaar' in routeConfig.extensions);
     });
 }
+function isOpenTabHttpError(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    const candidate = error;
+    return typeof candidate.status === 'number' && 'response' in candidate;
+}
 /**
  * Express payment middleware for x402 protocol (direct HTTP server instance).
  *
@@ -57,12 +67,12 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
     // Dynamically register bazaar extension if routes declare it and not already registered
     // Skip if pre-registered (e.g., in serverless environments where static imports are used)
     let bazaarPromise = null;
-    if (checkIfBazaarNeeded(httpServer.routesConfig) &&
-        !httpServer.ResourceServer.hasExtension('bazaar')) {
+    const httpServerInternals = getHTTPServerInternals(httpServer);
+    if (checkIfBazaarNeeded(httpServerInternals.routesConfig) &&
+        !httpServerInternals.ResourceServer.hasExtension('bazaar')) {
         bazaarPromise = import('@x402/extensions/bazaar')
             .then(({ bazaarResourceServerExtension }) => {
-            ;
-            httpServer.ResourceServer.registerExtension(bazaarResourceServerExtension);
+            httpServerInternals.ResourceServer.registerExtension(bazaarResourceServerExtension);
         })
             .catch((err) => {
             console.error('Failed to load bazaar extension:', err);
@@ -82,9 +92,8 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
                     return res.json(openTabResponse);
                 }
                 catch (error) {
-                    if (error instanceof Error && 'status' in error) {
-                        const openTabError = error;
-                        return res.status(openTabError.status).json(openTabError.response);
+                    if (isOpenTabHttpError(error)) {
+                        return res.status(error.status).json(error.response);
                     }
                     console.error('Failed to open tab:', error);
                     return res.status(500).json({
@@ -126,7 +135,7 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
             case 'no-payment-required':
                 // No payment needed, proceed directly to the route handler
                 return next();
-            case 'payment-error':
+            case 'payment-error': {
                 // Payment required but not provided or invalid
                 const { response } = result;
                 res.status(response.status);
@@ -140,7 +149,8 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
                     res.json(response.body || {});
                 }
                 return;
-            case 'payment-verified':
+            }
+            case 'payment-verified': {
                 // Payment is valid, need to wrap response for settlement
                 const { paymentPayload, paymentRequirements } = result;
                 // Intercept and buffer all core methods that can commit response to client
@@ -256,6 +266,7 @@ export function paymentMiddlewareFromHTTPServer(httpServer, tabConfig, paywallCo
                     bufferedCalls = [];
                 }
                 return;
+            }
         }
     };
 }

package/dist/server/facilitator.d.ts

@@ -1,5 +1,5 @@
 import { FacilitatorConfig, HTTPFacilitatorClient } from '@x402/core/server';
-import { Network, PaymentRequirements } from '@x402/core/types';
+import { Network, PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
 export interface OpenTabRequest {
     userAddress: string;
     recipientAddress: string;
@@ -16,6 +16,16 @@ export interface OpenTabResponse {
     ttlSeconds: number;
     nextReqId: string;
 }
+export interface CertificateResponse {
+    claims: string;
+    signature: string;
+}
+export type FourMicaSettleResponse = SettleResponse & {
+    certificate?: CertificateResponse;
+    txHash?: string;
+    networkId?: string;
+    error?: string;
+};
 export declare class OpenTabError extends Error {
     readonly status: number;
     readonly response: OpenTabResponse;
@@ -24,6 +34,7 @@ export declare class OpenTabError extends Error {
 export declare class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
     constructor(config?: FacilitatorConfig);
     openTab(userAddress: string, paymentRequirements: PaymentRequirements, ttlSeconds?: number): Promise<OpenTabResponse>;
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<FourMicaSettleResponse>;
     /**
      * Helper to convert objects to JSON-safe format.
      * Handles BigInt and other non-JSON types.

package/dist/server/facilitator.js

@@ -39,6 +39,28 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
         }
         throw new Error(`Facilitator openTab failed (${response.status}): ${JSON.stringify(data)}`);
     }
+    async settle(paymentPayload, paymentRequirements) {
+        let headers = {
+            'Content-Type': 'application/json',
+        };
+        const authHeaders = await this.createAuthHeaders('settle');
+        headers = { ...headers, ...authHeaders.headers };
+        const response = await fetch(`${this.url}/settle`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(this.safeJson({
+                x402Version: paymentPayload.x402Version,
+                paymentPayload,
+                paymentRequirements,
+            })),
+        });
+        const data = (await response.json());
+        const normalized = normalizeSettleResponse(data, paymentRequirements);
+        if (!response.ok || !normalized.success) {
+            throw new Error(`Facilitator settle failed (${response.status}): ${normalized.errorReason ?? normalized.error ?? 'unknown error'}`);
+        }
+        return normalized;
+    }
     /**
      * Helper to convert objects to JSON-safe format.
      * Handles BigInt and other non-JSON types.
@@ -50,3 +72,55 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
         return JSON.parse(JSON.stringify(obj, (_, value) => (typeof value === 'bigint' ? value.toString() : value)));
     }
 }
+function normalizeSettleResponse(payload, requirements) {
+    const transaction = String(payload.transaction ??
+        payload.transactionHash ??
+        payload.txHash ??
+        payload.tx_hash ??
+        payload.hash ??
+        '');
+    const network = String(payload.network ?? payload.networkId ?? payload.network_id ?? requirements.network);
+    const errorReason = typeof payload.errorReason === 'string'
+        ? payload.errorReason
+        : typeof payload.error_reason === 'string'
+            ? payload.error_reason
+            : typeof payload.error === 'string'
+                ? payload.error
+                : typeof payload.message === 'string'
+                    ? payload.message
+                    : undefined;
+    const certificate = payload.certificate &&
+        typeof payload.certificate === 'object' &&
+        typeof payload.certificate.claims === 'string' &&
+        typeof payload.certificate.signature === 'string'
+        ? {
+            claims: payload.certificate.claims,
+            signature: payload.certificate.signature,
+        }
+        : undefined;
+    return {
+        success: Boolean(payload.success ?? errorReason === undefined),
+        errorReason,
+        payer: typeof payload.payer === 'string'
+            ? payload.payer
+            : typeof payload.userAddress === 'string'
+                ? payload.userAddress
+                : typeof payload.user_address === 'string'
+                    ? payload.user_address
+                    : undefined,
+        transaction,
+        network,
+        certificate,
+        txHash: typeof payload.txHash === 'string'
+            ? payload.txHash
+            : typeof payload.tx_hash === 'string'
+                ? payload.tx_hash
+                : transaction || undefined,
+        networkId: typeof payload.networkId === 'string'
+            ? payload.networkId
+            : typeof payload.network_id === 'string'
+                ? payload.network_id
+                : network,
+        error: typeof payload.error === 'string' ? payload.error : undefined,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4mica/x402",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "TypeScript x402 utilities for interacting with the 4Mica payment network",
   "license": "MIT",

package/src/client/scheme.ts

@@ -5,6 +5,7 @@ import {
   PaymentRequirementsV1,
   X402Flow,
   X402PaymentRequired,
+  X402ResourceInfo,
 } from '@4mica/sdk'
 import { Account } from 'viem/accounts'
 import { SUPPORTED_NETWORKS } from '../server/scheme.js'
@@ -73,9 +74,23 @@ export class FourMicaEvmScheme implements SchemeNetworkClient {
         payload: signed.payload as unknown as Record<string, unknown>,
       }
     } else if (x402Version === 2) {
+      const resourcePayload =
+        paymentRequirements.extra &&
+        typeof paymentRequirements.extra === 'object' &&
+        'resource' in paymentRequirements.extra &&
+        typeof paymentRequirements.extra.resource === 'object' &&
+        paymentRequirements.extra.resource !== null
+          ? (paymentRequirements.extra.resource as Record<string, unknown>)
+          : {}
+
+      const resource: X402ResourceInfo = {
+        url: String(resourcePayload.url ?? ''),
+        description: String(resourcePayload.description ?? ''),
+        mimeType: String(resourcePayload.mimeType ?? ''),
+      }
       const paymentRequired: X402PaymentRequired = {
         x402Version: 2,
-        resource: { url: '', description: '', mimeType: '' },
+        resource,
         accepts: [paymentRequirements],
       }
       const signed = await x402Flow.signPaymentV2(

package/src/server/express/index.ts

@@ -36,10 +36,26 @@ interface TabConfig {
   ttlSeconds?: number
 }
 
+interface ResourceServerInternals {
+  register: (network: Network, server: SchemeNetworkServer) => unknown
+  hasExtension: (extension: string) => boolean
+  registerExtension: (extension: unknown) => unknown
+}
+
+interface HTTPServerInternals {
+  ResourceServer: ResourceServerInternals
+  routesConfig: RoutesConfig
+}
+
+function getHTTPServerInternals(httpServer: x402HTTPResourceServer): HTTPServerInternals {
+  return httpServer as unknown as HTTPServerInternals
+}
+
 function registerNetworkServers(httpServer: x402HTTPResourceServer, tabEndpoint: string) {
   const schemeServer = new FourMicaEvmScheme(tabEndpoint)
+  const server = getHTTPServerInternals(httpServer)
   SUPPORTED_NETWORKS.forEach((network) => {
-    ;(httpServer as any).ResourceServer.register(network, schemeServer)
+    server.ResourceServer.register(network, schemeServer)
   })
 }
 
@@ -53,6 +69,20 @@ function checkIfBazaarNeeded(routes: RoutesConfig): boolean {
   })
 }
 
+interface OpenTabHttpError {
+  status: number
+  response: unknown
+}
+
+function isOpenTabHttpError(error: unknown): error is OpenTabHttpError {
+  if (typeof error !== 'object' || error === null) {
+    return false
+  }
+
+  const candidate = error as { status?: unknown; response?: unknown }
+  return typeof candidate.status === 'number' && 'response' in candidate
+}
+
 /**
  * Configuration for registering a payment scheme with a specific network
  */
@@ -118,13 +148,14 @@ export function paymentMiddlewareFromHTTPServer(
   // Dynamically register bazaar extension if routes declare it and not already registered
   // Skip if pre-registered (e.g., in serverless environments where static imports are used)
   let bazaarPromise: Promise<void> | null = null
+  const httpServerInternals = getHTTPServerInternals(httpServer)
   if (
-    checkIfBazaarNeeded((httpServer as any).routesConfig) &&
-    !(httpServer as any).ResourceServer.hasExtension('bazaar')
+    checkIfBazaarNeeded(httpServerInternals.routesConfig) &&
+    !httpServerInternals.ResourceServer.hasExtension('bazaar')
   ) {
     bazaarPromise = import('@x402/extensions/bazaar')
       .then(({ bazaarResourceServerExtension }) => {
-        ;(httpServer as any).ResourceServer.registerExtension(bazaarResourceServerExtension)
+        httpServerInternals.ResourceServer.registerExtension(bazaarResourceServerExtension)
       })
       .catch((err) => {
         console.error('Failed to load bazaar extension:', err)
@@ -150,9 +181,8 @@ export function paymentMiddlewareFromHTTPServer(
           // Return the response
           return res.json(openTabResponse)
         } catch (error) {
-          if (error instanceof Error && 'status' in error) {
-            const openTabError = error as any
-            return res.status(openTabError.status).json(openTabError.response)
+          if (isOpenTabHttpError(error)) {
+            return res.status(error.status).json(error.response)
           }
           console.error('Failed to open tab:', error)
           return res.status(500).json({
@@ -200,7 +230,7 @@ export function paymentMiddlewareFromHTTPServer(
         // No payment needed, proceed directly to the route handler
         return next()
 
-      case 'payment-error':
+      case 'payment-error': {
         // Payment required but not provided or invalid
         const { response } = result
         res.status(response.status)
@@ -213,8 +243,9 @@ export function paymentMiddlewareFromHTTPServer(
           res.json(response.body || {})
         }
         return
+      }
 
-      case 'payment-verified':
+      case 'payment-verified': {
         // Payment is valid, need to wrap response for settlement
         const { paymentPayload, paymentRequirements } = result
 
@@ -346,6 +377,7 @@ export function paymentMiddlewareFromHTTPServer(
           bufferedCalls = []
         }
         return
+      }
     }
   }
 }

package/src/server/facilitator.ts

@@ -1,5 +1,5 @@
 import { FacilitatorConfig, HTTPFacilitatorClient } from '@x402/core/server'
-import { Network, PaymentRequirements } from '@x402/core/types'
+import { Network, PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types'
 
 const DEFAULT_FACILITATOR_URL = 'https://x402.4mica.xyz'
 
@@ -21,6 +21,18 @@ export interface OpenTabResponse {
   nextReqId: string
 }
 
+export interface CertificateResponse {
+  claims: string
+  signature: string
+}
+
+export type FourMicaSettleResponse = SettleResponse & {
+  certificate?: CertificateResponse
+  txHash?: string
+  networkId?: string
+  error?: string
+}
+
 export class OpenTabError extends Error {
   constructor(
     public readonly status: number,
@@ -75,6 +87,41 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
     throw new Error(`Facilitator openTab failed (${response.status}): ${JSON.stringify(data)}`)
   }
 
+  async settle(
+    paymentPayload: PaymentPayload,
+    paymentRequirements: PaymentRequirements
+  ): Promise<FourMicaSettleResponse> {
+    let headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+
+    const authHeaders = await this.createAuthHeaders('settle')
+    headers = { ...headers, ...authHeaders.headers }
+
+    const response = await fetch(`${this.url}/settle`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(
+        this.safeJson({
+          x402Version: paymentPayload.x402Version,
+          paymentPayload,
+          paymentRequirements,
+        })
+      ),
+    })
+
+    const data = (await response.json()) as Record<string, unknown>
+    const normalized = normalizeSettleResponse(data, paymentRequirements)
+
+    if (!response.ok || !normalized.success) {
+      throw new Error(
+        `Facilitator settle failed (${response.status}): ${normalized.errorReason ?? normalized.error ?? 'unknown error'}`
+      )
+    }
+
+    return normalized
+  }
+
   /**
    * Helper to convert objects to JSON-safe format.
    * Handles BigInt and other non-JSON types.
@@ -88,3 +135,70 @@ export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
     )
   }
 }
+
+function normalizeSettleResponse(
+  payload: Record<string, unknown>,
+  requirements: PaymentRequirements
+): FourMicaSettleResponse {
+  const transaction = String(
+    payload.transaction ??
+      payload.transactionHash ??
+      payload.txHash ??
+      payload.tx_hash ??
+      payload.hash ??
+      ''
+  )
+  const network = String(
+    payload.network ?? payload.networkId ?? payload.network_id ?? requirements.network
+  ) as Network
+  const errorReason =
+    typeof payload.errorReason === 'string'
+      ? payload.errorReason
+      : typeof payload.error_reason === 'string'
+        ? payload.error_reason
+        : typeof payload.error === 'string'
+          ? payload.error
+          : typeof payload.message === 'string'
+            ? payload.message
+            : undefined
+
+  const certificate =
+    payload.certificate &&
+    typeof payload.certificate === 'object' &&
+    typeof (payload.certificate as Record<string, unknown>).claims === 'string' &&
+    typeof (payload.certificate as Record<string, unknown>).signature === 'string'
+      ? {
+          claims: (payload.certificate as Record<string, string>).claims,
+          signature: (payload.certificate as Record<string, string>).signature,
+        }
+      : undefined
+
+  return {
+    success: Boolean(payload.success ?? errorReason === undefined),
+    errorReason,
+    payer:
+      typeof payload.payer === 'string'
+        ? payload.payer
+        : typeof payload.userAddress === 'string'
+          ? payload.userAddress
+          : typeof payload.user_address === 'string'
+            ? payload.user_address
+            : undefined,
+    transaction,
+    network,
+    certificate,
+    txHash:
+      typeof payload.txHash === 'string'
+        ? payload.txHash
+        : typeof payload.tx_hash === 'string'
+          ? payload.tx_hash
+          : transaction || undefined,
+    networkId:
+      typeof payload.networkId === 'string'
+        ? payload.networkId
+        : typeof payload.network_id === 'string'
+          ? payload.network_id
+          : network,
+    error: typeof payload.error === 'string' ? payload.error : undefined,
+  }
+}

package/tests/client-scheme.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { privateKeyToAccount } from 'viem/accounts'
+
+import { FourMicaEvmScheme } from '../src/client/scheme.js'
+
+describe('FourMicaEvmScheme', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('passes V2 resource metadata through to the SDK flow', async () => {
+    const signPaymentV2 = vi.fn().mockResolvedValue({
+      payload: {
+        claims: {
+          version: 'v2',
+          validation_request_hash: '0x' + '11'.repeat(32),
+          validation_subject_hash: '0x' + '22'.repeat(32),
+        },
+      },
+    })
+
+    vi.spyOn(FourMicaEvmScheme as never, 'createX402Flow' as never).mockResolvedValue({
+      signPayment: vi.fn(),
+      signPaymentV2,
+    } as never)
+
+    const scheme = await FourMicaEvmScheme.create(privateKeyToAccount(`0x${'11'.repeat(32)}`))
+
+    const requirements = {
+      scheme: '4mica-credit',
+      network: 'eip155:11155111',
+      asset: '0x2222222222222222222222222222222222222222',
+      amount: '10',
+      payTo: '0x1111111111111111111111111111111111111111',
+      extra: {
+        rpcUrl: 'https://custom.rpc.example',
+        validationRegistryAddress: '0x3333333333333333333333333333333333333333',
+        validatorAddress: '0x4444444444444444444444444444444444444444',
+        validatorAgentId: '7',
+        minValidationScore: 80,
+        requiredValidationTag: 'hard-finality',
+        resource: {
+          url: 'https://api.example.com/premium',
+          description: 'Premium dataset',
+          mimeType: 'application/json',
+        },
+      },
+    }
+
+    const result = await scheme.createPaymentPayload(2, requirements as never)
+
+    expect(result.x402Version).toBe(2)
+    expect(signPaymentV2).toHaveBeenCalledTimes(1)
+
+    const paymentRequired = signPaymentV2.mock.calls[0]?.[0]
+    expect(paymentRequired.resource).toEqual({
+      url: 'https://api.example.com/premium',
+      description: 'Premium dataset',
+      mimeType: 'application/json',
+    })
+
+    const accepted = signPaymentV2.mock.calls[0]?.[1]
+    expect(accepted).toMatchObject({
+      scheme: '4mica-credit',
+      network: 'eip155:11155111',
+      asset: '0x2222222222222222222222222222222222222222',
+      amount: '10',
+      payTo: '0x1111111111111111111111111111111111111111',
+    })
+    expect(accepted.extra).toMatchObject({
+      validationRegistryAddress: '0x3333333333333333333333333333333333333333',
+      validatorAddress: '0x4444444444444444444444444444444444444444',
+      validatorAgentId: '7',
+      minValidationScore: 80,
+      requiredValidationTag: 'hard-finality',
+    })
+  })
+
+  it('rejects unsupported x402 versions', async () => {
+    vi.spyOn(FourMicaEvmScheme as never, 'createX402Flow' as never).mockResolvedValue({
+      signPayment: vi.fn(),
+      signPaymentV2: vi.fn(),
+    } as never)
+
+    const scheme = await FourMicaEvmScheme.create(privateKeyToAccount(`0x${'11'.repeat(32)}`))
+
+    await expect(
+      scheme.createPaymentPayload(3, {
+        scheme: '4mica-credit',
+        network: 'eip155:11155111',
+        asset: '0x2222222222222222222222222222222222222222',
+        amount: '10',
+        payTo: '0x1111111111111111111111111111111111111111',
+      } as never)
+    ).rejects.toThrow('Unsupported x402Version: 3')
+  })
+})

package/tests/facilitator.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { FourMicaFacilitatorClient } from '../src/server/facilitator.js'
+
+describe('FourMicaFacilitatorClient', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  it('normalizes 4mica settle responses and preserves certificate fields', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          success: true,
+          txHash: '0xdeadbeef',
+          networkId: 'eip155:11155111',
+          certificate: {
+            claims: '0x' + '11'.repeat(32),
+            signature: '0x' + '22'.repeat(96),
+          },
+        }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      )
+    )
+
+    vi.stubGlobal('fetch', fetchMock)
+
+    const client = new FourMicaFacilitatorClient({ url: 'https://facilitator.example' })
+
+    const result = await client.settle(
+      {
+        x402Version: 2,
+        accepted: {
+          scheme: '4mica-credit',
+          network: 'eip155:11155111',
+          asset: '0x2222222222222222222222222222222222222222',
+          amount: '10',
+          payTo: '0x1111111111111111111111111111111111111111',
+        },
+        payload: {
+          claims: {
+            version: 'v2',
+          },
+          signature: '0x1234',
+          scheme: 'eip712',
+        },
+      } as never,
+      {
+        scheme: '4mica-credit',
+        network: 'eip155:11155111',
+        asset: '0x2222222222222222222222222222222222222222',
+        amount: '10',
+        payTo: '0x1111111111111111111111111111111111111111',
+      } as never
+    )
+
+    expect(result.success).toBe(true)
+    expect(result.transaction).toBe('0xdeadbeef')
+    expect(result.network).toBe('eip155:11155111')
+    expect(result.txHash).toBe('0xdeadbeef')
+    expect(result.networkId).toBe('eip155:11155111')
+    expect(result.certificate).toEqual({
+      claims: '0x' + '11'.repeat(32),
+      signature: '0x' + '22'.repeat(96),
+    })
+
+    const request = fetchMock.mock.calls[0]?.[1]
+    expect(typeof request?.body).toBe('string')
+    expect(String(request?.body)).toContain('"x402Version":2')
+    expect(String(request?.body)).toContain('"version":"v2"')
+  })
+
+  it('normalizes alias fields when the facilitator omits txHash/networkId', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          success: true,
+          transactionHash: '0xabc123',
+          network: 'eip155:80002',
+          user_address: '0x9999999999999999999999999999999999999999',
+        }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      )
+    )
+
+    vi.stubGlobal('fetch', fetchMock)
+
+    const client = new FourMicaFacilitatorClient({ url: 'https://facilitator.example' })
+    const result = await client.settle(
+      {
+        x402Version: 2,
+        accepted: {
+          scheme: '4mica-credit',
+          network: 'eip155:80002',
+          asset: '0x2222222222222222222222222222222222222222',
+          amount: '10',
+          payTo: '0x1111111111111111111111111111111111111111',
+        },
+        payload: {
+          claims: { version: 'v2' },
+          signature: '0x1234',
+          scheme: 'eip712',
+        },
+      } as never,
+      {
+        scheme: '4mica-credit',
+        network: 'eip155:80002',
+        asset: '0x2222222222222222222222222222222222222222',
+        amount: '10',
+        payTo: '0x1111111111111111111111111111111111111111',
+      } as never
+    )
+
+    expect(result.success).toBe(true)
+    expect(result.transaction).toBe('0xabc123')
+    expect(result.txHash).toBe('0xabc123')
+    expect(result.network).toBe('eip155:80002')
+    expect(result.networkId).toBe('eip155:80002')
+    expect(result.payer).toBe('0x9999999999999999999999999999999999999999')
+  })
+
+  it('surfaces facilitator errors using normalized reasons', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          success: false,
+          error_reason: 'unsupported x402Version 2',
+        }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      )
+    )
+
+    vi.stubGlobal('fetch', fetchMock)
+
+    const client = new FourMicaFacilitatorClient({ url: 'https://facilitator.example' })
+
+    await expect(
+      client.settle(
+        {
+          x402Version: 2,
+          accepted: {
+            scheme: '4mica-credit',
+            network: 'eip155:11155111',
+            asset: '0x2222222222222222222222222222222222222222',
+            amount: '10',
+            payTo: '0x1111111111111111111111111111111111111111',
+          },
+          payload: {
+            claims: { version: 'v2' },
+            signature: '0x1234',
+            scheme: 'eip712',
+          },
+        } as never,
+        {
+          scheme: '4mica-credit',
+          network: 'eip155:11155111',
+          asset: '0x2222222222222222222222222222222222222222',
+          amount: '10',
+          payTo: '0x1111111111111111111111111111111111111111',
+        } as never
+      )
+    ).rejects.toThrow('unsupported x402Version 2')
+  })
+})