@mixrpay/agent-sdk 0.8.9 → 0.9.5

package/dist/index.d.ts

@@ -1,356 +1,131 @@
 /**
- * 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,
- * };
- * ```
+ * @packageDocumentation
  */
 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 at https://mixrpay.com/manage/invites
-     * - Programmatically via the MixrPay API
-     *
-     * @example 'sk_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
-     */
+    /** Session key (sk_live_ or sk_test_ prefix). */
     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.
-     */
+    /** Override 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
-     */
+    /** Client-side max payment per request in USD. */
     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);
-     * }
-     * ```
-     */
+    /** Payment event callback. */
     onPayment?: (payment: PaymentEvent) => void;
-    /**
-     * x402 facilitator endpoint.
-     *
-     * The facilitator processes the payment and forwards the request.
-     * Default: 'https://x402.org/facilitator'
-     */
+    /** Override facilitator URL. */
     facilitatorUrl?: string;
-    /**
-     * MixrPay API base URL.
-     *
-     * Default: 'http://localhost:3000' (or MIXRPAY_BASE_URL env var)
-     */
+    /** Override API base URL. */
     baseUrl?: string;
-    /**
-     * Request timeout in milliseconds.
-     *
-     * Default: 30000 (30 seconds)
-     */
+    /** Request timeout in ms (default: 30000). */
     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
-     */
+    /** Log level (default: 'none'). */
     logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    /** Agent API key (agt_live_ prefix). Set automatically by connect(). */
+    apiKey?: string;
 }
-/**
- * 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;
-    /** Auto-generated unique ID for this request */
     requestId: string;
-    /** User-provided correlation ID (from X-Correlation-Id header if provided) */
     correlationId?: string;
 }
-/**
- * Information about a session key.
- */
 interface SessionKeyInfo {
-    /** The session key's derived address (used for signing requests) */
     address: string;
-    /**
-     * The wallet address this session key is authorized to spend from.
-     * This is the human's funded wallet, NOT your agent's external wallet.
-     * All charges are deducted from this wallet.
-     */
     walletAddress: string | null;
-    /** 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;
-    /** Allowed merchants/tools (empty = allow all) */
     allowedMerchants?: 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;
-    /** Session key limit info (if available) */
     sessionLimits?: {
-        /** Remaining daily limit in USD (null if no limit) */
         remainingDailyUsd: number | null;
-        /** Remaining total limit in USD (null if no limit) */
         remainingTotalUsd: number | null;
-        /** When the session key expires (null if never) */
         expiresAt: Date | null;
-        /** Hours until expiration (null if never) */
         expiresInHours: number | null;
     };
-    /** Network latency to API in milliseconds */
     latencyMs?: number;
-    /** Actionable recommendations based on issues found */
     recommendations: string[];
 }
-/**
- * Options for creating a session authorization with a MixrPay merchant.
- */
+/** @internal */
 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.
- */
+/** @internal */
 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.
- */
+/** @internal */
 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;
@@ -360,32 +135,87 @@ interface SessionStats {
         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());
- * ```
- */
+interface TokenBalance {
+    balance: string;
+    raw: string;
+    decimals?: number;
+}
+interface DelegationBudget {
+    budget_total_usd: string;
+    budget_spent_usd: string;
+    budget_remaining_usd: string;
+    per_tx_limit_usd: string;
+    daily_limit_usd: string;
+}
+interface BalancesResponse {
+    wallet_address: string;
+    chain: string;
+    chain_id: number;
+    balances: Record<string, TokenBalance>;
+    delegation?: DelegationBudget;
+    request_id: string;
+}
+interface TransferResponse {
+    success: boolean;
+    tx_hash: string;
+    amount_usd: string;
+    remaining_budget_usd: string | null;
+    charge_id: string;
+}
+interface SwapResponse {
+    success: boolean;
+    tx_hash: string;
+    sell_amount: string;
+    sell_token: string;
+    buy_amount: string;
+    min_buy_amount: string;
+    buy_token: string;
+    price: string;
+    gas_estimate: string;
+    remaining_budget_usd: string | null;
+    charge_id: string;
+}
+interface BridgeResponse {
+    success: boolean;
+    tx_hash: string;
+    order_id: string;
+    amount: string;
+    source_chain: string;
+    dest_chain: string;
+    estimated_receive: string;
+    remaining_budget_usd: string | null;
+    charge_id: string;
+}
+interface BridgeStatusResponse {
+    order_id: string;
+    status: 'pending' | 'fulfilled' | 'failed' | 'cancelled';
+    source_chain: string;
+    source_tx_hash: string;
+    dest_chain: string;
+    dest_tx_hash?: string;
+    estimated_time_remaining?: string;
+}
+interface FetchPaymentInfo {
+    paid: boolean;
+    amount_usd: string;
+    tx_hash?: string;
+    remaining_budget_usd: string | null;
+}
+interface FetchPaidResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+    payment?: FetchPaymentInfo;
+}
+interface FetchPaidOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: unknown;
+    maxPaymentUsd?: number;
+}
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.8.7";
+declare const SDK_VERSION = "0.9.4";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -553,11 +383,122 @@ interface AgentClaimInviteResult {
     /** Name of the person who created the invite */
     inviterName: string;
 }
+/**
+ * Options for activating an agent
+ */
+interface AgentActivateOptions {
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Agent runtime returned from activation
+ * Contains the wallet instance and all capabilities/tools available to the agent
+ */
+interface AgentRuntime {
+    /** Pre-configured AgentWallet instance */
+    wallet: AgentWallet;
+    /** Budget limits and current spending */
+    budget: {
+        maxTotalUsd: number | null;
+        maxDailyUsd: number | null;
+        maxPerTxUsd: number | null;
+        spentUsd: number;
+        remainingUsd: number | null;
+    };
+    /** Feature capabilities */
+    capabilities: {
+        executeTransactions: boolean;
+        gasSponsored: boolean;
+        batchedTx: boolean;
+    };
+    /** Installed business skills */
+    skills: Array<{
+        id: string;
+        name: string;
+        version: number;
+    }>;
+    /** Available tools */
+    tools: Array<{
+        name: string;
+        type: string;
+    }>;
+    /** Configured gateway providers and their tools */
+    gatewayProviders: Array<{
+        name: string;
+        tools: string[];
+    }>;
+}
+/**
+ * Options for AgentWallet.connect() auth cascade
+ */
+interface ConnectOptions {
+    /** Explicit session key (highest priority) */
+    sessionKey?: string;
+    /** Access code from MixrPay dashboard (mixr-xxx) - one-time use, auto-cached */
+    accessCode?: string;
+    /** Master key for multi-agent deployments */
+    masterKey?: string;
+    /** Agent name when using master key */
+    agentName?: string;
+    /** Enable interactive device flow login if no credentials found */
+    interactive?: boolean;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+    /** Log level for debugging */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    /** Client-side maximum payment amount in USD */
+    maxPaymentUsd?: number;
+    /** Callback for payment events */
+    onPayment?: (payment: PaymentEvent) => void;
+}
+/**
+ * Options for generating a SIWE (Sign-In with Ethereum) message
+ * Per EIP-4361: https://eips.ethereum.org/EIPS/eip-4361
+ */
+interface SiweOptions {
+    /** The domain making the request (e.g., "example.com") */
+    domain: string;
+    /** The URI of the resource being accessed */
+    uri: string;
+    /** Human-readable statement for the user */
+    statement?: string;
+    /** Server-provided nonce for replay protection (default: random UUID) */
+    nonce?: string;
+    /** When the message was issued (default: now) */
+    issuedAt?: Date;
+    /** When the signed message expires */
+    expirationTime?: Date;
+    /** When the signed message becomes valid */
+    notBefore?: Date;
+    /** System-specific request identifier */
+    requestId?: string;
+    /** List of resources the user is authorizing */
+    resources?: string[];
+}
+/**
+ * Result from generating a SIWE message
+ */
+interface SiweResult {
+    /** The formatted SIWE message */
+    message: string;
+    /** The signature (hex string with 0x prefix) */
+    signature: string;
+    /** The signing address */
+    address: string;
+    /** The chain ID */
+    chainId: number;
+    /** The nonce used */
+    nonce: string;
+    /** When the message was issued */
+    issuedAt: Date;
+    /** When the message expires (if set) */
+    expirationTime?: Date;
+}
 /**
  * Options for spawning a child invite
  */
 interface SpawnChildOptions {
-    /** Budget in USD for the child (max 20% of available) */
+    /** Budget in USD for the child (subject to platform limits) */
     budgetUsd: number;
     /** Name for the child invite */
     name: string;
@@ -574,13 +515,13 @@ interface SpawnChildResult {
     inviteCode: string;
     /** Database ID of the invite */
     inviteId: string;
-    /** Actual budget (may be less than requested due to 20% cap) */
+    /** Actual budget (may be less than requested due to platform limits) */
     budgetUsd: number;
     /** When the invite expires */
     expiresAt: Date;
     /** Depth in hierarchy (1 = child, 2 = grandchild, etc.) */
     depth: number;
-    /** How much this child can spawn (20% of their budget) */
+    /** How much this child can spawn */
     maxSpawnBudget: number;
     /** Allowed merchants for this child */
     allowedMerchants: string[];
@@ -597,9 +538,9 @@ interface AvailableBudget {
     allocatedToChildren: number;
     /** Available for spending or spawning */
     available: number;
-    /** Maximum budget for next spawn (20% of available) */
+    /** Maximum budget for next spawn */
     maxSpawnBudget: number;
-    /** Whether spawning is allowed (depth < 10, can_spawn, available > 0) */
+    /** Whether spawning is allowed */
     canSpawn: boolean;
 }
 /**
@@ -673,6 +614,16 @@ type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
  * @see {@link AgentWalletConfig} for configuration options
  * @see {@link PaymentEvent} for payment tracking
  */
+/**
+ * Configuration returned by {@link AgentWallet.mcp} for use with the
+ * Claude Agent SDK's `mcpServers` option or any MCP client that accepts
+ * stdio server configs.
+ */
+interface McpServerConfig {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+}
 declare class AgentWallet {
     private readonly sessionKey;
     private readonly walletAddress;
@@ -687,6 +638,10 @@ declare class AgentWallet {
     private sessionKeyInfoFetchedAt?;
     private allowlist?;
     private allowlistFetchedAt?;
+    private selfCustodyAddress?;
+    private selfCustodyKey?;
+    private agentInstanceId?;
+    private apiKey?;
     /**
      * Create a new AgentWallet instance.
      *
@@ -748,7 +703,7 @@ declare class AgentWallet {
     /**
      * Register a new agent with MixrPay.
      *
-     * This creates a Privy-managed embedded wallet for the agent's payments.
+     * This creates a platform-managed embedded wallet for the agent's payments.
      * The agent proves ownership of their external wallet by signing a challenge.
      *
      * @param options - Registration options including the private key
@@ -786,7 +741,7 @@ declare class AgentWallet {
         healthy: boolean;
         database: string;
         agentRegistrationAvailable: boolean;
-        privyConfigured: boolean;
+        walletServiceConfigured: boolean;
         error?: string;
     }>;
     /**
@@ -885,9 +840,11 @@ declare class AgentWallet {
     /**
      * Claim an agent invite code to receive a session key for the inviter's wallet.
      *
-     * This allows an agent to get a pre-configured session key from a human wallet owner
-     * without needing to register their own wallet or fund it. The human sets the budget
-     * limits and merchant whitelist when creating the invite.
+     * @deprecated Use `AgentWallet.fromAccessCode()` instead for a simpler flow that requires
+     * no wallet or signature. The new method:
+     * - Accepts a simple access code (mixr-xxx) instead of requiring a private key
+     * - Auto-caches credentials for subsequent calls
+     * - Works with `connect({ accessCode: 'mixr-xxx' })` or `MIXRPAY_ACCESS_CODE` env var
      *
      * @param options - Claim invite options including the invite code and agent's private key
      * @returns Claim result with the new session key
@@ -895,28 +852,211 @@ declare class AgentWallet {
      *
      * @example
      * ```typescript
-     * // Human creates invite at https://mixrpay.com/manage/invites, shares code "mixr-abc123"
-     *
+     * // DEPRECATED: Old way requiring private key
      * const result = await AgentWallet.claimInvite({
      *   inviteCode: 'mixr-abc123',
      *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
      * });
      *
-     * console.log(`Got session key: ${result.sessionKey}`);
-     * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
-     * console.log(`Invited by: ${result.inviterName}`);
-     *
-     * // Use the session key to make payments
-     * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
-     * const response = await wallet.fetch('https://api.example.com/endpoint');
+     * // NEW: Use fromAccessCode() instead - no private key needed
+     * const wallet = await AgentWallet.fromAccessCode('mixr-abc123');
+     * // or: const wallet = await AgentWallet.connect({ accessCode: 'mixr-abc123' });
      * ```
      */
     static claimInvite(options: AgentClaimInviteOptions): Promise<AgentClaimInviteResult>;
+    /**
+     * Activate an agent using a session key.
+     *
+     * This is the recommended way to initialize an agent at startup. It creates
+     * an AgentWallet instance and fetches all capabilities, budget info, skills,
+     * tools, and gateway providers in a single call.
+     *
+     * @param sessionKey - The session key in sk_live_ or sk_test_ format
+     * @param options - Optional configuration
+     * @returns AgentRuntime with wallet and all capabilities
+     * @throws {MixrPayError} If activation fails
+     *
+     * @example
+     * ```typescript
+     * // Activate at agent startup
+     * const runtime = await AgentWallet.activate(process.env.MIXRPAY_SESSION_KEY!);
+     *
+     * // Use the wallet for payments
+     * const response = await runtime.wallet.fetch('https://api.example.com/endpoint');
+     *
+     * // Check capabilities
+     * if (runtime.capabilities.gasSponsored) {
+     *   console.log('Gas is sponsored - no ETH needed!');
+     * }
+     *
+     * // List available gateway providers
+     * for (const provider of runtime.gatewayProviders) {
+     *   console.log(`${provider.name}: ${provider.tools.join(', ')}`);
+     * }
+     *
+     * // Check budget
+     * console.log(`Budget remaining: $${runtime.budget.remainingUsd}`);
+     * ```
+     */
+    static activate(sessionKey: string, options?: AgentActivateOptions): Promise<AgentRuntime>;
+    /**
+     * Connect to MixrPay with automatic credential resolution.
+     *
+     * This is the recommended zero-config entry point for agents. It implements
+     * an auth cascade that tries multiple credential sources in order:
+     *
+     * 1. **Explicit key**: If `sessionKey` is provided in options
+     * 2. **Environment variables**: `MIXRPAY_SESSION_KEY` (session key)
+     * 3. **Environment variables**: `MIXRPAY_API_KEY` or `MIXRPAY_AGENT_TOKEN` (agent token)
+     * 4. **Access code**: `options.accessCode` or `MIXRPAY_ACCESS_CODE` env var (one-time use)
+     * 5. **Master key + name**: `MIXRPAY_MASTER_KEY` + `options.agentName` (for multi-agent setups)
+     * 6. **Cached credentials**: Previously saved via `saveCredentials()` or CLI login
+     * 7. **Device flow**: Interactive browser-based login (if `interactive: true`)
+     *
+     * @param options - Optional connection options
+     * @returns Connected AgentWallet instance
+     * @throws {MixrPayError} If no credentials found and interactive mode disabled
+     *
+     * @example Zero-config (uses env vars or cached creds)
+     * ```typescript
+     * const wallet = await AgentWallet.connect();
+     * await wallet.fetch('https://api.example.com/endpoint');
+     * ```
+     *
+     * @example With explicit session key
+     * ```typescript
+     * const wallet = await AgentWallet.connect({
+     *   sessionKey: 'sk_live_...',
+     * });
+     * ```
+     *
+     * @example With master key for specific agent
+     * ```typescript
+     * const wallet = await AgentWallet.connect({
+     *   masterKey: process.env.MIXRPAY_MASTER_KEY,
+     *   agentName: 'research-agent',
+     * });
+     * ```
+     *
+     * @example Interactive mode (prompts for login if no creds)
+     * ```typescript
+     * const wallet = await AgentWallet.connect({
+     *   interactive: true,
+     * });
+     * ```
+     */
+    static connect(options?: ConnectOptions): Promise<AgentWallet>;
+    /**
+     * Create an AgentWallet from an API key (agt_live_xxx format).
+     *
+     * API keys are long-lived tokens that can be exchanged for session keys.
+     * This is useful for server-side deployments where you don't want to
+     * manage session key rotation manually.
+     *
+     * @param apiKey - API key in agt_live_xxx or agt_test_xxx format
+     * @param options - Optional configuration
+     * @returns Connected AgentWallet instance
+     * @throws {MixrPayError} If API key is invalid or exchange fails
+     *
+     * @example
+     * ```typescript
+     * const wallet = await AgentWallet.fromApiKey('agt_live_xxx');
+     * await wallet.fetch('https://api.example.com/endpoint');
+     * ```
+     */
+    static fromApiKey(apiKey: string, options?: {
+        baseUrl?: string;
+        logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    }): Promise<AgentWallet>;
+    /**
+     * Create an AgentWallet from an access code (mixr-xxx format).
+     *
+     * Access codes are one-time use codes generated in the MixrPay dashboard.
+     * After activation, the code is consumed and credentials are cached
+     * for subsequent use. This is the recommended method for external agents
+     * (Cursor, Claude, GPT, etc.) to connect to MixrPay.
+     *
+     * The access code is exchanged for:
+     * - `session_key` (sk_live_xxx) - used for signing delegation payments
+     * - `token` (agt_live_xxx) - bearer token for API calls
+     * - `agent_id` - AgentInstance ID for reference
+     * - `budget` - spending limits
+     * - `tools` - available MCP tools
+     *
+     * @param code - Access code in mixr-xxx format
+     * @param options - Optional configuration
+     * @returns Connected AgentWallet instance
+     * @throws {MixrPayError} If access code is invalid, expired, or already used
+     *
+     * @example
+     * ```typescript
+     * // First-time setup with access code
+     * const wallet = await AgentWallet.fromAccessCode('mixr-abc123def456');
+     *
+     * // Session key is auto-cached, subsequent calls use cached credentials
+     * const wallet2 = await AgentWallet.connect();
+     * ```
+     */
+    static fromAccessCode(code: string, options?: {
+        baseUrl?: string;
+        logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    }): Promise<AgentWallet>;
+    /**
+     * Create an AgentWallet using a master key for a specific agent.
+     *
+     * Master keys (mk_live_xxx) are organization-level credentials that can
+     * create sessions for any agent in the organization. This is useful for
+     * multi-agent deployments managed by a single entity.
+     *
+     * Note: Master key flow provides delegation access only. Self-custody
+     * wallet operations (createSelfCustodyWallet, transferUSDC, executeFromOwnWallet)
+     * require an agt_live_ token -- use fromApiKey() or fromAccessCode() instead.
+     *
+     * @param masterKey - Master key in mk_live_xxx format
+     * @param agentName - Name of the agent to connect as
+     * @param options - Optional configuration
+     * @returns Connected AgentWallet instance
+     * @throws {MixrPayError} If master key is invalid or agent not found
+     *
+     * @example
+     * ```typescript
+     * const wallet = await AgentWallet.fromMasterKey(
+     *   process.env.MIXRPAY_MASTER_KEY!,
+     *   'research-agent'
+     * );
+     * ```
+     */
+    static fromMasterKey(masterKey: string, agentName: string, options?: {
+        baseUrl?: string;
+        logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    }): Promise<AgentWallet>;
+    /**
+     * Interactive device flow login.
+     *
+     * Opens a browser for the user to authenticate, then polls for completion.
+     * This is the OAuth 2.0 Device Authorization Grant flow.
+     *
+     * @param options - Optional configuration
+     * @returns Connected AgentWallet instance
+     * @throws {MixrPayError} If device flow fails or times out
+     *
+     * @example
+     * ```typescript
+     * // In a CLI or terminal application
+     * const wallet = await AgentWallet.deviceFlowLogin();
+     * // User sees: "Visit https://mixrpay.com/device and enter code: ABCD-1234"
+     * // After user authenticates, wallet is ready to use
+     * ```
+     */
+    static deviceFlowLogin(options?: {
+        baseUrl?: string;
+        logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    }): Promise<AgentWallet>;
     /**
      * Spawn a child invite for sub-agents.
      *
      * Allows an agent to create an invite code for a sub-agent with a portion
-     * of their remaining budget (max 20%). The child inherits merchant restrictions
+     * of their remaining budget. The child inherits merchant restrictions
      * and cannot outlive the parent session.
      *
      * @param options - Spawn options
@@ -930,7 +1070,7 @@ declare class AgentWallet {
      *
      * // Spawn a child invite for a sub-agent
      * const childInvite = await wallet.spawnChildInvite({
-     *   budgetUsd: 10.00,  // Max 20% of available budget
+     *   budgetUsd: 10.00,
      *   name: 'Research Sub-Agent',
      *   allowedMerchants: ['firecrawl.dev'],  // Must be subset of parent
      *   expiresInDays: 7,  // Will be capped to parent's expiry
@@ -944,8 +1084,7 @@ declare class AgentWallet {
     /**
      * Get available budget information for spawning.
      *
-     * Returns the current budget status including how much can be spawned
-     * to child agents (20% of available).
+     * Returns the current budget status including spawn availability.
      *
      * @returns Budget information
      *
@@ -1130,17 +1269,195 @@ declare class AgentWallet {
      */
     getSpendingStats(): Promise<SpendingStats>;
     /**
-     * Get list of payments made in this session.
+     * 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;
+    /**
+     * Create a self-custody wallet for this agent.
+     *
+     * Generates a new private key, signs a proof of ownership, registers the
+     * address with MixrPay, and persists the key locally.
+     *
+     * The private key is stored locally and NEVER transmitted to MixrPay.
+     * MixrPay only stores the public address for transaction verification.
+     *
+     * @returns The wallet address and private key
+     * @throws {MixrPayError} If agent instance ID is not set or registration fails
+     *
+     * @example
+     * ```typescript
+     * const wallet = await AgentWallet.connect();
+     *
+     * // Create self-custody wallet (only needed once)
+     * const { address, privateKey } = await wallet.createSelfCustodyWallet();
+     * console.log(`Deposit address: ${address}`);
+     *
+     * // The private key is stored locally and loaded automatically
+     * ```
+     */
+    createSelfCustodyWallet(): Promise<{
+        address: `0x${string}`;
+        privateKey: `0x${string}`;
+    }>;
+    /**
+     * Register a wallet address with MixrPay.
+     *
+     * This is called automatically by createSelfCustodyWallet().
+     * Only use directly if you have an existing private key.
+     *
+     * @param address - The wallet address to register
+     * @param signature - Signature proving ownership
+     * @param timestamp - Timestamp used in signature message
+     * @throws {MixrPayError} If registration fails
+     */
+    private registerWalletAddress;
+    /**
+     * Load an existing self-custody wallet from local storage.
+     *
+     * @returns True if wallet was loaded, false if no wallet exists
+     */
+    loadSelfCustodyWallet(): Promise<boolean>;
+    /**
+     * Check if this agent has a self-custody wallet.
+     *
+     * @returns True if a self-custody wallet exists
+     */
+    hasSelfCustodyWallet(): Promise<boolean>;
+    /**
+     * Get the self-custody wallet address if one exists.
+     *
+     * @returns The wallet address or null if no self-custody wallet
+     */
+    getSelfCustodyAddress(): `0x${string}` | null;
+    /**
+     * Execute a transaction from the agent's self-custody wallet.
+     *
+     * Signs the transaction locally using viem and submits directly to Base RPC.
+     * Reports the transaction to MixrPay for audit logging.
+     *
+     * @param params - Transaction parameters
+     * @returns Transaction result with hash
+     * @throws {MixrPayError} If wallet not loaded or transaction fails
+     *
+     * @example
+     * ```typescript
+     * const result = await wallet.executeFromOwnWallet({
+     *   to: '0x...',
+     *   value: parseEther('0.01'),
+     *   data: '0x...',
+     * });
+     * console.log(`TX: ${result.txHash}`);
+     * ```
+     */
+    executeFromOwnWallet(params: {
+        to: `0x${string}`;
+        value?: bigint;
+        data?: `0x${string}`;
+        gasLimit?: bigint;
+    }): Promise<{
+        txHash: `0x${string}`;
+        reportedToMixrPay: boolean;
+    }>;
+    /**
+     * Transfer USDC from the agent's self-custody wallet.
+     *
+     * This is a convenience method for ERC-20 USDC transfers on Base.
+     * Returns the transaction hash. The transaction is automatically
+     * reported to MixrPay for audit logging.
+     *
+     * @param params - Transfer parameters
+     * @returns Transaction hash
+     * @throws {MixrPayError} If wallet not loaded or transfer fails
+     *
+     * @example
+     * ```typescript
+     * // Pay $5 USDC to a recipient
+     * const txHash = await wallet.transferUSDC({
+     *   to: '0xRecipientAddress...',
+     *   amountUsdc: 5.00,
+     * });
+     *
+     * console.log(`Transfer complete: ${txHash}`);
+     * ```
+     */
+    transferUSDC(params: {
+        to: `0x${string}`;
+        amountUsdc: number;
+    }): Promise<`0x${string}`>;
+    /**
+     * Report a transaction to MixrPay for audit logging.
+     *
+     * This is called automatically by executeFromOwnWallet().
+     *
+     * @param txHash - The transaction hash
+     * @param to - The recipient address
+     * @param value - The value transferred (in wei)
+     */
+    private reportTransaction;
+    /**
+     * Get the agent instance ID.
+     *
+     * @returns The agent instance ID or undefined if not set
+     */
+    getAgentInstanceId(): string | undefined;
+    /**
+     * Set the agent instance ID.
+     *
+     * This is typically set automatically when using fromApiKey() or connect().
+     *
+     * @param id - The agent instance ID
+     */
+    setAgentInstanceId(id: string): void;
+    /**
+     * Set the API key for self-custody operations.
      *
-     * @returns Array of payment events
+     * This is set automatically when using fromApiKey(). The API key is used
+     * for bearer token authentication on self-custody API calls (wallet registration,
+     * transaction reporting, etc.).
+     *
+     * @param key - The API key (agt_live_xxx or agt_test_xxx)
      */
-    getPaymentHistory(): PaymentEvent[];
+    setApiKey(key: string): void;
     /**
-     * Get the total amount spent in this session.
+     * Return an MCP server config for use with the Claude Agent SDK.
      *
-     * @returns Total spent in USD
+     * Spawns a child stdio MCP server process that exposes wallet tools
+     * (balance, marketplace, skills, transfers, budget delegation, tasks).
+     *
+     * @example With the Claude Agent SDK
+     * ```typescript
+     * import { query } from "@anthropic-ai/claude-agent-sdk";
+     * import { AgentWallet } from "@mixrpay/agent-sdk";
+     *
+     * const wallet = new AgentWallet({ sessionKey: process.env.MIXRPAY_SESSION_KEY! });
+     *
+     * for await (const msg of query({
+     *   prompt: "Use firecrawl to scrape example.com",
+     *   options: {
+     *     mcpServers: { mixrpay: wallet.mcp() },
+     *     allowedTools: ["mcp__mixrpay__*"],
+     *   },
+     * })) {
+     *   if (msg.type === "result" && msg.subtype === "success") console.log(msg.result);
+     * }
+     * ```
      */
-    getTotalSpent(): number;
+    mcp(): McpServerConfig;
+    /**
+     * Get the API key if set (internal use only).
+     *
+    // ===========================================================================
+    // Diagnostics
+    // ===========================================================================
+  
     /**
      * Run diagnostics to verify the wallet is properly configured.
      *
@@ -1160,6 +1477,41 @@ declare class AgentWallet {
      * ```
      */
     runDiagnostics(): Promise<DiagnosticsResult>;
+    /**
+     * Generate a SIWE (Sign-In with Ethereum) message and signature.
+     *
+     * This implements EIP-4361 and can be used to authenticate with services
+     * that support Sign-In with Ethereum, proving ownership of the session key.
+     *
+     * @param options - SIWE message options
+     * @returns SIWE message and signature
+     *
+     * @example Basic usage
+     * ```typescript
+     * const { message, signature } = await wallet.generateSiwe({
+     *   domain: 'example.com',
+     *   uri: 'https://example.com/login',
+     *   statement: 'Sign in to Example App',
+     * });
+     *
+     * // Send to server for verification
+     * await fetch('/api/verify', {
+     *   method: 'POST',
+     *   body: JSON.stringify({ message, signature }),
+     * });
+     * ```
+     *
+     * @example With nonce and expiration
+     * ```typescript
+     * const { message, signature } = await wallet.generateSiwe({
+     *   domain: 'myapp.com',
+     *   uri: 'https://myapp.com',
+     *   nonce: 'abc123',  // Server-provided nonce
+     *   expirationTime: new Date(Date.now() + 5 * 60 * 1000), // 5 min
+     * });
+     * ```
+     */
+    generateSiwe(options: SiweOptions): Promise<SiweResult>;
     /**
      * Enable or disable debug logging.
      *
@@ -1202,8 +1554,8 @@ declare class AgentWallet {
      * ```typescript
      * const session = await wallet.getOrCreateSession({
      *   merchantPublicKey: 'pk_live_abc123...',
-     *   spendingLimitUsd: 25.00,
-     *   durationDays: 7,
+     *   spendingLimitUsd: 100,
+     *   durationDays: 30,
      * });
      *
      * console.log(`Session active: $${session.remainingLimitUsd} remaining`);
@@ -1353,19 +1705,23 @@ declare class AgentWallet {
      * 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
+     * @returns Array of tools with pricing and metadata
      *
      * @example
      * ```typescript
-     * const tools = await wallet.listMCPTools();
+     * const tools = await wallet.listTools();
      * for (const tool of tools) {
      *   console.log(`${tool.name}: $${tool.priceUsd} - ${tool.description}`);
      * }
      * ```
      */
-    listMCPTools(): Promise<MCPTool[]>;
+    listTools(): Promise<Tool[]>;
+    /**
+     * @deprecated Use listTools() instead.
+     */
+    listMCPTools(): Promise<Tool[]>;
     /**
-     * Call an MCP tool with wallet authentication (direct pay per call).
+     * Call a 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.
@@ -1376,14 +1732,18 @@ declare class AgentWallet {
      *
      * @example
      * ```typescript
-     * const result = await wallet.callMCPTool('firecrawl/scrape', {
+     * const result = await wallet.callTool('firecrawl/scrape', {
      *   url: 'https://example.com',
      * });
      * console.log(result.data);
      * console.log(`Charged: $${result.chargedUsd}`);
      * ```
      */
-    callMCPTool(toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    callTool(toolName: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * @deprecated Use callTool() instead.
+     */
+    callMCPTool(toolName: string, args?: Record<string, unknown>): Promise<ToolResult>;
     /**
      * Deploy a JIT MCP server from the Glama directory.
      *
@@ -1459,6 +1819,46 @@ declare class AgentWallet {
      * ```
      */
     getJitInstance(instanceId: string): Promise<JitInstance>;
+    /**
+     * Execute an on-chain transaction from the human's wallet.
+     *
+     * Submits arbitrary calldata to any contract, bounded by the session key's
+     * budget limits (max_total, max_per_tx, max_daily). The platform validates
+     * the budget, executes the transaction, and records a charge.
+     *
+     * @param params - Transaction parameters
+     * @returns Transaction result with hash and remaining budget
+     * @throws {MixrPayError} If budget exceeded, tx reverted, or auth fails
+     *
+     * @example
+     * ```typescript
+     * // Bridge USDC via deBridge
+     * const quote = await deBridgeMcp.create_tx({ ... });
+     * const result = await wallet.executeTransaction({
+     *   to: quote.contractAddress,
+     *   data: quote.calldata,
+     *   estimatedCostUsd: 25.0,
+     *   description: 'Bridge 25 USDC Base -> Avalanche via deBridge',
+     * });
+     * console.log('TX:', result.txHash);
+     * console.log('Budget remaining:', result.remainingBudgetUsd);
+     * ```
+     */
+    executeTransaction(params: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+        value?: bigint;
+        chainId?: number;
+        estimatedCostUsd: number;
+        description?: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        success: boolean;
+        txHash: string;
+        chargeId: string;
+        estimatedCostUsd: number;
+        remainingBudgetUsd: number | null;
+    }>;
     /**
      * Use a configured skill by deploying a JIT MCP server with your saved API keys.
      *
@@ -1916,7 +2316,7 @@ declare class AgentWallet {
      */
     getAgentRunStatus(runId: string, _sessionId?: string): Promise<AgentRunStatusResult>;
     /**
-     * Call an MCP tool using session authorization (pre-authorized spending limit).
+     * Call a gateway 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.
@@ -1935,14 +2335,18 @@ declare class AgentWallet {
      * });
      *
      * // Use session for multiple calls
-     * const result = await wallet.callMCPToolWithSession(
+     * const result = await wallet.callToolWithSession(
      *   session.id,
      *   'firecrawl/scrape',
      *   { url: 'https://example.com' }
      * );
      * ```
      */
-    callMCPToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    callToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * @deprecated Use callToolWithSession() instead.
+     */
+    callMCPToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<ToolResult>;
     /**
      * Create a new task on the Task Board.
      *
@@ -2275,6 +2679,161 @@ declare class AgentWallet {
     private parseApprovalRequest;
     /** Helper to parse task from API response */
     private parseTask;
+    /**
+     * Get token balances for the wallet.
+     *
+     * Returns balances for USDC, ETH, and other tokens on the current chain.
+     * For delegation wallets, also includes budget information.
+     *
+     * @returns Multi-token balance information
+     * @throws {MixrPayError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances();
+     * console.log(`USDC: ${balances.balances.USDC.balance}`);
+     * console.log(`ETH: ${balances.balances.ETH.balance}`);
+     * if (balances.delegation) {
+     *   console.log(`Budget remaining: $${balances.delegation.remaining_usd}`);
+     * }
+     * ```
+     */
+    getBalances(): Promise<BalancesResponse>;
+    /**
+     * Transfer USDC to another address.
+     *
+     * For delegation wallets: Uses delegation signing (no local key needed).
+     * For self-custody wallets: Use transferUSDC() instead.
+     *
+     * @param to - Recipient address
+     * @param amount - Amount in USD (e.g., "10.50")
+     * @param currency - Currency to transfer (default: "USDC")
+     * @returns Transfer result with transaction hash
+     * @throws {MixrPayError} If the transfer fails
+     *
+     * @example
+     * ```typescript
+     * const result = await wallet.transfer('0x1234...', '10.00');
+     * console.log(`Transferred $${result.amount_usd}`);
+     * console.log(`TX: ${result.tx_hash}`);
+     * console.log(`Remaining budget: $${result.remaining_budget_usd}`);
+     * ```
+     */
+    transfer(to: string, amount: string, currency?: string): Promise<TransferResponse>;
+    /**
+     * Swap tokens using 0x Protocol on Base.
+     *
+     * Supports any ERC-20 token pair. First swap of a token may require
+     * an approval transaction (extra gas).
+     *
+     * @param sellToken - Token to sell (symbol or address, e.g., "USDC", "ETH")
+     * @param buyToken - Token to buy (symbol or address, e.g., "WETH", "USDC")
+     * @param sellAmount - Amount to sell in human-readable format (e.g., "100" for 100 USDC)
+     * @param slippageBps - Slippage tolerance in basis points (default: 100 = 1%)
+     * @returns Swap result with transaction hash and amounts
+     * @throws {MixrPayError} If the swap fails
+     *
+     * @example
+     * ```typescript
+     * // Swap 100 USDC for ETH
+     * const result = await wallet.swap('USDC', 'ETH', '100');
+     * console.log(`Swapped ${result.sell_amount} ${result.sell_token}`);
+     * console.log(`Received ${result.buy_amount} ${result.buy_token}`);
+     * console.log(`Price: ${result.price}`);
+     * ```
+     */
+    swap(sellToken: string, buyToken: string, sellAmount: string, slippageBps?: number): Promise<SwapResponse>;
+    /**
+     * Bridge tokens to another chain using deBridge.
+     *
+     * Currently supports bridging from Base to other EVM chains.
+     * The bridge transaction is submitted on the source chain; use
+     * getBridgeStatus() to check completion on the destination chain.
+     *
+     * @param token - Token to bridge (symbol, e.g., "USDC")
+     * @param amount - Amount in human-readable format (e.g., "100")
+     * @param destChain - Destination chain ID or name (e.g., "1" for Ethereum, "arbitrum")
+     * @param destAddress - Destination address (defaults to same address)
+     * @returns Bridge result with order ID for tracking
+     * @throws {MixrPayError} If the bridge fails
+     *
+     * @example
+     * ```typescript
+     * // Bridge 100 USDC to Arbitrum
+     * const result = await wallet.bridge('USDC', '100', 'arbitrum');
+     * console.log(`Bridge order: ${result.order_id}`);
+     * console.log(`Expected to receive: ${result.estimated_receive}`);
+     *
+     * // Check status later
+     * const status = await wallet.getBridgeStatus(result.order_id);
+     * if (status.status === 'fulfilled') {
+     *   console.log(`Completed! Dest TX: ${status.dest_tx_hash}`);
+     * }
+     * ```
+     */
+    bridge(token: string, amount: string, destChain: string, destAddress?: string): Promise<BridgeResponse>;
+    /**
+     * Check the status of a bridge order.
+     *
+     * @param orderId - The order ID from bridge()
+     * @returns Bridge status information
+     * @throws {MixrPayError} If the status check fails
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getBridgeStatus('abc123');
+     * switch (status.status) {
+     *   case 'pending':
+     *     console.log(`Still bridging... ETA: ${status.estimated_time_remaining}`);
+     *     break;
+     *   case 'fulfilled':
+     *     console.log(`Complete! TX: ${status.dest_tx_hash}`);
+     *     break;
+     *   case 'failed':
+     *     console.log('Bridge failed');
+     *     break;
+     * }
+     * ```
+     */
+    getBridgeStatus(orderId: string): Promise<BridgeStatusResponse>;
+    /**
+     * Fetch a URL with automatic x402 payment handling.
+     *
+     * If the server returns 402 Payment Required, this method automatically
+     * handles the payment from the wallet's delegation budget and retries
+     * the request. Zero x402 knowledge needed.
+     *
+     * This is the agent-facing version of x402 fetch. For the underlying
+     * fetch() that uses session key auth for x402, see the standard fetch() method.
+     *
+     * @param url - URL to fetch
+     * @param options - Fetch options (method, headers, body, maxPaymentUsd)
+     * @returns Response with status, headers, body, and optional payment info
+     * @throws {MixrPayError} If the fetch fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch from an x402-enabled API
+     * const result = await wallet.fetchPaid('https://api.example.com/data', {
+     *   method: 'POST',
+     *   body: { query: 'AI analysis' },
+     *   maxPaymentUsd: 1.0,
+     * });
+     *
+     * console.log(`Status: ${result.status}`);
+     * console.log(`Data: ${JSON.stringify(result.body)}`);
+     *
+     * if (result.payment?.paid) {
+     *   console.log(`Paid $${result.payment.amount_usd}`);
+     * }
+     * ```
+     */
+    fetchPaid(url: string, options?: FetchPaidOptions): Promise<FetchPaidResponse>;
+    /**
+     * Call the API with agent token auth (agt_live_xxx bearer token).
+     * Used by DeFi methods that require delegation auth.
+     */
+    private callApiWithAuth;
     /** Helper to call our API with auth */
     private callApi;
 }
@@ -2506,9 +3065,9 @@ interface MyTasksResult {
     };
 }
 /**
- * MCP Tool definition returned by listMCPTools()
+ * Tool definition returned by listTools()
  */
-interface MCPTool {
+interface Tool {
     /** Tool name in format "merchant/tool" */
     name: string;
     /** Human-readable description with price */
@@ -2524,10 +3083,12 @@ interface MCPTool {
     /** Whether the provider is domain-verified */
     verified: boolean;
 }
+/** @deprecated Use Tool instead */
+type MCPTool = Tool;
 /**
- * Result from calling an MCP tool
+ * Result from calling a tool
  */
-interface MCPToolResult {
+interface ToolResult {
     /** The tool's response data */
     data: unknown;
     /** Amount charged in USD */
@@ -2537,6 +3098,8 @@ interface MCPToolResult {
     /** Execution latency in milliseconds */
     latencyMs?: number;
 }
+/** @deprecated Use ToolResult instead */
+type MCPToolResult = ToolResult;
 /**
  * Message in an agent conversation
  */
@@ -3613,6 +4176,115 @@ declare class MerchantNotAllowedError extends MixrPayError {
     readonly allowedPatterns: string[];
     constructor(attempted: string, allowedPatterns: string[]);
 }
+/**
+ * Thrown when the API returns a 429 rate limit response.
+ *
+ * This error includes a suggested retry delay. The operation can be retried
+ * after waiting the specified time.
+ *
+ * ## Resolution
+ * 1. Wait for `retryAfterMs` milliseconds
+ * 2. Reduce request frequency
+ * 3. Contact support if limits are too restrictive
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await wallet.fetch(...);
+ * } catch (error) {
+ *   if (error instanceof RateLimitError) {
+ *     console.log(`Rate limited. Retry after ${error.retryAfterMs}ms`);
+ *     await sleep(error.retryAfterMs);
+ *     // Retry the operation
+ *   }
+ * }
+ * ```
+ */
+declare class RateLimitError extends MixrPayError {
+    constructor(retryAfterMs?: number, message?: string);
+    /**
+     * Rate limits are transient and operations can be retried after waiting.
+     * @returns true - always retryable after the delay
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Thrown when a network error occurs during an API call.
+ *
+ * This includes:
+ * - DNS resolution failures
+ * - Connection timeouts
+ * - Network disconnection
+ * - SSL/TLS errors
+ *
+ * ## Resolution
+ * 1. Check network connectivity
+ * 2. Retry the operation with exponential backoff
+ * 3. Check if the API endpoint is reachable
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await wallet.fetch(...);
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     console.log(`Network error: ${error.reason}`);
+ *     if (error.isRetryable()) {
+ *       await retry();
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class NetworkError extends MixrPayError {
+    /** The underlying error reason */
+    readonly reason: string;
+    constructor(reason: string, originalError?: Error);
+    /**
+     * Network errors are typically transient.
+     * @returns true - network issues usually resolve
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Thrown when authentication fails (401/403 responses).
+ *
+ * This error indicates:
+ * - Invalid API key or session key
+ * - Expired credentials
+ * - Missing authentication headers
+ * - Insufficient permissions
+ *
+ * ## Resolution
+ * 1. Verify your session key is correct
+ * 2. Check if the key has expired
+ * 3. Ensure the key has permissions for the operation
+ * 4. Request a new session key if needed
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await wallet.fetch(...);
+ * } catch (error) {
+ *   if (error instanceof AuthenticationError) {
+ *     console.log(`Auth failed: ${error.reason}`);
+ *     // Request new credentials
+ *   }
+ * }
+ * ```
+ */
+declare class AuthenticationError extends MixrPayError {
+    /** The specific authentication failure reason */
+    readonly reason: string;
+    /** HTTP status code (401 or 403) */
+    readonly statusCode: number;
+    constructor(reason: string, statusCode?: 401 | 403);
+    /**
+     * Authentication errors are not retryable without user action.
+     * @returns false - requires new credentials
+     */
+    isRetryable(): boolean;
+}
 /**
  * Check if an error is a MixrPay SDK error.
  *
@@ -3649,4 +4321,199 @@ declare function isMixrPayError(error: unknown): error is MixrPayError;
  */
 declare function getErrorMessage(error: unknown): string;
 
-export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AvailableBudget, type CallMerchantApiOptions, type ChargeResult, type ChildSession, type CompleteOptions, type CompleteResult, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SkillInfo, type SkillStatus, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, type UseSkillOptions, type UseSkillResult, X402ProtocolError, getErrorMessage, isMixrPayError };
+/**
+ * MixrPay Agent SDK - Credential Management
+ *
+ * Platform-aware credential storage for session keys and API tokens.
+ * Stores credentials securely with appropriate file permissions.
+ *
+ * Storage locations:
+ * - Linux/macOS: ~/.config/mixrpay/credentials.json
+ * - Windows: %APPDATA%/mixrpay/credentials.json
+ *
+ * File permissions: 0600 (read/write for owner only)
+ */
+interface StoredCredentials {
+    /** Session key (sk_live_xxx or sk_test_xxx) */
+    sessionKey?: string;
+    /** API token (agt_live_xxx) for API calls */
+    apiToken?: string;
+    /** @deprecated Use apiToken instead. Legacy connect token (ac_live_xxx) */
+    connectToken?: string;
+    /** Master key (mk_live_xxx) for multi-agent management */
+    masterKey?: string;
+    /** Default agent name (used with master key) */
+    defaultAgentName?: string;
+    /** Base URL override */
+    baseUrl?: string;
+    /** When credentials were last updated */
+    updatedAt?: string;
+}
+type CredentialLoadResult = {
+    success: true;
+    credentials: StoredCredentials;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Save credentials to the platform-specific config location.
+ *
+ * @param credentials - Credentials to save (merged with existing)
+ * @returns true if successful, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Save a session key
+ * await saveCredentials({ sessionKey: 'sk_live_xxx' });
+ *
+ * // Save multiple credentials
+ * await saveCredentials({
+ *   masterKey: 'mk_live_xxx',
+ *   defaultAgentName: 'my-agent',
+ * });
+ * ```
+ */
+declare function saveCredentials(credentials: Partial<StoredCredentials>): boolean;
+/**
+ * Load credentials from the platform-specific config location.
+ *
+ * @returns Loaded credentials or error
+ *
+ * @example
+ * ```typescript
+ * const result = loadCredentials();
+ * if (result.success) {
+ *   console.log('Session key:', result.credentials.sessionKey);
+ * }
+ * ```
+ */
+declare function loadCredentials(): CredentialLoadResult;
+/**
+ * Delete stored credentials.
+ *
+ * @param keys - Specific keys to delete, or undefined to delete all
+ * @returns true if successful
+ *
+ * @example
+ * ```typescript
+ * // Delete specific credentials
+ * deleteCredentials(['sessionKey', 'apiToken']);
+ *
+ * // Delete all credentials
+ * deleteCredentials();
+ * ```
+ */
+declare function deleteCredentials(keys?: (keyof StoredCredentials)[]): boolean;
+/**
+ * Check if credentials are stored.
+ *
+ * @returns true if any credentials are stored
+ */
+declare function hasCredentials(): boolean;
+/**
+ * Get the path to the credentials file (for debugging/info).
+ *
+ * @returns The credentials file path
+ */
+declare function getCredentialsFilePath(): string;
+
+/**
+ * MixrPay Agent SDK - Wallet Storage
+ * @packageDocumentation
+ */
+/**
+ * Structure of the stored wallet file
+ */
+interface StoredWallet {
+    /** Wallet address (0x-prefixed) */
+    address: string;
+    /** Private key (0x-prefixed hex) */
+    privateKey: string;
+    /** ISO timestamp when wallet was created */
+    createdAt: string;
+    /** SDK version that created the wallet */
+    sdkVersion: string;
+}
+/**
+ * Save a wallet private key to local storage.
+ *
+ * Creates the config directory if it doesn't exist.
+ * Sets file permissions to 0o600 (owner read/write only).
+ *
+ * @param privateKey - The wallet private key (0x-prefixed hex)
+ * @param address - The wallet address (0x-prefixed)
+ * @throws Error if unable to write to filesystem
+ *
+ * @example
+ * ```typescript
+ * import { saveWalletKey } from '@mixrpay/agent-sdk';
+ * import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+ *
+ * const privateKey = generatePrivateKey();
+ * const account = privateKeyToAccount(privateKey);
+ * await saveWalletKey(privateKey, account.address);
+ * ```
+ */
+declare function saveWalletKey(privateKey: `0x${string}`, address: string): Promise<void>;
+/**
+ * Load the wallet private key from storage.
+ *
+ * Checks in order:
+ * 1. MIXRPAY_WALLET_KEY environment variable
+ * 2. Local wallet file
+ *
+ * @returns The private key (0x-prefixed hex) or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { loadWalletKey } from '@mixrpay/agent-sdk';
+ *
+ * const privateKey = await loadWalletKey();
+ * if (privateKey) {
+ *   console.log('Wallet loaded successfully');
+ * }
+ * ```
+ */
+declare function loadWalletKey(): Promise<`0x${string}` | null>;
+/**
+ * Load the full wallet data including address and metadata.
+ *
+ * @returns The stored wallet data or null if not found
+ */
+declare function loadWalletData(): Promise<StoredWallet | null>;
+/**
+ * Check if a wallet key exists in storage.
+ *
+ * @returns True if a wallet key is available
+ *
+ * @example
+ * ```typescript
+ * import { hasWalletKey, loadWalletKey } from '@mixrpay/agent-sdk';
+ *
+ * if (await hasWalletKey()) {
+ *   const key = await loadWalletKey();
+ *   // Use existing wallet
+ * } else {
+ *   // Create new wallet
+ * }
+ * ```
+ */
+declare function hasWalletKey(): Promise<boolean>;
+/**
+ * Get the wallet storage path for debugging.
+ *
+ * @returns The path where the wallet would be stored
+ */
+declare function getWalletStoragePath(): string;
+/**
+ * Delete the stored wallet key.
+ *
+ * WARNING: This permanently deletes the wallet key. Make sure you have
+ * backed up the key before calling this.
+ *
+ * @returns True if a wallet was deleted, false if no wallet existed
+ */
+declare function deleteWalletKey(): Promise<boolean>;
+
+export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, AuthenticationError, type AvailableBudget, type BalancesResponse, type BridgeResponse, type BridgeStatusResponse, type CallMerchantApiOptions, type ChargeResult, type ChildSession, type CompleteOptions, type CompleteResult, type ConnectOptions, type CredentialLoadResult, type DelegationBudget, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type FetchPaidOptions, type FetchPaidResponse, type FetchPaymentInfo, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, type MCPTool, type MCPToolResult, type McpServerConfig, MerchantNotAllowedError, MixrPayError, NetworkError, type PaymentEvent, PaymentFailedError, RateLimitError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SiweOptions, type SiweResult, type SkillInfo, type SkillStatus, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, type StoredCredentials, type StoredWallet, type SwapResponse, type TokenBalance, type Tool, type ToolResult, type TransferResponse, type UseSkillOptions, type UseSkillResult, X402ProtocolError, deleteCredentials, deleteWalletKey, getCredentialsFilePath, getErrorMessage, getWalletStoragePath, hasCredentials, hasWalletKey, isMixrPayError, loadCredentials, loadWalletData, loadWalletKey, saveCredentials, saveWalletKey };