@mixrpay/agent-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,961 @@
+import { Hex } from 'viem';
+
+/**
+ * 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;
+}
+/**
+ * Payment requirements parsed from a 402 response.
+ *
+ * This represents what the server is asking for in exchange for the resource.
+ */
+interface PaymentRequirements {
+    /** Address to send payment to */
+    recipient: string;
+    /** Amount in USDC minor units (6 decimals). 1000000 = $1.00 */
+    amount: bigint;
+    /** Currency code (currently only "USDC" is supported) */
+    currency: string;
+    /** Chain ID (8453 for Base mainnet, 84532 for Base Sepolia) */
+    chainId: number;
+    /** URL where the payment should be submitted */
+    facilitatorUrl: string;
+    /** Unique nonce for this payment request */
+    nonce: string;
+    /** Unix timestamp when this payment request expires */
+    expiresAt: number;
+    /** Human-readable description of the payment */
+    description?: 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;
+}
+/**
+ * The X-PAYMENT header payload structure.
+ *
+ * This is what gets base64-encoded and sent in the X-PAYMENT header.
+ */
+interface X402PaymentPayload {
+    /** Protocol version (currently 1) */
+    x402Version: number;
+    /** Payment scheme ('exact' for USDC transfers) */
+    scheme: 'exact';
+    /** Network identifier */
+    network: 'base' | 'base-sepolia';
+    /** Payment payload containing signature and authorization */
+    payload: {
+        /** EIP-712 signature of the transferWithAuthorization */
+        signature: string;
+        /** TransferWithAuthorization parameters */
+        authorization: {
+            /** Sender address (smart wallet) */
+            from: string;
+            /** Recipient address */
+            to: string;
+            /** Amount in USDC minor units as string */
+            value: string;
+            /** Unix timestamp after which the authorization is valid */
+            validAfter: string;
+            /** Unix timestamp before which the authorization is valid */
+            validBefore: string;
+            /** Unique nonce (32 bytes hex) */
+            nonce: string;
+        };
+    };
+}
+/**
+ * EIP-712 domain for USDC transferWithAuthorization.
+ */
+interface EIP712Domain {
+    /** Contract name ('USD Coin' for USDC) */
+    name: string;
+    /** Contract version ('2' for USDC) */
+    version: string;
+    /** Chain ID */
+    chainId: number;
+    /** USDC contract address */
+    verifyingContract: `0x${string}`;
+}
+/**
+ * EIP-3009 TransferWithAuthorization message structure.
+ */
+interface TransferWithAuthorizationMessage {
+    /** Sender address */
+    from: `0x${string}`;
+    /** Recipient address */
+    to: `0x${string}`;
+    /** Amount in minor units */
+    value: bigint;
+    /** Unix timestamp after which the authorization is valid */
+    validAfter: bigint;
+    /** Unix timestamp before which the authorization is valid */
+    validBefore: bigint;
+    /** Unique nonce (32 bytes) */
+    nonce: `0x${string}`;
+}
+/**
+ * Response from the wallet balance endpoint.
+ */
+interface WalletBalanceResponse {
+    /** Balance in USD */
+    balanceUsd: number;
+    /** Balance in USDC minor units as string */
+    balanceMinor: string;
+    /** Currency code */
+    currency: string;
+    /** Wallet address */
+    walletAddress: string;
+}
+/**
+ * Response from the session key stats endpoint.
+ */
+interface SessionKeyStatsResponse {
+    /** Total spent in USD */
+    totalSpentUsd: number;
+    /** Number of transactions */
+    txCount: number;
+    /** Remaining daily limit in USD (null if no limit) */
+    remainingDailyUsd: number | null;
+    /** Remaining total limit in USD (null if no limit) */
+    remainingTotalUsd: number | null;
+    /** Expiration timestamp ISO string (null if never) */
+    expiresAt: string | null;
+}
+
+/**
+ * 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.1.0";
+/** Default API base URL - override with baseUrl option or MIXRPAY_BASE_URL env var */
+declare const DEFAULT_BASE_URL: string;
+/** Default x402 facilitator URL */
+declare const DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
+/** Default request timeout in milliseconds */
+declare const DEFAULT_TIMEOUT = 30000;
+/** 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;
+}
+
+/**
+ * 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 there's an error in x402 protocol handling.
+ *
+ * This indicates a problem with the payment protocol, usually due to:
+ * - Malformed 402 response from server
+ * - Missing required payment fields
+ * - Invalid payment parameters
+ * - Protocol version mismatch
+ *
+ * ## Resolution
+ * This is usually a server-side issue. Contact the API provider if the error persists.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof X402ProtocolError) {
+ *     console.log(`Protocol error: ${error.reason}`);
+ *     // Contact API provider or check server configuration
+ *   }
+ * }
+ * ```
+ */
+declare class X402ProtocolError extends MixrPayError {
+    /** Detailed reason for the protocol error */
+    readonly reason: string;
+    constructor(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;
+/**
+ * Get a user-friendly error message from any error.
+ *
+ * @param error - The error to get a message from
+ * @returns A user-friendly error message
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   const message = getErrorMessage(error);
+ *   showToast(message);
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
+
+/**
+ * MixrPay Agent SDK - Session Key Handling
+ *
+ * Session keys are derived private keys with on-chain spending limits that enable
+ * AI agents to sign USDC transferWithAuthorization transactions autonomously.
+ */
+
+/**
+ * Represents a session key for signing x402 payments.
+ *
+ * The session key format is: sk_live_{64_hex_chars} or sk_test_{64_hex_chars}
+ */
+declare class SessionKey {
+    private readonly privateKey;
+    private readonly account;
+    readonly address: `0x${string}`;
+    readonly isTest: boolean;
+    private constructor();
+    /**
+     * Parse a session key string into a SessionKey object.
+     *
+     * @param sessionKey - Session key in format sk_live_... or sk_test_...
+     * @returns SessionKey object
+     * @throws InvalidSessionKeyError if the format is invalid
+     */
+    static fromString(sessionKey: string): SessionKey;
+    /**
+     * Sign EIP-712 typed data for TransferWithAuthorization.
+     *
+     * @param domain - EIP-712 domain
+     * @param message - Transfer authorization message
+     * @returns Hex-encoded signature
+     */
+    signTransferAuthorization(domain: EIP712Domain, message: TransferWithAuthorizationMessage): Promise<Hex>;
+    /**
+     * Get the chain ID based on whether this is a test key.
+     */
+    getDefaultChainId(): number;
+}
+/**
+ * Build EIP-712 typed data for USDC transferWithAuthorization (EIP-3009).
+ *
+ * @param params - Parameters for the transfer authorization
+ * @returns Domain and message for EIP-712 signing
+ */
+declare function buildTransferAuthorizationData(params: {
+    fromAddress: `0x${string}`;
+    toAddress: `0x${string}`;
+    value: bigint;
+    validAfter: bigint;
+    validBefore: bigint;
+    nonce: Hex;
+    chainId: number;
+}): {
+    domain: EIP712Domain;
+    message: TransferWithAuthorizationMessage;
+};
+/**
+ * Generate a random 32-byte nonce as hex.
+ */
+declare function generateNonce(): Hex;
+
+/**
+ * MixrPay Agent SDK - x402 Protocol Handling
+ *
+ * The x402 protocol enables HTTP-native payments. When a server returns a 402 Payment
+ * Required response, the client can automatically fulfill the payment and retry.
+ */
+
+/**
+ * Parse payment requirements from a 402 response.
+ *
+ * The 402 response can include payment requirements in:
+ * 1. X-Payment-Required header (JSON)
+ * 2. WWW-Authenticate header (per x402 spec)
+ * 3. Response body (JSON)
+ *
+ * @param response - The HTTP response with status 402
+ * @returns Parsed payment requirements
+ * @throws X402ProtocolError if requirements cannot be parsed
+ */
+declare function parse402Response(response: Response): Promise<PaymentRequirements>;
+/**
+ * Build the X-PAYMENT header value for a payment request.
+ *
+ * This creates an EIP-3009 transferWithAuthorization, signs it with the session key,
+ * and encodes it for the X-PAYMENT header.
+ *
+ * @param requirements - Payment requirements from the 402 response
+ * @param sessionKey - Session key to sign the payment
+ * @param walletAddress - The smart wallet address that holds USDC
+ * @returns Base64-encoded JSON string for the X-PAYMENT header
+ */
+declare function buildXPaymentHeader(requirements: PaymentRequirements, sessionKey: SessionKey, walletAddress: `0x${string}`): Promise<string>;
+/**
+ * Check if payment requirements have expired.
+ */
+declare function isPaymentExpired(requirements: PaymentRequirements): boolean;
+/**
+ * Get payment amount in USD (USDC has 6 decimals).
+ */
+declare function getAmountUsd(requirements: PaymentRequirements): number;
+/**
+ * Validate that a payment amount is within acceptable limits.
+ *
+ * @param amountUsd - Payment amount in USD
+ * @param maxPaymentUsd - Optional client-side maximum per payment
+ * @throws X402ProtocolError if the amount exceeds limits
+ */
+declare function validatePaymentAmount(amountUsd: number, maxPaymentUsd?: number): void;
+
+export { AgentWallet, type AgentWalletConfig, DEFAULT_BASE_URL, DEFAULT_FACILITATOR_URL, DEFAULT_TIMEOUT, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, NETWORKS, type PaymentEvent, PaymentFailedError, type PaymentRequirements, SDK_VERSION, SessionKey, SessionKeyExpiredError, type SessionKeyInfo, type SessionKeyStatsResponse, SpendingLimitExceededError, type SpendingStats, type WalletBalanceResponse, type X402PaymentPayload, X402ProtocolError, buildTransferAuthorizationData, buildXPaymentHeader, generateNonce, getAmountUsd, getErrorMessage, isMixrPayError, isPaymentExpired, parse402Response, validatePaymentAmount };