@mixrpay/agent-sdk 0.9.5 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -200,6 +200,7 @@ interface FetchPaymentInfo {
200
200
  amount_usd: string;
201
201
  tx_hash?: string;
202
202
  remaining_budget_usd: string | null;
203
+ charge_id?: string;
203
204
  }
204
205
  interface FetchPaidResponse {
205
206
  status: number;
@@ -212,10 +213,291 @@ interface FetchPaidOptions {
212
213
  headers?: Record<string, string>;
213
214
  body?: unknown;
214
215
  maxPaymentUsd?: number;
216
+ /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
217
+ idempotencyKey?: string;
218
+ }
219
+ /**
220
+ * Options for transfer operations with idempotency support.
221
+ */
222
+ interface TransferOptions {
223
+ /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
224
+ idempotencyKey?: string;
225
+ }
226
+ /**
227
+ * Options for swap operations with idempotency support.
228
+ */
229
+ interface SwapOptions {
230
+ /** Slippage tolerance in basis points (default: 100 = 1%) */
231
+ slippageBps?: number;
232
+ /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
233
+ idempotencyKey?: string;
234
+ }
235
+ /**
236
+ * Options for bridge operations with idempotency support.
237
+ */
238
+ interface BridgeOptions {
239
+ /** Destination address (defaults to same address) */
240
+ destAddress?: string;
241
+ /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
242
+ idempotencyKey?: string;
243
+ }
244
+ /**
245
+ * Known charge types in the MixrPay system.
246
+ * The API may return additional types not listed here.
247
+ */
248
+ type KnownChargeType = 'payment' | 'defi_tx' | 'tool_call' | 'transfer' | 'swap' | 'bridge' | 'x402_payment' | 'jit_deploy';
249
+ /**
250
+ * Charge type - known types with autocomplete, plus string for forward compatibility.
251
+ */
252
+ type ChargeType = KnownChargeType | (string & {});
253
+ /**
254
+ * A single transaction record from the agent's transaction history.
255
+ */
256
+ interface TransactionRecord {
257
+ /** Unique charge ID */
258
+ id: string;
259
+ /** Type of charge (e.g., 'swap', 'transfer', 'bridge') */
260
+ chargeType: ChargeType;
261
+ /** Amount in USD (formatted string, e.g., "10.00") */
262
+ amount: string;
263
+ /** Currency (typically "USDC") */
264
+ currency: string;
265
+ /** Transaction status */
266
+ status: 'pending' | 'submitted' | 'confirmed' | 'failed';
267
+ /** Human-readable description */
268
+ description: string | null;
269
+ /** On-chain transaction hash (null if not yet submitted) */
270
+ txHash: string | null;
271
+ /** Source wallet address */
272
+ fromAddress: string;
273
+ /** Destination address */
274
+ toAddress: string;
275
+ /** Plan ID if this charge was part of a plan execution */
276
+ planId: string | null;
277
+ /** Step index within the plan */
278
+ planStepIndex: number | null;
279
+ /** ISO 8601 timestamp when the charge was created */
280
+ createdAt: string;
281
+ /** ISO 8601 timestamp when the charge was confirmed (null if pending/failed) */
282
+ confirmedAt: string | null;
283
+ }
284
+ /**
285
+ * Response from getTransactions() containing paginated transaction history.
286
+ */
287
+ interface TransactionsResponse {
288
+ /** Array of transaction records */
289
+ transactions: TransactionRecord[];
290
+ /** Total number of matching transactions */
291
+ total: number;
292
+ /** Whether there are more transactions beyond the current page */
293
+ hasMore: boolean;
294
+ }
295
+ /**
296
+ * Options for querying transaction history.
297
+ */
298
+ interface GetTransactionsOptions {
299
+ /** Maximum number of transactions to return (default: 20, max: 100) */
300
+ limit?: number;
301
+ /** Number of transactions to skip (for pagination) */
302
+ offset?: number;
303
+ /** Filter by charge type (e.g., 'swap', 'transfer') */
304
+ chargeType?: string;
305
+ /** Filter by status */
306
+ status?: 'pending' | 'submitted' | 'confirmed' | 'failed';
307
+ /** Only return transactions after this date */
308
+ since?: Date;
309
+ }
310
+ /**
311
+ * A tool definition formatted for the Anthropic API.
312
+ * Compatible with anthropic.messages.create({ tools: [...] }).
313
+ */
314
+ interface AnthropicToolDefinition {
315
+ /** Tool name (e.g., 'check_balance', 'transfer_usdc') */
316
+ name: string;
317
+ /** Description of what the tool does (shown to the LLM) */
318
+ description: string;
319
+ /** JSON Schema for the tool's input parameters */
320
+ input_schema: {
321
+ type: 'object';
322
+ properties: Record<string, unknown>;
323
+ required?: string[];
324
+ };
325
+ }
326
+ /**
327
+ * A toolkit containing Anthropic-compatible tool definitions and an executor.
328
+ * Returned by wallet.tools() for use with raw Anthropic SDK.
329
+ */
330
+ interface AnthropicToolkit {
331
+ /** Array of tool definitions for anthropic.messages.create({ tools: [...] }) */
332
+ definitions: AnthropicToolDefinition[];
333
+ /**
334
+ * Execute a tool by name with the given input.
335
+ * @param name - Tool name (e.g., 'check_balance')
336
+ * @param input - Tool input parameters
337
+ * @returns JSON string result (for tool_result content)
338
+ */
339
+ execute: (name: string, input: Record<string, unknown>) => Promise<string>;
340
+ }
341
+ /**
342
+ * Supported plan step actions.
343
+ */
344
+ type PlanStepAction = 'transfer' | 'swap' | 'bridge' | 'tool_call' | 'fetch' | 'custom';
345
+ /**
346
+ * A single step in a plan.
347
+ */
348
+ interface PlanStep {
349
+ /** Action type for this step */
350
+ action: PlanStepAction;
351
+ /** Parameters for the action */
352
+ params: Record<string, unknown>;
353
+ /** Estimated cost in USD */
354
+ estimatedCostUsd?: number;
355
+ /** Human-readable description */
356
+ description: string;
357
+ }
358
+ /**
359
+ * Plan submission request.
360
+ */
361
+ interface PlanSubmission {
362
+ /** Plan title */
363
+ title: string;
364
+ /** Optional description */
365
+ description?: string;
366
+ /** Steps to execute */
367
+ steps: PlanStep[];
368
+ /** Total estimated cost in USD */
369
+ totalEstimatedCostUsd: number;
370
+ /** Whether to require human approval (default: false) */
371
+ requiresApproval?: boolean;
372
+ /** Idempotency key for exactly-once submission */
373
+ idempotencyKey?: string;
374
+ }
375
+ /**
376
+ * Result from submitting a plan.
377
+ */
378
+ interface PlanSubmitResult {
379
+ /** Unique plan ID */
380
+ planId: string;
381
+ /** Plan status after submission */
382
+ status: 'pending_approval' | 'auto_approved';
383
+ /** URL for human approval (if pending) */
384
+ approvalUrl?: string;
385
+ }
386
+ /**
387
+ * Status values for plan steps.
388
+ */
389
+ type PlanStepStatusValue = 'pending' | 'executing' | 'completed' | 'failed' | 'skipped' | 'awaiting_confirmation';
390
+ /**
391
+ * Status of a single plan step.
392
+ */
393
+ interface PlanStepStatus {
394
+ /** Step index */
395
+ index: number;
396
+ /** Action type */
397
+ action: PlanStepAction;
398
+ /** Step description */
399
+ description: string;
400
+ /** Current status */
401
+ status: PlanStepStatusValue;
402
+ /** Estimated cost in USD */
403
+ estimatedCostUsd?: number;
404
+ /** Transaction hash (if completed) */
405
+ txHash?: string;
406
+ /** Charge ID (if completed) */
407
+ chargeId?: string;
408
+ /** Bridge order ID (if bridge action) */
409
+ bridgeOrderId?: string;
410
+ /** Error message (if failed) */
411
+ error?: string;
412
+ /** When execution started */
413
+ submittedAt?: string;
414
+ /** When execution completed */
415
+ completedAt?: string;
416
+ }
417
+ /**
418
+ * Overall plan status values.
419
+ */
420
+ type PlanStatusValue = 'pending_approval' | 'approved' | 'auto_approved' | 'rejected' | 'expired' | 'executing' | 'completed' | 'partial_failure' | 'failed';
421
+ /**
422
+ * Full plan status including step details.
423
+ */
424
+ interface PlanStatus {
425
+ /** Unique plan ID */
426
+ planId: string;
427
+ /** Plan title */
428
+ title: string;
429
+ /** Plan description */
430
+ description?: string;
431
+ /** Overall plan status */
432
+ status: PlanStatusValue;
433
+ /** Per-step status */
434
+ steps: PlanStepStatus[];
435
+ /** Total estimated cost in USD */
436
+ totalEstimatedCostUsd: number;
437
+ /** Approval info (if responded) */
438
+ approval?: {
439
+ status: string;
440
+ respondedAt?: string;
441
+ responseNote?: string;
442
+ };
443
+ /** When the plan was created */
444
+ createdAt: string;
445
+ /** When the plan expires */
446
+ expiresAt?: string;
447
+ }
448
+ /**
449
+ * Summary item for plan listing.
450
+ */
451
+ interface PlanListItem {
452
+ /** Unique plan ID */
453
+ planId: string;
454
+ /** Plan title */
455
+ title: string;
456
+ /** Overall status */
457
+ status: string;
458
+ /** Total estimated cost in USD */
459
+ totalEstimatedCostUsd: number;
460
+ /** Number of completed steps */
461
+ stepsCompleted: number;
462
+ /** Total number of steps */
463
+ stepsTotal: number;
464
+ /** When the plan was created */
465
+ createdAt: string;
466
+ }
467
+ /**
468
+ * Response from listing plans.
469
+ */
470
+ interface PlansListResponse {
471
+ /** List of plans */
472
+ plans: PlanListItem[];
473
+ /** Total number of matching plans */
474
+ total: number;
475
+ /** Whether more plans exist */
476
+ hasMore: boolean;
477
+ }
478
+ /**
479
+ * Options for listing plans.
480
+ */
481
+ interface ListPlansOptions {
482
+ /** Maximum number of plans to return */
483
+ limit?: number;
484
+ /** Offset for pagination */
485
+ offset?: number;
486
+ /** Filter by status */
487
+ status?: string;
488
+ }
489
+ /**
490
+ * Options for waiting on plan completion.
491
+ */
492
+ interface WaitForPlanOptions {
493
+ /** Poll interval in milliseconds (default: 15000) */
494
+ pollIntervalMs?: number;
495
+ /** Timeout in milliseconds (default: 1800000 = 30 min) */
496
+ timeoutMs?: number;
215
497
  }
216
498
 
217
499
  /** Current SDK version */
218
- declare const SDK_VERSION = "0.9.4";
500
+ declare const SDK_VERSION = "0.11.0";
219
501
  /** Supported networks */
220
502
  declare const NETWORKS: {
221
503
  readonly BASE_MAINNET: {
@@ -1269,9 +1551,13 @@ declare class AgentWallet {
1269
1551
  */
1270
1552
  getSpendingStats(): Promise<SpendingStats>;
1271
1553
  /**
1272
- * Get list of payments made in this session.
1554
+ * Get list of payments made in this session (in-memory only).
1273
1555
  *
1274
- * @returns Array of payment events
1556
+ * @deprecated Use {@link getTransactions} instead for persistent transaction history.
1557
+ * This method only returns payments from the current process and is lost on restart.
1558
+ * `getTransactions()` returns server-persisted transaction history across all sessions.
1559
+ *
1560
+ * @returns Array of payment events from the current session
1275
1561
  */
1276
1562
  getPaymentHistory(): PaymentEvent[];
1277
1563
  /**
@@ -1452,12 +1738,39 @@ declare class AgentWallet {
1452
1738
  */
1453
1739
  mcp(): McpServerConfig;
1454
1740
  /**
1455
- * Get the API key if set (internal use only).
1741
+ * Get tool definitions for use with the Anthropic SDK or other LLM frameworks.
1742
+ *
1743
+ * This provides an in-process alternative to the MCP server. While `mcp()` spawns
1744
+ * a subprocess for Claude Agent SDK integration, `tools()` returns function-callable
1745
+ * tools for direct use with `anthropic.messages.create({ tools: [...] })`.
1746
+ *
1747
+ * @returns Toolkit with Anthropic-compatible definitions and execute dispatcher
1456
1748
  *
1457
- // ===========================================================================
1458
- // Diagnostics
1459
- // ===========================================================================
1460
-
1749
+ * @example
1750
+ * ```typescript
1751
+ * import Anthropic from '@anthropic-ai/sdk';
1752
+ * import { AgentWallet } from '@mixrpay/agent-sdk';
1753
+ *
1754
+ * const wallet = AgentWallet.fromApiKey('agt_live_xxx');
1755
+ * const { definitions, execute } = wallet.tools();
1756
+ *
1757
+ * const response = await anthropic.messages.create({
1758
+ * model: 'claude-sonnet-4-5-20250514',
1759
+ * max_tokens: 1024,
1760
+ * tools: definitions,
1761
+ * messages: [{ role: 'user', content: 'Check my USDC balance' }],
1762
+ * });
1763
+ *
1764
+ * for (const block of response.content) {
1765
+ * if (block.type === 'tool_use') {
1766
+ * const result = await execute(block.name, block.input as Record<string, unknown>);
1767
+ * // Feed result back to Claude as tool_result
1768
+ * console.log(`Tool ${block.name} returned:`, result);
1769
+ * }
1770
+ * }
1771
+ * ```
1772
+ */
1773
+ tools(): AnthropicToolkit;
1461
1774
  /**
1462
1775
  * Run diagnostics to verify the wallet is properly configured.
1463
1776
  *
@@ -2699,6 +3012,35 @@ declare class AgentWallet {
2699
3012
  * ```
2700
3013
  */
2701
3014
  getBalances(): Promise<BalancesResponse>;
3015
+ /**
3016
+ * Get the agent's transaction history with filtering and pagination.
3017
+ *
3018
+ * Returns server-persisted transaction records including swaps, transfers,
3019
+ * bridges, and tool payments. Unlike `getPaymentHistory()`, this data
3020
+ * persists across process restarts and includes all historical transactions.
3021
+ *
3022
+ * @param options - Query options for filtering and pagination
3023
+ * @returns Paginated transaction records
3024
+ * @throws {MixrPayError} If the query fails
3025
+ *
3026
+ * @example
3027
+ * ```typescript
3028
+ * // Get recent transactions
3029
+ * const { transactions, total, hasMore } = await wallet.getTransactions();
3030
+ *
3031
+ * // Filter by type
3032
+ * const swaps = await wallet.getTransactions({ chargeType: 'swap' });
3033
+ *
3034
+ * // Paginate
3035
+ * const page2 = await wallet.getTransactions({ limit: 20, offset: 20 });
3036
+ *
3037
+ * // Get transactions since yesterday
3038
+ * const recent = await wallet.getTransactions({
3039
+ * since: new Date(Date.now() - 24 * 60 * 60 * 1000)
3040
+ * });
3041
+ * ```
3042
+ */
3043
+ getTransactions(options?: GetTransactionsOptions): Promise<TransactionsResponse>;
2702
3044
  /**
2703
3045
  * Transfer USDC to another address.
2704
3046
  *
@@ -2708,6 +3050,7 @@ declare class AgentWallet {
2708
3050
  * @param to - Recipient address
2709
3051
  * @param amount - Amount in USD (e.g., "10.50")
2710
3052
  * @param currency - Currency to transfer (default: "USDC")
3053
+ * @param options - Optional transfer options (idempotencyKey)
2711
3054
  * @returns Transfer result with transaction hash
2712
3055
  * @throws {MixrPayError} If the transfer fails
2713
3056
  *
@@ -2718,8 +3061,16 @@ declare class AgentWallet {
2718
3061
  * console.log(`TX: ${result.tx_hash}`);
2719
3062
  * console.log(`Remaining budget: $${result.remaining_budget_usd}`);
2720
3063
  * ```
3064
+ *
3065
+ * @example With idempotency key
3066
+ * ```typescript
3067
+ * const result = await wallet.transfer('0x1234...', '10.00', 'USDC', {
3068
+ * idempotencyKey: 'payment-123',
3069
+ * });
3070
+ * // If called again with same key, returns cached result
3071
+ * ```
2721
3072
  */
2722
- transfer(to: string, amount: string, currency?: string): Promise<TransferResponse>;
3073
+ transfer(to: string, amount: string, currency?: string, options?: TransferOptions): Promise<TransferResponse>;
2723
3074
  /**
2724
3075
  * Swap tokens using 0x Protocol on Base.
2725
3076
  *
@@ -2729,7 +3080,7 @@ declare class AgentWallet {
2729
3080
  * @param sellToken - Token to sell (symbol or address, e.g., "USDC", "ETH")
2730
3081
  * @param buyToken - Token to buy (symbol or address, e.g., "WETH", "USDC")
2731
3082
  * @param sellAmount - Amount to sell in human-readable format (e.g., "100" for 100 USDC)
2732
- * @param slippageBps - Slippage tolerance in basis points (default: 100 = 1%)
3083
+ * @param options - Optional swap options (slippageBps, idempotencyKey)
2733
3084
  * @returns Swap result with transaction hash and amounts
2734
3085
  * @throws {MixrPayError} If the swap fails
2735
3086
  *
@@ -2741,8 +3092,16 @@ declare class AgentWallet {
2741
3092
  * console.log(`Received ${result.buy_amount} ${result.buy_token}`);
2742
3093
  * console.log(`Price: ${result.price}`);
2743
3094
  * ```
3095
+ *
3096
+ * @example With options
3097
+ * ```typescript
3098
+ * const result = await wallet.swap('USDC', 'ETH', '100', {
3099
+ * slippageBps: 50,
3100
+ * idempotencyKey: 'swap-abc123',
3101
+ * });
3102
+ * ```
2744
3103
  */
2745
- swap(sellToken: string, buyToken: string, sellAmount: string, slippageBps?: number): Promise<SwapResponse>;
3104
+ swap(sellToken: string, buyToken: string, sellAmount: string, options?: SwapOptions | number): Promise<SwapResponse>;
2746
3105
  /**
2747
3106
  * Bridge tokens to another chain using deBridge.
2748
3107
  *
@@ -2753,7 +3112,7 @@ declare class AgentWallet {
2753
3112
  * @param token - Token to bridge (symbol, e.g., "USDC")
2754
3113
  * @param amount - Amount in human-readable format (e.g., "100")
2755
3114
  * @param destChain - Destination chain ID or name (e.g., "1" for Ethereum, "arbitrum")
2756
- * @param destAddress - Destination address (defaults to same address)
3115
+ * @param options - Optional bridge options (destAddress, idempotencyKey)
2757
3116
  * @returns Bridge result with order ID for tracking
2758
3117
  * @throws {MixrPayError} If the bridge fails
2759
3118
  *
@@ -2770,8 +3129,16 @@ declare class AgentWallet {
2770
3129
  * console.log(`Completed! Dest TX: ${status.dest_tx_hash}`);
2771
3130
  * }
2772
3131
  * ```
3132
+ *
3133
+ * @example With options
3134
+ * ```typescript
3135
+ * const result = await wallet.bridge('USDC', '100', 'arbitrum', {
3136
+ * destAddress: '0xabc...',
3137
+ * idempotencyKey: 'bridge-xyz789',
3138
+ * });
3139
+ * ```
2773
3140
  */
2774
- bridge(token: string, amount: string, destChain: string, destAddress?: string): Promise<BridgeResponse>;
3141
+ bridge(token: string, amount: string, destChain: string, options?: BridgeOptions | string): Promise<BridgeResponse>;
2775
3142
  /**
2776
3143
  * Check the status of a bridge order.
2777
3144
  *
@@ -2807,7 +3174,7 @@ declare class AgentWallet {
2807
3174
  * fetch() that uses session key auth for x402, see the standard fetch() method.
2808
3175
  *
2809
3176
  * @param url - URL to fetch
2810
- * @param options - Fetch options (method, headers, body, maxPaymentUsd)
3177
+ * @param options - Fetch options (method, headers, body, maxPaymentUsd, idempotencyKey)
2811
3178
  * @returns Response with status, headers, body, and optional payment info
2812
3179
  * @throws {MixrPayError} If the fetch fails
2813
3180
  *
@@ -2827,8 +3194,126 @@ declare class AgentWallet {
2827
3194
  * console.log(`Paid $${result.payment.amount_usd}`);
2828
3195
  * }
2829
3196
  * ```
3197
+ *
3198
+ * @example With idempotency key
3199
+ * ```typescript
3200
+ * const result = await wallet.fetchPaid('https://api.example.com/data', {
3201
+ * idempotencyKey: 'request-123',
3202
+ * });
3203
+ * // If called again with same key, returns cached result
3204
+ * ```
2830
3205
  */
2831
3206
  fetchPaid(url: string, options?: FetchPaidOptions): Promise<FetchPaidResponse>;
3207
+ /**
3208
+ * Submit a multi-step plan for approval or auto-approval.
3209
+ *
3210
+ * Plans allow agents to propose complex workflows (swap, bridge, transfer, etc.)
3211
+ * that can be reviewed by humans before execution.
3212
+ *
3213
+ * @param plan - Plan submission details
3214
+ * @returns Plan submission result with ID and status
3215
+ * @throws {MixrPayError} If submission fails
3216
+ *
3217
+ * @example
3218
+ * ```typescript
3219
+ * const result = await wallet.submitPlan({
3220
+ * title: 'Swap and Bridge to Arbitrum',
3221
+ * steps: [
3222
+ * { action: 'swap', params: { sellToken: 'USDC', buyToken: 'ETH', sellAmount: '100' }, description: 'Swap USDC for ETH' },
3223
+ * { action: 'bridge', params: { token: 'ETH', amount: '0.03', destChain: 'arbitrum' }, description: 'Bridge ETH to Arbitrum' },
3224
+ * ],
3225
+ * totalEstimatedCostUsd: 105,
3226
+ * });
3227
+ *
3228
+ * if (result.status === 'pending_approval') {
3229
+ * console.log(`Waiting for approval: ${result.approvalUrl}`);
3230
+ * } else {
3231
+ * await wallet.executePlan(result.planId);
3232
+ * }
3233
+ * ```
3234
+ */
3235
+ submitPlan(plan: PlanSubmission): Promise<PlanSubmitResult>;
3236
+ /**
3237
+ * Get the current status of a plan.
3238
+ *
3239
+ * @param planId - Plan ID
3240
+ * @returns Full plan status including step details
3241
+ * @throws {MixrPayError} If status check fails
3242
+ */
3243
+ getPlanStatus(planId: string): Promise<PlanStatus>;
3244
+ /**
3245
+ * List plans for this agent.
3246
+ *
3247
+ * @param options - Query options
3248
+ * @returns List of plans with summary info
3249
+ * @throws {MixrPayError} If listing fails
3250
+ */
3251
+ listPlans(options?: ListPlansOptions): Promise<PlansListResponse>;
3252
+ /**
3253
+ * Report progress on a plan step (internal use by executePlan).
3254
+ *
3255
+ * @param planId - Plan ID
3256
+ * @param stepIndex - Step index
3257
+ * @param status - New status
3258
+ * @param details - Optional details (txHash, chargeId, error)
3259
+ */
3260
+ private reportPlanProgress;
3261
+ /**
3262
+ * Wait for a bridge order to complete.
3263
+ *
3264
+ * Polls the bridge status endpoint until the bridge is fulfilled or fails.
3265
+ *
3266
+ * @param orderId - Bridge order ID
3267
+ * @param options - Polling options
3268
+ * @throws {MixrPayError} If bridge fails or times out
3269
+ */
3270
+ waitForBridgeCompletion(orderId: string, options?: WaitForPlanOptions): Promise<void>;
3271
+ /**
3272
+ * Wait for a plan to complete execution.
3273
+ *
3274
+ * Polls the plan status until it reaches a terminal state.
3275
+ *
3276
+ * @param planId - Plan ID
3277
+ * @param options - Polling options
3278
+ * @returns Final plan status
3279
+ */
3280
+ waitForPlanCompletion(planId: string, options?: WaitForPlanOptions): Promise<PlanStatus>;
3281
+ /**
3282
+ * Execute an approved plan.
3283
+ *
3284
+ * Orchestrates step-by-step execution of an approved plan, handling:
3285
+ * - Sequential execution of steps
3286
+ * - Idempotency (safe to retry on restart)
3287
+ * - Bridge wait times
3288
+ * - Partial failure tracking
3289
+ *
3290
+ * This method runs in the agent's container (not serverless), so it can
3291
+ * wait for long-running operations like bridge confirmations.
3292
+ *
3293
+ * @param planId - Plan ID to execute
3294
+ * @returns Final plan status
3295
+ * @throws {MixrPayError} If plan is not executable
3296
+ *
3297
+ * @example
3298
+ * ```typescript
3299
+ * // Submit and execute a plan
3300
+ * const { planId, status } = await wallet.submitPlan({
3301
+ * title: 'DeFi workflow',
3302
+ * steps: [...],
3303
+ * totalEstimatedCostUsd: 50,
3304
+ * });
3305
+ *
3306
+ * if (status === 'pending_approval') {
3307
+ * // Wait for human approval
3308
+ * await wallet.waitForPlanCompletion(planId);
3309
+ * }
3310
+ *
3311
+ * // Execute once approved
3312
+ * const result = await wallet.executePlan(planId);
3313
+ * console.log(`Plan ${result.status}: ${result.steps.filter(s => s.status === 'completed').length} steps completed`);
3314
+ * ```
3315
+ */
3316
+ executePlan(planId: string): Promise<PlanStatus>;
2832
3317
  /**
2833
3318
  * Call the API with agent token auth (agt_live_xxx bearer token).
2834
3319
  * Used by DeFi methods that require delegation auth.
@@ -4516,4 +5001,4 @@ declare function getWalletStoragePath(): string;
4516
5001
  */
4517
5002
  declare function deleteWalletKey(): Promise<boolean>;
4518
5003
 
4519
- 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 };
5004
+ 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 BridgeOptions, 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 ListPlansOptions, type MCPTool, type MCPToolResult, type McpServerConfig, MerchantNotAllowedError, MixrPayError, NetworkError, type PaymentEvent, PaymentFailedError, type PlanListItem, type PlanStatus, type PlanStatusValue, type PlanStep, type PlanStepAction, type PlanStepStatus, type PlanStepStatusValue, type PlanSubmission, type PlanSubmitResult, type PlansListResponse, 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 SwapOptions, type SwapResponse, type TokenBalance, type Tool, type ToolResult, type TransactionRecord, type TransactionsResponse, type TransferOptions, type TransferResponse, type UseSkillOptions, type UseSkillResult, type WaitForPlanOptions, X402ProtocolError, deleteCredentials, deleteWalletKey, getCredentialsFilePath, getErrorMessage, getWalletStoragePath, hasCredentials, hasWalletKey, isMixrPayError, loadCredentials, loadWalletData, loadWalletKey, saveCredentials, saveWalletKey };