@dexterai/x402 1.0.0

package/dist/server/index.d.cts

@@ -0,0 +1,191 @@
+import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, a as PaymentRequired } from '../types-DkTxHOns.cjs';
+export { B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, b as SOLANA_MAINNET_NETWORK, c as USDC_BASE, U as USDC_MINT } from '../types-DkTxHOns.cjs';
+
+/**
+ * Facilitator Client
+ *
+ * Communicates with the x402 facilitator for:
+ * - /supported - Get supported payment schemes and fee payer addresses
+ * - /verify - Verify a payment signature before processing
+ * - /settle - Submit the payment for execution
+ *
+ * Works with any x402 v2 facilitator (Dexter or others).
+ */
+
+/**
+ * Supported payment kind from facilitator /supported endpoint
+ */
+interface SupportedKind {
+    x402Version: number;
+    scheme: string;
+    network: string;
+    extra?: {
+        feePayer?: string;
+        decimals?: number;
+        name?: string;
+        version?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Response from facilitator /supported endpoint
+ */
+interface SupportedResponse {
+    kinds: SupportedKind[];
+}
+/**
+ * Client for communicating with an x402 v2 facilitator
+ */
+declare class FacilitatorClient {
+    private facilitatorUrl;
+    private cachedSupported;
+    private cacheTime;
+    private readonly CACHE_TTL_MS;
+    constructor(facilitatorUrl?: string);
+    /**
+     * Get supported payment kinds from the facilitator
+     * Results are cached for 1 minute to reduce network calls
+     */
+    getSupported(): Promise<SupportedResponse>;
+    /**
+     * Get the fee payer address for a specific network
+     *
+     * @param network - CAIP-2 network identifier
+     * @returns Fee payer address
+     */
+    getFeePayer(network: string): Promise<string>;
+    /**
+     * Get extra data for a network (feePayer, decimals, EIP-712 data, etc.)
+     *
+     * @param network - CAIP-2 network identifier
+     * @returns Extra data from /supported
+     */
+    getNetworkExtra(network: string): Promise<SupportedKind['extra']>;
+    /**
+     * Verify a payment with the facilitator
+     *
+     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
+     * @param requirements - The payment requirements that were sent to the client
+     * @returns Verification response
+     */
+    verifyPayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<VerifyResponse>;
+    /**
+     * Settle a payment with the facilitator
+     *
+     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
+     * @param requirements - The payment requirements that were sent to the client
+     * @returns Settlement response with transaction signature on success
+     */
+    settlePayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<SettleResponse>;
+}
+
+/**
+ * x402 v2 Server
+ *
+ * Server-side helpers for accepting x402 payments.
+ * Chain-agnostic - works with Solana, Base, and any x402-compatible network.
+ *
+ * @example
+ * ```typescript
+ * import { createX402Server } from '@dexterai/x402/server';
+ *
+ * const server = createX402Server({
+ *   payTo: 'YourAddress...',
+ *   network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+ * });
+ *
+ * // Handle 402 responses
+ * if (!paymentSignature) {
+ *   const requirements = await server.buildRequirements({
+ *     amountAtomic: '50000',
+ *     resourceUrl: '/api/protected',
+ *   });
+ *   res.setHeader('PAYMENT-REQUIRED', server.encodeRequirements(requirements));
+ *   res.status(402).json({});
+ *   return;
+ * }
+ *
+ * // Verify and settle
+ * const verify = await server.verifyPayment(paymentSignature);
+ * if (!verify.isValid) throw new Error(verify.invalidReason);
+ *
+ * const settle = await server.settlePayment(paymentSignature);
+ * if (!settle.success) throw new Error(settle.errorReason);
+ *
+ * // Payment successful!
+ * res.json({ transaction: settle.transaction });
+ * ```
+ */
+
+/**
+ * Asset configuration
+ */
+interface AssetConfig {
+    /** Token address (mint on Solana, contract on EVM) */
+    address: string;
+    /** Token decimals */
+    decimals: number;
+}
+/**
+ * Server configuration
+ */
+interface X402ServerConfig {
+    /** Address to receive payments */
+    payTo: string;
+    /** Facilitator URL (defaults to Dexter) */
+    facilitatorUrl?: string;
+    /** CAIP-2 network identifier */
+    network?: string;
+    /** Asset configuration (defaults to USDC) */
+    asset?: AssetConfig;
+    /** Default payment timeout in seconds */
+    defaultTimeoutSeconds?: number;
+}
+/**
+ * Options for building payment requirements
+ */
+interface BuildRequirementsOptions {
+    /** Amount in atomic units (e.g., '50000' for 0.05 USDC) */
+    amountAtomic: string;
+    /** Full URL of the resource */
+    resourceUrl: string;
+    /** Human-readable description */
+    description?: string;
+    /** MIME type of the response */
+    mimeType?: string;
+    /** Override timeout for this request */
+    timeoutSeconds?: number;
+}
+/**
+ * x402 Server interface
+ */
+interface X402Server {
+    /** Build payment requirements (fetches feePayer from facilitator) */
+    buildRequirements(options: BuildRequirementsOptions): Promise<PaymentRequired>;
+    /** Encode requirements for PAYMENT-REQUIRED header */
+    encodeRequirements(requirements: PaymentRequired): string;
+    /** Create complete 402 response object */
+    create402Response(requirements: PaymentRequired): {
+        status: 402;
+        headers: {
+            'PAYMENT-REQUIRED': string;
+        };
+        body: Record<string, unknown>;
+    };
+    /** Verify payment with facilitator */
+    verifyPayment(paymentSignatureHeader: string, requirements?: PaymentAccept): Promise<VerifyResponse>;
+    /** Settle payment via facilitator */
+    settlePayment(paymentSignatureHeader: string, requirements?: PaymentAccept): Promise<SettleResponse>;
+    /** Get PaymentAccept for verify/settle */
+    getPaymentAccept(options: BuildRequirementsOptions): Promise<PaymentAccept>;
+    /** Get network this server is configured for */
+    readonly network: string;
+    /** Get facilitator client for advanced usage */
+    readonly facilitator: FacilitatorClient;
+}
+/**
+ * Create an x402 server for accepting payments
+ */
+declare function createX402Server(config: X402ServerConfig): X402Server;
+
+export { type AssetConfig, type BuildRequirementsOptions, FacilitatorClient, PaymentAccept, PaymentRequired, SettleResponse, type SupportedKind, type SupportedResponse, VerifyResponse, type X402Server, type X402ServerConfig, createX402Server };

package/dist/server/index.d.ts

@@ -0,0 +1,191 @@
+import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, a as PaymentRequired } from '../types-DkTxHOns.js';
+export { B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, b as SOLANA_MAINNET_NETWORK, c as USDC_BASE, U as USDC_MINT } from '../types-DkTxHOns.js';
+
+/**
+ * Facilitator Client
+ *
+ * Communicates with the x402 facilitator for:
+ * - /supported - Get supported payment schemes and fee payer addresses
+ * - /verify - Verify a payment signature before processing
+ * - /settle - Submit the payment for execution
+ *
+ * Works with any x402 v2 facilitator (Dexter or others).
+ */
+
+/**
+ * Supported payment kind from facilitator /supported endpoint
+ */
+interface SupportedKind {
+    x402Version: number;
+    scheme: string;
+    network: string;
+    extra?: {
+        feePayer?: string;
+        decimals?: number;
+        name?: string;
+        version?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Response from facilitator /supported endpoint
+ */
+interface SupportedResponse {
+    kinds: SupportedKind[];
+}
+/**
+ * Client for communicating with an x402 v2 facilitator
+ */
+declare class FacilitatorClient {
+    private facilitatorUrl;
+    private cachedSupported;
+    private cacheTime;
+    private readonly CACHE_TTL_MS;
+    constructor(facilitatorUrl?: string);
+    /**
+     * Get supported payment kinds from the facilitator
+     * Results are cached for 1 minute to reduce network calls
+     */
+    getSupported(): Promise<SupportedResponse>;
+    /**
+     * Get the fee payer address for a specific network
+     *
+     * @param network - CAIP-2 network identifier
+     * @returns Fee payer address
+     */
+    getFeePayer(network: string): Promise<string>;
+    /**
+     * Get extra data for a network (feePayer, decimals, EIP-712 data, etc.)
+     *
+     * @param network - CAIP-2 network identifier
+     * @returns Extra data from /supported
+     */
+    getNetworkExtra(network: string): Promise<SupportedKind['extra']>;
+    /**
+     * Verify a payment with the facilitator
+     *
+     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
+     * @param requirements - The payment requirements that were sent to the client
+     * @returns Verification response
+     */
+    verifyPayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<VerifyResponse>;
+    /**
+     * Settle a payment with the facilitator
+     *
+     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
+     * @param requirements - The payment requirements that were sent to the client
+     * @returns Settlement response with transaction signature on success
+     */
+    settlePayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<SettleResponse>;
+}
+
+/**
+ * x402 v2 Server
+ *
+ * Server-side helpers for accepting x402 payments.
+ * Chain-agnostic - works with Solana, Base, and any x402-compatible network.
+ *
+ * @example
+ * ```typescript
+ * import { createX402Server } from '@dexterai/x402/server';
+ *
+ * const server = createX402Server({
+ *   payTo: 'YourAddress...',
+ *   network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+ * });
+ *
+ * // Handle 402 responses
+ * if (!paymentSignature) {
+ *   const requirements = await server.buildRequirements({
+ *     amountAtomic: '50000',
+ *     resourceUrl: '/api/protected',
+ *   });
+ *   res.setHeader('PAYMENT-REQUIRED', server.encodeRequirements(requirements));
+ *   res.status(402).json({});
+ *   return;
+ * }
+ *
+ * // Verify and settle
+ * const verify = await server.verifyPayment(paymentSignature);
+ * if (!verify.isValid) throw new Error(verify.invalidReason);
+ *
+ * const settle = await server.settlePayment(paymentSignature);
+ * if (!settle.success) throw new Error(settle.errorReason);
+ *
+ * // Payment successful!
+ * res.json({ transaction: settle.transaction });
+ * ```
+ */
+
+/**
+ * Asset configuration
+ */
+interface AssetConfig {
+    /** Token address (mint on Solana, contract on EVM) */
+    address: string;
+    /** Token decimals */
+    decimals: number;
+}
+/**
+ * Server configuration
+ */
+interface X402ServerConfig {
+    /** Address to receive payments */
+    payTo: string;
+    /** Facilitator URL (defaults to Dexter) */
+    facilitatorUrl?: string;
+    /** CAIP-2 network identifier */
+    network?: string;
+    /** Asset configuration (defaults to USDC) */
+    asset?: AssetConfig;
+    /** Default payment timeout in seconds */
+    defaultTimeoutSeconds?: number;
+}
+/**
+ * Options for building payment requirements
+ */
+interface BuildRequirementsOptions {
+    /** Amount in atomic units (e.g., '50000' for 0.05 USDC) */
+    amountAtomic: string;
+    /** Full URL of the resource */
+    resourceUrl: string;
+    /** Human-readable description */
+    description?: string;
+    /** MIME type of the response */
+    mimeType?: string;
+    /** Override timeout for this request */
+    timeoutSeconds?: number;
+}
+/**
+ * x402 Server interface
+ */
+interface X402Server {
+    /** Build payment requirements (fetches feePayer from facilitator) */
+    buildRequirements(options: BuildRequirementsOptions): Promise<PaymentRequired>;
+    /** Encode requirements for PAYMENT-REQUIRED header */
+    encodeRequirements(requirements: PaymentRequired): string;
+    /** Create complete 402 response object */
+    create402Response(requirements: PaymentRequired): {
+        status: 402;
+        headers: {
+            'PAYMENT-REQUIRED': string;
+        };
+        body: Record<string, unknown>;
+    };
+    /** Verify payment with facilitator */
+    verifyPayment(paymentSignatureHeader: string, requirements?: PaymentAccept): Promise<VerifyResponse>;
+    /** Settle payment via facilitator */
+    settlePayment(paymentSignatureHeader: string, requirements?: PaymentAccept): Promise<SettleResponse>;
+    /** Get PaymentAccept for verify/settle */
+    getPaymentAccept(options: BuildRequirementsOptions): Promise<PaymentAccept>;
+    /** Get network this server is configured for */
+    readonly network: string;
+    /** Get facilitator client for advanced usage */
+    readonly facilitator: FacilitatorClient;
+}
+/**
+ * Create an x402 server for accepting payments
+ */
+declare function createX402Server(config: X402ServerConfig): X402Server;
+
+export { type AssetConfig, type BuildRequirementsOptions, FacilitatorClient, PaymentAccept, PaymentRequired, SettleResponse, type SupportedKind, type SupportedResponse, VerifyResponse, type X402Server, type X402ServerConfig, createX402Server };

package/dist/server/index.js

@@ -0,0 +1,262 @@
+// src/types.ts
+var SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+var BASE_MAINNET_NETWORK = "eip155:8453";
+var USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+var USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var DEXTER_FACILITATOR_URL = "https://x402.dexter.cash";
+
+// src/utils.ts
+function decodeBase64Json(encoded) {
+  return JSON.parse(atob(encoded));
+}
+
+// src/server/facilitator-client.ts
+var FacilitatorClient = class {
+  facilitatorUrl;
+  cachedSupported = null;
+  cacheTime = 0;
+  CACHE_TTL_MS = 6e4;
+  // 1 minute cache
+  constructor(facilitatorUrl = DEXTER_FACILITATOR_URL) {
+    this.facilitatorUrl = facilitatorUrl.replace(/\/$/, "");
+  }
+  /**
+   * Get supported payment kinds from the facilitator
+   * Results are cached for 1 minute to reduce network calls
+   */
+  async getSupported() {
+    const now = Date.now();
+    if (this.cachedSupported && now - this.cacheTime < this.CACHE_TTL_MS) {
+      return this.cachedSupported;
+    }
+    const response = await fetch(`${this.facilitatorUrl}/supported`);
+    if (!response.ok) {
+      throw new Error(`Facilitator /supported returned ${response.status}`);
+    }
+    this.cachedSupported = await response.json();
+    this.cacheTime = now;
+    return this.cachedSupported;
+  }
+  /**
+   * Get the fee payer address for a specific network
+   *
+   * @param network - CAIP-2 network identifier
+   * @returns Fee payer address
+   */
+  async getFeePayer(network) {
+    const supported = await this.getSupported();
+    const kind = supported.kinds.find(
+      (k) => k.x402Version === 2 && k.scheme === "exact" && k.network === network
+    );
+    if (!kind?.extra?.feePayer) {
+      throw new Error(
+        `Facilitator does not support network "${network}" with scheme "exact", or feePayer not provided`
+      );
+    }
+    return kind.extra.feePayer;
+  }
+  /**
+   * Get extra data for a network (feePayer, decimals, EIP-712 data, etc.)
+   *
+   * @param network - CAIP-2 network identifier
+   * @returns Extra data from /supported
+   */
+  async getNetworkExtra(network) {
+    const supported = await this.getSupported();
+    const kind = supported.kinds.find(
+      (k) => k.x402Version === 2 && k.scheme === "exact" && k.network === network
+    );
+    return kind?.extra;
+  }
+  /**
+   * Verify a payment with the facilitator
+   *
+   * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
+   * @param requirements - The payment requirements that were sent to the client
+   * @returns Verification response
+   */
+  async verifyPayment(paymentSignatureHeader, requirements) {
+    try {
+      const paymentPayload = decodeBase64Json(paymentSignatureHeader);
+      const verifyPayload = {
+        paymentPayload,
+        paymentRequirements: requirements
+      };
+      const response = await fetch(`${this.facilitatorUrl}/verify`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(verifyPayload)
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`Facilitator /verify returned ${response.status}:`, errorText);
+        return {
+          isValid: false,
+          invalidReason: `facilitator_error_${response.status}`
+        };
+      }
+      return await response.json();
+    } catch (error) {
+      console.error("Payment verification failed:", error);
+      return {
+        isValid: false,
+        invalidReason: error instanceof Error ? error.message : "unexpected_verify_error"
+      };
+    }
+  }
+  /**
+   * Settle a payment with the facilitator
+   *
+   * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
+   * @param requirements - The payment requirements that were sent to the client
+   * @returns Settlement response with transaction signature on success
+   */
+  async settlePayment(paymentSignatureHeader, requirements) {
+    try {
+      const paymentPayload = decodeBase64Json(paymentSignatureHeader);
+      const settlePayload = {
+        paymentPayload,
+        paymentRequirements: requirements
+      };
+      const response = await fetch(`${this.facilitatorUrl}/settle`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(settlePayload)
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`Facilitator /settle returned ${response.status}:`, errorText);
+        return {
+          success: false,
+          network: requirements.network,
+          errorReason: `facilitator_error_${response.status}`
+        };
+      }
+      const result = await response.json();
+      return {
+        ...result,
+        network: requirements.network
+      };
+    } catch (error) {
+      console.error("Payment settlement failed:", error);
+      return {
+        success: false,
+        network: requirements.network,
+        errorReason: error instanceof Error ? error.message : "unexpected_settle_error"
+      };
+    }
+  }
+};
+
+// src/server/x402-server.ts
+function createX402Server(config) {
+  const {
+    payTo,
+    facilitatorUrl = DEXTER_FACILITATOR_URL,
+    network = SOLANA_MAINNET_NETWORK,
+    asset = { address: USDC_MINT, decimals: 6 },
+    defaultTimeoutSeconds = 60
+  } = config;
+  const facilitator = new FacilitatorClient(facilitatorUrl);
+  let cachedExtra = null;
+  async function getNetworkExtra() {
+    if (!cachedExtra) {
+      cachedExtra = await facilitator.getNetworkExtra(network);
+    }
+    if (!cachedExtra?.feePayer) {
+      throw new Error(`Facilitator does not provide feePayer for network "${network}"`);
+    }
+    return {
+      feePayer: cachedExtra.feePayer,
+      decimals: cachedExtra.decimals ?? asset.decimals,
+      // Include any additional EIP-712 data for EVM chains
+      name: cachedExtra.name,
+      version: cachedExtra.version
+    };
+  }
+  async function getPaymentAccept(options) {
+    const {
+      amountAtomic,
+      timeoutSeconds = defaultTimeoutSeconds
+    } = options;
+    const extra = await getNetworkExtra();
+    return {
+      scheme: "exact",
+      network,
+      amount: amountAtomic,
+      asset: asset.address,
+      payTo,
+      maxTimeoutSeconds: timeoutSeconds,
+      extra
+    };
+  }
+  async function buildRequirements(options) {
+    const {
+      resourceUrl,
+      description,
+      mimeType = "application/json"
+    } = options;
+    const resource = {
+      url: resourceUrl,
+      description,
+      mimeType
+    };
+    const accept = await getPaymentAccept(options);
+    return {
+      x402Version: 2,
+      resource,
+      accepts: [accept],
+      error: "Payment required"
+    };
+  }
+  function encodeRequirements(requirements) {
+    return btoa(JSON.stringify(requirements));
+  }
+  function create402Response(requirements) {
+    return {
+      status: 402,
+      headers: {
+        "PAYMENT-REQUIRED": encodeRequirements(requirements)
+      },
+      body: {}
+    };
+  }
+  async function verifyPayment(paymentSignatureHeader, requirements) {
+    const req = requirements || await getPaymentAccept({
+      amountAtomic: "0",
+      resourceUrl: ""
+    });
+    return facilitator.verifyPayment(paymentSignatureHeader, req);
+  }
+  async function settlePayment(paymentSignatureHeader, requirements) {
+    const req = requirements || await getPaymentAccept({
+      amountAtomic: "0",
+      resourceUrl: ""
+    });
+    return facilitator.settlePayment(paymentSignatureHeader, req);
+  }
+  return {
+    buildRequirements,
+    encodeRequirements,
+    create402Response,
+    verifyPayment,
+    settlePayment,
+    getPaymentAccept,
+    network,
+    facilitator
+  };
+}
+export {
+  BASE_MAINNET_NETWORK,
+  DEXTER_FACILITATOR_URL,
+  FacilitatorClient,
+  SOLANA_MAINNET_NETWORK,
+  USDC_BASE,
+  USDC_MINT,
+  createX402Server
+};
+//# sourceMappingURL=index.js.map