@mixrpay/agent-sdk 0.6.1 → 0.8.0

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.1";
+var SDK_VERSION = "0.8.0";
 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
   // ===========================================================================
   /**
@@ -1000,6 +1141,91 @@ var AgentWallet = class {
       remainingBalanceUsd: data.remaining_balance_usd
     };
   }
+  /**
+   * Claim an agent invite code to receive a session key for the inviter's wallet.
+   * 
+   * This allows an agent to get a pre-configured session key from a human wallet owner
+   * without needing to register their own wallet or fund it. The human sets the budget
+   * limits and merchant whitelist when creating the invite.
+   * 
+   * @param options - Claim invite options including the invite code and agent's private key
+   * @returns Claim result with the new session key
+   * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+   * 
+   * @example
+   * ```typescript
+   * // Human creates invite at their dashboard, shares code "mixr-abc123"
+   * 
+   * const result = await AgentWallet.claimInvite({
+   *   inviteCode: 'mixr-abc123',
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   * });
+   * 
+   * console.log(`Got session key: ${result.sessionKey}`);
+   * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+   * console.log(`Invited by: ${result.inviterName}`);
+   * 
+   * // Use the session key to make payments
+   * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+   * const response = await wallet.fetch('https://api.example.com/endpoint');
+   * ```
+   */
+  static async claimInvite(options) {
+    const { inviteCode, privateKey } = 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=claim-invite`
+    );
+    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 claimResponse = await fetch(`${baseUrl}/api/v1/agent/claim-invite`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        invite_code: inviteCode,
+        challenge,
+        agent_wallet_address: walletAddress,
+        signature
+      })
+    });
+    if (!claimResponse.ok) {
+      const error = await claimResponse.json().catch(() => ({}));
+      const errorMessage = error.error || `Failed to claim invite: ${claimResponse.status}`;
+      let helpText = "";
+      if (claimResponse.status === 404) {
+        helpText = " The invite code may be invalid or misspelled.";
+      } else if (claimResponse.status === 400) {
+        if (errorMessage.includes("already claimed")) {
+          helpText = " This invite has already been used by another agent.";
+        } else if (errorMessage.includes("expired")) {
+          helpText = " Ask the wallet owner to create a new invite.";
+        } else if (errorMessage.includes("revoked")) {
+          helpText = " The wallet owner has revoked this invite.";
+        }
+      }
+      throw new MixrPayError(`${errorMessage}${helpText}`);
+    }
+    const data = await claimResponse.json();
+    return {
+      sessionKey: data.session_key,
+      address: data.address,
+      sessionKeyId: data.session_key_id,
+      expiresAt: new Date(data.expires_at),
+      limits: {
+        budgetUsd: data.limits.budget_usd,
+        budgetPeriod: data.limits.budget_period,
+        maxPerTxUsd: data.limits.max_per_tx_usd
+      },
+      allowedMerchants: data.allowed_merchants || [],
+      inviterName: data.inviter_name || "Anonymous"
+    };
+  }
   // ===========================================================================
   // Core Methods
   // ===========================================================================
@@ -1038,6 +1264,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();
@@ -1311,7 +1538,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;
@@ -1877,6 +2105,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);
     }
@@ -2084,6 +2313,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",
@@ -2473,6 +2703,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: {
@@ -2523,6 +2754,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.1";
+declare const SDK_VERSION = "0.8.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -509,6 +511,43 @@ interface AgentWithdrawResult {
     /** Remaining balance after withdrawal */
     remainingBalanceUsd: number;
 }
+/**
+ * Options for claiming an agent invite
+ */
+interface AgentClaimInviteOptions {
+    /** The invite code provided by the human wallet owner (e.g., "mixr-abc123") */
+    inviteCode: string;
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from claiming an agent invite
+ */
+interface AgentClaimInviteResult {
+    /** The session key in sk_live_{hex} format - STORE SECURELY! */
+    sessionKey: string;
+    /** The derived public address of the session key */
+    address: string;
+    /** Session key database ID */
+    sessionKeyId: string;
+    /** When the session key expires */
+    expiresAt: Date;
+    /** Budget limits set by the inviter */
+    limits: {
+        /** Total budget in USD */
+        budgetUsd: number;
+        /** Budget period: 'daily', 'monthly', or 'total' */
+        budgetPeriod: string;
+        /** Maximum per transaction in USD (null = no limit) */
+        maxPerTxUsd: number | null;
+    };
+    /** Whitelisted merchants/tools (empty = allow all) */
+    allowedMerchants: string[];
+    /** Name of the person who created the invite */
+    inviterName: string;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -561,6 +600,8 @@ declare class AgentWallet {
     private totalSpentUsd;
     private sessionKeyInfo?;
     private sessionKeyInfoFetchedAt?;
+    private allowlist?;
+    private allowlistFetchedAt?;
     /**
      * Create a new AgentWallet instance.
      *
@@ -590,6 +631,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.
      *
@@ -727,6 +797,36 @@ declare class AgentWallet {
      * ```
      */
     static withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
+    /**
+     * Claim an agent invite code to receive a session key for the inviter's wallet.
+     *
+     * This allows an agent to get a pre-configured session key from a human wallet owner
+     * without needing to register their own wallet or fund it. The human sets the budget
+     * limits and merchant whitelist when creating the invite.
+     *
+     * @param options - Claim invite options including the invite code and agent's private key
+     * @returns Claim result with the new session key
+     * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+     *
+     * @example
+     * ```typescript
+     * // Human creates invite at their dashboard, shares code "mixr-abc123"
+     *
+     * const result = await AgentWallet.claimInvite({
+     *   inviteCode: 'mixr-abc123',
+     *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+     * });
+     *
+     * console.log(`Got session key: ${result.sessionKey}`);
+     * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+     * console.log(`Invited by: ${result.inviterName}`);
+     *
+     * // Use the session key to make payments
+     * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+     * const response = await wallet.fetch('https://api.example.com/endpoint');
+     * ```
+     */
+    static claimInvite(options: AgentClaimInviteOptions): Promise<AgentClaimInviteResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *
@@ -1783,6 +1883,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.
  *
@@ -1819,4 +1947,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.1";
+declare const SDK_VERSION = "0.8.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -509,6 +511,43 @@ interface AgentWithdrawResult {
     /** Remaining balance after withdrawal */
     remainingBalanceUsd: number;
 }
+/**
+ * Options for claiming an agent invite
+ */
+interface AgentClaimInviteOptions {
+    /** The invite code provided by the human wallet owner (e.g., "mixr-abc123") */
+    inviteCode: string;
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from claiming an agent invite
+ */
+interface AgentClaimInviteResult {
+    /** The session key in sk_live_{hex} format - STORE SECURELY! */
+    sessionKey: string;
+    /** The derived public address of the session key */
+    address: string;
+    /** Session key database ID */
+    sessionKeyId: string;
+    /** When the session key expires */
+    expiresAt: Date;
+    /** Budget limits set by the inviter */
+    limits: {
+        /** Total budget in USD */
+        budgetUsd: number;
+        /** Budget period: 'daily', 'monthly', or 'total' */
+        budgetPeriod: string;
+        /** Maximum per transaction in USD (null = no limit) */
+        maxPerTxUsd: number | null;
+    };
+    /** Whitelisted merchants/tools (empty = allow all) */
+    allowedMerchants: string[];
+    /** Name of the person who created the invite */
+    inviterName: string;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -561,6 +600,8 @@ declare class AgentWallet {
     private totalSpentUsd;
     private sessionKeyInfo?;
     private sessionKeyInfoFetchedAt?;
+    private allowlist?;
+    private allowlistFetchedAt?;
     /**
      * Create a new AgentWallet instance.
      *
@@ -590,6 +631,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.
      *
@@ -727,6 +797,36 @@ declare class AgentWallet {
      * ```
      */
     static withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
+    /**
+     * Claim an agent invite code to receive a session key for the inviter's wallet.
+     *
+     * This allows an agent to get a pre-configured session key from a human wallet owner
+     * without needing to register their own wallet or fund it. The human sets the budget
+     * limits and merchant whitelist when creating the invite.
+     *
+     * @param options - Claim invite options including the invite code and agent's private key
+     * @returns Claim result with the new session key
+     * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+     *
+     * @example
+     * ```typescript
+     * // Human creates invite at their dashboard, shares code "mixr-abc123"
+     *
+     * const result = await AgentWallet.claimInvite({
+     *   inviteCode: 'mixr-abc123',
+     *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+     * });
+     *
+     * console.log(`Got session key: ${result.sessionKey}`);
+     * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+     * console.log(`Invited by: ${result.inviterName}`);
+     *
+     * // Use the session key to make payments
+     * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+     * const response = await wallet.fetch('https://api.example.com/endpoint');
+     * ```
+     */
+    static claimInvite(options: AgentClaimInviteOptions): Promise<AgentClaimInviteResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *
@@ -1783,6 +1883,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.
  *
@@ -1819,4 +1947,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.1";
+var SDK_VERSION = "0.8.0";
 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
   // ===========================================================================
   /**
@@ -964,6 +1104,91 @@ var AgentWallet = class {
       remainingBalanceUsd: data.remaining_balance_usd
     };
   }
+  /**
+   * Claim an agent invite code to receive a session key for the inviter's wallet.
+   * 
+   * This allows an agent to get a pre-configured session key from a human wallet owner
+   * without needing to register their own wallet or fund it. The human sets the budget
+   * limits and merchant whitelist when creating the invite.
+   * 
+   * @param options - Claim invite options including the invite code and agent's private key
+   * @returns Claim result with the new session key
+   * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+   * 
+   * @example
+   * ```typescript
+   * // Human creates invite at their dashboard, shares code "mixr-abc123"
+   * 
+   * const result = await AgentWallet.claimInvite({
+   *   inviteCode: 'mixr-abc123',
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   * });
+   * 
+   * console.log(`Got session key: ${result.sessionKey}`);
+   * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+   * console.log(`Invited by: ${result.inviterName}`);
+   * 
+   * // Use the session key to make payments
+   * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+   * const response = await wallet.fetch('https://api.example.com/endpoint');
+   * ```
+   */
+  static async claimInvite(options) {
+    const { inviteCode, privateKey } = 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=claim-invite`
+    );
+    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 claimResponse = await fetch(`${baseUrl}/api/v1/agent/claim-invite`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        invite_code: inviteCode,
+        challenge,
+        agent_wallet_address: walletAddress,
+        signature
+      })
+    });
+    if (!claimResponse.ok) {
+      const error = await claimResponse.json().catch(() => ({}));
+      const errorMessage = error.error || `Failed to claim invite: ${claimResponse.status}`;
+      let helpText = "";
+      if (claimResponse.status === 404) {
+        helpText = " The invite code may be invalid or misspelled.";
+      } else if (claimResponse.status === 400) {
+        if (errorMessage.includes("already claimed")) {
+          helpText = " This invite has already been used by another agent.";
+        } else if (errorMessage.includes("expired")) {
+          helpText = " Ask the wallet owner to create a new invite.";
+        } else if (errorMessage.includes("revoked")) {
+          helpText = " The wallet owner has revoked this invite.";
+        }
+      }
+      throw new MixrPayError(`${errorMessage}${helpText}`);
+    }
+    const data = await claimResponse.json();
+    return {
+      sessionKey: data.session_key,
+      address: data.address,
+      sessionKeyId: data.session_key_id,
+      expiresAt: new Date(data.expires_at),
+      limits: {
+        budgetUsd: data.limits.budget_usd,
+        budgetPeriod: data.limits.budget_period,
+        maxPerTxUsd: data.limits.max_per_tx_usd
+      },
+      allowedMerchants: data.allowed_merchants || [],
+      inviterName: data.inviter_name || "Anonymous"
+    };
+  }
   // ===========================================================================
   // Core Methods
   // ===========================================================================
@@ -1002,6 +1227,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();
@@ -1275,7 +1501,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;
@@ -1841,6 +2068,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);
     }
@@ -2048,6 +2276,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",
@@ -2437,6 +2666,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: {
@@ -2486,6 +2716,7 @@ export {
   AgentWallet,
   InsufficientBalanceError,
   InvalidSessionKeyError,
+  MerchantNotAllowedError,
   MixrPayError,
   PaymentFailedError,
   SDK_VERSION,

package/package.json

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