@mixrpay/agent-sdk 0.3.2 → 0.3.3

package/README.md

@@ -1,495 +1,71 @@
-# MixrPay Agent SDK for JavaScript/TypeScript
+# @mixrpay/agent-sdk
 
-Enable AI agents to make autonomous payments. Supports both session-based payments (for MixrPay merchants) and x402 protocol (for external APIs).
+Enable AI agents to make payments.
 
-[![npm version](https://img.shields.io/npm/v/@mixrpay/agent-sdk)](https://www.npmjs.com/package/@mixrpay/agent-sdk)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
-
-## 🚀 Quick Start
-
-```typescript
-import { AgentWallet } from '@mixrpay/agent-sdk';
-
-const wallet = new AgentWallet({
-  sessionKey: 'sk_live_...'  // Get from wallet owner
-});
-
-// For MixrPay merchants (recommended):
-const response = await wallet.callMerchantApi({
-  url: 'https://api.merchant.com/generate',
-  merchantPublicKey: 'pk_live_abc123',
-  priceUsd: 0.05,
-  body: { prompt: 'Hello world' }
-});
-
-// For external x402 APIs:
-const response = await wallet.fetch('https://external-api.com/query');
-```
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @mixrpay/agent-sdk
-# or
-yarn add @mixrpay/agent-sdk
-# or
-pnpm add @mixrpay/agent-sdk
 ```
 
-## Two Payment Methods
-
-The Agent SDK supports **two payment patterns** depending on what API you're calling:
+## Setup
 
-### 1. Session-Based Payments (For MixrPay Merchants) ⭐ Recommended
-
-Use `callMerchantApi()` when the API uses MixrPay:
-
-```typescript
-const response = await wallet.callMerchantApi({
-  url: 'https://api.merchant.com/generate',
-  merchantPublicKey: 'pk_live_abc123',  // Merchant's MixrPay public key
-  priceUsd: 0.05,
-  method: 'POST',
-  body: { prompt: 'Hello world' },
-});
+```bash
+# .env
+MIXRPAY_SESSION_KEY=sk_live_...
 ```
 
-**How it works:**
-1. SDK creates/reuses a session authorization with the merchant
-2. SDK charges against the session
-3. Request is sent with `X-Mixr-Session` header
-4. No 402 round-trip needed—faster and cheaper
-
-**When to use:** APIs built with MixrPay, or any API that accepts `X-Mixr-Session` headers.
+Get session keys from [mixrpay.com/wallet/sessions](https://www.mixrpay.com/wallet/sessions).
 
-### 2. x402 Protocol (For External APIs)
-
-Use `fetch()` when calling APIs that implement x402 but aren't MixrPay merchants:
+## Usage
 
 ```typescript
-const response = await wallet.fetch('https://external-api.com/query', {
-  method: 'POST',
-  body: JSON.stringify({ prompt: 'Hello' })
-});
-```
-
-**How it works:**
-1. SDK makes initial request
-2. API returns `402 Payment Required`
-3. SDK signs payment authorization
-4. SDK retries with `X-PAYMENT` header
-
-**When to use:** External APIs that use standard x402 protocol.
-
-## 🔑 Getting Session Keys
-
-Session keys are created by wallet owners and grant spending permissions to agents:
-
-1. **From a wallet owner**: They create a session key at `/wallet/sessions`
-2. **Programmatically**: Via the MixrPay API
-
-Session keys look like: `sk_live_abc123...` (mainnet) or `sk_test_abc123...` (testnet)
-
-### Session Key Limits
-
-Each session key has configurable spending limits:
-- **Per-transaction**: Maximum amount per single request
-- **Daily**: Maximum total per 24 hours
-- **Total**: Maximum lifetime spend
-- **Expiration**: When the key becomes invalid
-
-## 📖 Session Management
-
-### Automatic (Recommended)
+import { AgentWallet } from '@mixrpay/agent-sdk';
 
-`callMerchantApi()` handles sessions automatically:
+const wallet = new AgentWallet({
+  sessionKey: process.env.MIXRPAY_SESSION_KEY!
+});
 
-```typescript
-// Sessions are created and reused automatically
 const response = await wallet.callMerchantApi({
   url: 'https://api.merchant.com/generate',
-  merchantPublicKey: 'pk_live_abc123',
+  merchantPublicKey: 'pk_live_...',
   priceUsd: 0.05,
-  body: { prompt: 'Hello' }
-});
-```
-
-### Manual Control
-
-For fine-grained control over sessions:
-
-```typescript
-// Get or create a session
-const session = await wallet.getOrCreateSession({
-  merchantPublicKey: 'pk_live_abc123',
-  spendingLimitUsd: 25,    // Max total spending
-  durationDays: 7,         // Session validity
-});
-
-console.log('Session ID:', session.id);
-console.log('Remaining:', session.remainingLimitUsd);
-console.log('Expires:', session.expiresAt);
-
-// Charge manually
-const charge = await wallet.chargeSession(session.id, 0.05, {
-  feature: 'generate',
-  idempotencyKey: `charge-${Date.now()}`,
-});
-
-// Then make your API call with the session
-const response = await fetch('https://api.merchant.com/generate', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'X-Mixr-Session': session.id,
-    'X-Mixr-Charged': 'true',  // Tell merchant payment is done
-  },
-  body: JSON.stringify({ prompt: 'Hello' }),
-});
-```
-
-### List and Revoke Sessions
-
-```typescript
-// List all active sessions
-const sessions = await wallet.listSessions();
-for (const session of sessions) {
-  console.log(`${session.merchantName}: $${session.remainingLimitUsd} remaining`);
-}
-
-// Revoke a session (e.g., when done with a merchant)
-await wallet.revokeSession(session.id);
-
-// Get session statistics
-const stats = await wallet.getSessionStats();
-console.log(`Active sessions: ${stats.activeCount}`);
-console.log(`Total authorized: $${stats.totalAuthorizedUsd}`);
-```
-
-## 💡 Usage Examples
-
-### With Payment Tracking
-
-```typescript
-import { AgentWallet, PaymentEvent } from '@mixrpay/agent-sdk';
-
-const wallet = new AgentWallet({
-  sessionKey: 'sk_live_...',
-  onPayment: (payment: PaymentEvent) => {
-    console.log(`💸 Paid $${payment.amountUsd.toFixed(4)} to ${payment.recipient}`);
-  },
+  body: { prompt: 'Hello world' }
 });
 
-// Make requests
-const response = await wallet.callMerchantApi({ ... });
-
-// Check spending
-const stats = await wallet.getSpendingStats();
-console.log(`Total spent: $${stats.totalSpentUsd.toFixed(2)}`);
-console.log(`Transactions: ${stats.txCount}`);
+const data = await response.json();
 ```
 
-### Error Handling
+## Error Handling
 
 ```typescript
-import {
-  AgentWallet,
-  InsufficientBalanceError,
-  SpendingLimitExceededError,
-  SessionKeyExpiredError,
-  // Session Authorization Errors
-  SessionExpiredError,
-  SessionLimitExceededError,
-  SessionNotFoundError,
-  SessionRevokedError,
-} from '@mixrpay/agent-sdk';
-
-const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
+import { AgentWallet, InsufficientBalanceError, SessionLimitExceededError } from '@mixrpay/agent-sdk';
 
 try {
   const response = await wallet.callMerchantApi({ ... });
 } catch (error) {
   if (error instanceof InsufficientBalanceError) {
-    console.log(`❌ Not enough funds: need $${error.required}, have $${error.available}`);
-    console.log(`   Top up at: ${error.topUpUrl}`);
-  } else if (error instanceof SessionExpiredError) {
-    console.log(`❌ Session ${error.sessionId} expired`);
-    // SDK will auto-create on next callMerchantApi()
-  } else if (error instanceof SessionLimitExceededError) {
-    console.log(`❌ Session limit exceeded`);
-    console.log(`   Limit: $${error.limit}, Requested: $${error.requested}, Remaining: $${error.remaining}`);
-  } else if (error instanceof SessionNotFoundError) {
-    console.log(`❌ Session ${error.sessionId} not found`);
-  } else if (error instanceof SessionRevokedError) {
-    console.log(`❌ Session ${error.sessionId} was revoked: ${error.reason || 'no reason given'}`);
-  } else if (error instanceof SpendingLimitExceededError) {
-    console.log(`❌ Session key limit exceeded: ${error.limitType}`);
-  } else if (error instanceof SessionKeyExpiredError) {
-    console.log(`❌ Session key expired at ${error.expiredAt}`);
-  } else {
-    throw error;
+    console.log(`Top up at: ${error.topUpUrl}`);
   }
 }
 ```
 
-### With Client-Side Safety Limit
+## Spending Controls
 
 ```typescript
 const wallet = new AgentWallet({
   sessionKey: 'sk_live_...',
-  maxPaymentUsd: 1.0,  // Never pay more than $1 per request
-});
-
-// If an API tries to charge more than $1, the SDK will throw
-// SpendingLimitExceededError with limitType: 'client_max'
-```
-
-### Debug Mode
-
-```typescript
-// Enable logging during initialization
-const wallet = new AgentWallet({
-  sessionKey: 'sk_live_...',
-  logLevel: 'debug',  // 'debug' | 'info' | 'warn' | 'error' | 'none'
-});
-
-// Or toggle at runtime
-wallet.setDebug(true);
-```
-
-## 🤖 AI Framework Integrations
-
-### Vercel AI SDK
-
-```typescript
-import { AgentWallet, SessionLimitExceededError } from '@mixrpay/agent-sdk';
-import { generateText } from 'ai';
-import { openai } from '@ai-sdk/openai';
-import { z } from 'zod';
-
-const wallet = new AgentWallet({
-  sessionKey: process.env.MIXRPAY_SESSION_KEY!,
-  maxPaymentUsd: 1.00,
+  maxPaymentUsd: 1.0,
+  onPayment: (payment) => console.log(`Paid $${payment.amountUsd}`),
 });
 
-const result = await generateText({
-  model: openai('gpt-4'),
-  tools: {
-    paidSearch: {
-      description: 'Search using a premium paid API',
-      parameters: z.object({ query: z.string() }),
-      execute: async ({ query }) => {
-        try {
-          const response = await wallet.callMerchantApi({
-            url: 'https://api.search.com/query',
-            merchantPublicKey: 'pk_live_...',
-            priceUsd: 0.05,
-            body: { query }
-          });
-          return response.json();
-        } catch (error) {
-          if (error instanceof SessionLimitExceededError) {
-            return { error: 'Budget exceeded', limit: error.limitType };
-          }
-          throw error;
-        }
-      }
-    }
-  },
-  prompt: 'Search for the latest AI news'
-});
+const balance = await wallet.getBalance();
 ```
 
-### LangChain.js
-
-```typescript
-import { AgentWallet, InsufficientBalanceError } from '@mixrpay/agent-sdk';
-import { DynamicTool } from '@langchain/core/tools';
-
-const wallet = new AgentWallet({ 
-  sessionKey: process.env.MIXRPAY_SESSION_KEY!,
-  maxPaymentUsd: 0.50,
-});
-
-const paidSearchTool = new DynamicTool({
-  name: 'paid_search',
-  description: 'Premium search API ($0.05/query)',
-  func: async (query: string) => {
-    try {
-      const response = await wallet.callMerchantApi({
-        url: 'https://api.search.com/query',
-        merchantPublicKey: 'pk_live_...',
-        priceUsd: 0.05,
-        body: { query }
-      });
-      const data = await response.json();
-      return JSON.stringify(data.results);
-    } catch (error) {
-      if (error instanceof InsufficientBalanceError) {
-        return `Error: Low balance. Top up: ${error.topUpUrl}`;
-      }
-      return `Error: ${error instanceof Error ? error.message : 'Unknown'}`;
-    }
-  }
-});
-```
-
-## 📚 API Reference
-
-### AgentWallet
-
-```typescript
-new AgentWallet({
-  // Required
-  sessionKey: string;              // Session key (sk_live_... or sk_test_...)
-  
-  // Optional
-  walletAddress?: string;          // Smart wallet address (auto-detected)
-  maxPaymentUsd?: number;          // Client-side payment limit
-  onPayment?: (PaymentEvent) => void;  // Payment callback
-  facilitatorUrl?: string;         // x402 facilitator URL
-  baseUrl?: string;                // MixrPay API base URL
-  timeout?: number;                // Request timeout in ms (default: 30000)
-  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
-})
-```
-
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `callMerchantApi(options)` | Make request to MixrPay merchant (session-based) |
-| `fetch(url, init?)` | Make request to x402 API (drop-in for native fetch) |
-| `getOrCreateSession(options)` | Get or create session with merchant |
-| `chargeSession(id, amount, options?)` | Charge against a session |
-| `listSessions()` | List all active sessions |
-| `revokeSession(id)` | Revoke a session |
-| `getSessionStats()` | Get session statistics |
-| `getBalance()` | Get USDC balance in USD |
-| `getSpendingStats()` | Get spending statistics |
-| `getSessionKeyInfo()` | Get session key details and limits |
-| `getPaymentHistory()` | Get list of payments made |
-| `getTotalSpent()` | Get total amount spent |
-| `getWalletAddress()` | Get wallet address |
-| `getNetwork()` | Get network info (Base or Base Sepolia) |
-| `isTestnet()` | Check if using testnet |
-| `runDiagnostics()` | Run health checks |
-| `setDebug(enable)` | Toggle debug logging |
-
-### Types
-
-```typescript
-interface SessionAuthorization {
-  id: string;
-  merchantId: string;
-  merchantName: string;
-  status: 'pending' | 'active' | 'expired' | 'revoked';
-  spendingLimitUsd: number;
-  amountUsedUsd: number;
-  remainingLimitUsd: number;
-  expiresAt: Date;
-  createdAt: Date;
-}
-
-interface SessionStats {
-  activeCount: number;
-  expiredCount: number;
-  revokedCount: number;
-  totalAuthorizedUsd: number;
-  totalSpentUsd: number;
-  totalRemainingUsd: number;
-  activeSessions: Array<{
-    id: string;
-    merchantName: string;
-    merchantPublicKey: string;
-    spendingLimitUsd: number;
-    remainingUsd: number;
-    expiresAt: Date;
-  }>;
-}
-
-interface ChargeResult {
-  success: boolean;
-  chargeId: string;
-  amountUsd: number;
-  txHash?: string;
-  remainingSessionBalanceUsd: number;
-}
-
-interface PaymentEvent {
-  amountUsd: number;
-  recipient: string;
-  txHash: string | null;
-  timestamp: Date;
-  description?: string;
-  url?: string;
-}
-```
-
-### Exceptions
-
-| Exception | When Thrown |
-|-----------|-------------|
-| `InsufficientBalanceError` | Wallet doesn't have enough USDC |
-| `SessionKeyExpiredError` | Session key has expired |
-| `SpendingLimitExceededError` | Would exceed session key limits |
-| `SessionExpiredError` | Session authorization has expired |
-| `SessionLimitExceededError` | Would exceed session spending limit |
-| `SessionNotFoundError` | Session ID is invalid |
-| `SessionRevokedError` | Session was revoked |
-| `PaymentFailedError` | Payment transaction failed |
-| `InvalidSessionKeyError` | Invalid session key format |
-| `X402ProtocolError` | x402 protocol handling error |
-
-## 🌐 Networks
-
-| Network | Chain ID | Session Key Prefix | USDC Address |
-|---------|----------|-------------------|--------------|
-| Base Mainnet | 8453 | `sk_live_` | Production USDC |
-| Base Sepolia | 84532 | `sk_test_` | Test USDC |
-
-### Testing on Testnet
-
-```typescript
-// Test environment setup
-const wallet = new AgentWallet({
-  sessionKey: 'sk_test_...',  // Use test key
-  baseUrl: 'http://localhost:3000',  // Local dev server
-});
-
-// The SDK automatically detects testnet from sk_test_ prefix
-console.log(`Testnet: ${wallet.isTestnet()}`);  // true
-```
-
-## 🔧 Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `MIXRPAY_SESSION_KEY` | Yes | Your session key (`sk_live_...` or `sk_test_...`) |
-| `MIXRPAY_BASE_URL` | No | MixrPay server URL (default: `https://www.mixrpay.com`) |
-
-## 🔒 Security Best Practices
-
-1. **Store session keys securely** - Use environment variables, never commit to source
-2. **Set appropriate limits** - Use `maxPaymentUsd` as a safety net
-3. **Monitor spending** - Use `onPayment` callback and `getSpendingStats()`
-4. **Use testnet first** - Test with `sk_test_` keys before production
-5. **Configure base URL** - Always set `baseUrl` explicitly in production
-
-## 📋 Changelog
-
-### v0.2.0 (Current)
-- Added session-based payments (`callMerchantApi()`)
-- Added session management (`getOrCreateSession()`, `listSessions()`, `revokeSession()`)
-- Added session-related error types
-- Improved documentation
+## Documentation
 
-### v0.1.0
-- Initial release
-- x402 payment handling via `fetch()`
-- Session key validation and spending limits
-- Payment callbacks and statistics
+[mixrpay.com/docs](https://www.mixrpay.com/docs)
 
-## 📝 License
+## License
 
 MIT

package/dist/index.cjs

@@ -1467,6 +1467,227 @@ var AgentWallet = class {
       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
+    };
+  }
+  /**
+   * 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
+    };
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -745,6 +745,129 @@ declare class AgentWallet {
      * Parse session response data into SessionAuthorization object.
      */
     private parseSessionResponse;
+    /**
+     * 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,
+     *   }),
+     * });
+     * ```
+     */
+    getMCPAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    listMCPTools(): Promise<MCPTool[]>;
+    /**
+     * 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}`);
+     * ```
+     */
+    callMCPTool(toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    /**
+     * 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' }
+     * );
+     * ```
+     */
+    callMCPToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+}
+/**
+ * MCP Tool definition returned by listMCPTools()
+ */
+interface MCPTool {
+    /** Tool name in format "merchant/tool" */
+    name: string;
+    /** Human-readable description with price */
+    description: string;
+    /** JSON Schema for tool input parameters */
+    inputSchema: Record<string, unknown>;
+    /** Price per call in USD */
+    priceUsd: number;
+    /** Merchant/provider name */
+    merchantName: string;
+    /** Merchant slug for session creation */
+    merchantSlug: string;
+    /** Whether the provider is domain-verified */
+    verified: boolean;
+}
+/**
+ * Result from calling an MCP tool
+ */
+interface MCPToolResult {
+    /** The tool's response data */
+    data: unknown;
+    /** Amount charged in USD */
+    chargedUsd: number;
+    /** On-chain transaction hash (if available) */
+    txHash?: string;
+    /** Execution latency in milliseconds */
+    latencyMs?: number;
 }
 
 /**

package/dist/index.d.ts

@@ -745,6 +745,129 @@ declare class AgentWallet {
      * Parse session response data into SessionAuthorization object.
      */
     private parseSessionResponse;
+    /**
+     * 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,
+     *   }),
+     * });
+     * ```
+     */
+    getMCPAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    listMCPTools(): Promise<MCPTool[]>;
+    /**
+     * 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}`);
+     * ```
+     */
+    callMCPTool(toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    /**
+     * 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' }
+     * );
+     * ```
+     */
+    callMCPToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+}
+/**
+ * MCP Tool definition returned by listMCPTools()
+ */
+interface MCPTool {
+    /** Tool name in format "merchant/tool" */
+    name: string;
+    /** Human-readable description with price */
+    description: string;
+    /** JSON Schema for tool input parameters */
+    inputSchema: Record<string, unknown>;
+    /** Price per call in USD */
+    priceUsd: number;
+    /** Merchant/provider name */
+    merchantName: string;
+    /** Merchant slug for session creation */
+    merchantSlug: string;
+    /** Whether the provider is domain-verified */
+    verified: boolean;
+}
+/**
+ * Result from calling an MCP tool
+ */
+interface MCPToolResult {
+    /** The tool's response data */
+    data: unknown;
+    /** Amount charged in USD */
+    chargedUsd: number;
+    /** On-chain transaction hash (if available) */
+    txHash?: string;
+    /** Execution latency in milliseconds */
+    latencyMs?: number;
 }
 
 /**

package/dist/index.js

@@ -1433,6 +1433,227 @@ var AgentWallet = class {
       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
+    };
+  }
+  /**
+   * 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixrpay/agent-sdk",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "MixrPay Agent SDK - Enable AI agents to make x402 payments with session keys",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,19 +29,7 @@
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
-  "keywords": [
-    "payments",
-    "ai-agents",
-    "x402",
-    "cryptocurrency",
-    "usdc",
-    "blockchain",
-    "web3",
-    "vercel-ai-sdk",
-    "langchain",
-    "ai",
-    "agent"
-  ],
+  "keywords": [],
   "author": "MixrPay <support@mixrpay.com>",
   "license": "MIT",
   "repository": {