@mixrpay/agent-sdk 0.9.5 → 0.10.0

package/dist/index.d.cts

@@ -213,9 +213,106 @@ interface FetchPaidOptions {
     body?: unknown;
     maxPaymentUsd?: number;
 }
+/**
+ * Known charge types in the MixrPay system.
+ * The API may return additional types not listed here.
+ */
+type KnownChargeType = 'payment' | 'defi_tx' | 'tool_call' | 'transfer' | 'swap' | 'bridge' | 'x402_payment' | 'jit_deploy';
+/**
+ * Charge type - known types with autocomplete, plus string for forward compatibility.
+ */
+type ChargeType = KnownChargeType | (string & {});
+/**
+ * A single transaction record from the agent's transaction history.
+ */
+interface TransactionRecord {
+    /** Unique charge ID */
+    id: string;
+    /** Type of charge (e.g., 'swap', 'transfer', 'bridge') */
+    chargeType: ChargeType;
+    /** Amount in USD (formatted string, e.g., "10.00") */
+    amount: string;
+    /** Currency (typically "USDC") */
+    currency: string;
+    /** Transaction status */
+    status: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    /** Human-readable description */
+    description: string | null;
+    /** On-chain transaction hash (null if not yet submitted) */
+    txHash: string | null;
+    /** Source wallet address */
+    fromAddress: string;
+    /** Destination address */
+    toAddress: string;
+    /** Plan ID if this charge was part of a plan execution */
+    planId: string | null;
+    /** Step index within the plan */
+    planStepIndex: number | null;
+    /** ISO 8601 timestamp when the charge was created */
+    createdAt: string;
+    /** ISO 8601 timestamp when the charge was confirmed (null if pending/failed) */
+    confirmedAt: string | null;
+}
+/**
+ * Response from getTransactions() containing paginated transaction history.
+ */
+interface TransactionsResponse {
+    /** Array of transaction records */
+    transactions: TransactionRecord[];
+    /** Total number of matching transactions */
+    total: number;
+    /** Whether there are more transactions beyond the current page */
+    hasMore: boolean;
+}
+/**
+ * Options for querying transaction history.
+ */
+interface GetTransactionsOptions {
+    /** Maximum number of transactions to return (default: 20, max: 100) */
+    limit?: number;
+    /** Number of transactions to skip (for pagination) */
+    offset?: number;
+    /** Filter by charge type (e.g., 'swap', 'transfer') */
+    chargeType?: string;
+    /** Filter by status */
+    status?: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    /** Only return transactions after this date */
+    since?: Date;
+}
+/**
+ * A tool definition formatted for the Anthropic API.
+ * Compatible with anthropic.messages.create({ tools: [...] }).
+ */
+interface AnthropicToolDefinition {
+    /** Tool name (e.g., 'check_balance', 'transfer_usdc') */
+    name: string;
+    /** Description of what the tool does (shown to the LLM) */
+    description: string;
+    /** JSON Schema for the tool's input parameters */
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * A toolkit containing Anthropic-compatible tool definitions and an executor.
+ * Returned by wallet.tools() for use with raw Anthropic SDK.
+ */
+interface AnthropicToolkit {
+    /** Array of tool definitions for anthropic.messages.create({ tools: [...] }) */
+    definitions: AnthropicToolDefinition[];
+    /**
+     * Execute a tool by name with the given input.
+     * @param name - Tool name (e.g., 'check_balance')
+     * @param input - Tool input parameters
+     * @returns JSON string result (for tool_result content)
+     */
+    execute: (name: string, input: Record<string, unknown>) => Promise<string>;
+}
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.9.4";
+declare const SDK_VERSION = "0.10.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -1269,9 +1366,13 @@ declare class AgentWallet {
      */
     getSpendingStats(): Promise<SpendingStats>;
     /**
-     * Get list of payments made in this session.
+     * Get list of payments made in this session (in-memory only).
+     *
+     * @deprecated Use {@link getTransactions} instead for persistent transaction history.
+     * This method only returns payments from the current process and is lost on restart.
+     * `getTransactions()` returns server-persisted transaction history across all sessions.
      *
-     * @returns Array of payment events
+     * @returns Array of payment events from the current session
      */
     getPaymentHistory(): PaymentEvent[];
     /**
@@ -1452,12 +1553,39 @@ declare class AgentWallet {
      */
     mcp(): McpServerConfig;
     /**
-     * Get the API key if set (internal use only).
+     * Get tool definitions for use with the Anthropic SDK or other LLM frameworks.
+     *
+     * This provides an in-process alternative to the MCP server. While `mcp()` spawns
+     * a subprocess for Claude Agent SDK integration, `tools()` returns function-callable
+     * tools for direct use with `anthropic.messages.create({ tools: [...] })`.
+     *
+     * @returns Toolkit with Anthropic-compatible definitions and execute dispatcher
+     *
+     * @example
+     * ```typescript
+     * import Anthropic from '@anthropic-ai/sdk';
+     * import { AgentWallet } from '@mixrpay/agent-sdk';
      *
-    // ===========================================================================
-    // Diagnostics
-    // ===========================================================================
-  
+     * const wallet = AgentWallet.fromApiKey('agt_live_xxx');
+     * const { definitions, execute } = wallet.tools();
+     *
+     * const response = await anthropic.messages.create({
+     *   model: 'claude-sonnet-4-5-20250514',
+     *   max_tokens: 1024,
+     *   tools: definitions,
+     *   messages: [{ role: 'user', content: 'Check my USDC balance' }],
+     * });
+     *
+     * for (const block of response.content) {
+     *   if (block.type === 'tool_use') {
+     *     const result = await execute(block.name, block.input as Record<string, unknown>);
+     *     // Feed result back to Claude as tool_result
+     *     console.log(`Tool ${block.name} returned:`, result);
+     *   }
+     * }
+     * ```
+     */
+    tools(): AnthropicToolkit;
     /**
      * Run diagnostics to verify the wallet is properly configured.
      *
@@ -2699,6 +2827,35 @@ declare class AgentWallet {
      * ```
      */
     getBalances(): Promise<BalancesResponse>;
+    /**
+     * Get the agent's transaction history with filtering and pagination.
+     *
+     * Returns server-persisted transaction records including swaps, transfers,
+     * bridges, and tool payments. Unlike `getPaymentHistory()`, this data
+     * persists across process restarts and includes all historical transactions.
+     *
+     * @param options - Query options for filtering and pagination
+     * @returns Paginated transaction records
+     * @throws {MixrPayError} If the query fails
+     *
+     * @example
+     * ```typescript
+     * // Get recent transactions
+     * const { transactions, total, hasMore } = await wallet.getTransactions();
+     *
+     * // Filter by type
+     * const swaps = await wallet.getTransactions({ chargeType: 'swap' });
+     *
+     * // Paginate
+     * const page2 = await wallet.getTransactions({ limit: 20, offset: 20 });
+     *
+     * // Get transactions since yesterday
+     * const recent = await wallet.getTransactions({
+     *   since: new Date(Date.now() - 24 * 60 * 60 * 1000)
+     * });
+     * ```
+     */
+    getTransactions(options?: GetTransactionsOptions): Promise<TransactionsResponse>;
     /**
      * Transfer USDC to another address.
      *
@@ -4516,4 +4673,4 @@ declare function getWalletStoragePath(): string;
  */
 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 };
+export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AnthropicToolDefinition, type AnthropicToolkit, AuthenticationError, type AvailableBudget, type BalancesResponse, type BridgeResponse, type BridgeStatusResponse, type CallMerchantApiOptions, type ChargeResult, type ChargeType, 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 GetTransactionsOptions, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, type KnownChargeType, 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 TransactionRecord, type TransactionsResponse, type TransferResponse, type UseSkillOptions, type UseSkillResult, X402ProtocolError, deleteCredentials, deleteWalletKey, getCredentialsFilePath, getErrorMessage, getWalletStoragePath, hasCredentials, hasWalletKey, isMixrPayError, loadCredentials, loadWalletData, loadWalletKey, saveCredentials, saveWalletKey };

package/dist/index.d.ts

@@ -213,9 +213,106 @@ interface FetchPaidOptions {
     body?: unknown;
     maxPaymentUsd?: number;
 }
+/**
+ * Known charge types in the MixrPay system.
+ * The API may return additional types not listed here.
+ */
+type KnownChargeType = 'payment' | 'defi_tx' | 'tool_call' | 'transfer' | 'swap' | 'bridge' | 'x402_payment' | 'jit_deploy';
+/**
+ * Charge type - known types with autocomplete, plus string for forward compatibility.
+ */
+type ChargeType = KnownChargeType | (string & {});
+/**
+ * A single transaction record from the agent's transaction history.
+ */
+interface TransactionRecord {
+    /** Unique charge ID */
+    id: string;
+    /** Type of charge (e.g., 'swap', 'transfer', 'bridge') */
+    chargeType: ChargeType;
+    /** Amount in USD (formatted string, e.g., "10.00") */
+    amount: string;
+    /** Currency (typically "USDC") */
+    currency: string;
+    /** Transaction status */
+    status: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    /** Human-readable description */
+    description: string | null;
+    /** On-chain transaction hash (null if not yet submitted) */
+    txHash: string | null;
+    /** Source wallet address */
+    fromAddress: string;
+    /** Destination address */
+    toAddress: string;
+    /** Plan ID if this charge was part of a plan execution */
+    planId: string | null;
+    /** Step index within the plan */
+    planStepIndex: number | null;
+    /** ISO 8601 timestamp when the charge was created */
+    createdAt: string;
+    /** ISO 8601 timestamp when the charge was confirmed (null if pending/failed) */
+    confirmedAt: string | null;
+}
+/**
+ * Response from getTransactions() containing paginated transaction history.
+ */
+interface TransactionsResponse {
+    /** Array of transaction records */
+    transactions: TransactionRecord[];
+    /** Total number of matching transactions */
+    total: number;
+    /** Whether there are more transactions beyond the current page */
+    hasMore: boolean;
+}
+/**
+ * Options for querying transaction history.
+ */
+interface GetTransactionsOptions {
+    /** Maximum number of transactions to return (default: 20, max: 100) */
+    limit?: number;
+    /** Number of transactions to skip (for pagination) */
+    offset?: number;
+    /** Filter by charge type (e.g., 'swap', 'transfer') */
+    chargeType?: string;
+    /** Filter by status */
+    status?: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    /** Only return transactions after this date */
+    since?: Date;
+}
+/**
+ * A tool definition formatted for the Anthropic API.
+ * Compatible with anthropic.messages.create({ tools: [...] }).
+ */
+interface AnthropicToolDefinition {
+    /** Tool name (e.g., 'check_balance', 'transfer_usdc') */
+    name: string;
+    /** Description of what the tool does (shown to the LLM) */
+    description: string;
+    /** JSON Schema for the tool's input parameters */
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * A toolkit containing Anthropic-compatible tool definitions and an executor.
+ * Returned by wallet.tools() for use with raw Anthropic SDK.
+ */
+interface AnthropicToolkit {
+    /** Array of tool definitions for anthropic.messages.create({ tools: [...] }) */
+    definitions: AnthropicToolDefinition[];
+    /**
+     * Execute a tool by name with the given input.
+     * @param name - Tool name (e.g., 'check_balance')
+     * @param input - Tool input parameters
+     * @returns JSON string result (for tool_result content)
+     */
+    execute: (name: string, input: Record<string, unknown>) => Promise<string>;
+}
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.9.4";
+declare const SDK_VERSION = "0.10.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -1269,9 +1366,13 @@ declare class AgentWallet {
      */
     getSpendingStats(): Promise<SpendingStats>;
     /**
-     * Get list of payments made in this session.
+     * Get list of payments made in this session (in-memory only).
+     *
+     * @deprecated Use {@link getTransactions} instead for persistent transaction history.
+     * This method only returns payments from the current process and is lost on restart.
+     * `getTransactions()` returns server-persisted transaction history across all sessions.
      *
-     * @returns Array of payment events
+     * @returns Array of payment events from the current session
      */
     getPaymentHistory(): PaymentEvent[];
     /**
@@ -1452,12 +1553,39 @@ declare class AgentWallet {
      */
     mcp(): McpServerConfig;
     /**
-     * Get the API key if set (internal use only).
+     * Get tool definitions for use with the Anthropic SDK or other LLM frameworks.
+     *
+     * This provides an in-process alternative to the MCP server. While `mcp()` spawns
+     * a subprocess for Claude Agent SDK integration, `tools()` returns function-callable
+     * tools for direct use with `anthropic.messages.create({ tools: [...] })`.
+     *
+     * @returns Toolkit with Anthropic-compatible definitions and execute dispatcher
+     *
+     * @example
+     * ```typescript
+     * import Anthropic from '@anthropic-ai/sdk';
+     * import { AgentWallet } from '@mixrpay/agent-sdk';
      *
-    // ===========================================================================
-    // Diagnostics
-    // ===========================================================================
-  
+     * const wallet = AgentWallet.fromApiKey('agt_live_xxx');
+     * const { definitions, execute } = wallet.tools();
+     *
+     * const response = await anthropic.messages.create({
+     *   model: 'claude-sonnet-4-5-20250514',
+     *   max_tokens: 1024,
+     *   tools: definitions,
+     *   messages: [{ role: 'user', content: 'Check my USDC balance' }],
+     * });
+     *
+     * for (const block of response.content) {
+     *   if (block.type === 'tool_use') {
+     *     const result = await execute(block.name, block.input as Record<string, unknown>);
+     *     // Feed result back to Claude as tool_result
+     *     console.log(`Tool ${block.name} returned:`, result);
+     *   }
+     * }
+     * ```
+     */
+    tools(): AnthropicToolkit;
     /**
      * Run diagnostics to verify the wallet is properly configured.
      *
@@ -2699,6 +2827,35 @@ declare class AgentWallet {
      * ```
      */
     getBalances(): Promise<BalancesResponse>;
+    /**
+     * Get the agent's transaction history with filtering and pagination.
+     *
+     * Returns server-persisted transaction records including swaps, transfers,
+     * bridges, and tool payments. Unlike `getPaymentHistory()`, this data
+     * persists across process restarts and includes all historical transactions.
+     *
+     * @param options - Query options for filtering and pagination
+     * @returns Paginated transaction records
+     * @throws {MixrPayError} If the query fails
+     *
+     * @example
+     * ```typescript
+     * // Get recent transactions
+     * const { transactions, total, hasMore } = await wallet.getTransactions();
+     *
+     * // Filter by type
+     * const swaps = await wallet.getTransactions({ chargeType: 'swap' });
+     *
+     * // Paginate
+     * const page2 = await wallet.getTransactions({ limit: 20, offset: 20 });
+     *
+     * // Get transactions since yesterday
+     * const recent = await wallet.getTransactions({
+     *   since: new Date(Date.now() - 24 * 60 * 60 * 1000)
+     * });
+     * ```
+     */
+    getTransactions(options?: GetTransactionsOptions): Promise<TransactionsResponse>;
     /**
      * Transfer USDC to another address.
      *
@@ -4516,4 +4673,4 @@ declare function getWalletStoragePath(): string;
  */
 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 };
+export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AnthropicToolDefinition, type AnthropicToolkit, AuthenticationError, type AvailableBudget, type BalancesResponse, type BridgeResponse, type BridgeStatusResponse, type CallMerchantApiOptions, type ChargeResult, type ChargeType, 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 GetTransactionsOptions, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, type KnownChargeType, 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 TransactionRecord, type TransactionsResponse, type TransferResponse, type UseSkillOptions, type UseSkillResult, X402ProtocolError, deleteCredentials, deleteWalletKey, getCredentialsFilePath, getErrorMessage, getWalletStoragePath, hasCredentials, hasWalletKey, isMixrPayError, loadCredentials, loadWalletData, loadWalletKey, saveCredentials, saveWalletKey };