@elizaos/plugin-wallet 2.0.0-beta.1 → 2.0.3-beta.5

package/dist/sdk/x402/budget.d.ts

@@ -0,0 +1,51 @@
+import type { X402ClientConfig, X402ServiceBudget, X402TransactionLog } from "./types.js";
+/**
+ * [MAX-ADDED] In-memory budget tracker for x402 payments.
+ * Enforces per-service caps, daily limits, and per-request maximums.
+ * On-chain spend limits are ALSO enforced by the AgentWallet contract —
+ * this is an additional client-side layer for granular service-level control.
+ */
+export declare class X402BudgetTracker {
+    private serviceBudgets;
+    private dailySpend;
+    private globalDailySpend;
+    private dailyResetTimestamp;
+    private transactionLog;
+    private globalDailyLimit;
+    private globalPerRequestMax;
+    constructor(config?: X402ClientConfig);
+    /**
+     * Check if a payment is within budget limits.
+     * Returns { allowed: true } or { allowed: false, reason: string }.
+     */
+    checkBudget(service: string, amount: bigint): {
+        allowed: boolean;
+        reason?: string;
+    };
+    /**
+     * Record a completed payment.
+     */
+    recordPayment(log: X402TransactionLog): void;
+    /**
+     * Get transaction history, optionally filtered.
+     */
+    getTransactionLog(filter?: {
+        service?: string;
+        since?: number;
+    }): X402TransactionLog[];
+    /**
+     * Get current daily spend summary.
+     */
+    getDailySpendSummary(): {
+        global: bigint;
+        byService: Record<string, bigint>;
+        resetsAt: number;
+    };
+    /**
+     * Add or update a service budget at runtime.
+     */
+    setServiceBudget(budget: X402ServiceBudget): void;
+    private findServiceBudget;
+    private maybeResetDaily;
+    private startOfDay;
+}

package/dist/sdk/x402/chains/abstract/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Abstract x402 Delegated Payment Facilitator Adapter
+ *
+ * Abstract's x402 implementation uses a delegated facilitator pattern:
+ * 1. The agent wallet does NOT sign the payment tx directly
+ * 2. A "payment facilitator" contract is designated per-merchant
+ * 3. The agent's wallet delegates authorization via a signed EIP-712 permit
+ * 4. The facilitator executes the actual chain transaction
+ *
+ * Chain IDs:
+ *   - Abstract Mainnet: 2741
+ *   - Abstract Testnet: 11124
+ */
+import type { Address, Hex, WalletClient } from "viem";
+export declare const ABSTRACT_CHAIN_IDS: {
+    readonly mainnet: 2741;
+    readonly testnet: 11124;
+};
+/** USDC on Abstract Mainnet (official Bridged USDC) */
+export declare const ABSTRACT_USDC: Record<number, Address>;
+/** Abstract's approved payment facilitator contracts */
+export declare const ABSTRACT_APPROVED_FACILITATORS: Address[];
+export interface AbstractDelegatedPaymentConfig {
+    /** The facilitator contract address (must be on approved list or user-allowlisted) */
+    facilitatorAddress: Address;
+    /** Token to pay with (default: USDC on Abstract) */
+    token?: Address;
+    /** Permit deadline in seconds from now (default: 300 = 5 min) */
+    deadlineSeconds?: number;
+    /** User-allowlisted facilitator addresses (extends the approved list) */
+    userAllowlist?: Address[];
+}
+export interface DelegatedPaymentPermit {
+    facilitator: Address;
+    token: Address;
+    amount: bigint;
+    payTo: Address;
+    nonce: bigint;
+    deadline: bigint;
+    resource: string;
+}
+export interface AbstractPaymentResult {
+    /** EIP-712 signature for the facilitator permit */
+    permitSignature: Hex;
+    /** Encoded permit data to submit to the facilitator contract */
+    permitData: Hex;
+    /** The permit fields for verification */
+    permit: DelegatedPaymentPermit;
+    /** Chain ID this payment is valid on */
+    chainId: number;
+}
+/**
+ * Adapter for Abstract's delegated payment facilitator x402 model.
+ *
+ * Instead of signing a direct payment transaction, the agent signs an EIP-712
+ * permit authorizing a facilitator contract to execute the payment on its behalf.
+ * This is Abstract's model — the agent's keys never touch the chain directly.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new AbstractDelegatedFacilitatorAdapter(walletClient, {
+ *   facilitatorAddress: '0x5FbDB2315678afecb367f032d93F642f64180aa3',
+ * });
+ *
+ * const result = await adapter.signPaymentPermit({
+ *   amount: 1_000_000n, // 1 USDC (6 decimals)
+ *   payTo: '0xmerchant...',
+ *   nonce: 0n,
+ *   resource: 'https://api.example.com/resource',
+ * });
+ * ```
+ */
+export declare class AbstractDelegatedFacilitatorAdapter {
+    private walletClient;
+    private config;
+    private chainId;
+    constructor(walletClient: WalletClient, config: AbstractDelegatedPaymentConfig, chainId?: number);
+    /**
+     * Sign an EIP-712 delegated payment permit for the Abstract facilitator.
+     * This replaces direct tx signing — the permit is submitted to the facilitator contract.
+     */
+    signPaymentPermit(params: {
+        amount: bigint;
+        payTo: Address;
+        nonce: bigint;
+        resource: string;
+    }): Promise<AbstractPaymentResult>;
+    /**
+     * Build the x402 payment payload for Abstract's delegated facilitator model.
+     * This payload replaces the standard txHash payload in the X-PAYMENT header.
+     */
+    buildX402Payload(params: {
+        amount: bigint;
+        payTo: Address;
+        nonce: bigint;
+        resource: string;
+    }): Promise<Record<string, unknown>>;
+    /** Check if a chain ID is an Abstract chain */
+    static isAbstractChain(chainId: number): boolean;
+    /** Get the network string for x402 payment requirements (e.g. "abstract:2741") */
+    static getNetworkString(chainId: number): string;
+}
+/**
+ * Abstract chain IDs to add to SUPPORTED_CHAINS in the main SDK.
+ * These route through AbstractDelegatedFacilitatorAdapter for x402 payments.
+ */
+export declare const ABSTRACT_SUPPORTED_CHAINS: {
+    readonly "abstract:2741": {
+        readonly chainId: 2741;
+        readonly name: "Abstract Mainnet";
+        readonly rpcUrl: "https://api.mainnet.abs.xyz";
+        readonly nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        readonly blockExplorer: "https://explorer.mainnet.abs.xyz";
+        readonly x402Model: "delegated-facilitator";
+        readonly usdc: `0x${string}`;
+    };
+    readonly "abstract-testnet:11124": {
+        readonly chainId: 11124;
+        readonly name: "Abstract Testnet";
+        readonly rpcUrl: "https://api.testnet.abs.xyz";
+        readonly nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        readonly blockExplorer: "https://explorer.testnet.abs.xyz";
+        readonly x402Model: "delegated-facilitator";
+        readonly usdc: `0x${string}`;
+    };
+};

package/dist/sdk/x402/client.d.ts

@@ -0,0 +1,66 @@
+import { type AgentWallet } from "../wallet-core.js";
+import { X402BudgetTracker } from "./budget.js";
+import type { X402ClientConfig, X402PaymentRequired, X402PaymentRequirements, X402TransactionLog } from "./types.js";
+/**
+ * [MAX-ADDED] x402 Payment Client for AgentWallet.
+ *
+ * Handles the full x402 payment flow:
+ * 1. Detects 402 Payment Required responses
+ * 2. Parses payment instructions from PAYMENT-REQUIRED header
+ * 3. Validates against budget controls
+ * 4. Executes USDC payment via AgentWallet contract
+ * 5. Retries original request with payment proof
+ */
+export declare class X402Client {
+    private wallet;
+    private config;
+    private budget;
+    private supportedNetworks;
+    constructor(wallet: AgentWallet, config?: X402ClientConfig);
+    /**
+     * Make an x402-aware fetch request. Automatically handles 402 responses.
+     */
+    fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Parse a 402 response to extract payment requirements.
+     */
+    parse402Response(response: Response): Promise<X402PaymentRequired | null>;
+    /**
+     * Select the best compatible payment option from offered requirements.
+     * Prefers: Base network, stablecoins, exact scheme.
+     *
+     * v6 change: resolves assets via TokenRegistry in addition to USDC_ADDRESSES.
+     * Now accepts any ERC-20 whose address is in the TokenRegistry for the network.
+     */
+    selectPaymentOption(accepts: X402PaymentRequirements[]): X402PaymentRequirements | null;
+    /**
+     * Execute the payment via AgentWallet's agentTransferToken.
+     *
+     * v6 change: resolves asset address via TokenRegistry before executing.
+     * The 402 response may specify an asset by symbol ("USDC") or by address.
+     */
+    private executePayment;
+    /** Get the budget tracker for direct inspection */
+    get budgetTracker(): X402BudgetTracker;
+    /** Get transaction log */
+    getTransactionLog(filter?: {
+        service?: string;
+        since?: number;
+    }): X402TransactionLog[];
+    /** Get daily spend summary */
+    getDailySpendSummary(): {
+        global: bigint;
+        byService: Record<string, bigint>;
+        resetsAt: number;
+    };
+}
+export declare class X402PaymentError extends Error {
+    readonly paymentRequirements: X402PaymentRequirements;
+    constructor(message: string, paymentRequirements: X402PaymentRequirements);
+}
+export declare class X402BudgetExceededError extends Error {
+    readonly reason: string;
+    readonly url: string;
+    readonly paymentRequirements: X402PaymentRequirements;
+    constructor(reason: string, url: string, paymentRequirements: X402PaymentRequirements);
+}

package/dist/sdk/x402/index.d.ts

@@ -0,0 +1,8 @@
+export { X402BudgetTracker } from "./budget.js";
+export type { AbstractDelegatedPaymentConfig, AbstractPaymentResult, DelegatedPaymentPermit, } from "./chains/abstract/index.js";
+export { ABSTRACT_APPROVED_FACILITATORS, ABSTRACT_CHAIN_IDS, ABSTRACT_SUPPORTED_CHAINS, ABSTRACT_USDC, AbstractDelegatedFacilitatorAdapter, } from "./chains/abstract/index.js";
+export { X402BudgetExceededError, X402Client, X402PaymentError, } from "./client.js";
+export { createX402Client, createX402Fetch, wrapWithX402, } from "./middleware.js";
+export { buildSupportedAssets, isStablecoin, parseNetworkChainId, resolveAssetAddress, resolveAssetDecimals, } from "./multi-asset.js";
+export type { X402ClientConfig, X402PaymentPayload, X402PaymentRequired, X402PaymentRequirements, X402ResourceInfo, X402ServiceBudget, X402SettlementResponse, X402TransactionLog, } from "./types.js";
+export { DEFAULT_SUPPORTED_NETWORKS, USDC_ADDRESSES } from "./types.js";

package/dist/sdk/x402/middleware.d.ts

@@ -0,0 +1,37 @@
+import type { AgentWallet } from "../wallet-core.js";
+import { X402Client } from "./client.js";
+import type { X402ClientConfig } from "./types.js";
+/**
+ * [MAX-ADDED] Create an x402-aware HTTP client.
+ *
+ * Usage:
+ *   const client = createX402Client(wallet, { globalDailyLimit: 10_000_000n });
+ *   const response = await client.fetch('https://api.example.com/data');
+ *   // If the endpoint returns 402, payment is handled automatically
+ *
+ * @param wallet - AgentWallet instance from createWallet()
+ * @param config - Optional x402 client configuration
+ * @returns X402Client with .fetch() method and budget controls
+ */
+export declare function createX402Client(wallet: AgentWallet, config?: X402ClientConfig): X402Client;
+/**
+ * [MAX-ADDED] Create an x402-aware fetch function (drop-in replacement).
+ *
+ * Usage:
+ *   const x402Fetch = createX402Fetch(wallet);
+ *   const response = await x402Fetch('https://api.example.com/data');
+ *
+ * @param wallet - AgentWallet instance from createWallet()
+ * @param config - Optional x402 client configuration
+ * @returns A fetch-compatible function that handles 402 payments
+ */
+export declare function createX402Fetch(wallet: AgentWallet, config?: X402ClientConfig): typeof globalThis.fetch;
+/**
+ * [MAX-ADDED] Wrap an existing fetch-like function to be x402-aware.
+ * Useful for wrapping custom HTTP clients or test mocks.
+ *
+ * @param fetchFn - The original fetch function to wrap
+ * @param wallet - AgentWallet instance
+ * @param config - Optional x402 client configuration
+ */
+export declare function wrapWithX402(fetchFn: typeof globalThis.fetch, wallet: AgentWallet, config?: X402ClientConfig): typeof globalThis.fetch;

package/dist/sdk/x402/multi-asset.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module x402/multi-asset
+ * Multi-asset support utilities for the x402 payment client.
+ *
+ * Resolves asset names/symbols → token addresses via the global TokenRegistry.
+ * This extends x402 beyond USDC-only to support any token the 402 response requests.
+ *
+ * All address lookups use the TokenRegistry from src/tokens/registry.ts.
+ * Fallback: USDC_ADDRESSES from x402/types.ts.
+ */
+import type { Address } from "viem";
+/**
+ * Network string format used in x402: "chainName:chainId" (e.g. "base:8453").
+ * Returns the chainId portion as a number.
+ */
+export declare function parseNetworkChainId(network: string): number | null;
+/**
+ * Resolve an asset address in the context of a 402 response.
+ * The asset field may be:
+ *   1. A token symbol ("USDC", "WETH", etc.) → look up in registry by symbol
+ *   2. A hex contract address → look up in registry by address (must be registered)
+ *
+ * Only returns an address if the asset is known in the TokenRegistry.
+ * Unknown addresses are NOT accepted — they must be explicitly added or
+ * whitelisted via supportedAssets config.
+ *
+ * @param asset - Asset identifier from the 402 response
+ * @param network - Network string from the 402 response (e.g. "base:8453")
+ * @returns Resolved contract address, or null if not found in registry
+ */
+export declare function resolveAssetAddress(asset: string, network: string): Address | null;
+/**
+ * Get token decimals for a given asset+network pair.
+ * Used to correctly format amounts in x402 payments.
+ *
+ * @param asset - Asset address (hex) or symbol
+ * @param network - Network string (e.g. "base:8453")
+ * @returns Decimals, defaults to 6 for USDC-like stable, 18 for everything else
+ */
+export declare function resolveAssetDecimals(asset: string, network: string): number;
+/**
+ * Build a set of accepted payment assets for an x402 client, using the
+ * global registry to auto-populate known tokens per network.
+ *
+ * @param networks - List of network strings (e.g. ["base:8453", "arbitrum:42161"])
+ * @param symbols - Token symbols to include (e.g. ["USDC", "USDT", "WETH"])
+ * @returns Map from network string → array of token addresses
+ */
+export declare function buildSupportedAssets(networks: string[], symbols?: string[]): Record<string, Address[]>;
+/**
+ * Check if a given asset address is a known stablecoin (6 decimals) on the network.
+ */
+export declare function isStablecoin(asset: string, network: string): boolean;

package/dist/sdk/x402/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @module x402/types
+ * x402 protocol type definitions and well-known asset constants.
+ *
+ * Implements the x402 HTTP payment protocol spec (coinbase/x402) for
+ * multi-chain USDC payments. Covers 10 mainnet chains: Base, Ethereum,
+ * Arbitrum, Polygon, Optimism, Avalanche, Unichain, Linea, Sonic, Worldchain.
+ *
+ * USDC addresses are sourced from Circle's official registry:
+ * https://developers.circle.com/stablecoins/usdc-contract-addresses
+ */
+import type { Address, Hash } from "viem";
+/** Resource information included in x402 responses */
+export interface X402ResourceInfo {
+    url: string;
+    description: string;
+    mimeType: string;
+}
+/** Payment requirements returned in 402 response PAYMENT-REQUIRED header */
+export interface X402PaymentRequirements {
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+/** Full 402 response payload (base64-decoded from PAYMENT-REQUIRED header) */
+export interface X402PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource: X402ResourceInfo;
+    accepts: X402PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+}
+/** Payment payload sent back with PAYMENT-SIGNATURE header */
+export interface X402PaymentPayload {
+    x402Version: number;
+    resource: X402ResourceInfo;
+    accepted: X402PaymentRequirements;
+    payload: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+}
+/** Settlement response returned in PAYMENT-RESPONSE header */
+export interface X402SettlementResponse {
+    success: boolean;
+    txHash?: string;
+    network?: string;
+    error?: string;
+}
+/** Per-service spending cap configuration */
+export interface X402ServiceBudget {
+    /** Domain or URL pattern (e.g. "api.example.com" or "*") */
+    service: string;
+    /** Max spend per single request in token base units */
+    maxPerRequest: bigint;
+    /** Max total spend per day in token base units */
+    dailyLimit: bigint;
+}
+/** Transaction log entry for x402 payments */
+export interface X402TransactionLog {
+    timestamp: number;
+    service: string;
+    url: string;
+    amount: bigint;
+    token: Address;
+    recipient: Address;
+    txHash: Hash;
+    network: string;
+    scheme: string;
+    success: boolean;
+    error?: string;
+}
+/** Configuration for the x402 client */
+export interface X402ClientConfig {
+    /** Service-level budget controls */
+    serviceBudgets?: X402ServiceBudget[];
+    /** Global daily spending limit (token base units, default: unlimited) */
+    globalDailyLimit?: bigint;
+    /** Global per-request max (token base units, default: unlimited) */
+    globalPerRequestMax?: bigint;
+    /** Supported networks (default: ["base:8453"]) */
+    supportedNetworks?: string[];
+    /** Supported assets by network (default: USDC on Base) */
+    supportedAssets?: Record<string, Address[]>;
+    /** Max retries after payment (default: 1) */
+    maxRetries?: number;
+    /** Custom facilitator URL (optional, for verify/settle) */
+    facilitatorUrl?: string;
+    /** Whether to auto-pay 402 responses (default: true) */
+    autoPay?: boolean;
+    /** Callback before payment — return false to reject */
+    onBeforePayment?: (req: X402PaymentRequirements, url: string) => Promise<boolean> | boolean;
+    /** Callback after payment */
+    onPaymentComplete?: (log: X402TransactionLog) => void;
+}
+/**
+ * USDC contract addresses by network (chain-name:chainId format).
+ * Sources:
+ *   - EVM chains: https://developers.circle.com/cctp/references/contract-addresses
+ *   - Linea: https://linea.build/ecosystem/usdc
+ *   - Unichain: https://docs.unichain.org/docs/technical-information/token-addresses
+ *   - Sonic: https://docs.soniclabs.com/build/useful-addresses
+ *   - Worldchain: https://docs.worldcoin.org/world-chain/addresses/usdc
+ */
+export declare const USDC_ADDRESSES: Record<string, Address>;
+/** Default supported networks (all mainnet chains) */
+export declare const DEFAULT_SUPPORTED_NETWORKS: readonly ["base:8453", "ethereum:1", "arbitrum:42161", "polygon:137", "bsc:56", "optimism:10", "avalanche:43114", "unichain:130", "linea:59144", "sonic:146", "worldchain:480"];

package/dist/security/wallet-context-safety.d.ts

@@ -0,0 +1,7 @@
+import type { Memory } from "@elizaos/core";
+export declare const EVM_ADDRESS_PATTERN: RegExp;
+export declare function sanitizeWalletDisplayLabel(label: string): string;
+export declare function readMemoryText(message: Memory): string;
+export declare function messageAuthorizesEvmRecipient(message: Memory, options: Record<string, unknown> | undefined, recipient: string): boolean;
+export declare function assertWalletFinancialActionAllowed(message: Memory, subaction: string | undefined): void;
+export declare function assertEvmTransferRecipientAuthorized(message: Memory, options: Record<string, unknown> | undefined, recipient: string): void;

package/dist/security/wallet-financial-confirmation.d.ts

@@ -0,0 +1,23 @@
+import type { ActionResult, ConfirmationDecision, HandlerCallback, IAgentRuntime, Memory } from "@elizaos/core";
+import type { WalletRouterParams } from "../types/wallet-router.js";
+/** Cache namespace for on-chain wallet writes (GHSA-rqm7-f4jc-84x3). */
+export declare const WALLET_FINANCIAL_CONFIRM_ACTION = "WALLET_FINANCIAL";
+export declare function requiresWalletFinancialConfirmation(params: Pick<WalletRouterParams, "subaction" | "dryRun">): boolean;
+export declare function walletFinancialPendingKey(params: Pick<WalletRouterParams, "subaction" | "chain" | "toChain" | "amount" | "recipient" | "fromToken" | "toToken" | "slippageBps" | "op" | "governor" | "proposalId">): string;
+export declare function walletFinancialPreview(params: Pick<WalletRouterParams, "subaction" | "chain" | "toChain" | "amount" | "recipient" | "fromToken" | "toToken" | "op">): string;
+export type WalletFinancialGateResult = {
+    readonly proceed: true;
+} | {
+    readonly proceed: false;
+    readonly decision: ConfirmationDecision;
+    readonly text: string;
+};
+export declare function gateWalletFinancialExecution(args: {
+    runtime: IAgentRuntime;
+    message: Memory;
+    params: WalletRouterParams;
+    callback?: HandlerCallback;
+}): Promise<WalletFinancialGateResult>;
+export declare function walletFinancialGateActionResult(gate: Extract<WalletFinancialGateResult, {
+    proceed: false;
+}>): ActionResult;

package/dist/services/wallet-backend-service.d.ts

@@ -0,0 +1,39 @@
+import { type IAgentRuntime, Service } from "@elizaos/core";
+import type { WalletChainHandler, WalletChainHandlerMetadata, WalletRouterFailure, WalletRouterParams, WalletRouterResult, WalletRouterSubaction } from "../types/wallet-router.js";
+import type { WalletBackend } from "../wallet/backend.js";
+import "../core-augmentation.js";
+export declare const WALLET_BACKEND_SERVICE_TYPE: "wallet-backend";
+/**
+ * Runtime service exposing {@link WalletBackend}. Retrieve via
+ * `runtime.getService("wallet-backend")`.
+ */
+export declare class WalletBackendService extends Service {
+    static serviceType: "wallet-backend";
+    capabilityDescription: string;
+    private backend;
+    private backendLoadError;
+    private readonly handlers;
+    private readonly aliases;
+    static start(runtime: IAgentRuntime): Promise<WalletBackendService>;
+    getWalletBackend(): WalletBackend;
+    getWalletBackendOrNull(): WalletBackend | null;
+    registerChainHandler(handler: WalletChainHandler): void;
+    listChainHandlers(): WalletChainHandlerMetadata[];
+    listChainHandlersForSubaction(subaction: WalletRouterSubaction): WalletChainHandlerMetadata[];
+    getCapabilities(): {
+        readonly chains: readonly WalletChainHandlerMetadata[];
+    };
+    /**
+     * Resolve chain + required fields without signing. Used before out-of-band
+     * financial confirmation so invalid params fail fast (GHSA-rqm7-f4jc-84x3).
+     */
+    preflightWalletAction(params: WalletRouterParams): WalletRouterFailure | null;
+    routeWalletAction(params: WalletRouterParams): Promise<WalletRouterResult>;
+    stop(): Promise<void>;
+    private resolveHandler;
+    private validateRequiredParams;
+    private createContext;
+    private getWalletServices;
+    private getTokenDataService;
+    private toMetadata;
+}

package/dist/types/wallet-router.d.ts

@@ -0,0 +1,130 @@
+import type { IAgentRuntime, ITokenDataService, IWalletService } from "@elizaos/core";
+import { z } from "zod";
+import type { WalletBackend } from "../wallet/backend.js";
+export declare const WALLET_ROUTER_SUBACTIONS: readonly ["transfer", "swap", "bridge", "gov"];
+export type WalletRouterSubaction = (typeof WALLET_ROUTER_SUBACTIONS)[number];
+export declare const WALLET_ROUTER_MODES: readonly ["prepare", "execute"];
+export type WalletRouterMode = (typeof WALLET_ROUTER_MODES)[number];
+export declare const WALLET_GOV_OPS: readonly ["propose", "vote", "queue", "execute"];
+export type WalletGovOp = (typeof WALLET_GOV_OPS)[number];
+export interface WalletRouterParams {
+    readonly subaction: WalletRouterSubaction;
+    readonly chain?: string;
+    readonly toChain?: string;
+    readonly fromToken?: string;
+    readonly toToken?: string;
+    readonly amount?: string;
+    readonly recipient?: string;
+    readonly slippageBps?: number;
+    readonly mode: WalletRouterMode;
+    readonly dryRun: boolean;
+    readonly op?: WalletGovOp;
+    readonly governor?: string;
+    readonly proposalId?: string;
+    readonly support?: number;
+    readonly targets?: readonly string[];
+    readonly values?: readonly string[];
+    readonly calldatas?: readonly string[];
+    readonly description?: string;
+}
+export interface WalletTokenMetadata {
+    readonly symbol: string;
+    readonly address: string;
+    readonly decimals?: number;
+    readonly native?: boolean;
+}
+export interface WalletSignerMetadata {
+    readonly required: boolean;
+    readonly kind: "evm" | "solana" | "off-chain";
+    readonly source?: string;
+    readonly description?: string;
+}
+export interface WalletDryRunMetadata {
+    readonly supported: boolean;
+    readonly supportedActions: readonly WalletRouterSubaction[];
+    readonly description?: string;
+}
+export interface WalletChainHandlerMetadata {
+    readonly chainId: string;
+    readonly chain: string;
+    readonly name: string;
+    readonly aliases: readonly string[];
+    readonly supportedActions: readonly WalletRouterSubaction[];
+    readonly tokens: readonly WalletTokenMetadata[];
+    readonly signer: WalletSignerMetadata;
+    readonly dryRun: WalletDryRunMetadata;
+}
+export interface WalletRouterContext {
+    readonly runtime: IAgentRuntime;
+    readonly walletBackend: WalletBackend | null;
+    readonly walletServices: readonly IWalletService[];
+    readonly tokenDataService: ITokenDataService | null;
+}
+export interface WalletRouterExecution {
+    readonly status: "prepared" | "submitted";
+    readonly chain: string;
+    readonly chainId: string;
+    readonly subaction: WalletRouterSubaction;
+    readonly dryRun: boolean;
+    readonly mode: WalletRouterMode;
+    readonly transactionHash?: string;
+    readonly signature?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly amount?: string;
+    readonly fromToken?: string;
+    readonly toToken?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface WalletChainHandler extends WalletChainHandlerMetadata {
+    execute(params: WalletRouterParams, context: WalletRouterContext): Promise<WalletRouterExecution>;
+}
+export type WalletRouterErrorCode = "INVALID_PARAMS" | "UNSUPPORTED_CHAIN" | "UNSUPPORTED_SUBACTION" | "AMBIGUOUS_CHAIN" | "DRY_RUN_UNSUPPORTED" | "EXECUTION_FAILED";
+export interface WalletRouterFailure {
+    readonly ok: false;
+    readonly error: WalletRouterErrorCode;
+    readonly detail: string;
+    readonly candidates?: readonly WalletChainHandlerMetadata[];
+}
+export interface WalletRouterSuccess {
+    readonly ok: true;
+    readonly result: WalletRouterExecution;
+    readonly handler: WalletChainHandlerMetadata;
+}
+export type WalletRouterResult = WalletRouterSuccess | WalletRouterFailure;
+export declare const WalletRouterParamsSchema: z.ZodObject<{
+    subaction: z.ZodEnum<{
+        transfer: "transfer";
+        swap: "swap";
+        bridge: "bridge";
+        gov: "gov";
+    }>;
+    chain: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    toChain: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    fromToken: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    toToken: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    amount: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    recipient: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    slippageBps: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        prepare: "prepare";
+        execute: "execute";
+    }>>;
+    dryRun: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+    op: z.ZodOptional<z.ZodEnum<{
+        execute: "execute";
+        propose: "propose";
+        vote: "vote";
+        queue: "queue";
+    }>>;
+    governor: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    proposalId: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+    support: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    targets: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    values: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    calldatas: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    description: z.ZodPipe<z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | undefined, string | number | null | undefined>>;
+}, z.core.$strip>;
+export declare function parseWalletRouterParams(input: unknown): WalletRouterParams;
+export declare function isWalletRouterSubaction(value: unknown): value is WalletRouterSubaction;
+export declare function normalizeWalletChainKey(value: string | number): string;