@mixrpay/agent-sdk 0.4.1

package/dist/index.js

@@ -0,0 +1,1985 @@
+// src/session-key.ts
+import {
+  privateKeyToAccount,
+  signTypedData,
+  signMessage as viemSignMessage
+} from "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;
+  }
+};
+var SessionExpiredError = class extends MixrPayError {
+  /** ID of the expired session */
+  sessionId;
+  /** When the session expired (ISO string or Date) */
+  expiredAt;
+  constructor(sessionId, expiredAt) {
+    super(
+      `Session ${sessionId} has expired${expiredAt ? ` at ${expiredAt}` : ""}. A new session will be created automatically on your next request.`,
+      "SESSION_EXPIRED"
+    );
+    this.name = "SessionExpiredError";
+    this.sessionId = sessionId;
+    this.expiredAt = expiredAt;
+  }
+};
+var SessionLimitExceededError = class extends MixrPayError {
+  /** ID of the session */
+  sessionId;
+  /** The session's spending limit in USD */
+  limit;
+  /** The amount requested in USD */
+  requested;
+  /** Remaining balance in the session (limit - used) */
+  remaining;
+  constructor(limit, requested, remaining, sessionId) {
+    super(
+      `Session spending limit exceeded: limit is $${limit.toFixed(2)}, requested $${requested.toFixed(2)}, remaining $${remaining.toFixed(2)}. Create a new session with a higher limit to continue.`,
+      "SESSION_LIMIT_EXCEEDED"
+    );
+    this.name = "SessionLimitExceededError";
+    this.sessionId = sessionId;
+    this.limit = limit;
+    this.requested = requested;
+    this.remaining = remaining;
+  }
+};
+var SessionNotFoundError = class extends MixrPayError {
+  /** The session ID that was not found */
+  sessionId;
+  constructor(sessionId) {
+    super(
+      `Session ${sessionId} not found. It may have been deleted or never existed. Create a new session with getOrCreateSession().`,
+      "SESSION_NOT_FOUND"
+    );
+    this.name = "SessionNotFoundError";
+    this.sessionId = sessionId;
+  }
+};
+var SessionRevokedError = class extends MixrPayError {
+  /** The session ID that was revoked */
+  sessionId;
+  /** Optional reason for revocation */
+  reason;
+  constructor(sessionId, reason) {
+    super(
+      `Session ${sessionId} has been revoked${reason ? `: ${reason}` : ""}. Create a new session with getOrCreateSession().`,
+      "SESSION_REVOKED"
+    );
+    this.name = "SessionRevokedError";
+    this.sessionId = sessionId;
+    this.reason = reason;
+  }
+};
+function isMixrPayError(error) {
+  return error instanceof MixrPayError;
+}
+
+// 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 = privateKeyToAccount(privateKey);
+    this.address = this.account.address;
+    this.isTest = isTest;
+  }
+  /**
+   * Get the private key as hex string (without 0x prefix).
+   * Used for API authentication headers.
+   */
+  get privateKeyHex() {
+    return this.privateKey.slice(2);
+  }
+  /**
+   * 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 signTypedData({
+      privateKey: this.privateKey,
+      domain,
+      types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+      primaryType: "TransferWithAuthorization",
+      message
+    });
+  }
+  /**
+   * Sign a plain message (EIP-191 personal sign).
+   * 
+   * @param message - Message to sign
+   * @returns Hex-encoded signature
+   */
+  async signMessage(message) {
+    return viemSignMessage({
+      privateKey: this.privateKey,
+      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("")}`;
+}
+function buildSessionAuthMessage(timestamp, address) {
+  return `MixrPay:${timestamp}:${address.toLowerCase()}`;
+}
+async function createSessionAuthPayload(sessionKey) {
+  const timestamp = Date.now();
+  const message = buildSessionAuthMessage(timestamp, sessionKey.address);
+  const signature = await sessionKey.signMessage(message);
+  return {
+    address: sessionKey.address,
+    timestamp,
+    signature
+  };
+}
+
+// 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;
+}
+
+// src/agent-wallet.ts
+var SDK_VERSION = "0.4.1";
+var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
+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);
+  }
+  // ===========================================================================
+  // Session Authorization Methods (for MixrPay Merchants)
+  // ===========================================================================
+  /**
+   * Create the X-Session-Auth header for secure API authentication.
+   * Uses signature-based authentication - private key is NEVER transmitted.
+   * 
+   * @returns Headers object with X-Session-Auth
+   */
+  async getSessionAuthHeaders() {
+    const payload = await createSessionAuthPayload(this.sessionKey);
+    return {
+      "X-Session-Auth": JSON.stringify(payload)
+    };
+  }
+  /**
+   * Get an existing session or create a new one with a MixrPay merchant.
+   * 
+   * This is the recommended way to interact with MixrPay-enabled APIs.
+   * If an active session exists, it will be returned. Otherwise, a new
+   * session authorization request will be created and confirmed.
+   * 
+   * @param options - Session creation options
+   * @returns Active session authorization
+   * 
+   * @throws {MixrPayError} If merchant is not found or session creation fails
+   * 
+   * @example
+   * ```typescript
+   * const session = await wallet.getOrCreateSession({
+   *   merchantPublicKey: 'pk_live_abc123...',
+   *   spendingLimitUsd: 25.00,
+   *   durationDays: 7,
+   * });
+   * 
+   * console.log(`Session active: $${session.remainingLimitUsd} remaining`);
+   * ```
+   */
+  async getOrCreateSession(options) {
+    this.logger.debug("getOrCreateSession called", options);
+    const { merchantPublicKey, spendingLimitUsd = 25, durationDays = 7 } = options;
+    try {
+      const existingSession = await this.getSessionByMerchant(merchantPublicKey);
+      if (existingSession && existingSession.status === "active") {
+        this.logger.debug("Found existing active session", existingSession.id);
+        return existingSession;
+      }
+    } catch {
+    }
+    this.logger.info(`Creating new session with merchant ${merchantPublicKey.slice(0, 20)}...`);
+    const authHeaders = await this.getSessionAuthHeaders();
+    const authorizeResponse = await fetch(`${this.baseUrl}/api/v2/session/authorize`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        merchant_public_key: merchantPublicKey,
+        spending_limit_usd: spendingLimitUsd,
+        duration_days: durationDays
+      })
+    });
+    if (!authorizeResponse.ok) {
+      const error = await authorizeResponse.json().catch(() => ({}));
+      throw new MixrPayError(
+        error.message || error.error || `Failed to create session: ${authorizeResponse.status}`
+      );
+    }
+    const authorizeData = await authorizeResponse.json();
+    const sessionId = authorizeData.session_id;
+    const messageToSign = authorizeData.message_to_sign;
+    if (!sessionId || !messageToSign) {
+      throw new MixrPayError("Invalid authorize response: missing session_id or message_to_sign");
+    }
+    this.logger.debug("Signing session authorization message...");
+    const signature = await this.sessionKey.signMessage(messageToSign);
+    const confirmResponse = await fetch(`${this.baseUrl}/api/v2/session/confirm`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        signature,
+        wallet_address: this.walletAddress
+      })
+    });
+    if (!confirmResponse.ok) {
+      const error = await confirmResponse.json().catch(() => ({}));
+      throw new MixrPayError(
+        error.message || `Failed to confirm session: ${confirmResponse.status}`
+      );
+    }
+    const confirmData = await confirmResponse.json();
+    this.logger.info(`Session created: ${confirmData.session?.id || sessionId}`);
+    return this.parseSessionResponse(confirmData.session || confirmData);
+  }
+  /**
+   * Get session status for a specific merchant.
+   * 
+   * @param merchantPublicKey - The merchant's public key
+   * @returns Session authorization or null if not found
+   */
+  async getSessionByMerchant(merchantPublicKey) {
+    this.logger.debug("getSessionByMerchant", merchantPublicKey);
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/session/status?merchant_public_key=${encodeURIComponent(merchantPublicKey)}`, {
+      headers: authHeaders
+    });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.message || `Failed to get session: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.session ? this.parseSessionResponse(data.session) : null;
+  }
+  /**
+   * List all session authorizations for this wallet.
+   * 
+   * @returns Array of session authorizations
+   * 
+   * @example
+   * ```typescript
+   * const sessions = await wallet.listSessions();
+   * for (const session of sessions) {
+   *   console.log(`${session.merchantName}: $${session.remainingLimitUsd} remaining`);
+   * }
+   * ```
+   */
+  async listSessions() {
+    this.logger.debug("listSessions");
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/session/list`, {
+      headers: authHeaders
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.message || `Failed to list sessions: ${response.status}`);
+    }
+    const data = await response.json();
+    return (data.sessions || []).map((s) => this.parseSessionResponse(s));
+  }
+  /**
+   * Revoke a session authorization.
+   * 
+   * After revocation, no further charges can be made against this session.
+   * 
+   * @param sessionId - The session ID to revoke
+   * @returns true if revoked successfully
+   * 
+   * @example
+   * ```typescript
+   * const revoked = await wallet.revokeSession('sess_abc123');
+   * if (revoked) {
+   *   console.log('Session revoked successfully');
+   * }
+   * ```
+   */
+  async revokeSession(sessionId) {
+    this.logger.debug("revokeSession", sessionId);
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/session/revoke`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({ session_id: sessionId })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      this.logger.error("Failed to revoke session:", error);
+      return false;
+    }
+    this.logger.info(`Session ${sessionId} revoked`);
+    return true;
+  }
+  /**
+   * Get statistics about all session authorizations.
+   * 
+   * This provides an overview of active, expired, and revoked sessions,
+   * along with aggregate spending information.
+   * 
+   * @returns Session statistics
+   * 
+   * @example
+   * ```typescript
+   * const stats = await wallet.getSessionStats();
+   * console.log(`Active sessions: ${stats.activeCount}`);
+   * console.log(`Total authorized: $${stats.totalAuthorizedUsd.toFixed(2)}`);
+   * console.log(`Total remaining: $${stats.totalRemainingUsd.toFixed(2)}`);
+   * 
+   * for (const session of stats.activeSessions) {
+   *   console.log(`${session.merchantName}: $${session.remainingUsd} remaining`);
+   * }
+   * ```
+   */
+  async getSessionStats() {
+    this.logger.debug("getSessionStats");
+    const sessions = await this.listSessions();
+    const now = /* @__PURE__ */ new Date();
+    const active = [];
+    const expired = [];
+    const revoked = [];
+    for (const session of sessions) {
+      if (session.status === "revoked") {
+        revoked.push(session);
+      } else if (session.status === "expired" || session.expiresAt && session.expiresAt < now) {
+        expired.push(session);
+      } else if (session.status === "active") {
+        active.push(session);
+      }
+    }
+    const totalAuthorizedUsd = active.reduce((sum, s) => sum + s.spendingLimitUsd, 0);
+    const totalSpentUsd = sessions.reduce((sum, s) => sum + s.amountUsedUsd, 0);
+    const totalRemainingUsd = active.reduce((sum, s) => sum + s.remainingLimitUsd, 0);
+    return {
+      activeCount: active.length,
+      expiredCount: expired.length,
+      revokedCount: revoked.length,
+      totalAuthorizedUsd,
+      totalSpentUsd,
+      totalRemainingUsd,
+      activeSessions: active.map((s) => ({
+        id: s.id,
+        merchantName: s.merchantName,
+        merchantPublicKey: s.merchantId,
+        // merchantId is the public key in this context
+        spendingLimitUsd: s.spendingLimitUsd,
+        remainingUsd: s.remainingLimitUsd,
+        expiresAt: s.expiresAt
+      }))
+    };
+  }
+  /**
+   * Charge against an active session authorization.
+   * 
+   * This is useful when you need to manually charge a session outside of
+   * the `callMerchantApi()` flow.
+   * 
+   * @param sessionId - The session ID to charge
+   * @param amountUsd - Amount to charge in USD
+   * @param options - Additional charge options
+   * @returns Charge result
+   * 
+   * @example
+   * ```typescript
+   * const result = await wallet.chargeSession('sess_abc123', 0.05, {
+   *   feature: 'ai-generation',
+   *   idempotencyKey: 'unique-key-123',
+   * });
+   * 
+   * console.log(`Charged $${result.amountUsd}, remaining: $${result.remainingSessionBalanceUsd}`);
+   * ```
+   */
+  async chargeSession(sessionId, amountUsd, options = {}) {
+    this.logger.debug("chargeSession", { sessionId, amountUsd, options });
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/charge`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        price_usd: amountUsd,
+        feature: options.feature,
+        idempotency_key: options.idempotencyKey,
+        metadata: options.metadata
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      const errorCode = error.error || error.error_code || "";
+      if (response.status === 402) {
+        if (errorCode === "session_limit_exceeded") {
+          const limit = error.sessionLimitUsd || error.session_limit_usd || 0;
+          const remaining = error.remainingUsd || error.remaining_usd || 0;
+          throw new SessionLimitExceededError(limit, amountUsd, remaining, sessionId);
+        }
+        if (errorCode === "insufficient_balance") {
+          throw new InsufficientBalanceError(
+            amountUsd,
+            error.availableUsd || error.available_usd || 0
+          );
+        }
+      }
+      if (response.status === 404 || errorCode === "session_not_found") {
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (errorCode === "session_expired") {
+        throw new SessionExpiredError(sessionId, error.expiredAt || error.expires_at);
+      }
+      if (errorCode === "session_revoked") {
+        throw new SessionRevokedError(sessionId, error.reason);
+      }
+      throw new MixrPayError(error.message || `Charge failed: ${response.status}`);
+    }
+    const data = await response.json();
+    this.logger.payment(amountUsd, sessionId, options.feature);
+    return {
+      success: true,
+      chargeId: data.chargeId || data.charge_id,
+      amountUsd: data.amountUsd || data.amount_usd || amountUsd,
+      txHash: data.txHash || data.tx_hash,
+      remainingSessionBalanceUsd: data.remainingSessionBalanceUsd || data.remaining_session_balance_usd || 0
+    };
+  }
+  /**
+   * Call a MixrPay merchant's API with automatic session management.
+   * 
+   * This is the recommended way to interact with MixrPay-enabled APIs.
+   * It automatically:
+   * 1. Gets or creates a session authorization
+   * 2. Adds the `X-Mixr-Session` header to the request
+   * 3. Handles payment errors and session expiration
+   * 
+   * @param options - API call options
+   * @returns Response from the merchant API
+   * 
+   * @example
+   * ```typescript
+   * const response = await wallet.callMerchantApi({
+   *   url: 'https://api.merchant.com/generate',
+   *   merchantPublicKey: 'pk_live_abc123...',
+   *   method: 'POST',
+   *   body: { prompt: 'Hello world' },
+   *   priceUsd: 0.05,
+   * });
+   * 
+   * const data = await response.json();
+   * ```
+   */
+  async callMerchantApi(options) {
+    const {
+      url,
+      method = "POST",
+      body,
+      headers: customHeaders = {},
+      merchantPublicKey,
+      priceUsd,
+      feature
+    } = options;
+    this.logger.debug("callMerchantApi", { url, method, merchantPublicKey, priceUsd });
+    if (priceUsd !== void 0 && this.maxPaymentUsd !== void 0 && priceUsd > this.maxPaymentUsd) {
+      throw new SpendingLimitExceededError("client_max", this.maxPaymentUsd, priceUsd);
+    }
+    const session = await this.getOrCreateSession({
+      merchantPublicKey,
+      spendingLimitUsd: 25,
+      // Default limit
+      durationDays: 7
+    });
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Mixr-Session": session.id,
+      ...customHeaders
+    };
+    if (feature) {
+      headers["X-Mixr-Feature"] = feature;
+    }
+    const requestBody = body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0;
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: requestBody,
+      signal: AbortSignal.timeout(this.timeout)
+    });
+    const chargedAmount = response.headers.get("X-Mixr-Charged");
+    if (chargedAmount) {
+      const amountUsd = parseFloat(chargedAmount);
+      if (!isNaN(amountUsd)) {
+        const payment = {
+          amountUsd,
+          recipient: merchantPublicKey,
+          txHash: response.headers.get("X-Payment-TxHash"),
+          timestamp: /* @__PURE__ */ new Date(),
+          description: feature || "API call",
+          url
+        };
+        this.payments.push(payment);
+        this.totalSpentUsd += amountUsd;
+        this.logger.payment(amountUsd, merchantPublicKey, feature);
+        if (this.onPayment) {
+          this.onPayment(payment);
+        }
+      }
+    }
+    if (response.status === 402) {
+      const errorData = await response.json().catch(() => ({}));
+      const errorCode = errorData.error || errorData.error_code || "";
+      if (errorCode === "session_expired") {
+        this.logger.info("Session expired, creating new one...");
+        const newSession = await this.getOrCreateSession({
+          merchantPublicKey,
+          spendingLimitUsd: 25,
+          durationDays: 7
+        });
+        headers["X-Mixr-Session"] = newSession.id;
+        return fetch(url, {
+          method,
+          headers,
+          body: requestBody,
+          signal: AbortSignal.timeout(this.timeout)
+        });
+      }
+      if (errorCode === "session_limit_exceeded") {
+        const limit = errorData.sessionLimitUsd || errorData.session_limit_usd || 0;
+        const remaining = errorData.remainingUsd || errorData.remaining_usd || 0;
+        throw new SessionLimitExceededError(limit, priceUsd || 0, remaining, session.id);
+      }
+      if (errorCode === "session_revoked") {
+        throw new SessionRevokedError(session.id, errorData.reason);
+      }
+      if (errorCode === "session_not_found") {
+        throw new SessionNotFoundError(session.id);
+      }
+      if (errorCode === "insufficient_balance") {
+        throw new InsufficientBalanceError(
+          priceUsd || 0,
+          errorData.availableUsd || errorData.available_usd || 0
+        );
+      }
+    }
+    return response;
+  }
+  /**
+   * Parse session response data into SessionAuthorization object.
+   */
+  parseSessionResponse(data) {
+    return {
+      id: data.id || data.session_id || data.sessionId,
+      merchantId: data.merchantId || data.merchant_id,
+      merchantName: data.merchantName || data.merchant_name || "Unknown",
+      status: data.status || "active",
+      spendingLimitUsd: Number(data.spendingLimitUsd || data.spending_limit_usd || data.spendingLimit || 0),
+      amountUsedUsd: Number(data.amountUsedUsd || data.amount_used_usd || data.amountUsed || 0),
+      remainingLimitUsd: Number(
+        data.remainingLimitUsd || data.remaining_limit_usd || data.remainingLimit || Number(data.spendingLimitUsd || data.spending_limit_usd || 0) - Number(data.amountUsedUsd || data.amount_used_usd || 0)
+      ),
+      expiresAt: new Date(data.expiresAt || data.expires_at),
+      createdAt: new Date(data.createdAt || data.created_at)
+    };
+  }
+  // ===========================================================================
+  // MCP (Model Context Protocol) Methods
+  // ===========================================================================
+  /**
+   * Get authentication headers for MCP wallet-based authentication.
+   * 
+   * These headers prove wallet ownership without transmitting the private key.
+   * Use for direct pay-per-call mode (no session needed).
+   * 
+   * @returns Headers object with X-Mixr-Wallet, X-Mixr-Signature, X-Mixr-Timestamp
+   * 
+   * @example
+   * ```typescript
+   * const headers = await wallet.getMCPAuthHeaders();
+   * const response = await fetch('https://mixrpay.com/api/mcp', {
+   *   method: 'POST',
+   *   headers: {
+   *     'Content-Type': 'application/json',
+   *     ...headers,
+   *   },
+   *   body: JSON.stringify({
+   *     jsonrpc: '2.0',
+   *     method: 'tools/list',
+   *     id: 1,
+   *   }),
+   * });
+   * ```
+   */
+  async getMCPAuthHeaders() {
+    const timestamp = Date.now().toString();
+    const message = `MixrPay MCP Auth
+Wallet: ${this.walletAddress}
+Timestamp: ${timestamp}`;
+    const signature = await this.sessionKey.signMessage(message);
+    return {
+      "X-Mixr-Wallet": this.walletAddress,
+      "X-Mixr-Signature": signature,
+      "X-Mixr-Timestamp": timestamp
+    };
+  }
+  /**
+   * List available MCP tools from the MixrPay gateway.
+   * 
+   * Returns all tools exposed by MCP providers on the MixrPay marketplace.
+   * Each tool includes pricing information.
+   * 
+   * @returns Array of MCP tools with pricing and metadata
+   * 
+   * @example
+   * ```typescript
+   * const tools = await wallet.listMCPTools();
+   * for (const tool of tools) {
+   *   console.log(`${tool.name}: $${tool.priceUsd} - ${tool.description}`);
+   * }
+   * ```
+   */
+  async listMCPTools() {
+    this.logger.debug("listMCPTools");
+    const response = await fetch(`${this.baseUrl}/api/mcp`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tools/list",
+        id: Date.now()
+      })
+    });
+    if (!response.ok) {
+      throw new MixrPayError(`Failed to list MCP tools: ${response.status}`);
+    }
+    const result = await response.json();
+    if (result.error) {
+      throw new MixrPayError(result.error.message || "Failed to list MCP tools");
+    }
+    return (result.result?.tools || []).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      priceUsd: tool["x-mixrpay"]?.priceUsd || 0,
+      merchantName: tool["x-mixrpay"]?.merchantName,
+      merchantSlug: tool["x-mixrpay"]?.merchantSlug,
+      verified: tool["x-mixrpay"]?.verified || false
+    }));
+  }
+  /**
+   * Call an MCP tool with wallet authentication (direct pay per call).
+   * 
+   * This method signs a fresh auth message for each call, charging
+   * directly from your wallet balance without needing a session.
+   * 
+   * @param toolName - The tool name in format "merchant/tool"
+   * @param args - Arguments to pass to the tool
+   * @returns Tool execution result
+   * 
+   * @example
+   * ```typescript
+   * const result = await wallet.callMCPTool('firecrawl/scrape', {
+   *   url: 'https://example.com',
+   * });
+   * console.log(result.data);
+   * console.log(`Charged: $${result.chargedUsd}`);
+   * ```
+   */
+  async callMCPTool(toolName, args = {}) {
+    this.logger.debug("callMCPTool", { toolName, args });
+    const authHeaders = await this.getMCPAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/mcp`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: { name: toolName, arguments: args },
+        id: Date.now()
+      })
+    });
+    const result = await response.json();
+    if (result.error) {
+      throw new MixrPayError(result.error.message || "MCP tool call failed");
+    }
+    const content = result.result?.content?.[0];
+    const data = content?.text ? JSON.parse(content.text) : null;
+    const mixrpay = result.result?._mixrpay || {};
+    if (mixrpay.chargedUsd) {
+      const payment = {
+        amountUsd: mixrpay.chargedUsd,
+        recipient: toolName.split("/")[0] || toolName,
+        txHash: mixrpay.txHash,
+        timestamp: /* @__PURE__ */ new Date(),
+        description: `MCP: ${toolName}`,
+        url: `${this.baseUrl}/api/mcp`
+      };
+      this.payments.push(payment);
+      this.totalSpentUsd += mixrpay.chargedUsd;
+      this.logger.payment(mixrpay.chargedUsd, toolName, "MCP call");
+      if (this.onPayment) {
+        this.onPayment(payment);
+      }
+    }
+    return {
+      data,
+      chargedUsd: mixrpay.chargedUsd || 0,
+      txHash: mixrpay.txHash,
+      latencyMs: mixrpay.latencyMs
+    };
+  }
+  // ===========================================================================
+  // Agent Runtime API
+  // ===========================================================================
+  /**
+   * Run an AI agent with LLM and tool execution.
+   * 
+   * This method orchestrates a full agentic loop:
+   * - Multi-turn reasoning with LLM
+   * - Automatic tool execution
+   * - Bundled billing (single charge at end)
+   * - Optional streaming via SSE
+   * 
+   * @param options - Agent run options
+   * @returns Agent run result with response and cost breakdown
+   * 
+   * @example Basic usage
+   * ```typescript
+   * const result = await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Find AI startups in SF' }],
+   * });
+   * 
+   * console.log(result.response);
+   * console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+   * ```
+   * 
+   * @example With custom config
+   * ```typescript
+   * const result = await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Research quantum computing' }],
+   *   config: {
+   *     model: 'gpt-4o',
+   *     maxIterations: 15,
+   *     tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+   *     systemPrompt: 'You are a research assistant.',
+   *   },
+   * });
+   * ```
+   * 
+   * @example With streaming
+   * ```typescript
+   * await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Analyze this company' }],
+   *   stream: true,
+   *   onEvent: (event) => {
+   *     if (event.type === 'llm_chunk') {
+   *       process.stdout.write(event.delta);
+   *     } else if (event.type === 'tool_call') {
+   *       console.log(`Calling tool: ${event.tool}`);
+   *     }
+   *   },
+   * });
+   * ```
+   */
+  async runAgent(options) {
+    const {
+      sessionId,
+      messages,
+      config = {},
+      stream = false,
+      idempotencyKey,
+      onEvent
+    } = options;
+    this.logger.debug("runAgent", { sessionId, messageCount: messages.length, config, stream });
+    const body = {
+      session_id: sessionId,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      config: {
+        model: config.model,
+        max_iterations: config.maxIterations,
+        tools: config.tools,
+        system_prompt: config.systemPrompt
+      },
+      stream,
+      idempotency_key: idempotencyKey
+    };
+    const AGENT_RUN_TIMEOUT = 18e4;
+    if (!stream) {
+      const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Mixr-Session": sessionId
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(AGENT_RUN_TIMEOUT)
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+      }
+      const data = await response.json();
+      if (data.cost?.total_usd > 0) {
+        const payment = {
+          amountUsd: data.cost.total_usd,
+          recipient: "mixrpay-agent-run",
+          txHash: data.tx_hash,
+          timestamp: /* @__PURE__ */ new Date(),
+          description: `Agent run: ${data.run_id}`,
+          url: `${this.baseUrl}/api/v2/agent/run`
+        };
+        this.payments.push(payment);
+        this.totalSpentUsd += data.cost.total_usd;
+        this.logger.payment(data.cost.total_usd, "agent-run", data.run_id);
+        if (this.onPayment) {
+          this.onPayment(payment);
+        }
+      }
+      return {
+        runId: data.run_id,
+        status: data.status,
+        response: data.response,
+        iterations: data.iterations,
+        toolsUsed: data.tools_used,
+        cost: {
+          llmUsd: data.cost.llm_usd,
+          toolsUsd: data.cost.tools_usd,
+          totalUsd: data.cost.total_usd
+        },
+        tokens: data.tokens,
+        sessionRemainingUsd: data.session_remaining_usd,
+        txHash: data.tx_hash
+      };
+    }
+    return this.runAgentStreaming(sessionId, body, onEvent);
+  }
+  /**
+   * Internal: Handle streaming agent run via SSE
+   */
+  async runAgentStreaming(sessionId, body, onEvent) {
+    const STREAMING_TIMEOUT = 3e5;
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mixr-Session": sessionId
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(STREAMING_TIMEOUT)
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new MixrPayError("No response body for streaming");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let result = null;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      let currentEvent = "";
+      for (const line of lines) {
+        if (line.startsWith("event: ")) {
+          currentEvent = line.slice(7).trim();
+        } else if (line.startsWith("data: ") && currentEvent) {
+          try {
+            const data = JSON.parse(line.slice(6));
+            const event = this.parseSSEEvent(currentEvent, data);
+            if (event) {
+              onEvent?.(event);
+              if (currentEvent === "complete") {
+                result = {
+                  runId: data.run_id,
+                  status: "completed",
+                  response: data.response,
+                  iterations: data.iterations,
+                  toolsUsed: data.tools_used,
+                  cost: {
+                    llmUsd: 0,
+                    // Not provided in streaming complete
+                    toolsUsd: 0,
+                    totalUsd: data.total_cost_usd
+                  },
+                  tokens: { prompt: 0, completion: 0 },
+                  sessionRemainingUsd: 0,
+                  txHash: data.tx_hash
+                };
+                if (data.total_cost_usd > 0) {
+                  const payment = {
+                    amountUsd: data.total_cost_usd,
+                    recipient: "mixrpay-agent-run",
+                    txHash: data.tx_hash,
+                    timestamp: /* @__PURE__ */ new Date(),
+                    description: `Agent run: ${data.run_id}`,
+                    url: `${this.baseUrl}/api/v2/agent/run`
+                  };
+                  this.payments.push(payment);
+                  this.totalSpentUsd += data.total_cost_usd;
+                  if (this.onPayment) {
+                    this.onPayment(payment);
+                  }
+                }
+              }
+              if (currentEvent === "error") {
+                throw new MixrPayError(data.error || "Agent run failed");
+              }
+            }
+          } catch (e) {
+            if (e instanceof MixrPayError) throw e;
+            this.logger.warn("Failed to parse SSE event:", e);
+          }
+          currentEvent = "";
+        }
+      }
+    }
+    if (!result) {
+      throw new MixrPayError("Agent run completed without final result");
+    }
+    return result;
+  }
+  /**
+   * Internal: Parse SSE event into typed event object
+   */
+  parseSSEEvent(eventType, data) {
+    switch (eventType) {
+      case "run_start":
+        return { type: "run_start", runId: data.run_id };
+      case "iteration_start":
+        return { type: "iteration_start", iteration: data.iteration };
+      case "llm_chunk":
+        return { type: "llm_chunk", delta: data.delta };
+      case "tool_call":
+        return { type: "tool_call", tool: data.tool, arguments: data.arguments };
+      case "tool_result":
+        return {
+          type: "tool_result",
+          tool: data.tool,
+          success: data.success,
+          costUsd: data.cost_usd,
+          error: data.error
+        };
+      case "iteration_complete":
+        return {
+          type: "iteration_complete",
+          iteration: data.iteration,
+          tokens: data.tokens,
+          costUsd: data.cost_usd
+        };
+      case "complete":
+        return {
+          type: "complete",
+          runId: data.run_id,
+          response: data.response,
+          totalCostUsd: data.total_cost_usd,
+          txHash: data.tx_hash,
+          iterations: data.iterations,
+          toolsUsed: data.tools_used
+        };
+      case "error":
+        return {
+          type: "error",
+          error: data.error,
+          partialCostUsd: data.partial_cost_usd
+        };
+      default:
+        return null;
+    }
+  }
+  /**
+   * Get the status of an agent run by ID.
+   * 
+   * @param runId - The agent run ID
+   * @param sessionId - The session ID (for authentication)
+   * @returns Agent run status and results
+   * 
+   * @example
+   * ```typescript
+   * const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+   * console.log(`Status: ${status.status}`);
+   * if (status.status === 'completed') {
+   *   console.log(status.response);
+   * }
+   * ```
+   */
+  async getAgentRunStatus(runId, sessionId) {
+    this.logger.debug("getAgentRunStatus", { runId, sessionId });
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run/${runId}`, {
+      headers: {
+        "X-Mixr-Session": sessionId
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get run status: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      runId: data.run_id,
+      status: data.status,
+      response: data.response,
+      iterations: data.iterations,
+      toolsUsed: data.tools_used,
+      cost: {
+        llmUsd: data.cost.llm_usd,
+        toolsUsd: data.cost.tools_usd,
+        totalUsd: data.cost.total_usd
+      },
+      tokens: data.tokens,
+      txHash: data.tx_hash,
+      error: data.error,
+      startedAt: new Date(data.started_at),
+      completedAt: data.completed_at ? new Date(data.completed_at) : void 0
+    };
+  }
+  /**
+   * Call an MCP tool using session authorization (pre-authorized spending limit).
+   * 
+   * Use this when you've already created a session with the tool provider
+   * and want to use that spending limit instead of direct wallet charges.
+   * 
+   * @param sessionId - The session ID for the tool provider
+   * @param toolName - The tool name in format "merchant/tool"
+   * @param args - Arguments to pass to the tool
+   * @returns Tool execution result
+   * 
+   * @example
+   * ```typescript
+   * // Create session with provider first
+   * const session = await wallet.getOrCreateSession({
+   *   merchantPublicKey: 'pk_live_firecrawl_...',
+   *   spendingLimitUsd: 50,
+   * });
+   * 
+   * // Use session for multiple calls
+   * const result = await wallet.callMCPToolWithSession(
+   *   session.id,
+   *   'firecrawl/scrape',
+   *   { url: 'https://example.com' }
+   * );
+   * ```
+   */
+  async callMCPToolWithSession(sessionId, toolName, args = {}) {
+    this.logger.debug("callMCPToolWithSession", { sessionId, toolName, args });
+    const response = await fetch(`${this.baseUrl}/api/mcp`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mixr-Session": sessionId
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: { name: toolName, arguments: args },
+        id: Date.now()
+      })
+    });
+    const result = await response.json();
+    if (result.error) {
+      throw new MixrPayError(result.error.message || "MCP tool call failed");
+    }
+    const content = result.result?.content?.[0];
+    const data = content?.text ? JSON.parse(content.text) : null;
+    const mixrpay = result.result?._mixrpay || {};
+    if (mixrpay.chargedUsd) {
+      const payment = {
+        amountUsd: mixrpay.chargedUsd,
+        recipient: toolName.split("/")[0] || toolName,
+        txHash: mixrpay.txHash,
+        timestamp: /* @__PURE__ */ new Date(),
+        description: `MCP: ${toolName}`,
+        url: `${this.baseUrl}/api/mcp`
+      };
+      this.payments.push(payment);
+      this.totalSpentUsd += mixrpay.chargedUsd;
+      this.logger.payment(mixrpay.chargedUsd, toolName, "MCP call (session)");
+      if (this.onPayment) {
+        this.onPayment(payment);
+      }
+    }
+    return {
+      data,
+      chargedUsd: mixrpay.chargedUsd || 0,
+      txHash: mixrpay.txHash,
+      latencyMs: mixrpay.latencyMs
+    };
+  }
+};
+export {
+  AgentWallet,
+  InsufficientBalanceError,
+  InvalidSessionKeyError,
+  MixrPayError,
+  PaymentFailedError,
+  SDK_VERSION,
+  SessionExpiredError,
+  SessionKeyExpiredError,
+  SessionLimitExceededError,
+  SessionNotFoundError,
+  SessionRevokedError,
+  SpendingLimitExceededError,
+  isMixrPayError
+};