uvd-x402-sdk 2.4.0 → 2.6.0

package/src/providers/near/index.ts

@@ -32,8 +32,10 @@ import type {
   PaymentInfo,
   NEARPaymentPayload,
   WalletAdapter,
+  X402Version,
 } from '../../types';
 import { X402Error } from '../../types';
+import { chainToCAIP2 } from '../../utils';
 
 // NEAR configuration
 const NEAR_CONFIG = {
@@ -473,19 +475,34 @@ export class NEARProvider implements WalletAdapter {
 
   /**
    * Encode NEAR payment as X-PAYMENT header
+   *
+   * @param paymentPayload - JSON-encoded payment payload from signPayment()
+   * @param version - x402 protocol version (1 or 2, defaults to 1)
+   * @returns Base64-encoded X-PAYMENT header value
    */
-  encodePaymentHeader(paymentPayload: string): string {
+  encodePaymentHeader(paymentPayload: string, version: X402Version = 1): string {
     const payload = JSON.parse(paymentPayload) as NEARPaymentPayload;
 
-    const x402Payload = {
-      x402Version: 1,
-      scheme: 'exact',
-      network: 'near',
-      payload: {
-        signedDelegateAction: payload.signedDelegateAction,
-      },
+    // Build the payload data
+    const payloadData = {
+      signedDelegateAction: payload.signedDelegateAction,
     };
 
+    // Format in x402 standard format (v1 or v2)
+    const x402Payload = version === 2
+      ? {
+          x402Version: 2 as const,
+          scheme: 'exact' as const,
+          network: chainToCAIP2('near'), // CAIP-2 format for v2
+          payload: payloadData,
+        }
+      : {
+          x402Version: 1 as const,
+          scheme: 'exact' as const,
+          network: 'near', // Plain chain name for v1
+          payload: payloadData,
+        };
+
     return btoa(JSON.stringify(x402Payload));
   }
 

package/src/providers/solana/index.ts

@@ -43,9 +43,11 @@ import type {
   PaymentInfo,
   SolanaPaymentPayload,
   WalletAdapter,
+  X402Version,
 } from '../../types';
 import { X402Error } from '../../types';
 import { getChainByName } from '../../chains';
+import { chainToCAIP2 } from '../../utils';
 
 /**
  * Browser-compatible base64 encoding for Uint8Array
@@ -395,24 +397,41 @@ export class SVMProvider implements WalletAdapter {
   /**
    * Encode SVM payment as X-PAYMENT header
    *
-   * @param paymentPayload - The payment payload JSON string
-   * @param chainConfig - Optional chain config (defaults to 'solana' if not provided)
+   * @param paymentPayload - JSON-encoded payment payload from signPayment()
+   * @param chainConfig - Chain configuration (optional, defaults to 'solana')
+   * @param version - x402 protocol version (1 or 2, defaults to 1)
+   * @returns Base64-encoded X-PAYMENT header value
    */
-  encodePaymentHeader(paymentPayload: string, chainConfig?: ChainConfig): string {
+  encodePaymentHeader(
+    paymentPayload: string,
+    chainConfig?: ChainConfig,
+    version: X402Version = 1
+  ): string {
     const payload = JSON.parse(paymentPayload) as SolanaPaymentPayload;
 
     // Use chain name from config, or default to 'solana' for backward compatibility
     const networkName = chainConfig?.name || 'solana';
 
-    const x402Payload = {
-      x402Version: 1,
-      scheme: 'exact',
-      network: networkName,
-      payload: {
-        transaction: payload.transaction,
-      },
+    // Build the payload data
+    const payloadData = {
+      transaction: payload.transaction,
     };
 
+    // Format in x402 standard format (v1 or v2)
+    const x402Payload = version === 2
+      ? {
+          x402Version: 2 as const,
+          scheme: 'exact' as const,
+          network: chainToCAIP2(networkName), // CAIP-2 format for v2
+          payload: payloadData,
+        }
+      : {
+          x402Version: 1 as const,
+          scheme: 'exact' as const,
+          network: networkName, // Plain chain name for v1
+          payload: payloadData,
+        };
+
     return btoa(JSON.stringify(x402Payload));
   }
 

package/src/providers/stellar/index.ts

@@ -25,8 +25,10 @@ import type {
   PaymentInfo,
   StellarPaymentPayload,
   WalletAdapter,
+  X402Version,
 } from '../../types';
 import { X402Error } from '../../types';
+import { chainToCAIP2 } from '../../utils';
 
 /**
  * Browser-compatible text to Uint8Array encoding
@@ -343,25 +345,40 @@ export class StellarProvider implements WalletAdapter {
 
   /**
    * Encode Stellar payment as X-PAYMENT header
+   *
+   * @param paymentPayload - JSON-encoded payment payload from signPayment()
+   * @param version - x402 protocol version (1 or 2, defaults to 1)
+   * @returns Base64-encoded X-PAYMENT header value
    */
-  encodePaymentHeader(paymentPayload: string): string {
+  encodePaymentHeader(paymentPayload: string, version: X402Version = 1): string {
     const payload = JSON.parse(paymentPayload) as StellarPaymentPayload;
 
-    const x402Payload = {
-      x402Version: 1,
-      scheme: 'exact',
-      network: 'stellar',
-      payload: {
-        from: payload.from,
-        to: payload.to,
-        amount: payload.amount,
-        tokenContract: payload.tokenContract,
-        authorizationEntryXdr: payload.authorizationEntryXdr,
-        nonce: payload.nonce,
-        signatureExpirationLedger: payload.signatureExpirationLedger,
-      },
+    // Build the payload data
+    const payloadData = {
+      from: payload.from,
+      to: payload.to,
+      amount: payload.amount,
+      tokenContract: payload.tokenContract,
+      authorizationEntryXdr: payload.authorizationEntryXdr,
+      nonce: payload.nonce,
+      signatureExpirationLedger: payload.signatureExpirationLedger,
     };
 
+    // Format in x402 standard format (v1 or v2)
+    const x402Payload = version === 2
+      ? {
+          x402Version: 2 as const,
+          scheme: 'exact' as const,
+          network: chainToCAIP2('stellar'), // CAIP-2 format for v2
+          payload: payloadData,
+        }
+      : {
+          x402Version: 1 as const,
+          scheme: 'exact' as const,
+          network: 'stellar', // Plain chain name for v1
+          payload: payloadData,
+        };
+
     return btoa(JSON.stringify(x402Payload));
   }
 

package/src/types/index.ts

@@ -230,6 +230,27 @@ export interface PaymentRequest {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * x402 payment header names
+ *
+ * - 'X-PAYMENT': v1 header name (default, most compatible)
+ * - 'PAYMENT-SIGNATURE': v2 header name (newer standard)
+ *
+ * Both headers use the same base64-encoded JSON payload format.
+ * The facilitator accepts both headers.
+ */
+export type X402HeaderName = 'X-PAYMENT' | 'PAYMENT-SIGNATURE';
+
+/**
+ * Payment headers object containing both v1 and v2 header formats
+ */
+export interface PaymentHeaders {
+  /** v1 header: X-PAYMENT */
+  'X-PAYMENT': string;
+  /** v2 header: PAYMENT-SIGNATURE (same value, different header name) */
+  'PAYMENT-SIGNATURE': string;
+}
+
 /**
  * Result of a payment operation
  */
@@ -238,6 +259,19 @@ export interface PaymentResult {
   success: boolean;
   /** Base64-encoded X-PAYMENT header value */
   paymentHeader: string;
+  /**
+   * Payment headers object for easy use with fetch/axios
+   *
+   * @example
+   * ```ts
+   * // Use v1 header
+   * fetch(url, { headers: { 'X-PAYMENT': result.headers['X-PAYMENT'] } });
+   *
+   * // Use v2 header
+   * fetch(url, { headers: { 'PAYMENT-SIGNATURE': result.headers['PAYMENT-SIGNATURE'] } });
+   * ```
+   */
+  headers: PaymentHeaders;
   /** Transaction hash (if available) */
   transactionHash?: string;
   /** Network where payment was made */

package/src/utils/index.ts

@@ -22,4 +22,8 @@ export {
 export {
   validateRecipient,
   validateAmount,
+  createPaymentHeaders,
+  getPaymentHeader,
+  DEFAULT_PAYMENT_HEADER,
+  PAYMENT_HEADER_NAMES,
 } from './validation';

package/src/utils/validation.ts

@@ -1,10 +1,11 @@
 /**
- * uvd-x402-sdk - Validation Utilities
+ * uvd-x402-sdk - Validation and Payment Header Utilities
  *
- * Functions for validating payment parameters to prevent
- * invalid or empty values from being processed.
+ * Functions for validating payment parameters and creating
+ * payment headers for HTTP requests.
  */
 
+import type { X402HeaderName, PaymentHeaders } from '../types';
 import { X402Error } from '../types';
 
 /**
@@ -149,3 +150,75 @@ export function validateAmount(amount: string | undefined | null): asserts amoun
     );
   }
 }
+
+// ============================================================================
+// PAYMENT HEADER UTILITIES
+// ============================================================================
+
+/**
+ * Create payment headers object from a base64-encoded payload
+ *
+ * Returns an object with both X-PAYMENT and PAYMENT-SIGNATURE headers,
+ * making it easy to use either header format.
+ *
+ * @param paymentHeader - Base64-encoded payment payload
+ * @returns PaymentHeaders object with both header formats
+ *
+ * @example
+ * ```ts
+ * const headers = createPaymentHeaders(paymentHeader);
+ *
+ * // Use v1 header (most compatible)
+ * fetch(url, { headers: { 'X-PAYMENT': headers['X-PAYMENT'] } });
+ *
+ * // Use v2 header
+ * fetch(url, { headers: { 'PAYMENT-SIGNATURE': headers['PAYMENT-SIGNATURE'] } });
+ * ```
+ */
+export function createPaymentHeaders(paymentHeader: string): PaymentHeaders {
+  return {
+    'X-PAYMENT': paymentHeader,
+    'PAYMENT-SIGNATURE': paymentHeader,
+  };
+}
+
+/**
+ * Get a single payment header by name
+ *
+ * @param paymentHeader - Base64-encoded payment payload
+ * @param headerName - Header name to use ('X-PAYMENT' or 'PAYMENT-SIGNATURE')
+ * @returns Object with a single header entry
+ *
+ * @example
+ * ```ts
+ * // Use with fetch spread operator
+ * fetch(url, {
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *     ...getPaymentHeader(result.paymentHeader, 'X-PAYMENT'),
+ *   },
+ * });
+ * ```
+ */
+export function getPaymentHeader(
+  paymentHeader: string,
+  headerName: X402HeaderName = 'X-PAYMENT'
+): Record<X402HeaderName, string> {
+  return { [headerName]: paymentHeader } as Record<X402HeaderName, string>;
+}
+
+/**
+ * Default x402 payment header name
+ *
+ * Use 'X-PAYMENT' for maximum compatibility with all facilitators.
+ * Use 'PAYMENT-SIGNATURE' for x402 v2 compliance.
+ */
+export const DEFAULT_PAYMENT_HEADER: X402HeaderName = 'X-PAYMENT';
+
+/**
+ * All supported x402 payment header names
+ */
+export const PAYMENT_HEADER_NAMES: readonly X402HeaderName[] = [
+  'X-PAYMENT',
+  'PAYMENT-SIGNATURE',
+] as const;