@mixrpay/agent-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,982 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentWallet: () => AgentWallet,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  DEFAULT_FACILITATOR_URL: () => DEFAULT_FACILITATOR_URL,
+  DEFAULT_TIMEOUT: () => DEFAULT_TIMEOUT,
+  InsufficientBalanceError: () => InsufficientBalanceError,
+  InvalidSessionKeyError: () => InvalidSessionKeyError,
+  MixrPayError: () => MixrPayError,
+  NETWORKS: () => NETWORKS,
+  PaymentFailedError: () => PaymentFailedError,
+  SDK_VERSION: () => SDK_VERSION,
+  SessionKey: () => SessionKey,
+  SessionKeyExpiredError: () => SessionKeyExpiredError,
+  SpendingLimitExceededError: () => SpendingLimitExceededError,
+  X402ProtocolError: () => X402ProtocolError,
+  buildTransferAuthorizationData: () => buildTransferAuthorizationData,
+  buildXPaymentHeader: () => buildXPaymentHeader,
+  generateNonce: () => generateNonce,
+  getAmountUsd: () => getAmountUsd,
+  getErrorMessage: () => getErrorMessage,
+  isMixrPayError: () => isMixrPayError,
+  isPaymentExpired: () => isPaymentExpired,
+  parse402Response: () => parse402Response,
+  validatePaymentAmount: () => validatePaymentAmount
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/session-key.ts
+var import_accounts = require("viem/accounts");
+
+// src/errors.ts
+var MixrPayError = class extends Error {
+  /** Error code for programmatic handling */
+  code;
+  constructor(message, code = "MIXRPAY_ERROR") {
+    super(message);
+    this.name = "MixrPayError";
+    this.code = code;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var InsufficientBalanceError = class extends MixrPayError {
+  /** Amount required for the payment in USD */
+  required;
+  /** Current available balance in USD */
+  available;
+  /** URL where the user can top up their wallet */
+  topUpUrl;
+  constructor(required, available) {
+    const shortage = required - available;
+    super(
+      `Insufficient balance: need $${required.toFixed(2)}, have $${available.toFixed(2)} (short $${shortage.toFixed(2)}). Top up your wallet to continue.`,
+      "INSUFFICIENT_BALANCE"
+    );
+    this.name = "InsufficientBalanceError";
+    this.required = required;
+    this.available = available;
+    this.topUpUrl = "/wallet";
+  }
+};
+var SessionKeyExpiredError = class extends MixrPayError {
+  /** When the session key expired */
+  expiredAt;
+  constructor(expiredAt) {
+    super(
+      `Session key expired at ${expiredAt}. Request a new session key from the wallet owner or create one at your MixrPay server /wallet/sessions`,
+      "SESSION_KEY_EXPIRED"
+    );
+    this.name = "SessionKeyExpiredError";
+    this.expiredAt = expiredAt;
+  }
+};
+var SpendingLimitExceededError = class extends MixrPayError {
+  /** Type of limit that was exceeded */
+  limitType;
+  /** The limit amount in USD */
+  limit;
+  /** The amount that was attempted in USD */
+  attempted;
+  constructor(limitType, limit, attempted) {
+    const limitNames = {
+      per_tx: "Per-transaction",
+      daily: "Daily",
+      total: "Total",
+      client_max: "Client-side"
+    };
+    const limitName = limitNames[limitType] || limitType;
+    const suggestion = limitType === "daily" ? "Wait until tomorrow or request a higher limit." : limitType === "client_max" ? "Increase maxPaymentUsd in your AgentWallet configuration." : "Request a new session key with a higher limit.";
+    super(
+      `${limitName} spending limit exceeded: limit is $${limit.toFixed(2)}, attempted $${attempted.toFixed(2)}. ${suggestion}`,
+      "SPENDING_LIMIT_EXCEEDED"
+    );
+    this.name = "SpendingLimitExceededError";
+    this.limitType = limitType;
+    this.limit = limit;
+    this.attempted = attempted;
+  }
+};
+var PaymentFailedError = class extends MixrPayError {
+  /** Detailed reason for the failure */
+  reason;
+  /** Transaction hash if the tx was submitted (for debugging) */
+  txHash;
+  constructor(reason, txHash) {
+    let message = `Payment failed: ${reason}`;
+    if (txHash) {
+      message += ` (tx: ${txHash} - check on basescan.org)`;
+    }
+    super(message, "PAYMENT_FAILED");
+    this.name = "PaymentFailedError";
+    this.reason = reason;
+    this.txHash = txHash;
+  }
+};
+var InvalidSessionKeyError = class extends MixrPayError {
+  /** Detailed reason why the key is invalid */
+  reason;
+  constructor(reason = "Invalid session key format") {
+    super(
+      `${reason}. Session keys should be in format: sk_live_<64 hex chars> or sk_test_<64 hex chars>. Get one from your MixrPay server /wallet/sessions`,
+      "INVALID_SESSION_KEY"
+    );
+    this.name = "InvalidSessionKeyError";
+    this.reason = reason;
+  }
+};
+var X402ProtocolError = class extends MixrPayError {
+  /** Detailed reason for the protocol error */
+  reason;
+  constructor(reason) {
+    super(
+      `x402 protocol error: ${reason}. This may indicate a server configuration issue. If the problem persists, contact the API provider.`,
+      "X402_PROTOCOL_ERROR"
+    );
+    this.name = "X402ProtocolError";
+    this.reason = reason;
+  }
+};
+function isMixrPayError(error) {
+  return error instanceof MixrPayError;
+}
+function getErrorMessage(error) {
+  if (error instanceof MixrPayError) {
+    return error.message;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+// src/session-key.ts
+var USDC_ADDRESSES = {
+  8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  // Base Mainnet
+  84532: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+  // Base Sepolia
+};
+var USDC_EIP712_DOMAIN_BASE = {
+  name: "USD Coin",
+  version: "2"
+};
+var TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+var SessionKey = class _SessionKey {
+  privateKey;
+  account;
+  address;
+  isTest;
+  constructor(privateKey, isTest) {
+    this.privateKey = privateKey;
+    this.account = (0, import_accounts.privateKeyToAccount)(privateKey);
+    this.address = this.account.address;
+    this.isTest = isTest;
+  }
+  /**
+   * Parse a session key string into a SessionKey object.
+   * 
+   * @param sessionKey - Session key in format sk_live_... or sk_test_...
+   * @returns SessionKey object
+   * @throws InvalidSessionKeyError if the format is invalid
+   */
+  static fromString(sessionKey) {
+    const pattern = /^sk_(live|test)_([a-fA-F0-9]{64})$/;
+    const match = sessionKey.match(pattern);
+    if (!match) {
+      throw new InvalidSessionKeyError(
+        "Session key must be in format sk_live_{64_hex} or sk_test_{64_hex}"
+      );
+    }
+    const env = match[1];
+    const hexKey = match[2];
+    try {
+      const privateKey = `0x${hexKey}`;
+      return new _SessionKey(privateKey, env === "test");
+    } catch (e) {
+      throw new InvalidSessionKeyError(`Failed to decode session key: ${e}`);
+    }
+  }
+  /**
+   * Sign EIP-712 typed data for TransferWithAuthorization.
+   * 
+   * @param domain - EIP-712 domain
+   * @param message - Transfer authorization message
+   * @returns Hex-encoded signature
+   */
+  async signTransferAuthorization(domain, message) {
+    return (0, import_accounts.signTypedData)({
+      privateKey: this.privateKey,
+      domain,
+      types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+      primaryType: "TransferWithAuthorization",
+      message
+    });
+  }
+  /**
+   * Get the chain ID based on whether this is a test key.
+   */
+  getDefaultChainId() {
+    return this.isTest ? 84532 : 8453;
+  }
+};
+function buildTransferAuthorizationData(params) {
+  const usdcAddress = USDC_ADDRESSES[params.chainId];
+  if (!usdcAddress) {
+    throw new Error(`USDC not supported on chain ${params.chainId}`);
+  }
+  const domain = {
+    ...USDC_EIP712_DOMAIN_BASE,
+    chainId: params.chainId,
+    verifyingContract: usdcAddress
+  };
+  const message = {
+    from: params.fromAddress,
+    to: params.toAddress,
+    value: params.value,
+    validAfter: params.validAfter,
+    validBefore: params.validBefore,
+    nonce: params.nonce
+  };
+  return { domain, message };
+}
+function generateNonce() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `0x${Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+// src/x402.ts
+async function parse402Response(response) {
+  let paymentData = null;
+  const paymentHeader = response.headers.get("X-Payment-Required");
+  if (paymentHeader) {
+    try {
+      paymentData = JSON.parse(paymentHeader);
+    } catch {
+    }
+  }
+  if (!paymentData) {
+    const authHeader = response.headers.get("WWW-Authenticate");
+    if (authHeader?.startsWith("X-402 ")) {
+      try {
+        const encoded = authHeader.slice(6);
+        paymentData = JSON.parse(atob(encoded));
+      } catch {
+      }
+    }
+  }
+  if (!paymentData) {
+    try {
+      paymentData = await response.json();
+    } catch {
+    }
+  }
+  if (!paymentData) {
+    throw new X402ProtocolError("Could not parse payment requirements from 402 response");
+  }
+  if (!paymentData.recipient) {
+    throw new X402ProtocolError("Missing recipient in payment requirements");
+  }
+  if (!paymentData.amount) {
+    throw new X402ProtocolError("Missing amount in payment requirements");
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  return {
+    recipient: paymentData.recipient,
+    amount: BigInt(paymentData.amount),
+    currency: paymentData.currency || "USDC",
+    chainId: paymentData.chainId || paymentData.chain_id || 8453,
+    facilitatorUrl: paymentData.facilitatorUrl || paymentData.facilitator_url || "https://x402.org/facilitator",
+    nonce: paymentData.nonce || generateNonce().slice(2),
+    // Remove 0x prefix for storage
+    expiresAt: paymentData.expiresAt || paymentData.expires_at || now + 300,
+    description: paymentData.description
+  };
+}
+async function buildXPaymentHeader(requirements, sessionKey, walletAddress) {
+  const nonceHex = requirements.nonce.length === 64 ? `0x${requirements.nonce}` : generateNonce();
+  const now = BigInt(Math.floor(Date.now() / 1e3));
+  const validAfter = now - 60n;
+  const validBefore = BigInt(requirements.expiresAt);
+  const { domain, message } = buildTransferAuthorizationData({
+    fromAddress: walletAddress,
+    toAddress: requirements.recipient,
+    value: requirements.amount,
+    validAfter,
+    validBefore,
+    nonce: nonceHex,
+    chainId: requirements.chainId
+  });
+  const signature = await sessionKey.signTransferAuthorization(domain, message);
+  const paymentPayload = {
+    x402Version: 1,
+    scheme: "exact",
+    network: requirements.chainId === 8453 ? "base" : "base-sepolia",
+    payload: {
+      signature,
+      authorization: {
+        from: walletAddress,
+        to: requirements.recipient,
+        value: requirements.amount.toString(),
+        validAfter: validAfter.toString(),
+        validBefore: validBefore.toString(),
+        nonce: nonceHex
+      }
+    }
+  };
+  return btoa(JSON.stringify(paymentPayload));
+}
+function isPaymentExpired(requirements) {
+  return Date.now() / 1e3 > requirements.expiresAt;
+}
+function getAmountUsd(requirements) {
+  return Number(requirements.amount) / 1e6;
+}
+function validatePaymentAmount(amountUsd, maxPaymentUsd) {
+  if (amountUsd <= 0) {
+    throw new X402ProtocolError(`Invalid payment amount: $${amountUsd.toFixed(2)}`);
+  }
+  if (maxPaymentUsd !== void 0 && amountUsd > maxPaymentUsd) {
+    throw new X402ProtocolError(
+      `Payment amount $${amountUsd.toFixed(2)} exceeds client limit $${maxPaymentUsd.toFixed(2)}`
+    );
+  }
+}
+
+// src/agent-wallet.ts
+var SDK_VERSION = "0.1.0";
+var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "http://localhost:3000";
+var DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
+var DEFAULT_TIMEOUT = 3e4;
+var NETWORKS = {
+  BASE_MAINNET: { chainId: 8453, name: "Base", isTestnet: false },
+  BASE_SEPOLIA: { chainId: 84532, name: "Base Sepolia", isTestnet: true }
+};
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4
+};
+var Logger = class {
+  level;
+  prefix;
+  constructor(level = "none", prefix = "[MixrPay]") {
+    this.level = level;
+    this.prefix = prefix;
+  }
+  setLevel(level) {
+    this.level = level;
+  }
+  shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+  }
+  debug(...args) {
+    if (this.shouldLog("debug")) {
+      console.log(`${this.prefix} \u{1F50D}`, ...args);
+    }
+  }
+  info(...args) {
+    if (this.shouldLog("info")) {
+      console.log(`${this.prefix} \u2139\uFE0F`, ...args);
+    }
+  }
+  warn(...args) {
+    if (this.shouldLog("warn")) {
+      console.warn(`${this.prefix} \u26A0\uFE0F`, ...args);
+    }
+  }
+  error(...args) {
+    if (this.shouldLog("error")) {
+      console.error(`${this.prefix} \u274C`, ...args);
+    }
+  }
+  payment(amount, recipient, description) {
+    if (this.shouldLog("info")) {
+      const desc = description ? ` for "${description}"` : "";
+      console.log(`${this.prefix} \u{1F4B8} Paid $${amount.toFixed(4)} to ${recipient.slice(0, 10)}...${desc}`);
+    }
+  }
+};
+var AgentWallet = class {
+  sessionKey;
+  walletAddress;
+  maxPaymentUsd;
+  onPayment;
+  baseUrl;
+  timeout;
+  logger;
+  // Payment tracking
+  payments = [];
+  totalSpentUsd = 0;
+  // Session key info cache
+  sessionKeyInfo;
+  sessionKeyInfoFetchedAt;
+  /**
+   * Create a new AgentWallet instance.
+   * 
+   * @param config - Configuration options
+   * @throws {InvalidSessionKeyError} If the session key format is invalid
+   * 
+   * @example Basic initialization
+   * ```typescript
+   * const wallet = new AgentWallet({
+   *   sessionKey: 'sk_live_abc123...'
+   * });
+   * ```
+   * 
+   * @example With all options
+   * ```typescript
+   * const wallet = new AgentWallet({
+   *   sessionKey: 'sk_live_abc123...',
+   *   maxPaymentUsd: 5.0,           // Client-side safety limit
+   *   onPayment: (p) => log(p),     // Track payments
+   *   logLevel: 'info',             // Enable logging
+   *   timeout: 60000,               // 60s timeout
+   * });
+   * ```
+   */
+  constructor(config) {
+    this.validateConfig(config);
+    this.sessionKey = SessionKey.fromString(config.sessionKey);
+    this.walletAddress = config.walletAddress || this.sessionKey.address;
+    this.maxPaymentUsd = config.maxPaymentUsd;
+    this.onPayment = config.onPayment;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.logger = new Logger(config.logLevel || "none");
+    this.logger.debug("AgentWallet initialized", {
+      walletAddress: this.walletAddress,
+      isTestnet: this.isTestnet(),
+      maxPaymentUsd: this.maxPaymentUsd
+    });
+  }
+  /**
+   * Validate the configuration before initialization.
+   */
+  validateConfig(config) {
+    if (!config.sessionKey) {
+      throw new InvalidSessionKeyError(
+        "Session key is required. Get one from the wallet owner or create one at your MixrPay server /wallet/sessions"
+      );
+    }
+    const key = config.sessionKey.trim();
+    if (!key.startsWith("sk_live_") && !key.startsWith("sk_test_")) {
+      throw new InvalidSessionKeyError(
+        `Invalid session key prefix. Expected 'sk_live_' (mainnet) or 'sk_test_' (testnet), got '${key.slice(0, 10)}...'`
+      );
+    }
+    const expectedLength = 8 + 64;
+    if (key.length !== expectedLength) {
+      throw new InvalidSessionKeyError(
+        `Invalid session key length. Expected ${expectedLength} characters, got ${key.length}. Make sure you copied the complete key.`
+      );
+    }
+    const hexPortion = key.slice(8);
+    if (!/^[0-9a-fA-F]+$/.test(hexPortion)) {
+      throw new InvalidSessionKeyError(
+        "Invalid session key format. The key should contain only hexadecimal characters after the prefix."
+      );
+    }
+    if (config.maxPaymentUsd !== void 0) {
+      if (config.maxPaymentUsd <= 0) {
+        throw new MixrPayError("maxPaymentUsd must be a positive number");
+      }
+      if (config.maxPaymentUsd > 1e4) {
+        this.logger?.warn("maxPaymentUsd is very high ($" + config.maxPaymentUsd + "). Consider using a lower limit for safety.");
+      }
+    }
+  }
+  // ===========================================================================
+  // Core Methods
+  // ===========================================================================
+  /**
+   * Make an HTTP request, automatically handling x402 payment if required.
+   * 
+   * This is a drop-in replacement for the native `fetch()` function.
+   * If the server returns 402 Payment Required:
+   * 1. Parse payment requirements from response
+   * 2. Sign transferWithAuthorization using session key
+   * 3. Retry request with X-PAYMENT header
+   * 
+   * @param url - Request URL
+   * @param init - Request options (same as native fetch)
+   * @returns Response from the server
+   * 
+   * @throws {InsufficientBalanceError} If wallet doesn't have enough USDC
+   * @throws {SessionKeyExpiredError} If session key has expired
+   * @throws {SpendingLimitExceededError} If payment would exceed limits
+   * @throws {PaymentFailedError} If payment transaction failed
+   * 
+   * @example GET request
+   * ```typescript
+   * const response = await wallet.fetch('https://api.example.com/data');
+   * const data = await response.json();
+   * ```
+   * 
+   * @example POST request with JSON
+   * ```typescript
+   * const response = await wallet.fetch('https://api.example.com/generate', {
+   *   method: 'POST',
+   *   headers: { 'Content-Type': 'application/json' },
+   *   body: JSON.stringify({ prompt: 'Hello world' })
+   * });
+   * ```
+   */
+  async fetch(url, init) {
+    this.logger.debug(`Fetching ${init?.method || "GET"} ${url}`);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      let response = await fetch(url, {
+        ...init,
+        signal: controller.signal
+      });
+      this.logger.debug(`Initial response: ${response.status}`);
+      if (response.status === 402) {
+        this.logger.info(`Payment required for ${url}`);
+        response = await this.handlePaymentRequired(url, init, response);
+      }
+      return response;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new MixrPayError(`Request timeout after ${this.timeout}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Handle a 402 Payment Required response.
+   */
+  async handlePaymentRequired(url, init, response) {
+    let requirements;
+    try {
+      requirements = await parse402Response(response);
+      this.logger.debug("Payment requirements:", {
+        amount: `$${getAmountUsd(requirements).toFixed(4)}`,
+        recipient: requirements.recipient,
+        description: requirements.description
+      });
+    } catch (e) {
+      this.logger.error("Failed to parse payment requirements:", e);
+      throw new PaymentFailedError(
+        `Failed to parse payment requirements: ${e}. The server may not be properly configured for x402 payments.`
+      );
+    }
+    if (isPaymentExpired(requirements)) {
+      throw new PaymentFailedError(
+        "Payment requirements have expired. This usually means the request took too long. Try again."
+      );
+    }
+    const amountUsd = getAmountUsd(requirements);
+    if (this.maxPaymentUsd !== void 0 && amountUsd > this.maxPaymentUsd) {
+      throw new SpendingLimitExceededError(
+        "client_max",
+        this.maxPaymentUsd,
+        amountUsd
+      );
+    }
+    let xPayment;
+    try {
+      this.logger.debug("Signing payment authorization...");
+      xPayment = await buildXPaymentHeader(
+        requirements,
+        this.sessionKey,
+        this.walletAddress
+      );
+    } catch (e) {
+      this.logger.error("Failed to sign payment:", e);
+      throw new PaymentFailedError(
+        `Failed to sign payment: ${e}. This may indicate an issue with the session key.`
+      );
+    }
+    this.logger.debug("Retrying request with payment...");
+    const headers = new Headers(init?.headers);
+    headers.set("X-PAYMENT", xPayment);
+    const retryResponse = await fetch(url, {
+      ...init,
+      headers
+    });
+    if (retryResponse.status !== 402) {
+      const payment = {
+        amountUsd,
+        recipient: requirements.recipient,
+        txHash: retryResponse.headers.get("X-Payment-TxHash"),
+        timestamp: /* @__PURE__ */ new Date(),
+        description: requirements.description,
+        url
+      };
+      this.payments.push(payment);
+      this.totalSpentUsd += amountUsd;
+      this.logger.payment(amountUsd, requirements.recipient, requirements.description);
+      if (this.onPayment) {
+        this.onPayment(payment);
+      }
+    } else {
+      await this.handlePaymentError(retryResponse);
+    }
+    return retryResponse;
+  }
+  /**
+   * Handle payment-specific errors from the response.
+   */
+  async handlePaymentError(response) {
+    let errorData = {};
+    try {
+      errorData = await response.json();
+    } catch {
+    }
+    const errorCode = errorData.error_code || "";
+    const errorMessage = errorData.error || errorData.message || "Payment required";
+    this.logger.error("Payment failed:", { errorCode, errorMessage, errorData });
+    if (errorCode === "insufficient_balance") {
+      const required = errorData.required || 0;
+      const available = errorData.available || 0;
+      throw new InsufficientBalanceError(required, available);
+    } else if (errorCode === "session_key_expired") {
+      throw new SessionKeyExpiredError(errorData.expired_at || "unknown");
+    } else if (errorCode === "spending_limit_exceeded") {
+      throw new SpendingLimitExceededError(
+        errorData.limit_type || "unknown",
+        errorData.limit || 0,
+        errorData.attempted || 0
+      );
+    } else {
+      throw new PaymentFailedError(errorMessage);
+    }
+  }
+  // ===========================================================================
+  // Wallet Information
+  // ===========================================================================
+  /**
+   * Get the wallet address.
+   * 
+   * @returns The Ethereum address of the smart wallet
+   */
+  getWalletAddress() {
+    return this.walletAddress;
+  }
+  /**
+   * Check if using testnet session key.
+   * 
+   * @returns true if using Base Sepolia (testnet), false if using Base Mainnet
+   */
+  isTestnet() {
+    return this.sessionKey.isTest;
+  }
+  /**
+   * Get the network information.
+   * 
+   * @returns Network details including chain ID and name
+   */
+  getNetwork() {
+    return this.isTestnet() ? NETWORKS.BASE_SEPOLIA : NETWORKS.BASE_MAINNET;
+  }
+  /**
+   * Get current USDC balance of the wallet.
+   * 
+   * @returns USDC balance in USD
+   * 
+   * @example
+   * ```typescript
+   * const balance = await wallet.getBalance();
+   * console.log(`Balance: $${balance.toFixed(2)}`);
+   * ```
+   */
+  async getBalance() {
+    this.logger.debug("Fetching wallet balance...");
+    try {
+      const response = await fetch(`${this.baseUrl}/v1/wallet/balance`, {
+        headers: {
+          "X-Session-Key": this.sessionKey.address
+        }
+      });
+      if (response.ok) {
+        const data = await response.json();
+        const balance = data.balance_usd || data.balanceUsd || 0;
+        this.logger.debug(`Balance: $${balance}`);
+        return balance;
+      }
+    } catch (error) {
+      this.logger.warn("Failed to fetch balance:", error);
+    }
+    this.logger.debug("Using estimated balance based on tracking");
+    return Math.max(0, 100 - this.totalSpentUsd);
+  }
+  /**
+   * Get information about the session key.
+   * 
+   * @param refresh - Force refresh from server (default: use cache if < 60s old)
+   * @returns Session key details including limits and expiration
+   * 
+   * @example
+   * ```typescript
+   * const info = await wallet.getSessionKeyInfo();
+   * console.log(`Daily limit: $${info.limits.dailyUsd}`);
+   * console.log(`Expires: ${info.expiresAt}`);
+   * ```
+   */
+  async getSessionKeyInfo(refresh = false) {
+    const cacheAge = this.sessionKeyInfoFetchedAt ? Date.now() - this.sessionKeyInfoFetchedAt : Infinity;
+    if (!refresh && this.sessionKeyInfo && cacheAge < 6e4) {
+      return this.sessionKeyInfo;
+    }
+    this.logger.debug("Fetching session key info...");
+    try {
+      const response = await fetch(`${this.baseUrl}/v1/session-key/info`, {
+        headers: {
+          "X-Session-Key": this.sessionKey.address
+        }
+      });
+      if (response.ok) {
+        const data = await response.json();
+        this.sessionKeyInfo = {
+          address: this.sessionKey.address,
+          isValid: data.is_valid ?? data.isValid ?? true,
+          limits: {
+            perTxUsd: data.per_tx_limit_usd ?? data.perTxLimitUsd ?? null,
+            dailyUsd: data.daily_limit_usd ?? data.dailyLimitUsd ?? null,
+            totalUsd: data.total_limit_usd ?? data.totalLimitUsd ?? null
+          },
+          usage: {
+            todayUsd: data.today_spent_usd ?? data.todaySpentUsd ?? 0,
+            totalUsd: data.total_spent_usd ?? data.totalSpentUsd ?? 0,
+            txCount: data.tx_count ?? data.txCount ?? 0
+          },
+          expiresAt: data.expires_at ? new Date(data.expires_at) : null,
+          createdAt: data.created_at ? new Date(data.created_at) : null,
+          name: data.name
+        };
+        this.sessionKeyInfoFetchedAt = Date.now();
+        return this.sessionKeyInfo;
+      }
+    } catch (error) {
+      this.logger.warn("Failed to fetch session key info:", error);
+    }
+    return {
+      address: this.sessionKey.address,
+      isValid: true,
+      limits: { perTxUsd: null, dailyUsd: null, totalUsd: null },
+      usage: { todayUsd: this.totalSpentUsd, totalUsd: this.totalSpentUsd, txCount: this.payments.length },
+      expiresAt: null,
+      createdAt: null
+    };
+  }
+  /**
+   * Get spending stats for this session key.
+   * 
+   * @returns Spending statistics
+   * 
+   * @example
+   * ```typescript
+   * const stats = await wallet.getSpendingStats();
+   * console.log(`Spent: $${stats.totalSpentUsd.toFixed(2)}`);
+   * console.log(`Remaining daily: $${stats.remainingDailyUsd?.toFixed(2) ?? 'unlimited'}`);
+   * ```
+   */
+  async getSpendingStats() {
+    this.logger.debug("Fetching spending stats...");
+    try {
+      const response = await fetch(`${this.baseUrl}/v1/session-key/stats`, {
+        headers: {
+          "X-Session-Key": this.sessionKey.address
+        }
+      });
+      if (response.ok) {
+        const data = await response.json();
+        return {
+          totalSpentUsd: data.total_spent_usd || data.totalSpentUsd || this.totalSpentUsd,
+          txCount: data.tx_count || data.txCount || this.payments.length,
+          remainingDailyUsd: data.remaining_daily_usd || data.remainingDailyUsd || null,
+          remainingTotalUsd: data.remaining_total_usd || data.remainingTotalUsd || null,
+          expiresAt: data.expires_at ? new Date(data.expires_at) : null
+        };
+      }
+    } catch (error) {
+      this.logger.warn("Failed to fetch spending stats:", error);
+    }
+    return {
+      totalSpentUsd: this.totalSpentUsd,
+      txCount: this.payments.length,
+      remainingDailyUsd: null,
+      remainingTotalUsd: null,
+      expiresAt: null
+    };
+  }
+  /**
+   * Get list of payments made in this session.
+   * 
+   * @returns Array of payment events
+   */
+  getPaymentHistory() {
+    return [...this.payments];
+  }
+  /**
+   * Get the total amount spent in this session.
+   * 
+   * @returns Total spent in USD
+   */
+  getTotalSpent() {
+    return this.totalSpentUsd;
+  }
+  // ===========================================================================
+  // Diagnostics
+  // ===========================================================================
+  /**
+   * Run diagnostics to verify the wallet is properly configured.
+   * 
+   * This is useful for debugging integration issues.
+   * 
+   * @returns Diagnostic results with status and any issues found
+   * 
+   * @example
+   * ```typescript
+   * const diagnostics = await wallet.runDiagnostics();
+   * if (diagnostics.healthy) {
+   *   console.log('✅ Wallet is ready to use');
+   * } else {
+   *   console.log('❌ Issues found:');
+   *   diagnostics.issues.forEach(issue => console.log(`  - ${issue}`));
+   * }
+   * ```
+   */
+  async runDiagnostics() {
+    this.logger.info("Running diagnostics...");
+    const issues = [];
+    const checks = {};
+    checks.sessionKeyFormat = true;
+    try {
+      const response = await fetch(`${this.baseUrl}/health`, {
+        method: "GET",
+        signal: AbortSignal.timeout(5e3)
+      });
+      checks.apiConnectivity = response.ok;
+      if (!response.ok) {
+        issues.push(`API server returned ${response.status}. Check baseUrl configuration.`);
+      }
+    } catch {
+      checks.apiConnectivity = false;
+      issues.push("Cannot connect to MixrPay API. Check your network connection and baseUrl.");
+    }
+    try {
+      const info = await this.getSessionKeyInfo(true);
+      checks.sessionKeyValid = info.isValid;
+      if (!info.isValid) {
+        issues.push("Session key is invalid or has been revoked.");
+      }
+      if (info.expiresAt && info.expiresAt < /* @__PURE__ */ new Date()) {
+        checks.sessionKeyValid = false;
+        issues.push(`Session key expired on ${info.expiresAt.toISOString()}`);
+      }
+    } catch {
+      checks.sessionKeyValid = false;
+      issues.push("Could not verify session key validity.");
+    }
+    try {
+      const balance = await this.getBalance();
+      checks.hasBalance = balance > 0;
+      if (balance <= 0) {
+        issues.push("Wallet has no USDC balance. Top up at your MixrPay server /wallet");
+      } else if (balance < 1) {
+        issues.push(`Low balance: $${balance.toFixed(2)}. Consider topping up.`);
+      }
+    } catch {
+      checks.hasBalance = false;
+      issues.push("Could not fetch wallet balance.");
+    }
+    const healthy = issues.length === 0;
+    this.logger.info("Diagnostics complete:", { healthy, issues });
+    return {
+      healthy,
+      issues,
+      checks,
+      sdkVersion: SDK_VERSION,
+      network: this.getNetwork().name,
+      walletAddress: this.walletAddress
+    };
+  }
+  /**
+   * Enable or disable debug logging.
+   * 
+   * @param enable - true to enable debug logging, false to disable
+   * 
+   * @example
+   * ```typescript
+   * wallet.setDebug(true);  // Enable detailed logs
+   * await wallet.fetch(...);
+   * wallet.setDebug(false); // Disable logs
+   * ```
+   */
+  setDebug(enable) {
+    this.logger.setLevel(enable ? "debug" : "none");
+  }
+  /**
+   * Set the log level.
+   * 
+   * @param level - 'debug' | 'info' | 'warn' | 'error' | 'none'
+   */
+  setLogLevel(level) {
+    this.logger.setLevel(level);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentWallet,
+  DEFAULT_BASE_URL,
+  DEFAULT_FACILITATOR_URL,
+  DEFAULT_TIMEOUT,
+  InsufficientBalanceError,
+  InvalidSessionKeyError,
+  MixrPayError,
+  NETWORKS,
+  PaymentFailedError,
+  SDK_VERSION,
+  SessionKey,
+  SessionKeyExpiredError,
+  SpendingLimitExceededError,
+  X402ProtocolError,
+  buildTransferAuthorizationData,
+  buildXPaymentHeader,
+  generateNonce,
+  getAmountUsd,
+  getErrorMessage,
+  isMixrPayError,
+  isPaymentExpired,
+  parse402Response,
+  validatePaymentAmount
+});