@dexterai/x402 1.0.2 → 1.0.3

package/README.md

@@ -95,6 +95,9 @@ app.post('/protected', async (req, res) => {
 });
 ```
 
+> ⚠️ **Note:** The server SDK (`createX402Server`) has not been battle-tested in production. 
+> The client SDK and React hook have been verified with real payments.
+
 ### React
 
 ```tsx

package/dist/utils/index.cjs

@@ -0,0 +1,110 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/index.ts
+var utils_exports = {};
+__export(utils_exports, {
+  fromAtomicUnits: () => fromAtomicUnits,
+  getChainFamily: () => getChainFamily,
+  getChainName: () => getChainName,
+  getExplorerUrl: () => getExplorerUrl,
+  toAtomicUnits: () => toAtomicUnits
+});
+module.exports = __toCommonJS(utils_exports);
+
+// src/types.ts
+var SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+var BASE_MAINNET_NETWORK = "eip155:8453";
+
+// src/utils.ts
+function toAtomicUnits(amount, decimals) {
+  const multiplier = Math.pow(10, decimals);
+  return Math.floor(amount * multiplier).toString();
+}
+function fromAtomicUnits(atomicUnits, decimals) {
+  const divisor = Math.pow(10, decimals);
+  return Number(atomicUnits) / divisor;
+}
+function getChainFamily(network) {
+  if (network.startsWith("solana:") || network === "solana") {
+    return "solana";
+  }
+  if (network.startsWith("eip155:") || ["base", "ethereum", "arbitrum"].includes(network)) {
+    return "evm";
+  }
+  return "unknown";
+}
+function getChainName(network) {
+  const mapping = {
+    [SOLANA_MAINNET_NETWORK]: "Solana",
+    "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": "Solana Devnet",
+    "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z": "Solana Testnet",
+    "solana": "Solana",
+    [BASE_MAINNET_NETWORK]: "Base",
+    "eip155:84532": "Base Sepolia",
+    "eip155:1": "Ethereum",
+    "eip155:42161": "Arbitrum One",
+    "base": "Base",
+    "ethereum": "Ethereum",
+    "arbitrum": "Arbitrum"
+  };
+  return mapping[network] || network;
+}
+function getExplorerUrl(txSignature, network) {
+  const family = getChainFamily(network);
+  if (family === "solana") {
+    const isDevnet = network.includes("devnet") || network === "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+    if (isDevnet) {
+      return `https://solscan.io/tx/${txSignature}?cluster=devnet`;
+    }
+    return `https://www.orbmarkets.io/tx/${txSignature}`;
+  }
+  if (family === "evm") {
+    let chainId = "8453";
+    if (network.startsWith("eip155:")) {
+      chainId = network.split(":")[1];
+    } else if (network === "ethereum") {
+      chainId = "1";
+    } else if (network === "arbitrum") {
+      chainId = "42161";
+    }
+    switch (chainId) {
+      case "8453":
+        return `https://basescan.org/tx/${txSignature}`;
+      case "84532":
+        return `https://sepolia.basescan.org/tx/${txSignature}`;
+      case "1":
+        return `https://etherscan.io/tx/${txSignature}`;
+      case "42161":
+        return `https://arbiscan.io/tx/${txSignature}`;
+      default:
+        return `https://basescan.org/tx/${txSignature}`;
+    }
+  }
+  return `https://solscan.io/tx/${txSignature}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fromAtomicUnits,
+  getChainFamily,
+  getChainName,
+  getExplorerUrl,
+  toAtomicUnits
+});
+//# sourceMappingURL=index.cjs.map

package/dist/utils/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/index.ts","../../src/types.ts","../../src/utils.ts"],"sourcesContent":["/**\n * @dexterai/x402 Utils\n *\n * Helper functions for x402 payments.\n *\n * @example\n * ```typescript\n * import { toAtomicUnits, fromAtomicUnits } from '@dexterai/x402/utils';\n *\n * const atomic = toAtomicUnits(0.05, 6); // '50000'\n * const human = fromAtomicUnits('50000', 6); // 0.05\n * ```\n */\n\nexport {\n  toAtomicUnits,\n  fromAtomicUnits,\n  getChainFamily,\n  getChainName,\n  getExplorerUrl,\n  type ChainFamily,\n} from '../utils';\n","/**\n * x402 v2 SDK — Shared Types\n *\n * Chain-agnostic types for x402 v2 payments.\n * Works with Solana, Base, and any future x402-compatible networks.\n */\n\n// ============================================================================\n// Network Constants\n// ============================================================================\n\n/** CAIP-2 network identifier for Solana mainnet */\nexport const SOLANA_MAINNET_NETWORK = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';\n\n/** CAIP-2 network identifier for Base mainnet */\nexport const BASE_MAINNET_NETWORK = 'eip155:8453';\n\n/** Alias for Solana mainnet */\nexport const SOLANA_MAINNET = SOLANA_MAINNET_NETWORK;\n\n/** Alias for Base mainnet */\nexport const BASE_MAINNET = BASE_MAINNET_NETWORK;\n\n// ============================================================================\n// Asset Constants\n// ============================================================================\n\n/** USDC mint on Solana mainnet */\nexport const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';\n\n/** USDC address on Base mainnet */\nexport const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';\n\n// ============================================================================\n// Facilitator Constants\n// ============================================================================\n\n/** Dexter's public x402 v2 facilitator URL */\nexport const DEXTER_FACILITATOR_URL = 'https://x402.dexter.cash';\n\n// ============================================================================\n// Payment Types\n// ============================================================================\n\n/**\n * Asset configuration for payments\n */\nexport interface AssetConfig {\n  /** Token address (mint on Solana, contract on EVM) */\n  address: string;\n  /** Token decimals */\n  decimals: number;\n  /** Optional: Human-readable symbol */\n  symbol?: string;\n}\n\n/**\n * Resource info included in payment requirements\n */\nexport interface ResourceInfo {\n  /** Resource URL */\n  url: string;\n  /** Human-readable description */\n  description?: string;\n  /** MIME type of the resource */\n  mimeType?: string;\n}\n\n/**\n * Extra fields in payment requirements\n * Chain-specific fields may vary\n */\nexport interface AcceptsExtra {\n  /** Facilitator address that pays tx fees (required) */\n  feePayer: string;\n  /** Token decimals (required) */\n  decimals: number;\n  /** EIP-712: Token name (EVM only) */\n  name?: string;\n  /** EIP-712: Token version (EVM only) */\n  version?: string;\n  /** Additional chain-specific fields */\n  [key: string]: unknown;\n}\n\n/**\n * A single payment option in the accepts array\n */\nexport interface PaymentAccept {\n  /** Payment scheme (always 'exact' for x402 v2) */\n  scheme: 'exact';\n  /** CAIP-2 network identifier */\n  network: string;\n  /** Payment amount in atomic units (as string to avoid precision loss) */\n  amount: string;\n  /** Token address */\n  asset: string;\n  /** Seller's address to receive payment */\n  payTo: string;\n  /** Maximum seconds until payment expires */\n  maxTimeoutSeconds: number;\n  /** Chain-specific extra data */\n  extra: AcceptsExtra;\n}\n\n/**\n * Full PaymentRequired structure (sent in PAYMENT-REQUIRED header)\n */\nexport interface PaymentRequired {\n  /** x402 version (always 2) */\n  x402Version: 2;\n  /** Resource being accessed */\n  resource: ResourceInfo;\n  /** Available payment options */\n  accepts: PaymentAccept[];\n  /** Optional error message */\n  error?: string;\n}\n\n/**\n * PaymentSignature structure (sent in PAYMENT-SIGNATURE header)\n */\nexport interface PaymentSignature {\n  /** x402 version (always 2) */\n  x402Version: 2;\n  /** Resource being accessed */\n  resource: ResourceInfo;\n  /** The payment option that was accepted */\n  accepted: PaymentAccept;\n  /** The signed payment */\n  payload: {\n    /** Signed transaction (base64 for Solana, JSON for EVM) */\n    transaction: string;\n  };\n}\n\n// ============================================================================\n// Facilitator Response Types\n// ============================================================================\n\n/**\n * Response from /verify endpoint\n */\nexport interface VerifyResponse {\n  /** Whether the payment is valid */\n  isValid: boolean;\n  /** Reason for invalidity (if invalid) */\n  invalidReason?: string;\n  /** Payer address */\n  payer?: string;\n}\n\n/**\n * Response from /settle endpoint\n */\nexport interface SettleResponse {\n  /** Whether settlement succeeded */\n  success: boolean;\n  /** Transaction signature/hash */\n  transaction?: string;\n  /** Network the payment was made on */\n  network: string;\n  /** Error reason (if failed) */\n  errorReason?: string;\n  /** Error code (if failed) */\n  errorCode?: string;\n  /** Payer address */\n  payer?: string;\n}\n\n// ============================================================================\n// Error Types\n// ============================================================================\n\n/**\n * SDK error codes\n */\nexport type X402ErrorCode =\n  // Client errors\n  | 'missing_payment_required_header'\n  | 'invalid_payment_required'\n  | 'unsupported_network'\n  | 'no_matching_payment_option'\n  | 'no_solana_accept' // Legacy, kept for compatibility\n  | 'missing_fee_payer'\n  | 'missing_decimals'\n  | 'amount_exceeds_max'\n  | 'insufficient_balance'\n  | 'wallet_missing_sign_transaction'\n  | 'wallet_not_connected'\n  | 'transaction_build_failed'\n  | 'payment_rejected'\n  // Server errors\n  | 'invalid_payment_signature'\n  | 'facilitator_verify_failed'\n  | 'facilitator_settle_failed'\n  | 'facilitator_request_failed'\n  | 'no_matching_requirement';\n\n/**\n * Custom error class for x402 operations\n */\nexport class X402Error extends Error {\n  /** Error code for programmatic handling */\n  code: X402ErrorCode;\n  /** Additional error details */\n  details?: unknown;\n\n  constructor(code: X402ErrorCode, message: string, details?: unknown) {\n    super(message);\n    this.name = 'X402Error';\n    this.code = code;\n    this.details = details;\n    // Maintain proper prototype chain\n    Object.setPrototypeOf(this, X402Error.prototype);\n  }\n}\n","/**\n * Utility Functions\n *\n * Chain-agnostic helpers for x402 payments.\n */\n\nimport { SOLANA_MAINNET_NETWORK, BASE_MAINNET_NETWORK } from './types';\n\n// ============================================================================\n// Amount Conversion\n// ============================================================================\n\n/**\n * Convert human-readable amount to atomic units\n *\n * @param amount - Human-readable amount (e.g., 0.05 for $0.05)\n * @param decimals - Token decimals (e.g., 6 for USDC)\n * @returns Amount in atomic units as string\n *\n * @example\n * ```typescript\n * toAtomicUnits(0.05, 6) // '50000'\n * toAtomicUnits(1.50, 6) // '1500000'\n * ```\n */\nexport function toAtomicUnits(amount: number, decimals: number): string {\n  const multiplier = Math.pow(10, decimals);\n  return Math.floor(amount * multiplier).toString();\n}\n\n/**\n * Convert atomic units to human-readable amount\n *\n * @param atomicUnits - Amount in smallest units\n * @param decimals - Token decimals\n * @returns Human-readable amount\n *\n * @example\n * ```typescript\n * fromAtomicUnits('50000', 6) // 0.05\n * fromAtomicUnits(1500000n, 6) // 1.5\n * ```\n */\nexport function fromAtomicUnits(\n  atomicUnits: string | bigint | number,\n  decimals: number\n): number {\n  const divisor = Math.pow(10, decimals);\n  return Number(atomicUnits) / divisor;\n}\n\n// ============================================================================\n// Network Helpers\n// ============================================================================\n\n/**\n * Network type\n */\nexport type ChainFamily = 'solana' | 'evm' | 'unknown';\n\n/**\n * Get the chain family from a CAIP-2 network identifier\n *\n * @param network - CAIP-2 network identifier\n * @returns Chain family\n *\n * @example\n * ```typescript\n * getChainFamily('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp') // 'solana'\n * getChainFamily('eip155:8453') // 'evm'\n * ```\n */\nexport function getChainFamily(network: string): ChainFamily {\n  if (network.startsWith('solana:') || network === 'solana') {\n    return 'solana';\n  }\n  if (network.startsWith('eip155:') || ['base', 'ethereum', 'arbitrum'].includes(network)) {\n    return 'evm';\n  }\n  return 'unknown';\n}\n\n/**\n * Get default RPC URL for a network\n *\n * @param network - CAIP-2 network identifier\n * @returns Default RPC URL\n */\nexport function getDefaultRpcUrl(network: string): string {\n  const family = getChainFamily(network);\n\n  if (family === 'solana') {\n    if (network.includes('devnet') || network === 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1') {\n      return 'https://api.devnet.solana.com';\n    }\n    if (network.includes('testnet') || network === 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z') {\n      return 'https://api.testnet.solana.com';\n    }\n    return 'https://api.mainnet-beta.solana.com';\n  }\n\n  if (family === 'evm') {\n    // Extract chain ID from CAIP-2\n    if (network.startsWith('eip155:')) {\n      const chainId = network.split(':')[1];\n      switch (chainId) {\n        case '8453': return 'https://mainnet.base.org';\n        case '84532': return 'https://sepolia.base.org';\n        case '1': return 'https://eth.llamarpc.com';\n        case '42161': return 'https://arb1.arbitrum.io/rpc';\n        default: return 'https://mainnet.base.org';\n      }\n    }\n    // Legacy names\n    if (network === 'base') return 'https://mainnet.base.org';\n    if (network === 'ethereum') return 'https://eth.llamarpc.com';\n    if (network === 'arbitrum') return 'https://arb1.arbitrum.io/rpc';\n    return 'https://mainnet.base.org';\n  }\n\n  // Unknown - return a generic\n  return 'https://api.mainnet-beta.solana.com';\n}\n\n/**\n * Get human-readable chain name\n *\n * @param network - CAIP-2 network identifier\n * @returns Human-readable name\n */\nexport function getChainName(network: string): string {\n  const mapping: Record<string, string> = {\n    [SOLANA_MAINNET_NETWORK]: 'Solana',\n    'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1': 'Solana Devnet',\n    'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z': 'Solana Testnet',\n    'solana': 'Solana',\n    [BASE_MAINNET_NETWORK]: 'Base',\n    'eip155:84532': 'Base Sepolia',\n    'eip155:1': 'Ethereum',\n    'eip155:42161': 'Arbitrum One',\n    'base': 'Base',\n    'ethereum': 'Ethereum',\n    'arbitrum': 'Arbitrum',\n  };\n  return mapping[network] || network;\n}\n\n// ============================================================================\n// Transaction URL Helpers\n// ============================================================================\n\n/**\n * Get explorer URL for a transaction\n *\n * @param txSignature - Transaction signature/hash\n * @param network - CAIP-2 network identifier\n * @returns Explorer URL\n */\nexport function getExplorerUrl(txSignature: string, network: string): string {\n  const family = getChainFamily(network);\n\n  if (family === 'solana') {\n    const isDevnet = network.includes('devnet') || network === 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';\n    if (isDevnet) {\n      return `https://solscan.io/tx/${txSignature}?cluster=devnet`;\n    }\n    // Prefer Orb Markets for mainnet\n    return `https://www.orbmarkets.io/tx/${txSignature}`;\n  }\n\n  if (family === 'evm') {\n    // Extract chain ID\n    let chainId = '8453'; // Default to Base\n    if (network.startsWith('eip155:')) {\n      chainId = network.split(':')[1];\n    } else if (network === 'ethereum') {\n      chainId = '1';\n    } else if (network === 'arbitrum') {\n      chainId = '42161';\n    }\n\n    switch (chainId) {\n      case '8453': return `https://basescan.org/tx/${txSignature}`;\n      case '84532': return `https://sepolia.basescan.org/tx/${txSignature}`;\n      case '1': return `https://etherscan.io/tx/${txSignature}`;\n      case '42161': return `https://arbiscan.io/tx/${txSignature}`;\n      default: return `https://basescan.org/tx/${txSignature}`;\n    }\n  }\n\n  return `https://solscan.io/tx/${txSignature}`;\n}\n\n// ============================================================================\n// Encoding Helpers\n// ============================================================================\n\n/**\n * Encode an object as base64 JSON\n */\nexport function encodeBase64Json(obj: unknown): string {\n  return btoa(JSON.stringify(obj));\n}\n\n/**\n * Decode base64 JSON to object\n */\nexport function decodeBase64Json<T>(encoded: string): T {\n  return JSON.parse(atob(encoded)) as T;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACYO,IAAM,yBAAyB;AAG/B,IAAM,uBAAuB;;;ACU7B,SAAS,cAAc,QAAgB,UAA0B;AACtE,QAAM,aAAa,KAAK,IAAI,IAAI,QAAQ;AACxC,SAAO,KAAK,MAAM,SAAS,UAAU,EAAE,SAAS;AAClD;AAeO,SAAS,gBACd,aACA,UACQ;AACR,QAAM,UAAU,KAAK,IAAI,IAAI,QAAQ;AACrC,SAAO,OAAO,WAAW,IAAI;AAC/B;AAuBO,SAAS,eAAe,SAA8B;AAC3D,MAAI,QAAQ,WAAW,SAAS,KAAK,YAAY,UAAU;AACzD,WAAO;AAAA,EACT;AACA,MAAI,QAAQ,WAAW,SAAS,KAAK,CAAC,QAAQ,YAAY,UAAU,EAAE,SAAS,OAAO,GAAG;AACvF,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAkDO,SAAS,aAAa,SAAyB;AACpD,QAAM,UAAkC;AAAA,IACtC,CAAC,sBAAsB,GAAG;AAAA,IAC1B,2CAA2C;AAAA,IAC3C,2CAA2C;AAAA,IAC3C,UAAU;AAAA,IACV,CAAC,oBAAoB,GAAG;AAAA,IACxB,gBAAgB;AAAA,IAChB,YAAY;AAAA,IACZ,gBAAgB;AAAA,IAChB,QAAQ;AAAA,IACR,YAAY;AAAA,IACZ,YAAY;AAAA,EACd;AACA,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAaO,SAAS,eAAe,aAAqB,SAAyB;AAC3E,QAAM,SAAS,eAAe,OAAO;AAErC,MAAI,WAAW,UAAU;AACvB,UAAM,WAAW,QAAQ,SAAS,QAAQ,KAAK,YAAY;AAC3D,QAAI,UAAU;AACZ,aAAO,yBAAyB,WAAW;AAAA,IAC7C;AAEA,WAAO,gCAAgC,WAAW;AAAA,EACpD;AAEA,MAAI,WAAW,OAAO;AAEpB,QAAI,UAAU;AACd,QAAI,QAAQ,WAAW,SAAS,GAAG;AACjC,gBAAU,QAAQ,MAAM,GAAG,EAAE,CAAC;AAAA,IAChC,WAAW,YAAY,YAAY;AACjC,gBAAU;AAAA,IACZ,WAAW,YAAY,YAAY;AACjC,gBAAU;AAAA,IACZ;AAEA,YAAQ,SAAS;AAAA,MACf,KAAK;AAAQ,eAAO,2BAA2B,WAAW;AAAA,MAC1D,KAAK;AAAS,eAAO,mCAAmC,WAAW;AAAA,MACnE,KAAK;AAAK,eAAO,2BAA2B,WAAW;AAAA,MACvD,KAAK;AAAS,eAAO,0BAA0B,WAAW;AAAA,MAC1D;AAAS,eAAO,2BAA2B,WAAW;AAAA,IACxD;AAAA,EACF;AAEA,SAAO,yBAAyB,WAAW;AAC7C;","names":[]}

package/dist/utils/index.d.cts

@@ -0,0 +1,67 @@
+/**
+ * Utility Functions
+ *
+ * Chain-agnostic helpers for x402 payments.
+ */
+/**
+ * Convert human-readable amount to atomic units
+ *
+ * @param amount - Human-readable amount (e.g., 0.05 for $0.05)
+ * @param decimals - Token decimals (e.g., 6 for USDC)
+ * @returns Amount in atomic units as string
+ *
+ * @example
+ * ```typescript
+ * toAtomicUnits(0.05, 6) // '50000'
+ * toAtomicUnits(1.50, 6) // '1500000'
+ * ```
+ */
+declare function toAtomicUnits(amount: number, decimals: number): string;
+/**
+ * Convert atomic units to human-readable amount
+ *
+ * @param atomicUnits - Amount in smallest units
+ * @param decimals - Token decimals
+ * @returns Human-readable amount
+ *
+ * @example
+ * ```typescript
+ * fromAtomicUnits('50000', 6) // 0.05
+ * fromAtomicUnits(1500000n, 6) // 1.5
+ * ```
+ */
+declare function fromAtomicUnits(atomicUnits: string | bigint | number, decimals: number): number;
+/**
+ * Network type
+ */
+type ChainFamily = 'solana' | 'evm' | 'unknown';
+/**
+ * Get the chain family from a CAIP-2 network identifier
+ *
+ * @param network - CAIP-2 network identifier
+ * @returns Chain family
+ *
+ * @example
+ * ```typescript
+ * getChainFamily('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp') // 'solana'
+ * getChainFamily('eip155:8453') // 'evm'
+ * ```
+ */
+declare function getChainFamily(network: string): ChainFamily;
+/**
+ * Get human-readable chain name
+ *
+ * @param network - CAIP-2 network identifier
+ * @returns Human-readable name
+ */
+declare function getChainName(network: string): string;
+/**
+ * Get explorer URL for a transaction
+ *
+ * @param txSignature - Transaction signature/hash
+ * @param network - CAIP-2 network identifier
+ * @returns Explorer URL
+ */
+declare function getExplorerUrl(txSignature: string, network: string): string;
+
+export { type ChainFamily, fromAtomicUnits, getChainFamily, getChainName, getExplorerUrl, toAtomicUnits };

package/dist/utils/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Utility Functions
+ *
+ * Chain-agnostic helpers for x402 payments.
+ */
+/**
+ * Convert human-readable amount to atomic units
+ *
+ * @param amount - Human-readable amount (e.g., 0.05 for $0.05)
+ * @param decimals - Token decimals (e.g., 6 for USDC)
+ * @returns Amount in atomic units as string
+ *
+ * @example
+ * ```typescript
+ * toAtomicUnits(0.05, 6) // '50000'
+ * toAtomicUnits(1.50, 6) // '1500000'
+ * ```
+ */
+declare function toAtomicUnits(amount: number, decimals: number): string;
+/**
+ * Convert atomic units to human-readable amount
+ *
+ * @param atomicUnits - Amount in smallest units
+ * @param decimals - Token decimals
+ * @returns Human-readable amount
+ *
+ * @example
+ * ```typescript
+ * fromAtomicUnits('50000', 6) // 0.05
+ * fromAtomicUnits(1500000n, 6) // 1.5
+ * ```
+ */
+declare function fromAtomicUnits(atomicUnits: string | bigint | number, decimals: number): number;
+/**
+ * Network type
+ */
+type ChainFamily = 'solana' | 'evm' | 'unknown';
+/**
+ * Get the chain family from a CAIP-2 network identifier
+ *
+ * @param network - CAIP-2 network identifier
+ * @returns Chain family
+ *
+ * @example
+ * ```typescript
+ * getChainFamily('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp') // 'solana'
+ * getChainFamily('eip155:8453') // 'evm'
+ * ```
+ */
+declare function getChainFamily(network: string): ChainFamily;
+/**
+ * Get human-readable chain name
+ *
+ * @param network - CAIP-2 network identifier
+ * @returns Human-readable name
+ */
+declare function getChainName(network: string): string;
+/**
+ * Get explorer URL for a transaction
+ *
+ * @param txSignature - Transaction signature/hash
+ * @param network - CAIP-2 network identifier
+ * @returns Explorer URL
+ */
+declare function getExplorerUrl(txSignature: string, network: string): string;
+
+export { type ChainFamily, fromAtomicUnits, getChainFamily, getChainName, getExplorerUrl, toAtomicUnits };

package/dist/utils/index.js

@@ -0,0 +1,79 @@
+// src/types.ts
+var SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+var BASE_MAINNET_NETWORK = "eip155:8453";
+
+// src/utils.ts
+function toAtomicUnits(amount, decimals) {
+  const multiplier = Math.pow(10, decimals);
+  return Math.floor(amount * multiplier).toString();
+}
+function fromAtomicUnits(atomicUnits, decimals) {
+  const divisor = Math.pow(10, decimals);
+  return Number(atomicUnits) / divisor;
+}
+function getChainFamily(network) {
+  if (network.startsWith("solana:") || network === "solana") {
+    return "solana";
+  }
+  if (network.startsWith("eip155:") || ["base", "ethereum", "arbitrum"].includes(network)) {
+    return "evm";
+  }
+  return "unknown";
+}
+function getChainName(network) {
+  const mapping = {
+    [SOLANA_MAINNET_NETWORK]: "Solana",
+    "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": "Solana Devnet",
+    "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z": "Solana Testnet",
+    "solana": "Solana",
+    [BASE_MAINNET_NETWORK]: "Base",
+    "eip155:84532": "Base Sepolia",
+    "eip155:1": "Ethereum",
+    "eip155:42161": "Arbitrum One",
+    "base": "Base",
+    "ethereum": "Ethereum",
+    "arbitrum": "Arbitrum"
+  };
+  return mapping[network] || network;
+}
+function getExplorerUrl(txSignature, network) {
+  const family = getChainFamily(network);
+  if (family === "solana") {
+    const isDevnet = network.includes("devnet") || network === "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+    if (isDevnet) {
+      return `https://solscan.io/tx/${txSignature}?cluster=devnet`;
+    }
+    return `https://www.orbmarkets.io/tx/${txSignature}`;
+  }
+  if (family === "evm") {
+    let chainId = "8453";
+    if (network.startsWith("eip155:")) {
+      chainId = network.split(":")[1];
+    } else if (network === "ethereum") {
+      chainId = "1";
+    } else if (network === "arbitrum") {
+      chainId = "42161";
+    }
+    switch (chainId) {
+      case "8453":
+        return `https://basescan.org/tx/${txSignature}`;
+      case "84532":
+        return `https://sepolia.basescan.org/tx/${txSignature}`;
+      case "1":
+        return `https://etherscan.io/tx/${txSignature}`;
+      case "42161":
+        return `https://arbiscan.io/tx/${txSignature}`;
+      default:
+        return `https://basescan.org/tx/${txSignature}`;
+    }
+  }
+  return `https://solscan.io/tx/${txSignature}`;
+}
+export {
+  fromAtomicUnits,
+  getChainFamily,
+  getChainName,
+  getExplorerUrl,
+  toAtomicUnits
+};
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types.ts","../../src/utils.ts"],"sourcesContent":["/**\n * x402 v2 SDK — Shared Types\n *\n * Chain-agnostic types for x402 v2 payments.\n * Works with Solana, Base, and any future x402-compatible networks.\n */\n\n// ============================================================================\n// Network Constants\n// ============================================================================\n\n/** CAIP-2 network identifier for Solana mainnet */\nexport const SOLANA_MAINNET_NETWORK = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';\n\n/** CAIP-2 network identifier for Base mainnet */\nexport const BASE_MAINNET_NETWORK = 'eip155:8453';\n\n/** Alias for Solana mainnet */\nexport const SOLANA_MAINNET = SOLANA_MAINNET_NETWORK;\n\n/** Alias for Base mainnet */\nexport const BASE_MAINNET = BASE_MAINNET_NETWORK;\n\n// ============================================================================\n// Asset Constants\n// ============================================================================\n\n/** USDC mint on Solana mainnet */\nexport const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';\n\n/** USDC address on Base mainnet */\nexport const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';\n\n// ============================================================================\n// Facilitator Constants\n// ============================================================================\n\n/** Dexter's public x402 v2 facilitator URL */\nexport const DEXTER_FACILITATOR_URL = 'https://x402.dexter.cash';\n\n// ============================================================================\n// Payment Types\n// ============================================================================\n\n/**\n * Asset configuration for payments\n */\nexport interface AssetConfig {\n  /** Token address (mint on Solana, contract on EVM) */\n  address: string;\n  /** Token decimals */\n  decimals: number;\n  /** Optional: Human-readable symbol */\n  symbol?: string;\n}\n\n/**\n * Resource info included in payment requirements\n */\nexport interface ResourceInfo {\n  /** Resource URL */\n  url: string;\n  /** Human-readable description */\n  description?: string;\n  /** MIME type of the resource */\n  mimeType?: string;\n}\n\n/**\n * Extra fields in payment requirements\n * Chain-specific fields may vary\n */\nexport interface AcceptsExtra {\n  /** Facilitator address that pays tx fees (required) */\n  feePayer: string;\n  /** Token decimals (required) */\n  decimals: number;\n  /** EIP-712: Token name (EVM only) */\n  name?: string;\n  /** EIP-712: Token version (EVM only) */\n  version?: string;\n  /** Additional chain-specific fields */\n  [key: string]: unknown;\n}\n\n/**\n * A single payment option in the accepts array\n */\nexport interface PaymentAccept {\n  /** Payment scheme (always 'exact' for x402 v2) */\n  scheme: 'exact';\n  /** CAIP-2 network identifier */\n  network: string;\n  /** Payment amount in atomic units (as string to avoid precision loss) */\n  amount: string;\n  /** Token address */\n  asset: string;\n  /** Seller's address to receive payment */\n  payTo: string;\n  /** Maximum seconds until payment expires */\n  maxTimeoutSeconds: number;\n  /** Chain-specific extra data */\n  extra: AcceptsExtra;\n}\n\n/**\n * Full PaymentRequired structure (sent in PAYMENT-REQUIRED header)\n */\nexport interface PaymentRequired {\n  /** x402 version (always 2) */\n  x402Version: 2;\n  /** Resource being accessed */\n  resource: ResourceInfo;\n  /** Available payment options */\n  accepts: PaymentAccept[];\n  /** Optional error message */\n  error?: string;\n}\n\n/**\n * PaymentSignature structure (sent in PAYMENT-SIGNATURE header)\n */\nexport interface PaymentSignature {\n  /** x402 version (always 2) */\n  x402Version: 2;\n  /** Resource being accessed */\n  resource: ResourceInfo;\n  /** The payment option that was accepted */\n  accepted: PaymentAccept;\n  /** The signed payment */\n  payload: {\n    /** Signed transaction (base64 for Solana, JSON for EVM) */\n    transaction: string;\n  };\n}\n\n// ============================================================================\n// Facilitator Response Types\n// ============================================================================\n\n/**\n * Response from /verify endpoint\n */\nexport interface VerifyResponse {\n  /** Whether the payment is valid */\n  isValid: boolean;\n  /** Reason for invalidity (if invalid) */\n  invalidReason?: string;\n  /** Payer address */\n  payer?: string;\n}\n\n/**\n * Response from /settle endpoint\n */\nexport interface SettleResponse {\n  /** Whether settlement succeeded */\n  success: boolean;\n  /** Transaction signature/hash */\n  transaction?: string;\n  /** Network the payment was made on */\n  network: string;\n  /** Error reason (if failed) */\n  errorReason?: string;\n  /** Error code (if failed) */\n  errorCode?: string;\n  /** Payer address */\n  payer?: string;\n}\n\n// ============================================================================\n// Error Types\n// ============================================================================\n\n/**\n * SDK error codes\n */\nexport type X402ErrorCode =\n  // Client errors\n  | 'missing_payment_required_header'\n  | 'invalid_payment_required'\n  | 'unsupported_network'\n  | 'no_matching_payment_option'\n  | 'no_solana_accept' // Legacy, kept for compatibility\n  | 'missing_fee_payer'\n  | 'missing_decimals'\n  | 'amount_exceeds_max'\n  | 'insufficient_balance'\n  | 'wallet_missing_sign_transaction'\n  | 'wallet_not_connected'\n  | 'transaction_build_failed'\n  | 'payment_rejected'\n  // Server errors\n  | 'invalid_payment_signature'\n  | 'facilitator_verify_failed'\n  | 'facilitator_settle_failed'\n  | 'facilitator_request_failed'\n  | 'no_matching_requirement';\n\n/**\n * Custom error class for x402 operations\n */\nexport class X402Error extends Error {\n  /** Error code for programmatic handling */\n  code: X402ErrorCode;\n  /** Additional error details */\n  details?: unknown;\n\n  constructor(code: X402ErrorCode, message: string, details?: unknown) {\n    super(message);\n    this.name = 'X402Error';\n    this.code = code;\n    this.details = details;\n    // Maintain proper prototype chain\n    Object.setPrototypeOf(this, X402Error.prototype);\n  }\n}\n","/**\n * Utility Functions\n *\n * Chain-agnostic helpers for x402 payments.\n */\n\nimport { SOLANA_MAINNET_NETWORK, BASE_MAINNET_NETWORK } from './types';\n\n// ============================================================================\n// Amount Conversion\n// ============================================================================\n\n/**\n * Convert human-readable amount to atomic units\n *\n * @param amount - Human-readable amount (e.g., 0.05 for $0.05)\n * @param decimals - Token decimals (e.g., 6 for USDC)\n * @returns Amount in atomic units as string\n *\n * @example\n * ```typescript\n * toAtomicUnits(0.05, 6) // '50000'\n * toAtomicUnits(1.50, 6) // '1500000'\n * ```\n */\nexport function toAtomicUnits(amount: number, decimals: number): string {\n  const multiplier = Math.pow(10, decimals);\n  return Math.floor(amount * multiplier).toString();\n}\n\n/**\n * Convert atomic units to human-readable amount\n *\n * @param atomicUnits - Amount in smallest units\n * @param decimals - Token decimals\n * @returns Human-readable amount\n *\n * @example\n * ```typescript\n * fromAtomicUnits('50000', 6) // 0.05\n * fromAtomicUnits(1500000n, 6) // 1.5\n * ```\n */\nexport function fromAtomicUnits(\n  atomicUnits: string | bigint | number,\n  decimals: number\n): number {\n  const divisor = Math.pow(10, decimals);\n  return Number(atomicUnits) / divisor;\n}\n\n// ============================================================================\n// Network Helpers\n// ============================================================================\n\n/**\n * Network type\n */\nexport type ChainFamily = 'solana' | 'evm' | 'unknown';\n\n/**\n * Get the chain family from a CAIP-2 network identifier\n *\n * @param network - CAIP-2 network identifier\n * @returns Chain family\n *\n * @example\n * ```typescript\n * getChainFamily('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp') // 'solana'\n * getChainFamily('eip155:8453') // 'evm'\n * ```\n */\nexport function getChainFamily(network: string): ChainFamily {\n  if (network.startsWith('solana:') || network === 'solana') {\n    return 'solana';\n  }\n  if (network.startsWith('eip155:') || ['base', 'ethereum', 'arbitrum'].includes(network)) {\n    return 'evm';\n  }\n  return 'unknown';\n}\n\n/**\n * Get default RPC URL for a network\n *\n * @param network - CAIP-2 network identifier\n * @returns Default RPC URL\n */\nexport function getDefaultRpcUrl(network: string): string {\n  const family = getChainFamily(network);\n\n  if (family === 'solana') {\n    if (network.includes('devnet') || network === 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1') {\n      return 'https://api.devnet.solana.com';\n    }\n    if (network.includes('testnet') || network === 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z') {\n      return 'https://api.testnet.solana.com';\n    }\n    return 'https://api.mainnet-beta.solana.com';\n  }\n\n  if (family === 'evm') {\n    // Extract chain ID from CAIP-2\n    if (network.startsWith('eip155:')) {\n      const chainId = network.split(':')[1];\n      switch (chainId) {\n        case '8453': return 'https://mainnet.base.org';\n        case '84532': return 'https://sepolia.base.org';\n        case '1': return 'https://eth.llamarpc.com';\n        case '42161': return 'https://arb1.arbitrum.io/rpc';\n        default: return 'https://mainnet.base.org';\n      }\n    }\n    // Legacy names\n    if (network === 'base') return 'https://mainnet.base.org';\n    if (network === 'ethereum') return 'https://eth.llamarpc.com';\n    if (network === 'arbitrum') return 'https://arb1.arbitrum.io/rpc';\n    return 'https://mainnet.base.org';\n  }\n\n  // Unknown - return a generic\n  return 'https://api.mainnet-beta.solana.com';\n}\n\n/**\n * Get human-readable chain name\n *\n * @param network - CAIP-2 network identifier\n * @returns Human-readable name\n */\nexport function getChainName(network: string): string {\n  const mapping: Record<string, string> = {\n    [SOLANA_MAINNET_NETWORK]: 'Solana',\n    'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1': 'Solana Devnet',\n    'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z': 'Solana Testnet',\n    'solana': 'Solana',\n    [BASE_MAINNET_NETWORK]: 'Base',\n    'eip155:84532': 'Base Sepolia',\n    'eip155:1': 'Ethereum',\n    'eip155:42161': 'Arbitrum One',\n    'base': 'Base',\n    'ethereum': 'Ethereum',\n    'arbitrum': 'Arbitrum',\n  };\n  return mapping[network] || network;\n}\n\n// ============================================================================\n// Transaction URL Helpers\n// ============================================================================\n\n/**\n * Get explorer URL for a transaction\n *\n * @param txSignature - Transaction signature/hash\n * @param network - CAIP-2 network identifier\n * @returns Explorer URL\n */\nexport function getExplorerUrl(txSignature: string, network: string): string {\n  const family = getChainFamily(network);\n\n  if (family === 'solana') {\n    const isDevnet = network.includes('devnet') || network === 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';\n    if (isDevnet) {\n      return `https://solscan.io/tx/${txSignature}?cluster=devnet`;\n    }\n    // Prefer Orb Markets for mainnet\n    return `https://www.orbmarkets.io/tx/${txSignature}`;\n  }\n\n  if (family === 'evm') {\n    // Extract chain ID\n    let chainId = '8453'; // Default to Base\n    if (network.startsWith('eip155:')) {\n      chainId = network.split(':')[1];\n    } else if (network === 'ethereum') {\n      chainId = '1';\n    } else if (network === 'arbitrum') {\n      chainId = '42161';\n    }\n\n    switch (chainId) {\n      case '8453': return `https://basescan.org/tx/${txSignature}`;\n      case '84532': return `https://sepolia.basescan.org/tx/${txSignature}`;\n      case '1': return `https://etherscan.io/tx/${txSignature}`;\n      case '42161': return `https://arbiscan.io/tx/${txSignature}`;\n      default: return `https://basescan.org/tx/${txSignature}`;\n    }\n  }\n\n  return `https://solscan.io/tx/${txSignature}`;\n}\n\n// ============================================================================\n// Encoding Helpers\n// ============================================================================\n\n/**\n * Encode an object as base64 JSON\n */\nexport function encodeBase64Json(obj: unknown): string {\n  return btoa(JSON.stringify(obj));\n}\n\n/**\n * Decode base64 JSON to object\n */\nexport function decodeBase64Json<T>(encoded: string): T {\n  return JSON.parse(atob(encoded)) as T;\n}\n"],"mappings":";AAYO,IAAM,yBAAyB;AAG/B,IAAM,uBAAuB;;;ACU7B,SAAS,cAAc,QAAgB,UAA0B;AACtE,QAAM,aAAa,KAAK,IAAI,IAAI,QAAQ;AACxC,SAAO,KAAK,MAAM,SAAS,UAAU,EAAE,SAAS;AAClD;AAeO,SAAS,gBACd,aACA,UACQ;AACR,QAAM,UAAU,KAAK,IAAI,IAAI,QAAQ;AACrC,SAAO,OAAO,WAAW,IAAI;AAC/B;AAuBO,SAAS,eAAe,SAA8B;AAC3D,MAAI,QAAQ,WAAW,SAAS,KAAK,YAAY,UAAU;AACzD,WAAO;AAAA,EACT;AACA,MAAI,QAAQ,WAAW,SAAS,KAAK,CAAC,QAAQ,YAAY,UAAU,EAAE,SAAS,OAAO,GAAG;AACvF,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAkDO,SAAS,aAAa,SAAyB;AACpD,QAAM,UAAkC;AAAA,IACtC,CAAC,sBAAsB,GAAG;AAAA,IAC1B,2CAA2C;AAAA,IAC3C,2CAA2C;AAAA,IAC3C,UAAU;AAAA,IACV,CAAC,oBAAoB,GAAG;AAAA,IACxB,gBAAgB;AAAA,IAChB,YAAY;AAAA,IACZ,gBAAgB;AAAA,IAChB,QAAQ;AAAA,IACR,YAAY;AAAA,IACZ,YAAY;AAAA,EACd;AACA,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAaO,SAAS,eAAe,aAAqB,SAAyB;AAC3E,QAAM,SAAS,eAAe,OAAO;AAErC,MAAI,WAAW,UAAU;AACvB,UAAM,WAAW,QAAQ,SAAS,QAAQ,KAAK,YAAY;AAC3D,QAAI,UAAU;AACZ,aAAO,yBAAyB,WAAW;AAAA,IAC7C;AAEA,WAAO,gCAAgC,WAAW;AAAA,EACpD;AAEA,MAAI,WAAW,OAAO;AAEpB,QAAI,UAAU;AACd,QAAI,QAAQ,WAAW,SAAS,GAAG;AACjC,gBAAU,QAAQ,MAAM,GAAG,EAAE,CAAC;AAAA,IAChC,WAAW,YAAY,YAAY;AACjC,gBAAU;AAAA,IACZ,WAAW,YAAY,YAAY;AACjC,gBAAU;AAAA,IACZ;AAEA,YAAQ,SAAS;AAAA,MACf,KAAK;AAAQ,eAAO,2BAA2B,WAAW;AAAA,MAC1D,KAAK;AAAS,eAAO,mCAAmC,WAAW;AAAA,MACnE,KAAK;AAAK,eAAO,2BAA2B,WAAW;AAAA,MACvD,KAAK;AAAS,eAAO,0BAA0B,WAAW;AAAA,MAC1D;AAAS,eAAO,2BAA2B,WAAW;AAAA,IACxD;AAAA,EACF;AAEA,SAAO,yBAAyB,WAAW;AAC7C;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexterai/x402",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Chain-agnostic x402 v2 SDK for Solana, Base, and EVM payments",
   "author": "Dexter",
   "license": "MIT",
@@ -25,6 +25,11 @@
       "types": "./dist/adapters/index.d.ts",
       "import": "./dist/adapters/index.js",
       "require": "./dist/adapters/index.cjs"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js",
+      "require": "./dist/utils/index.cjs"
     }
   },
   "files": [
@@ -37,7 +42,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "echo 'Real payment tests require funded wallets. Run: npx tsx test/real-payment-solana.ts'",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build",
     "release": "npm version patch && npm publish --access public",
@@ -90,7 +95,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Dexter-DAO/x402-sdk"
+    "url": "https://github.com/Dexter-DAO/dexter-x402-sdk"
   },
   "homepage": "https://dexter.cash/sdk",
   "bugs": {