@mixrpay/agent-sdk 0.4.1

package/dist/index.d.cts

@@ -0,0 +1,1431 @@
+/**
+ * MixrPay Agent SDK - Type definitions
+ *
+ * This file contains all TypeScript types and interfaces used throughout the SDK.
+ */
+/**
+ * Configuration options for AgentWallet.
+ *
+ * @example Minimal configuration
+ * ```typescript
+ * const config: AgentWalletConfig = {
+ *   sessionKey: 'sk_live_abc123...'
+ * };
+ * ```
+ *
+ * @example Full configuration
+ * ```typescript
+ * const config: AgentWalletConfig = {
+ *   sessionKey: 'sk_live_abc123...',
+ *   maxPaymentUsd: 5.0,
+ *   onPayment: (p) => console.log(`Paid $${p.amountUsd}`),
+ *   logLevel: 'info',
+ *   timeout: 60000,
+ * };
+ * ```
+ */
+interface AgentWalletConfig {
+    /**
+     * Session key granted by the wallet owner.
+     *
+     * Format: `sk_live_` (mainnet) or `sk_test_` (testnet) followed by 64 hex characters.
+     *
+     * Get session keys from:
+     * - The wallet owner's MixrPay dashboard
+     * - Programmatically via the MixrPay API
+     * - The MixrPay widget session key management
+     *
+     * @example 'sk_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
+     */
+    sessionKey: string;
+    /**
+     * Optional smart wallet address.
+     *
+     * If not provided, will be derived from the session key.
+     * Only needed in advanced scenarios where the session key address
+     * differs from the wallet address.
+     */
+    walletAddress?: string;
+    /**
+     * Optional client-side maximum payment per request in USD.
+     *
+     * This is an additional safety limit on the client side, independent
+     * of the session key's limits. Useful for preventing accidental
+     * large payments due to bugs or misconfiguration.
+     *
+     * @example 5.0 - Maximum $5 per request
+     */
+    maxPaymentUsd?: number;
+    /**
+     * Optional callback when a payment is successfully made.
+     *
+     * Use this to track payments in your application, update UI,
+     * or log payment events.
+     *
+     * @example
+     * ```typescript
+     * onPayment: (payment) => {
+     *   console.log(`Paid $${payment.amountUsd} for ${payment.description}`);
+     *   analytics.track('payment', payment);
+     * }
+     * ```
+     */
+    onPayment?: (payment: PaymentEvent) => void;
+    /**
+     * x402 facilitator endpoint.
+     *
+     * The facilitator processes the payment and forwards the request.
+     * Default: 'https://x402.org/facilitator'
+     */
+    facilitatorUrl?: string;
+    /**
+     * MixrPay API base URL.
+     *
+     * Default: 'http://localhost:3000' (or MIXRPAY_BASE_URL env var)
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Log level for SDK operations.
+     *
+     * - 'debug': Verbose logging for development
+     * - 'info': Important events (payments, etc.)
+     * - 'warn': Warnings only
+     * - 'error': Errors only
+     * - 'none': No logging (default)
+     *
+     * @example 'info' - Log payments and important events
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+}
+/**
+ * Record of a payment made by the SDK.
+ *
+ * This is emitted via the `onPayment` callback and stored in the payment history.
+ */
+interface PaymentEvent {
+    /** Payment amount in USD */
+    amountUsd: number;
+    /** Recipient wallet address */
+    recipient: string;
+    /** Transaction hash on the blockchain (if available) */
+    txHash: string | null;
+    /** Timestamp when the payment was made */
+    timestamp: Date;
+    /** Description of what was paid for (from the server) */
+    description?: string;
+    /** URL that triggered the payment */
+    url?: string;
+}
+/**
+ * Information about a session key.
+ */
+interface SessionKeyInfo {
+    /** The session key's address (derived public key) */
+    address: string;
+    /** Whether the session key is currently valid */
+    isValid: boolean;
+    /** Spending limits configured for this session key */
+    limits: {
+        /** Maximum amount per transaction in USD (null = no limit) */
+        perTxUsd: number | null;
+        /** Maximum amount per day in USD (null = no limit) */
+        dailyUsd: number | null;
+        /** Maximum total amount in USD (null = no limit) */
+        totalUsd: number | null;
+    };
+    /** Current usage statistics */
+    usage: {
+        /** Amount spent today in USD */
+        todayUsd: number;
+        /** Total amount spent in USD */
+        totalUsd: number;
+        /** Number of transactions made */
+        txCount: number;
+    };
+    /** When the session key expires (null = never) */
+    expiresAt: Date | null;
+    /** When the session key was created */
+    createdAt: Date | null;
+    /** Optional name given to this session key */
+    name?: string;
+}
+/**
+ * Spending statistics for the current session.
+ */
+interface SpendingStats {
+    /** Total amount spent in USD during this session */
+    totalSpentUsd: number;
+    /** Number of payment transactions made */
+    txCount: number;
+    /** Remaining daily limit in USD (null if no limit or unknown) */
+    remainingDailyUsd: number | null;
+    /** Remaining total limit in USD (null if no limit or unknown) */
+    remainingTotalUsd: number | null;
+    /** When the session key expires (null if never or unknown) */
+    expiresAt: Date | null;
+}
+/**
+ * Result of running diagnostics on the wallet.
+ */
+interface DiagnosticsResult {
+    /** Whether all checks passed */
+    healthy: boolean;
+    /** List of issues found (empty if healthy) */
+    issues: string[];
+    /** Individual check results */
+    checks: {
+        /** Session key format is valid */
+        sessionKeyFormat?: boolean;
+        /** Can connect to MixrPay API */
+        apiConnectivity?: boolean;
+        /** Session key is valid and not expired */
+        sessionKeyValid?: boolean;
+        /** Wallet has USDC balance */
+        hasBalance?: boolean;
+    };
+    /** SDK version */
+    sdkVersion: string;
+    /** Network name (Base or Base Sepolia) */
+    network: string;
+    /** Wallet address */
+    walletAddress: string;
+}
+/**
+ * Options for creating a session authorization with a MixrPay merchant.
+ */
+interface CreateSessionOptions {
+    /**
+     * The merchant's MixrPay public key.
+     * Format: `pk_live_...` or `pk_test_...`
+     */
+    merchantPublicKey: string;
+    /**
+     * Maximum spending limit for this session in USD.
+     * @default 25.00
+     */
+    spendingLimitUsd?: number;
+    /**
+     * Number of days this session should be valid.
+     * @default 7
+     */
+    durationDays?: number;
+}
+/**
+ * Status of a session authorization.
+ */
+type SessionAuthStatus = 'pending' | 'active' | 'expired' | 'revoked';
+/**
+ * A session authorization with a MixrPay merchant.
+ *
+ * This represents a user-approved spending permission for a specific merchant.
+ */
+interface SessionAuthorization {
+    /** Unique session ID */
+    id: string;
+    /** Merchant ID */
+    merchantId: string;
+    /** Merchant name */
+    merchantName: string;
+    /** Current session status */
+    status: SessionAuthStatus;
+    /** Maximum spending limit in USD */
+    spendingLimitUsd: number;
+    /** Amount already spent in USD */
+    amountUsedUsd: number;
+    /** Remaining spending limit in USD */
+    remainingLimitUsd: number;
+    /** When the session expires */
+    expiresAt: Date;
+    /** When the session was created */
+    createdAt: Date;
+}
+/**
+ * Options for calling a MixrPay merchant's API.
+ */
+interface CallMerchantApiOptions {
+    /**
+     * The merchant API URL to call.
+     */
+    url: string;
+    /**
+     * HTTP method (default: 'POST').
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /**
+     * Request body (will be JSON-serialized if object).
+     */
+    body?: unknown;
+    /**
+     * Additional headers to include.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The merchant's MixrPay public key.
+     * Required to identify which session to use.
+     */
+    merchantPublicKey: string;
+    /**
+     * Expected price in USD for this request.
+     * Used for client-side validation.
+     */
+    priceUsd?: number;
+    /**
+     * Feature slug for tracking/analytics.
+     */
+    feature?: string;
+}
+/**
+ * Options for charging against a session.
+ */
+interface ChargeSessionOptions {
+    /** Feature slug for tracking */
+    feature?: string;
+    /** Idempotency key to prevent double-charges */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a session charge.
+ */
+interface ChargeResult {
+    /** Whether the charge succeeded */
+    success: boolean;
+    /** Charge ID */
+    chargeId: string;
+    /** Amount charged in USD */
+    amountUsd: number;
+    /** Transaction hash (if on-chain) */
+    txHash?: string;
+    /** Remaining session balance in USD */
+    remainingSessionBalanceUsd: number;
+}
+/**
+ * Statistics about session authorizations.
+ *
+ * This provides an overview of all sessions managed by the wallet.
+ */
+interface SessionStats {
+    /** Number of active sessions */
+    activeCount: number;
+    /** Number of expired sessions */
+    expiredCount: number;
+    /** Number of revoked sessions */
+    revokedCount: number;
+    /** Total amount authorized across all active sessions in USD */
+    totalAuthorizedUsd: number;
+    /** Total amount spent across all sessions in USD */
+    totalSpentUsd: number;
+    /** Total remaining across all active sessions in USD */
+    totalRemainingUsd: number;
+    /** List of active sessions (summary) */
+    activeSessions: Array<{
+        id: string;
+        merchantName: string;
+        merchantPublicKey: string;
+        spendingLimitUsd: number;
+        remainingUsd: number;
+        expiresAt: Date;
+    }>;
+}
+
+/**
+ * MixrPay Agent SDK - AgentWallet
+ *
+ * Main class for AI agents to make x402 payments. Provides a simple interface
+ * for making HTTP requests that automatically handle payments using session keys.
+ *
+ * @example Quick Start
+ * ```typescript
+ * import { AgentWallet } from '@mixrpay/agent-sdk';
+ *
+ * // Initialize with your session key
+ * const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
+ *
+ * // Make requests - payments handled automatically!
+ * const response = await wallet.fetch('https://api.example.com/ai/query', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ prompt: 'Hello world' })
+ * });
+ *
+ * console.log(await response.json());
+ * ```
+ */
+
+/** Current SDK version */
+declare const SDK_VERSION = "0.4.1";
+/** Supported networks */
+declare const NETWORKS: {
+    readonly BASE_MAINNET: {
+        readonly chainId: 8453;
+        readonly name: "Base";
+        readonly isTestnet: false;
+    };
+    readonly BASE_SEPOLIA: {
+        readonly chainId: 84532;
+        readonly name: "Base Sepolia";
+        readonly isTestnet: true;
+    };
+};
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+/**
+ * A wallet wrapper for AI agents that handles x402 payments automatically.
+ *
+ * The AgentWallet makes it easy for AI agents to access paid APIs. When a server
+ * returns a 402 Payment Required response, the SDK automatically handles the payment
+ * using a session key and retries the request.
+ *
+ * ## Features
+ * - 🔐 **Secure**: Session keys have built-in spending limits
+ * - 🤖 **Agent-Ready**: Works with any AI framework (Vercel AI SDK, LangChain, etc.)
+ * - ⚡ **Automatic**: No manual payment handling needed
+ * - 📊 **Tracking**: Built-in spending statistics and payment history
+ * - 🔄 **Drop-in**: Uses the same interface as native `fetch()`
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * const wallet = new AgentWallet({
+ *   sessionKey: 'sk_live_...',  // Get this from the wallet owner
+ *   onPayment: (p) => console.log(`Paid $${p.amountUsd}`)
+ * });
+ *
+ * // Just use fetch() - payments are automatic!
+ * const response = await wallet.fetch('https://api.example.com/endpoint');
+ * ```
+ *
+ * ## Session Keys
+ *
+ * Session keys are granted by wallet owners and have spending limits:
+ * - **Per-transaction limit**: Maximum amount per single request
+ * - **Daily limit**: Maximum total per 24 hours
+ * - **Total limit**: Maximum lifetime spend
+ * - **Expiration**: When the key becomes invalid
+ *
+ * Keys are prefixed with `sk_live_` (mainnet) or `sk_test_` (testnet).
+ *
+ * @see {@link AgentWalletConfig} for configuration options
+ * @see {@link PaymentEvent} for payment tracking
+ */
+declare class AgentWallet {
+    private readonly sessionKey;
+    private readonly walletAddress;
+    private readonly maxPaymentUsd?;
+    private readonly onPayment?;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly logger;
+    private payments;
+    private totalSpentUsd;
+    private sessionKeyInfo?;
+    private sessionKeyInfoFetchedAt?;
+    /**
+     * Create a new AgentWallet instance.
+     *
+     * @param config - Configuration options
+     * @throws {InvalidSessionKeyError} If the session key format is invalid
+     *
+     * @example Basic initialization
+     * ```typescript
+     * const wallet = new AgentWallet({
+     *   sessionKey: 'sk_live_abc123...'
+     * });
+     * ```
+     *
+     * @example With all options
+     * ```typescript
+     * const wallet = new AgentWallet({
+     *   sessionKey: 'sk_live_abc123...',
+     *   maxPaymentUsd: 5.0,           // Client-side safety limit
+     *   onPayment: (p) => log(p),     // Track payments
+     *   logLevel: 'info',             // Enable logging
+     *   timeout: 60000,               // 60s timeout
+     * });
+     * ```
+     */
+    constructor(config: AgentWalletConfig);
+    /**
+     * Validate the configuration before initialization.
+     */
+    private validateConfig;
+    /**
+     * Make an HTTP request, automatically handling x402 payment if required.
+     *
+     * This is a drop-in replacement for the native `fetch()` function.
+     * If the server returns 402 Payment Required:
+     * 1. Parse payment requirements from response
+     * 2. Sign transferWithAuthorization using session key
+     * 3. Retry request with X-PAYMENT header
+     *
+     * @param url - Request URL
+     * @param init - Request options (same as native fetch)
+     * @returns Response from the server
+     *
+     * @throws {InsufficientBalanceError} If wallet doesn't have enough USDC
+     * @throws {SessionKeyExpiredError} If session key has expired
+     * @throws {SpendingLimitExceededError} If payment would exceed limits
+     * @throws {PaymentFailedError} If payment transaction failed
+     *
+     * @example GET request
+     * ```typescript
+     * const response = await wallet.fetch('https://api.example.com/data');
+     * const data = await response.json();
+     * ```
+     *
+     * @example POST request with JSON
+     * ```typescript
+     * const response = await wallet.fetch('https://api.example.com/generate', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ prompt: 'Hello world' })
+     * });
+     * ```
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Handle a 402 Payment Required response.
+     */
+    private handlePaymentRequired;
+    /**
+     * Handle payment-specific errors from the response.
+     */
+    private handlePaymentError;
+    /**
+     * Get the wallet address.
+     *
+     * @returns The Ethereum address of the smart wallet
+     */
+    getWalletAddress(): `0x${string}`;
+    /**
+     * Check if using testnet session key.
+     *
+     * @returns true if using Base Sepolia (testnet), false if using Base Mainnet
+     */
+    isTestnet(): boolean;
+    /**
+     * Get the network information.
+     *
+     * @returns Network details including chain ID and name
+     */
+    getNetwork(): typeof NETWORKS.BASE_MAINNET | typeof NETWORKS.BASE_SEPOLIA;
+    /**
+     * Get current USDC balance of the wallet.
+     *
+     * @returns USDC balance in USD
+     *
+     * @example
+     * ```typescript
+     * const balance = await wallet.getBalance();
+     * console.log(`Balance: $${balance.toFixed(2)}`);
+     * ```
+     */
+    getBalance(): Promise<number>;
+    /**
+     * Get information about the session key.
+     *
+     * @param refresh - Force refresh from server (default: use cache if < 60s old)
+     * @returns Session key details including limits and expiration
+     *
+     * @example
+     * ```typescript
+     * const info = await wallet.getSessionKeyInfo();
+     * console.log(`Daily limit: $${info.limits.dailyUsd}`);
+     * console.log(`Expires: ${info.expiresAt}`);
+     * ```
+     */
+    getSessionKeyInfo(refresh?: boolean): Promise<SessionKeyInfo>;
+    /**
+     * Get spending stats for this session key.
+     *
+     * @returns Spending statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await wallet.getSpendingStats();
+     * console.log(`Spent: $${stats.totalSpentUsd.toFixed(2)}`);
+     * console.log(`Remaining daily: $${stats.remainingDailyUsd?.toFixed(2) ?? 'unlimited'}`);
+     * ```
+     */
+    getSpendingStats(): Promise<SpendingStats>;
+    /**
+     * Get list of payments made in this session.
+     *
+     * @returns Array of payment events
+     */
+    getPaymentHistory(): PaymentEvent[];
+    /**
+     * Get the total amount spent in this session.
+     *
+     * @returns Total spent in USD
+     */
+    getTotalSpent(): number;
+    /**
+     * Run diagnostics to verify the wallet is properly configured.
+     *
+     * This is useful for debugging integration issues.
+     *
+     * @returns Diagnostic results with status and any issues found
+     *
+     * @example
+     * ```typescript
+     * const diagnostics = await wallet.runDiagnostics();
+     * if (diagnostics.healthy) {
+     *   console.log('✅ Wallet is ready to use');
+     * } else {
+     *   console.log('❌ Issues found:');
+     *   diagnostics.issues.forEach(issue => console.log(`  - ${issue}`));
+     * }
+     * ```
+     */
+    runDiagnostics(): Promise<DiagnosticsResult>;
+    /**
+     * Enable or disable debug logging.
+     *
+     * @param enable - true to enable debug logging, false to disable
+     *
+     * @example
+     * ```typescript
+     * wallet.setDebug(true);  // Enable detailed logs
+     * await wallet.fetch(...);
+     * wallet.setDebug(false); // Disable logs
+     * ```
+     */
+    setDebug(enable: boolean): void;
+    /**
+     * Set the log level.
+     *
+     * @param level - 'debug' | 'info' | 'warn' | 'error' | 'none'
+     */
+    setLogLevel(level: LogLevel): void;
+    /**
+     * Create the X-Session-Auth header for secure API authentication.
+     * Uses signature-based authentication - private key is NEVER transmitted.
+     *
+     * @returns Headers object with X-Session-Auth
+     */
+    private getSessionAuthHeaders;
+    /**
+     * Get an existing session or create a new one with a MixrPay merchant.
+     *
+     * This is the recommended way to interact with MixrPay-enabled APIs.
+     * If an active session exists, it will be returned. Otherwise, a new
+     * session authorization request will be created and confirmed.
+     *
+     * @param options - Session creation options
+     * @returns Active session authorization
+     *
+     * @throws {MixrPayError} If merchant is not found or session creation fails
+     *
+     * @example
+     * ```typescript
+     * const session = await wallet.getOrCreateSession({
+     *   merchantPublicKey: 'pk_live_abc123...',
+     *   spendingLimitUsd: 25.00,
+     *   durationDays: 7,
+     * });
+     *
+     * console.log(`Session active: $${session.remainingLimitUsd} remaining`);
+     * ```
+     */
+    getOrCreateSession(options: CreateSessionOptions): Promise<SessionAuthorization>;
+    /**
+     * Get session status for a specific merchant.
+     *
+     * @param merchantPublicKey - The merchant's public key
+     * @returns Session authorization or null if not found
+     */
+    getSessionByMerchant(merchantPublicKey: string): Promise<SessionAuthorization | null>;
+    /**
+     * List all session authorizations for this wallet.
+     *
+     * @returns Array of session authorizations
+     *
+     * @example
+     * ```typescript
+     * const sessions = await wallet.listSessions();
+     * for (const session of sessions) {
+     *   console.log(`${session.merchantName}: $${session.remainingLimitUsd} remaining`);
+     * }
+     * ```
+     */
+    listSessions(): Promise<SessionAuthorization[]>;
+    /**
+     * Revoke a session authorization.
+     *
+     * After revocation, no further charges can be made against this session.
+     *
+     * @param sessionId - The session ID to revoke
+     * @returns true if revoked successfully
+     *
+     * @example
+     * ```typescript
+     * const revoked = await wallet.revokeSession('sess_abc123');
+     * if (revoked) {
+     *   console.log('Session revoked successfully');
+     * }
+     * ```
+     */
+    revokeSession(sessionId: string): Promise<boolean>;
+    /**
+     * Get statistics about all session authorizations.
+     *
+     * This provides an overview of active, expired, and revoked sessions,
+     * along with aggregate spending information.
+     *
+     * @returns Session statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await wallet.getSessionStats();
+     * console.log(`Active sessions: ${stats.activeCount}`);
+     * console.log(`Total authorized: $${stats.totalAuthorizedUsd.toFixed(2)}`);
+     * console.log(`Total remaining: $${stats.totalRemainingUsd.toFixed(2)}`);
+     *
+     * for (const session of stats.activeSessions) {
+     *   console.log(`${session.merchantName}: $${session.remainingUsd} remaining`);
+     * }
+     * ```
+     */
+    getSessionStats(): Promise<SessionStats>;
+    /**
+     * Charge against an active session authorization.
+     *
+     * This is useful when you need to manually charge a session outside of
+     * the `callMerchantApi()` flow.
+     *
+     * @param sessionId - The session ID to charge
+     * @param amountUsd - Amount to charge in USD
+     * @param options - Additional charge options
+     * @returns Charge result
+     *
+     * @example
+     * ```typescript
+     * const result = await wallet.chargeSession('sess_abc123', 0.05, {
+     *   feature: 'ai-generation',
+     *   idempotencyKey: 'unique-key-123',
+     * });
+     *
+     * console.log(`Charged $${result.amountUsd}, remaining: $${result.remainingSessionBalanceUsd}`);
+     * ```
+     */
+    chargeSession(sessionId: string, amountUsd: number, options?: ChargeSessionOptions): Promise<ChargeResult>;
+    /**
+     * Call a MixrPay merchant's API with automatic session management.
+     *
+     * This is the recommended way to interact with MixrPay-enabled APIs.
+     * It automatically:
+     * 1. Gets or creates a session authorization
+     * 2. Adds the `X-Mixr-Session` header to the request
+     * 3. Handles payment errors and session expiration
+     *
+     * @param options - API call options
+     * @returns Response from the merchant API
+     *
+     * @example
+     * ```typescript
+     * const response = await wallet.callMerchantApi({
+     *   url: 'https://api.merchant.com/generate',
+     *   merchantPublicKey: 'pk_live_abc123...',
+     *   method: 'POST',
+     *   body: { prompt: 'Hello world' },
+     *   priceUsd: 0.05,
+     * });
+     *
+     * const data = await response.json();
+     * ```
+     */
+    callMerchantApi(options: CallMerchantApiOptions): Promise<Response>;
+    /**
+     * 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>;
+    /**
+     * Run an AI agent with LLM and tool execution.
+     *
+     * This method orchestrates a full agentic loop:
+     * - Multi-turn reasoning with LLM
+     * - Automatic tool execution
+     * - Bundled billing (single charge at end)
+     * - Optional streaming via SSE
+     *
+     * @param options - Agent run options
+     * @returns Agent run result with response and cost breakdown
+     *
+     * @example Basic usage
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Find AI startups in SF' }],
+     * });
+     *
+     * console.log(result.response);
+     * console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+     * ```
+     *
+     * @example With custom config
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Research quantum computing' }],
+     *   config: {
+     *     model: 'gpt-4o',
+     *     maxIterations: 15,
+     *     tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+     *     systemPrompt: 'You are a research assistant.',
+     *   },
+     * });
+     * ```
+     *
+     * @example With streaming
+     * ```typescript
+     * await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Analyze this company' }],
+     *   stream: true,
+     *   onEvent: (event) => {
+     *     if (event.type === 'llm_chunk') {
+     *       process.stdout.write(event.delta);
+     *     } else if (event.type === 'tool_call') {
+     *       console.log(`Calling tool: ${event.tool}`);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    runAgent(options: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Internal: Handle streaming agent run via SSE
+     */
+    private runAgentStreaming;
+    /**
+     * Internal: Parse SSE event into typed event object
+     */
+    private parseSSEEvent;
+    /**
+     * Get the status of an agent run by ID.
+     *
+     * @param runId - The agent run ID
+     * @param sessionId - The session ID (for authentication)
+     * @returns Agent run status and results
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+     * console.log(`Status: ${status.status}`);
+     * if (status.status === 'completed') {
+     *   console.log(status.response);
+     * }
+     * ```
+     */
+    getAgentRunStatus(runId: string, sessionId: string): Promise<AgentRunStatusResult>;
+    /**
+     * 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;
+}
+/**
+ * Message in an agent conversation
+ */
+interface AgentMessage {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    /** Message content */
+    content: string;
+}
+/**
+ * Configuration for an agent run
+ */
+interface AgentRunConfig {
+    /** LLM model to use (default: gpt-4o-mini) */
+    model?: string;
+    /** Maximum iterations before stopping (default: 10, max: 25) */
+    maxIterations?: number;
+    /** Specific tools to enable (e.g., ['platform/exa-search', 'platform/firecrawl-scrape']) */
+    tools?: string[];
+    /** Custom system prompt for the agent */
+    systemPrompt?: string;
+}
+/**
+ * Options for running an agent
+ */
+interface AgentRunOptions {
+    /** Session ID for authentication and billing */
+    sessionId: string;
+    /** Conversation messages */
+    messages: AgentMessage[];
+    /** Agent configuration */
+    config?: AgentRunConfig;
+    /** Enable SSE streaming (default: false) */
+    stream?: boolean;
+    /** Unique key for idempotency */
+    idempotencyKey?: string;
+    /** Callback for streaming events */
+    onEvent?: (event: AgentRunEvent) => void;
+}
+/**
+ * Result from an agent run
+ */
+interface AgentRunResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'completed' | 'failed';
+    /** Final response from the agent */
+    response: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        /** LLM cost in USD */
+        llmUsd: number;
+        /** Tool execution cost in USD */
+        toolsUsd: number;
+        /** Total cost in USD */
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        /** Prompt tokens used */
+        prompt: number;
+        /** Completion tokens used */
+        completion: number;
+    };
+    /** Remaining session balance in USD */
+    sessionRemainingUsd: number;
+    /** On-chain transaction hash for payment */
+    txHash?: string;
+}
+/**
+ * Streaming events from an agent run
+ */
+type AgentRunEvent = {
+    type: 'run_start';
+    runId: string;
+} | {
+    type: 'iteration_start';
+    iteration: number;
+} | {
+    type: 'llm_chunk';
+    delta: string;
+} | {
+    type: 'tool_call';
+    tool: string;
+    arguments: unknown;
+} | {
+    type: 'tool_result';
+    tool: string;
+    success: boolean;
+    costUsd: number;
+    error?: string;
+} | {
+    type: 'iteration_complete';
+    iteration: number;
+    tokens?: {
+        prompt?: number;
+        completion?: number;
+    };
+    costUsd?: number;
+} | {
+    type: 'complete';
+    runId: string;
+    response: string;
+    totalCostUsd: number;
+    txHash?: string;
+    iterations: number;
+    toolsUsed: string[];
+} | {
+    type: 'error';
+    error: string;
+    partialCostUsd?: number;
+};
+/**
+ * Result from getting agent run status
+ */
+interface AgentRunStatusResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'running' | 'completed' | 'failed' | 'interrupted';
+    /** Final response (if completed) */
+    response?: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        llmUsd: number;
+        toolsUsd: number;
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        prompt: number;
+        completion: number;
+    };
+    /** On-chain transaction hash */
+    txHash?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** When the run started */
+    startedAt: Date;
+    /** When the run completed */
+    completedAt?: Date;
+}
+
+/**
+ * MixrPay Agent SDK - Custom Errors
+ *
+ * These errors provide clear, actionable messages for common x402 payment failures.
+ * Each error includes:
+ * - A clear description of what went wrong
+ * - Relevant data for programmatic handling
+ * - Suggestions for how to fix the issue
+ *
+ * @example Handling errors
+ * ```typescript
+ * try {
+ *   await wallet.fetch('https://api.example.com/query');
+ * } catch (error) {
+ *   if (error instanceof InsufficientBalanceError) {
+ *     console.log(`Need $${error.required}, have $${error.available}`);
+ *     console.log('Top up at:', error.topUpUrl);
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base error class for all MixrPay SDK errors.
+ *
+ * All SDK errors extend this class, making it easy to catch all MixrPay-related
+ * errors in a single catch block.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await wallet.fetch(...);
+ * } catch (error) {
+ *   if (error instanceof MixrPayError) {
+ *     // Handle any MixrPay error
+ *     console.log(error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class MixrPayError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Thrown when the wallet doesn't have enough USDC for the payment.
+ *
+ * This error indicates the smart wallet needs to be topped up with more USDC.
+ *
+ * ## Resolution
+ * 1. Direct the user to top up their wallet
+ * 2. Use a smaller transaction (if possible)
+ * 3. Wait for pending deposits to confirm
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof InsufficientBalanceError) {
+ *     console.log(`Need $${error.required.toFixed(2)}, have $${error.available.toFixed(2)}`);
+ *     console.log(`Top up at: ${error.topUpUrl}`);
+ *   }
+ * }
+ * ```
+ */
+declare class InsufficientBalanceError extends MixrPayError {
+    /** Amount required for the payment in USD */
+    readonly required: number;
+    /** Current available balance in USD */
+    readonly available: number;
+    /** URL where the user can top up their wallet */
+    readonly topUpUrl: string;
+    constructor(required: number, available: number);
+}
+/**
+ * Thrown when the session key has expired.
+ *
+ * Session keys have an expiration date set by the wallet owner. Once expired,
+ * the key can no longer authorize payments.
+ *
+ * ## Resolution
+ * 1. Request a new session key from the wallet owner
+ * 2. Create a new session key (if you have wallet access)
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof SessionKeyExpiredError) {
+ *     console.log(`Session key expired at ${error.expiredAt}`);
+ *     // Request new key from wallet owner
+ *   }
+ * }
+ * ```
+ */
+declare class SessionKeyExpiredError extends MixrPayError {
+    /** When the session key expired */
+    readonly expiredAt: string;
+    constructor(expiredAt: string);
+}
+/**
+ * Thrown when a payment would exceed session key spending limits.
+ *
+ * Session keys can have three types of limits:
+ * - **per_tx**: Maximum per single transaction
+ * - **daily**: Maximum total per 24-hour period
+ * - **total**: Maximum lifetime spend
+ * - **client_max**: Client-side limit set in AgentWalletConfig
+ *
+ * ## Resolution
+ * - **per_tx**: Use a smaller transaction or request higher limit
+ * - **daily**: Wait until tomorrow or request higher limit
+ * - **total**: Request a new session key with higher limit
+ * - **client_max**: Increase maxPaymentUsd in config or remove it
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof SpendingLimitExceededError) {
+ *     if (error.limitType === 'daily') {
+ *       console.log('Daily limit reached. Try again tomorrow.');
+ *     } else if (error.limitType === 'per_tx') {
+ *       console.log(`Max per transaction is $${error.limit}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class SpendingLimitExceededError extends MixrPayError {
+    /** Type of limit that was exceeded */
+    readonly limitType: 'per_tx' | 'daily' | 'total' | 'client_max' | string;
+    /** The limit amount in USD */
+    readonly limit: number;
+    /** The amount that was attempted in USD */
+    readonly attempted: number;
+    constructor(limitType: string, limit: number, attempted: number);
+}
+/**
+ * Thrown when a payment transaction fails.
+ *
+ * This is a general error for payment failures that don't fit other categories.
+ * Check the `reason` property for more details.
+ *
+ * ## Common Causes
+ * - Network issues
+ * - Invalid payment parameters
+ * - Server-side errors
+ * - Blockchain congestion
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof PaymentFailedError) {
+ *     console.log(`Payment failed: ${error.reason}`);
+ *     if (error.txHash) {
+ *       console.log(`Check transaction: https://basescan.org/tx/${error.txHash}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class PaymentFailedError extends MixrPayError {
+    /** Detailed reason for the failure */
+    readonly reason: string;
+    /** Transaction hash if the tx was submitted (for debugging) */
+    readonly txHash?: string;
+    constructor(reason: string, txHash?: string);
+}
+/**
+ * Thrown when the session key format is invalid.
+ *
+ * Session keys must:
+ * - Start with `sk_live_` (mainnet) or `sk_test_` (testnet)
+ * - Be followed by exactly 64 hexadecimal characters
+ * - Total length: 72 characters
+ *
+ * ## Common Issues
+ * - Incomplete copy/paste
+ * - Extra whitespace
+ * - Using API key instead of session key
+ * - Using public key instead of private key
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof InvalidSessionKeyError) {
+ *     console.log(`Invalid key: ${error.reason}`);
+ *     console.log('Get a valid session key from your MixrPay server /wallet/sessions');
+ *   }
+ * }
+ * ```
+ */
+declare class InvalidSessionKeyError extends MixrPayError {
+    /** Detailed reason why the key is invalid */
+    readonly reason: string;
+    constructor(reason?: string);
+}
+/**
+ * Thrown when a session authorization has expired.
+ *
+ * Session authorizations have an expiration date set when created. Once expired,
+ * the session can no longer be used for payments.
+ *
+ * ## Resolution
+ * Create a new session with the merchant using `wallet.getOrCreateSession()`.
+ * The SDK will automatically create a new session on the next `callMerchantApi()` call.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof SessionExpiredError) {
+ *     console.log(`Session ${error.sessionId} expired at ${error.expiredAt}`);
+ *     // SDK will auto-create new session on next callMerchantApi()
+ *   }
+ * }
+ * ```
+ */
+declare class SessionExpiredError extends MixrPayError {
+    /** ID of the expired session */
+    readonly sessionId: string;
+    /** When the session expired (ISO string or Date) */
+    readonly expiredAt?: string;
+    constructor(sessionId: string, expiredAt?: string);
+}
+/**
+ * Thrown when a payment would exceed the session's spending limit.
+ *
+ * Each session authorization has a spending limit set by the user. Once the limit
+ * is reached, no more payments can be made until a new session is created.
+ *
+ * ## Resolution
+ * - Create a new session with a higher limit
+ * - Wait for the current session to be renewed (if auto-renewal is enabled)
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof SessionLimitExceededError) {
+ *     console.log(`Session limit: $${error.limit}, requested: $${error.requested}`);
+ *     console.log(`Remaining: $${error.remaining}`);
+ *   }
+ * }
+ * ```
+ */
+declare class SessionLimitExceededError extends MixrPayError {
+    /** ID of the session */
+    readonly sessionId?: string;
+    /** The session's spending limit in USD */
+    readonly limit: number;
+    /** The amount requested in USD */
+    readonly requested: number;
+    /** Remaining balance in the session (limit - used) */
+    readonly remaining: number;
+    constructor(limit: number, requested: number, remaining: number, sessionId?: string);
+}
+/**
+ * Thrown when a session ID is invalid or not found.
+ *
+ * This can happen if:
+ * - The session ID was incorrectly formatted
+ * - The session was deleted
+ * - The session belongs to a different user/merchant
+ *
+ * ## Resolution
+ * Create a new session using `wallet.getOrCreateSession()`.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof SessionNotFoundError) {
+ *     console.log(`Session ${error.sessionId} not found`);
+ *     const newSession = await wallet.getOrCreateSession({ ... });
+ *   }
+ * }
+ * ```
+ */
+declare class SessionNotFoundError extends MixrPayError {
+    /** The session ID that was not found */
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/**
+ * Thrown when attempting to use a session that has been revoked.
+ *
+ * Sessions can be revoked by:
+ * - The user (wallet owner)
+ * - The merchant
+ * - Automatically by the system (e.g., suspicious activity)
+ *
+ * ## Resolution
+ * Create a new session using `wallet.getOrCreateSession()`.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof SessionRevokedError) {
+ *     console.log(`Session ${error.sessionId} was revoked`);
+ *     if (error.reason) console.log(`Reason: ${error.reason}`);
+ *   }
+ * }
+ * ```
+ */
+declare class SessionRevokedError extends MixrPayError {
+    /** The session ID that was revoked */
+    readonly sessionId: string;
+    /** Optional reason for revocation */
+    readonly reason?: string;
+    constructor(sessionId: string, reason?: string);
+}
+/**
+ * Check if an error is a MixrPay SDK error.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a MixrPayError or subclass
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await wallet.fetch(...);
+ * } catch (error) {
+ *   if (isMixrPayError(error)) {
+ *     console.log('MixrPay error:', error.code, error.message);
+ *   } else {
+ *     console.log('Other error:', error);
+ *   }
+ * }
+ * ```
+ */
+declare function isMixrPayError(error: unknown): error is MixrPayError;
+
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };