@mixrpay/agent-sdk 0.6.0 → 0.7.0

package/README.md

@@ -41,9 +41,13 @@ await wallet.fetch(url, options);
 // Get wallet balance
 const balance = await wallet.getBalance();
 
-// Track payments
-const payments = wallet.getPaymentHistory();
-const total = wallet.getTotalSpent();
+// Pre-flight balance check
+const check = await wallet.canAfford(0.50);
+if (check.canAfford) { /* proceed */ }
+
+// Run diagnostics
+const diag = await wallet.runDiagnostics();
+console.log(diag.recommendations);
 ```
 
 ## Configuration
@@ -63,6 +67,7 @@ import {
   AgentWallet,
   InsufficientBalanceError,
   SessionLimitExceededError,
+  MixrPayError,
 } from '@mixrpay/agent-sdk';
 
 try {
@@ -71,12 +76,27 @@ try {
   if (error instanceof InsufficientBalanceError) {
     console.log(`Need $${error.required}, have $${error.available}`);
   }
+  
+  // Check if error is retryable
+  if (error instanceof MixrPayError && error.isRetryable()) {
+    const delay = error.retryAfterMs || 1000;
+    await sleep(delay);
+    return retry();
+  }
 }
 ```
 
+## What's New in v0.6.0
+
+- `canAfford(amountUsd)` - Pre-flight balance check
+- `isRetryable()` on all errors - Determine if operation should be retried
+- `retryAfterMs` on errors - Suggested retry delay
+- Enhanced `runDiagnostics()` - Session limits, latency, recommendations
+- `requestId` and `correlationId` in payment events
+
 ## Documentation
 
-[mixrpay.com/build](https://www.mixrpay.com/build)
+[mixrpay.com/docs](https://www.mixrpay.com/docs)
 
 ## License
 

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   AgentWallet: () => AgentWallet,
   InsufficientBalanceError: () => InsufficientBalanceError,
   InvalidSessionKeyError: () => InvalidSessionKeyError,
+  MerchantNotAllowedError: () => MerchantNotAllowedError,
   MixrPayError: () => MixrPayError,
   PaymentFailedError: () => PaymentFailedError,
   SDK_VERSION: () => SDK_VERSION,
@@ -265,6 +266,23 @@ var SessionRevokedError = class extends MixrPayError {
     this.reason = reason;
   }
 };
+var MerchantNotAllowedError = class extends MixrPayError {
+  /** The merchant/tool that was attempted */
+  attempted;
+  /** The patterns that are allowed by the session */
+  allowedPatterns;
+  constructor(attempted, allowedPatterns) {
+    const patternsPreview = allowedPatterns.slice(0, 3).join(", ");
+    const suffix = allowedPatterns.length > 3 ? "..." : "";
+    super(
+      `Payment to "${attempted}" not allowed. Session allowlist: ${patternsPreview}${suffix}. Update the session allowlist or create a new session.`,
+      "MERCHANT_NOT_ALLOWED"
+    );
+    this.name = "MerchantNotAllowedError";
+    this.attempted = attempted;
+    this.allowedPatterns = allowedPatterns;
+  }
+};
 function isMixrPayError(error) {
   return error instanceof MixrPayError;
 }
@@ -507,7 +525,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.6.1";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -575,6 +593,9 @@ var AgentWallet = class {
   // Session key info cache
   sessionKeyInfo;
   sessionKeyInfoFetchedAt;
+  // Merchant allowlist (fetched from server)
+  allowlist;
+  allowlistFetchedAt;
   /**
    * Create a new AgentWallet instance.
    * 
@@ -651,6 +672,126 @@ var AgentWallet = class {
     }
   }
   // ===========================================================================
+  // Merchant Allowlist Validation
+  // ===========================================================================
+  /**
+   * Fetch the merchant allowlist from the server.
+   * Caches the result for 5 minutes to avoid excessive API calls.
+   */
+  async fetchAllowlist() {
+    const CACHE_TTL_MS = 5 * 60 * 1e3;
+    if (this.allowlist !== void 0 && this.allowlistFetchedAt) {
+      const age = Date.now() - this.allowlistFetchedAt;
+      if (age < CACHE_TTL_MS) {
+        return this.allowlist;
+      }
+    }
+    try {
+      const info = await this.getSessionKeyInfo();
+      this.allowlist = info.allowedMerchants || [];
+      this.allowlistFetchedAt = Date.now();
+      this.logger.debug("Fetched allowlist", {
+        patterns: this.allowlist.length,
+        allowAll: this.allowlist.length === 0
+      });
+      return this.allowlist;
+    } catch (error) {
+      this.logger.warn("Failed to fetch allowlist, allowing all merchants", { error });
+      this.allowlist = [];
+      this.allowlistFetchedAt = Date.now();
+      return this.allowlist;
+    }
+  }
+  /**
+   * Validate that a target is allowed by the session's allowlist.
+   * 
+   * @param target - URL, domain, or tool name to check
+   * @param type - Type of target: 'url' for HTTP requests, 'tool' for MCP tools
+   * @throws {MerchantNotAllowedError} If target is not in allowlist
+   */
+  async validateMerchantAllowed(target, type) {
+    const allowlist = await this.fetchAllowlist();
+    if (allowlist.length === 0) {
+      return;
+    }
+    const isAllowed = this.matchesAllowlist(target, allowlist, type);
+    if (!isAllowed) {
+      throw new MerchantNotAllowedError(target, allowlist);
+    }
+  }
+  /**
+   * Check if a target matches any pattern in the allowlist.
+   */
+  matchesAllowlist(target, allowlist, type) {
+    for (const pattern of allowlist) {
+      if (this.matchPattern(target, pattern, type)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Check if a target matches a single pattern.
+   */
+  matchPattern(target, pattern, type) {
+    if (type === "url") {
+      return this.matchUrlPattern(target, pattern);
+    } else {
+      return this.matchToolPattern(target, pattern);
+    }
+  }
+  /**
+   * Match a URL or domain against a pattern.
+   */
+  matchUrlPattern(target, pattern) {
+    let hostname;
+    try {
+      if (target.includes("://")) {
+        const url = new URL(target);
+        hostname = url.hostname.toLowerCase();
+      } else {
+        hostname = target.toLowerCase();
+      }
+    } catch {
+      return false;
+    }
+    const normalizedPattern = pattern.toLowerCase().trim();
+    let patternDomain = normalizedPattern;
+    if (patternDomain.includes("://")) {
+      try {
+        patternDomain = new URL(patternDomain).hostname;
+      } catch {
+      }
+    }
+    if (hostname === patternDomain) {
+      return true;
+    }
+    if (patternDomain.startsWith("*.")) {
+      const baseDomain = patternDomain.substring(2);
+      if (hostname.endsWith(`.${baseDomain}`) && hostname !== baseDomain) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Match an MCP tool name against a pattern.
+   */
+  matchToolPattern(toolName, pattern) {
+    const normalizedTool = toolName.toLowerCase().trim();
+    const normalizedPattern = pattern.toLowerCase().trim();
+    if (normalizedTool === normalizedPattern) {
+      return true;
+    }
+    if (normalizedPattern.endsWith("/*")) {
+      const baseProvider = normalizedPattern.substring(0, normalizedPattern.length - 2);
+      if (normalizedTool.startsWith(`${baseProvider}/`)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // ===========================================================================
   // Static Agent Registration Methods
   // ===========================================================================
   /**
@@ -699,7 +840,19 @@ var AgentWallet = class {
     });
     if (!registerResponse.ok) {
       const error = await registerResponse.json().catch(() => ({}));
-      throw new MixrPayError(error.error || `Registration failed: ${registerResponse.status}`);
+      const errorMessage = error.error || `Registration failed with status ${registerResponse.status}`;
+      const requestId = error.request_id;
+      const errorCode = error.code;
+      let helpText = "";
+      if (registerResponse.status === 503) {
+        helpText = " The service may be temporarily unavailable. Please try again later.";
+      } else if (registerResponse.status === 500) {
+        helpText = " This is a server error. Please contact support with the request ID.";
+      } else if (errorCode === "MISSING_CHALLENGE" || errorCode === "MISSING_SIGNATURE") {
+        helpText = " This may indicate an SDK bug. Please update to the latest version.";
+      }
+      const fullMessage = requestId ? `${errorMessage} (request_id: ${requestId})${helpText}` : `${errorMessage}${helpText}`;
+      throw new MixrPayError(fullMessage);
     }
     const data = await registerResponse.json();
     return {
@@ -707,6 +860,52 @@ var AgentWallet = class {
       depositAddress: data.deposit_address
     };
   }
+  /**
+   * Check if the MixrPay server is properly configured for agent registration.
+   * 
+   * Use this to diagnose registration issues before attempting to register.
+   * 
+   * @param baseUrl - MixrPay API base URL (default: https://www.mixrpay.com)
+   * @returns Server health status including agent registration availability
+   * 
+   * @example
+   * ```typescript
+   * const status = await AgentWallet.checkServerHealth();
+   * if (!status.agentRegistrationAvailable) {
+   *   console.error('Agent registration is not available:', status);
+   * }
+   * ```
+   */
+  static async checkServerHealth(baseUrl) {
+    const url = (baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    try {
+      const response = await fetch(`${url}/api/health/ready?details=true`);
+      if (!response.ok) {
+        return {
+          healthy: false,
+          database: "unknown",
+          agentRegistrationAvailable: false,
+          privyConfigured: false,
+          error: `Health check failed with status ${response.status}`
+        };
+      }
+      const data = await response.json();
+      return {
+        healthy: data.status === "ready",
+        database: data.database || "unknown",
+        agentRegistrationAvailable: data.services?.agentRegistration?.available ?? false,
+        privyConfigured: data.services?.privy?.configured ?? false
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        database: "unreachable",
+        agentRegistrationAvailable: false,
+        privyConfigured: false,
+        error: error instanceof Error ? error.message : "Failed to reach server"
+      };
+    }
+  }
   /**
    * Get a session key for an already-registered agent.
    * 
@@ -881,6 +1080,67 @@ var AgentWallet = class {
     }
     return true;
   }
+  /**
+   * Withdraw USDC from agent's MixrPay wallet to their external wallet.
+   * 
+   * SECURITY: Withdrawals can ONLY go to the agent's own registration wallet
+   * (the wallet used during `register()`). This prevents prompt injection
+   * attacks where a compromised agent might be tricked into withdrawing
+   * to an attacker's address.
+   * 
+   * @param options - Withdrawal options
+   * @returns Withdrawal result with transaction hash
+   * @throws {MixrPayError} If withdrawal fails
+   * 
+   * @example
+   * ```typescript
+   * const result = await AgentWallet.withdraw({
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   *   amountUsd: 50.00,
+   * });
+   * 
+   * console.log(`Withdrew $${result.amountUsd}`);
+   * console.log(`Transaction: ${result.txHash}`);
+   * console.log(`Remaining balance: $${result.remainingBalanceUsd}`);
+   * ```
+   */
+  static async withdraw(options) {
+    const { privateKey, amountUsd } = options;
+    const baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    const account = (0, import_accounts2.privateKeyToAccount)(privateKey);
+    const walletAddress = account.address;
+    const challengeResponse = await fetch(
+      `${baseUrl}/api/v1/agent/challenge?wallet=${walletAddress}&action=withdraw`
+    );
+    if (!challengeResponse.ok) {
+      const error = await challengeResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get challenge: ${challengeResponse.status}`);
+    }
+    const { challenge, message } = await challengeResponse.json();
+    const signature = await (0, import_accounts2.signMessage)({ message, privateKey });
+    const withdrawResponse = await fetch(`${baseUrl}/api/v1/agent/withdraw`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        challenge,
+        external_wallet: walletAddress,
+        signature,
+        to_address: walletAddress,
+        // Always withdraw to self
+        amount_usd: amountUsd
+      })
+    });
+    if (!withdrawResponse.ok) {
+      const error = await withdrawResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Withdrawal failed: ${withdrawResponse.status}`);
+    }
+    const data = await withdrawResponse.json();
+    return {
+      txHash: data.tx_hash,
+      amountUsd: data.amount_usd,
+      remainingBalanceUsd: data.remaining_balance_usd
+    };
+  }
   // ===========================================================================
   // Core Methods
   // ===========================================================================
@@ -919,6 +1179,7 @@ var AgentWallet = class {
    */
   async fetch(url, init) {
     this.logger.debug(`Fetching ${init?.method || "GET"} ${url}`);
+    await this.validateMerchantAllowed(url, "url");
     const requestId = crypto.randomUUID();
     const correlationId = this.extractCorrelationId(init?.headers);
     const controller = new AbortController();
@@ -1192,7 +1453,8 @@ var AgentWallet = class {
           },
           expiresAt: data.expires_at ? new Date(data.expires_at) : null,
           createdAt: data.created_at ? new Date(data.created_at) : null,
-          name: data.name
+          name: data.name,
+          allowedMerchants: data.allowed_merchants ?? data.allowedMerchants ?? []
         };
         this.sessionKeyInfoFetchedAt = Date.now();
         return this.sessionKeyInfo;
@@ -1758,6 +2020,7 @@ var AgentWallet = class {
       feature
     } = options;
     this.logger.debug("callMerchantApi", { url, method, merchantPublicKey, priceUsd });
+    await this.validateMerchantAllowed(url, "url");
     if (priceUsd !== void 0 && this.maxPaymentUsd !== void 0 && priceUsd > this.maxPaymentUsd) {
       throw new SpendingLimitExceededError("client_max", this.maxPaymentUsd, priceUsd);
     }
@@ -1965,6 +2228,7 @@ Timestamp: ${timestamp}`;
    */
   async callMCPTool(toolName, args = {}) {
     this.logger.debug("callMCPTool", { toolName, args });
+    await this.validateMerchantAllowed(toolName, "tool");
     const authHeaders = await this.getMCPAuthHeaders();
     const response = await fetch(`${this.baseUrl}/api/mcp`, {
       method: "POST",
@@ -2354,6 +2618,7 @@ Timestamp: ${timestamp}`;
    */
   async callMCPToolWithSession(sessionId, toolName, args = {}) {
     this.logger.debug("callMCPToolWithSession", { sessionId, toolName, args });
+    await this.validateMerchantAllowed(toolName, "tool");
     const response = await fetch(`${this.baseUrl}/api/mcp`, {
       method: "POST",
       headers: {
@@ -2404,6 +2669,7 @@ Timestamp: ${timestamp}`;
   AgentWallet,
   InsufficientBalanceError,
   InvalidSessionKeyError,
+  MerchantNotAllowedError,
   MixrPayError,
   PaymentFailedError,
   SDK_VERSION,

package/dist/index.d.cts

@@ -158,6 +158,8 @@ interface SessionKeyInfo {
     createdAt: Date | null;
     /** Optional name given to this session key */
     name?: string;
+    /** Allowed merchants/tools (empty = allow all) */
+    allowedMerchants?: string[];
 }
 /**
  * Spending statistics for the current session.
@@ -378,7 +380,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.6.0";
+declare const SDK_VERSION = "0.6.1";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -487,6 +489,28 @@ interface AgentRevokeSessionKeyOptions {
     /** MixrPay API base URL (default: https://www.mixrpay.com) */
     baseUrl?: string;
 }
+/**
+ * Options for withdrawing funds
+ */
+interface AgentWithdrawOptions {
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** Amount to withdraw in USD */
+    amountUsd: number;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from withdrawal
+ */
+interface AgentWithdrawResult {
+    /** On-chain transaction hash */
+    txHash: string;
+    /** Amount withdrawn in USD */
+    amountUsd: number;
+    /** Remaining balance after withdrawal */
+    remainingBalanceUsd: number;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -539,6 +563,8 @@ declare class AgentWallet {
     private totalSpentUsd;
     private sessionKeyInfo?;
     private sessionKeyInfoFetchedAt?;
+    private allowlist?;
+    private allowlistFetchedAt?;
     /**
      * Create a new AgentWallet instance.
      *
@@ -568,6 +594,35 @@ declare class AgentWallet {
      * Validate the configuration before initialization.
      */
     private validateConfig;
+    /**
+     * Fetch the merchant allowlist from the server.
+     * Caches the result for 5 minutes to avoid excessive API calls.
+     */
+    private fetchAllowlist;
+    /**
+     * Validate that a target is allowed by the session's allowlist.
+     *
+     * @param target - URL, domain, or tool name to check
+     * @param type - Type of target: 'url' for HTTP requests, 'tool' for MCP tools
+     * @throws {MerchantNotAllowedError} If target is not in allowlist
+     */
+    private validateMerchantAllowed;
+    /**
+     * Check if a target matches any pattern in the allowlist.
+     */
+    private matchesAllowlist;
+    /**
+     * Check if a target matches a single pattern.
+     */
+    private matchPattern;
+    /**
+     * Match a URL or domain against a pattern.
+     */
+    private matchUrlPattern;
+    /**
+     * Match an MCP tool name against a pattern.
+     */
+    private matchToolPattern;
     /**
      * Register a new agent with MixrPay.
      *
@@ -589,6 +644,29 @@ declare class AgentWallet {
      * ```
      */
     static register(options: AgentRegisterOptions): Promise<AgentRegisterResult>;
+    /**
+     * Check if the MixrPay server is properly configured for agent registration.
+     *
+     * Use this to diagnose registration issues before attempting to register.
+     *
+     * @param baseUrl - MixrPay API base URL (default: https://www.mixrpay.com)
+     * @returns Server health status including agent registration availability
+     *
+     * @example
+     * ```typescript
+     * const status = await AgentWallet.checkServerHealth();
+     * if (!status.agentRegistrationAvailable) {
+     *   console.error('Agent registration is not available:', status);
+     * }
+     * ```
+     */
+    static checkServerHealth(baseUrl?: string): Promise<{
+        healthy: boolean;
+        database: string;
+        agentRegistrationAvailable: boolean;
+        privyConfigured: boolean;
+        error?: string;
+    }>;
     /**
      * Get a session key for an already-registered agent.
      *
@@ -657,6 +735,31 @@ declare class AgentWallet {
      * ```
      */
     static revokeSessionKey(options: AgentRevokeSessionKeyOptions): Promise<boolean>;
+    /**
+     * Withdraw USDC from agent's MixrPay wallet to their external wallet.
+     *
+     * SECURITY: Withdrawals can ONLY go to the agent's own registration wallet
+     * (the wallet used during `register()`). This prevents prompt injection
+     * attacks where a compromised agent might be tricked into withdrawing
+     * to an attacker's address.
+     *
+     * @param options - Withdrawal options
+     * @returns Withdrawal result with transaction hash
+     * @throws {MixrPayError} If withdrawal fails
+     *
+     * @example
+     * ```typescript
+     * const result = await AgentWallet.withdraw({
+     *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+     *   amountUsd: 50.00,
+     * });
+     *
+     * console.log(`Withdrew $${result.amountUsd}`);
+     * console.log(`Transaction: ${result.txHash}`);
+     * console.log(`Remaining balance: $${result.remainingBalanceUsd}`);
+     * ```
+     */
+    static withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *
@@ -1713,6 +1816,34 @@ declare class SessionRevokedError extends MixrPayError {
     readonly reason?: string;
     constructor(sessionId: string, reason?: string);
 }
+/**
+ * Thrown when a payment is attempted to a merchant/tool not in the session's allowlist.
+ *
+ * This error indicates the session key has a configured allowlist that doesn't
+ * include the target merchant or tool.
+ *
+ * ## Resolution
+ * 1. Update the session's allowlist to include the target
+ * 2. Create a new session with the correct allowlist
+ * 3. Use a session without allowlist restrictions
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof MerchantNotAllowedError) {
+ *     console.log(`Cannot pay "${error.attempted}"`);
+ *     console.log(`Allowed patterns: ${error.allowedPatterns.join(', ')}`);
+ *   }
+ * }
+ * ```
+ */
+declare class MerchantNotAllowedError extends MixrPayError {
+    /** The merchant/tool that was attempted */
+    readonly attempted: string;
+    /** The patterns that are allowed by the session */
+    readonly allowedPatterns: string[];
+    constructor(attempted: string, allowedPatterns: string[]);
+}
 /**
  * Check if an error is a MixrPay SDK error.
  *
@@ -1749,4 +1880,4 @@ declare function isMixrPayError(error: unknown): error is MixrPayError;
  */
 declare function getErrorMessage(error: unknown): string;
 
-export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };

package/dist/index.d.ts

@@ -158,6 +158,8 @@ interface SessionKeyInfo {
     createdAt: Date | null;
     /** Optional name given to this session key */
     name?: string;
+    /** Allowed merchants/tools (empty = allow all) */
+    allowedMerchants?: string[];
 }
 /**
  * Spending statistics for the current session.
@@ -378,7 +380,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.6.0";
+declare const SDK_VERSION = "0.6.1";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -487,6 +489,28 @@ interface AgentRevokeSessionKeyOptions {
     /** MixrPay API base URL (default: https://www.mixrpay.com) */
     baseUrl?: string;
 }
+/**
+ * Options for withdrawing funds
+ */
+interface AgentWithdrawOptions {
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** Amount to withdraw in USD */
+    amountUsd: number;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from withdrawal
+ */
+interface AgentWithdrawResult {
+    /** On-chain transaction hash */
+    txHash: string;
+    /** Amount withdrawn in USD */
+    amountUsd: number;
+    /** Remaining balance after withdrawal */
+    remainingBalanceUsd: number;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -539,6 +563,8 @@ declare class AgentWallet {
     private totalSpentUsd;
     private sessionKeyInfo?;
     private sessionKeyInfoFetchedAt?;
+    private allowlist?;
+    private allowlistFetchedAt?;
     /**
      * Create a new AgentWallet instance.
      *
@@ -568,6 +594,35 @@ declare class AgentWallet {
      * Validate the configuration before initialization.
      */
     private validateConfig;
+    /**
+     * Fetch the merchant allowlist from the server.
+     * Caches the result for 5 minutes to avoid excessive API calls.
+     */
+    private fetchAllowlist;
+    /**
+     * Validate that a target is allowed by the session's allowlist.
+     *
+     * @param target - URL, domain, or tool name to check
+     * @param type - Type of target: 'url' for HTTP requests, 'tool' for MCP tools
+     * @throws {MerchantNotAllowedError} If target is not in allowlist
+     */
+    private validateMerchantAllowed;
+    /**
+     * Check if a target matches any pattern in the allowlist.
+     */
+    private matchesAllowlist;
+    /**
+     * Check if a target matches a single pattern.
+     */
+    private matchPattern;
+    /**
+     * Match a URL or domain against a pattern.
+     */
+    private matchUrlPattern;
+    /**
+     * Match an MCP tool name against a pattern.
+     */
+    private matchToolPattern;
     /**
      * Register a new agent with MixrPay.
      *
@@ -589,6 +644,29 @@ declare class AgentWallet {
      * ```
      */
     static register(options: AgentRegisterOptions): Promise<AgentRegisterResult>;
+    /**
+     * Check if the MixrPay server is properly configured for agent registration.
+     *
+     * Use this to diagnose registration issues before attempting to register.
+     *
+     * @param baseUrl - MixrPay API base URL (default: https://www.mixrpay.com)
+     * @returns Server health status including agent registration availability
+     *
+     * @example
+     * ```typescript
+     * const status = await AgentWallet.checkServerHealth();
+     * if (!status.agentRegistrationAvailable) {
+     *   console.error('Agent registration is not available:', status);
+     * }
+     * ```
+     */
+    static checkServerHealth(baseUrl?: string): Promise<{
+        healthy: boolean;
+        database: string;
+        agentRegistrationAvailable: boolean;
+        privyConfigured: boolean;
+        error?: string;
+    }>;
     /**
      * Get a session key for an already-registered agent.
      *
@@ -657,6 +735,31 @@ declare class AgentWallet {
      * ```
      */
     static revokeSessionKey(options: AgentRevokeSessionKeyOptions): Promise<boolean>;
+    /**
+     * Withdraw USDC from agent's MixrPay wallet to their external wallet.
+     *
+     * SECURITY: Withdrawals can ONLY go to the agent's own registration wallet
+     * (the wallet used during `register()`). This prevents prompt injection
+     * attacks where a compromised agent might be tricked into withdrawing
+     * to an attacker's address.
+     *
+     * @param options - Withdrawal options
+     * @returns Withdrawal result with transaction hash
+     * @throws {MixrPayError} If withdrawal fails
+     *
+     * @example
+     * ```typescript
+     * const result = await AgentWallet.withdraw({
+     *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+     *   amountUsd: 50.00,
+     * });
+     *
+     * console.log(`Withdrew $${result.amountUsd}`);
+     * console.log(`Transaction: ${result.txHash}`);
+     * console.log(`Remaining balance: $${result.remainingBalanceUsd}`);
+     * ```
+     */
+    static withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *
@@ -1713,6 +1816,34 @@ declare class SessionRevokedError extends MixrPayError {
     readonly reason?: string;
     constructor(sessionId: string, reason?: string);
 }
+/**
+ * Thrown when a payment is attempted to a merchant/tool not in the session's allowlist.
+ *
+ * This error indicates the session key has a configured allowlist that doesn't
+ * include the target merchant or tool.
+ *
+ * ## Resolution
+ * 1. Update the session's allowlist to include the target
+ * 2. Create a new session with the correct allowlist
+ * 3. Use a session without allowlist restrictions
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof MerchantNotAllowedError) {
+ *     console.log(`Cannot pay "${error.attempted}"`);
+ *     console.log(`Allowed patterns: ${error.allowedPatterns.join(', ')}`);
+ *   }
+ * }
+ * ```
+ */
+declare class MerchantNotAllowedError extends MixrPayError {
+    /** The merchant/tool that was attempted */
+    readonly attempted: string;
+    /** The patterns that are allowed by the session */
+    readonly allowedPatterns: string[];
+    constructor(attempted: string, allowedPatterns: string[]);
+}
 /**
  * Check if an error is a MixrPay SDK error.
  *
@@ -1749,4 +1880,4 @@ declare function isMixrPayError(error: unknown): error is MixrPayError;
  */
 declare function getErrorMessage(error: unknown): string;
 
-export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };

package/dist/index.js

@@ -229,6 +229,23 @@ var SessionRevokedError = class extends MixrPayError {
     this.reason = reason;
   }
 };
+var MerchantNotAllowedError = class extends MixrPayError {
+  /** The merchant/tool that was attempted */
+  attempted;
+  /** The patterns that are allowed by the session */
+  allowedPatterns;
+  constructor(attempted, allowedPatterns) {
+    const patternsPreview = allowedPatterns.slice(0, 3).join(", ");
+    const suffix = allowedPatterns.length > 3 ? "..." : "";
+    super(
+      `Payment to "${attempted}" not allowed. Session allowlist: ${patternsPreview}${suffix}. Update the session allowlist or create a new session.`,
+      "MERCHANT_NOT_ALLOWED"
+    );
+    this.name = "MerchantNotAllowedError";
+    this.attempted = attempted;
+    this.allowedPatterns = allowedPatterns;
+  }
+};
 function isMixrPayError(error) {
   return error instanceof MixrPayError;
 }
@@ -471,7 +488,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.6.1";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -539,6 +556,9 @@ var AgentWallet = class {
   // Session key info cache
   sessionKeyInfo;
   sessionKeyInfoFetchedAt;
+  // Merchant allowlist (fetched from server)
+  allowlist;
+  allowlistFetchedAt;
   /**
    * Create a new AgentWallet instance.
    * 
@@ -615,6 +635,126 @@ var AgentWallet = class {
     }
   }
   // ===========================================================================
+  // Merchant Allowlist Validation
+  // ===========================================================================
+  /**
+   * Fetch the merchant allowlist from the server.
+   * Caches the result for 5 minutes to avoid excessive API calls.
+   */
+  async fetchAllowlist() {
+    const CACHE_TTL_MS = 5 * 60 * 1e3;
+    if (this.allowlist !== void 0 && this.allowlistFetchedAt) {
+      const age = Date.now() - this.allowlistFetchedAt;
+      if (age < CACHE_TTL_MS) {
+        return this.allowlist;
+      }
+    }
+    try {
+      const info = await this.getSessionKeyInfo();
+      this.allowlist = info.allowedMerchants || [];
+      this.allowlistFetchedAt = Date.now();
+      this.logger.debug("Fetched allowlist", {
+        patterns: this.allowlist.length,
+        allowAll: this.allowlist.length === 0
+      });
+      return this.allowlist;
+    } catch (error) {
+      this.logger.warn("Failed to fetch allowlist, allowing all merchants", { error });
+      this.allowlist = [];
+      this.allowlistFetchedAt = Date.now();
+      return this.allowlist;
+    }
+  }
+  /**
+   * Validate that a target is allowed by the session's allowlist.
+   * 
+   * @param target - URL, domain, or tool name to check
+   * @param type - Type of target: 'url' for HTTP requests, 'tool' for MCP tools
+   * @throws {MerchantNotAllowedError} If target is not in allowlist
+   */
+  async validateMerchantAllowed(target, type) {
+    const allowlist = await this.fetchAllowlist();
+    if (allowlist.length === 0) {
+      return;
+    }
+    const isAllowed = this.matchesAllowlist(target, allowlist, type);
+    if (!isAllowed) {
+      throw new MerchantNotAllowedError(target, allowlist);
+    }
+  }
+  /**
+   * Check if a target matches any pattern in the allowlist.
+   */
+  matchesAllowlist(target, allowlist, type) {
+    for (const pattern of allowlist) {
+      if (this.matchPattern(target, pattern, type)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Check if a target matches a single pattern.
+   */
+  matchPattern(target, pattern, type) {
+    if (type === "url") {
+      return this.matchUrlPattern(target, pattern);
+    } else {
+      return this.matchToolPattern(target, pattern);
+    }
+  }
+  /**
+   * Match a URL or domain against a pattern.
+   */
+  matchUrlPattern(target, pattern) {
+    let hostname;
+    try {
+      if (target.includes("://")) {
+        const url = new URL(target);
+        hostname = url.hostname.toLowerCase();
+      } else {
+        hostname = target.toLowerCase();
+      }
+    } catch {
+      return false;
+    }
+    const normalizedPattern = pattern.toLowerCase().trim();
+    let patternDomain = normalizedPattern;
+    if (patternDomain.includes("://")) {
+      try {
+        patternDomain = new URL(patternDomain).hostname;
+      } catch {
+      }
+    }
+    if (hostname === patternDomain) {
+      return true;
+    }
+    if (patternDomain.startsWith("*.")) {
+      const baseDomain = patternDomain.substring(2);
+      if (hostname.endsWith(`.${baseDomain}`) && hostname !== baseDomain) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Match an MCP tool name against a pattern.
+   */
+  matchToolPattern(toolName, pattern) {
+    const normalizedTool = toolName.toLowerCase().trim();
+    const normalizedPattern = pattern.toLowerCase().trim();
+    if (normalizedTool === normalizedPattern) {
+      return true;
+    }
+    if (normalizedPattern.endsWith("/*")) {
+      const baseProvider = normalizedPattern.substring(0, normalizedPattern.length - 2);
+      if (normalizedTool.startsWith(`${baseProvider}/`)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // ===========================================================================
   // Static Agent Registration Methods
   // ===========================================================================
   /**
@@ -663,7 +803,19 @@ var AgentWallet = class {
     });
     if (!registerResponse.ok) {
       const error = await registerResponse.json().catch(() => ({}));
-      throw new MixrPayError(error.error || `Registration failed: ${registerResponse.status}`);
+      const errorMessage = error.error || `Registration failed with status ${registerResponse.status}`;
+      const requestId = error.request_id;
+      const errorCode = error.code;
+      let helpText = "";
+      if (registerResponse.status === 503) {
+        helpText = " The service may be temporarily unavailable. Please try again later.";
+      } else if (registerResponse.status === 500) {
+        helpText = " This is a server error. Please contact support with the request ID.";
+      } else if (errorCode === "MISSING_CHALLENGE" || errorCode === "MISSING_SIGNATURE") {
+        helpText = " This may indicate an SDK bug. Please update to the latest version.";
+      }
+      const fullMessage = requestId ? `${errorMessage} (request_id: ${requestId})${helpText}` : `${errorMessage}${helpText}`;
+      throw new MixrPayError(fullMessage);
     }
     const data = await registerResponse.json();
     return {
@@ -671,6 +823,52 @@ var AgentWallet = class {
       depositAddress: data.deposit_address
     };
   }
+  /**
+   * Check if the MixrPay server is properly configured for agent registration.
+   * 
+   * Use this to diagnose registration issues before attempting to register.
+   * 
+   * @param baseUrl - MixrPay API base URL (default: https://www.mixrpay.com)
+   * @returns Server health status including agent registration availability
+   * 
+   * @example
+   * ```typescript
+   * const status = await AgentWallet.checkServerHealth();
+   * if (!status.agentRegistrationAvailable) {
+   *   console.error('Agent registration is not available:', status);
+   * }
+   * ```
+   */
+  static async checkServerHealth(baseUrl) {
+    const url = (baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    try {
+      const response = await fetch(`${url}/api/health/ready?details=true`);
+      if (!response.ok) {
+        return {
+          healthy: false,
+          database: "unknown",
+          agentRegistrationAvailable: false,
+          privyConfigured: false,
+          error: `Health check failed with status ${response.status}`
+        };
+      }
+      const data = await response.json();
+      return {
+        healthy: data.status === "ready",
+        database: data.database || "unknown",
+        agentRegistrationAvailable: data.services?.agentRegistration?.available ?? false,
+        privyConfigured: data.services?.privy?.configured ?? false
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        database: "unreachable",
+        agentRegistrationAvailable: false,
+        privyConfigured: false,
+        error: error instanceof Error ? error.message : "Failed to reach server"
+      };
+    }
+  }
   /**
    * Get a session key for an already-registered agent.
    * 
@@ -845,6 +1043,67 @@ var AgentWallet = class {
     }
     return true;
   }
+  /**
+   * Withdraw USDC from agent's MixrPay wallet to their external wallet.
+   * 
+   * SECURITY: Withdrawals can ONLY go to the agent's own registration wallet
+   * (the wallet used during `register()`). This prevents prompt injection
+   * attacks where a compromised agent might be tricked into withdrawing
+   * to an attacker's address.
+   * 
+   * @param options - Withdrawal options
+   * @returns Withdrawal result with transaction hash
+   * @throws {MixrPayError} If withdrawal fails
+   * 
+   * @example
+   * ```typescript
+   * const result = await AgentWallet.withdraw({
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   *   amountUsd: 50.00,
+   * });
+   * 
+   * console.log(`Withdrew $${result.amountUsd}`);
+   * console.log(`Transaction: ${result.txHash}`);
+   * console.log(`Remaining balance: $${result.remainingBalanceUsd}`);
+   * ```
+   */
+  static async withdraw(options) {
+    const { privateKey, amountUsd } = options;
+    const baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    const account = privateKeyToAccount2(privateKey);
+    const walletAddress = account.address;
+    const challengeResponse = await fetch(
+      `${baseUrl}/api/v1/agent/challenge?wallet=${walletAddress}&action=withdraw`
+    );
+    if (!challengeResponse.ok) {
+      const error = await challengeResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get challenge: ${challengeResponse.status}`);
+    }
+    const { challenge, message } = await challengeResponse.json();
+    const signature = await signMessage({ message, privateKey });
+    const withdrawResponse = await fetch(`${baseUrl}/api/v1/agent/withdraw`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        challenge,
+        external_wallet: walletAddress,
+        signature,
+        to_address: walletAddress,
+        // Always withdraw to self
+        amount_usd: amountUsd
+      })
+    });
+    if (!withdrawResponse.ok) {
+      const error = await withdrawResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Withdrawal failed: ${withdrawResponse.status}`);
+    }
+    const data = await withdrawResponse.json();
+    return {
+      txHash: data.tx_hash,
+      amountUsd: data.amount_usd,
+      remainingBalanceUsd: data.remaining_balance_usd
+    };
+  }
   // ===========================================================================
   // Core Methods
   // ===========================================================================
@@ -883,6 +1142,7 @@ var AgentWallet = class {
    */
   async fetch(url, init) {
     this.logger.debug(`Fetching ${init?.method || "GET"} ${url}`);
+    await this.validateMerchantAllowed(url, "url");
     const requestId = crypto.randomUUID();
     const correlationId = this.extractCorrelationId(init?.headers);
     const controller = new AbortController();
@@ -1156,7 +1416,8 @@ var AgentWallet = class {
           },
           expiresAt: data.expires_at ? new Date(data.expires_at) : null,
           createdAt: data.created_at ? new Date(data.created_at) : null,
-          name: data.name
+          name: data.name,
+          allowedMerchants: data.allowed_merchants ?? data.allowedMerchants ?? []
         };
         this.sessionKeyInfoFetchedAt = Date.now();
         return this.sessionKeyInfo;
@@ -1722,6 +1983,7 @@ var AgentWallet = class {
       feature
     } = options;
     this.logger.debug("callMerchantApi", { url, method, merchantPublicKey, priceUsd });
+    await this.validateMerchantAllowed(url, "url");
     if (priceUsd !== void 0 && this.maxPaymentUsd !== void 0 && priceUsd > this.maxPaymentUsd) {
       throw new SpendingLimitExceededError("client_max", this.maxPaymentUsd, priceUsd);
     }
@@ -1929,6 +2191,7 @@ Timestamp: ${timestamp}`;
    */
   async callMCPTool(toolName, args = {}) {
     this.logger.debug("callMCPTool", { toolName, args });
+    await this.validateMerchantAllowed(toolName, "tool");
     const authHeaders = await this.getMCPAuthHeaders();
     const response = await fetch(`${this.baseUrl}/api/mcp`, {
       method: "POST",
@@ -2318,6 +2581,7 @@ Timestamp: ${timestamp}`;
    */
   async callMCPToolWithSession(sessionId, toolName, args = {}) {
     this.logger.debug("callMCPToolWithSession", { sessionId, toolName, args });
+    await this.validateMerchantAllowed(toolName, "tool");
     const response = await fetch(`${this.baseUrl}/api/mcp`, {
       method: "POST",
       headers: {
@@ -2367,6 +2631,7 @@ export {
   AgentWallet,
   InsufficientBalanceError,
   InvalidSessionKeyError,
+  MerchantNotAllowedError,
   MixrPayError,
   PaymentFailedError,
   SDK_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixrpay/agent-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MixrPay Agent SDK - Enable AI agents to make x402 payments with session keys",
   "type": "module",
   "main": "./dist/index.js",