feat: support fxUSD and multi-decimal EIP-3009 stablecoins

dist/index.d.ts

@@ -362,18 +362,50 @@ declare class ResponseCache {
     isEnabled(): boolean;
 }
 
+/**
+ * EIP-3009 payment asset on Base network.
+ * Represents a stablecoin that supports `transferWithAuthorization`
+ * for gasless, single-step payment settlements.
+ */
+type BasePaymentAsset = {
+    chain: "base";
+    asset: `0x${string}`;
+    symbol: string;
+    decimals: number;
+    name: string;
+    transferMethod: "eip3009";
+    priority?: number;
+    enabled?: boolean;
+};
+/** Default payment asset: USDC on Base (6 decimals, EIP-3009). */
+declare const DEFAULT_BASE_PAYMENT_ASSET: BasePaymentAsset;
+/**
+ * Validate and normalize a single payment asset from an API response.
+ * Returns undefined if the input is missing required fields or uses a non-EIP-3009 transfer method.
+ * Symbols are uppercased; names are trimmed.
+ */
+declare function normalizeBasePaymentAsset(value: unknown): BasePaymentAsset | undefined;
+/**
+ * Fetch the highest-priority EIP-3009 payment asset from the API.
+ * Convenience wrapper around {@link fetchBasePaymentAssets} that returns only the first asset.
+ */
+declare function fetchBasePaymentAsset(apiBase: string, baseFetch?: typeof fetch): Promise<BasePaymentAsset | undefined>;
+
 /**
  * Balance Monitor for ClawRouter
  *
- * Monitors USDC balance on Base network with intelligent caching.
+ * Monitors stablecoin balance on Base network with intelligent caching.
+ * Supports any EIP-3009 stablecoin (USDC, fxUSD, EURC, etc.) with
+ * automatic normalization from native decimals to USD micros (6 decimals).
  * Provides pre-request balance checks to prevent failed payments.
  *
  * Caching Strategy:
  *   - TTL: 30 seconds (balance is cached to avoid excessive RPC calls)
  *   - Optimistic deduction: after successful payment, subtract estimated cost from cache
  *   - Invalidation: on payment failure, immediately refresh from RPC
  */
-/** Balance thresholds in USDC smallest unit (6 decimals) */
+
+/** Balance thresholds in USD micros (6 decimals, normalized from any stablecoin) */
 declare const BALANCE_THRESHOLDS: {
     /** Low balance warning threshold: $1.00 */
     readonly LOW_BALANCE_MICROS: 1000000n;
@@ -382,10 +414,12 @@ declare const BALANCE_THRESHOLDS: {
 };
 /** Balance information returned by checkBalance() */
 type BalanceInfo = {
-    /** Raw balance in USDC smallest unit (6 decimals) */
+    /** Raw balance normalized to USD micros (6 decimals, regardless of the underlying asset's native decimals) */
     balance: bigint;
     /** Formatted balance as "$X.XX" */
     balanceUSD: string;
+    /** Symbol of the active Base payment asset */
+    assetSymbol: string;
     /** True if balance < $1.00 */
     isLow: boolean;
     /** True if balance < $0.0001 (effectively zero) */
@@ -403,7 +437,7 @@ type SufficiencyResult = {
     shortfall?: string;
 };
 /**
- * Monitors USDC balance on Base network.
+ * Monitors stablecoin balance on Base network.
  *
  * Usage:
  *   const monitor = new BalanceMonitor("0x...");
@@ -413,11 +447,12 @@ type SufficiencyResult = {
 declare class BalanceMonitor {
     private readonly client;
     private readonly walletAddress;
+    private asset;
     /** Cached balance (null = not yet fetched) */
     private cachedBalance;
     /** Timestamp when cache was last updated */
     private cachedAt;
-    constructor(walletAddress: string);
+    constructor(walletAddress: string, asset?: BasePaymentAsset);
     /**
      * Check current USDC balance.
      * Uses cache if valid, otherwise fetches from RPC.
@@ -426,14 +461,14 @@ declare class BalanceMonitor {
     /**
      * Check if balance is sufficient for an estimated cost.
      *
-     * @param estimatedCostMicros - Estimated cost in USDC smallest unit (6 decimals)
+     * @param estimatedCostMicros - Estimated cost in USD micros (6 decimals)
      */
     checkSufficient(estimatedCostMicros: bigint): Promise<SufficiencyResult>;
     /**
      * Optimistically deduct estimated cost from cached balance.
      * Call this after a successful payment to keep cache accurate.
      *
-     * @param amountMicros - Amount to deduct in USDC smallest unit
+     * @param amountMicros - Amount to deduct in USD micros
      */
     deductEstimated(amountMicros: bigint): void;
     /**
@@ -445,18 +480,22 @@ declare class BalanceMonitor {
      * Force refresh balance from RPC (ignores cache).
      */
     refresh(): Promise<BalanceInfo>;
+    setAsset(asset: BasePaymentAsset): void;
+    getAsset(): BasePaymentAsset;
     /**
-     * Format USDC amount (in micros) as "$X.XX".
+     * Format a stablecoin amount (normalized to USD micros) as "$X.XX".
      */
-    formatUSDC(amountMicros: bigint): string;
+    formatUSD(amountMicros: bigint): string;
     /**
      * Get the wallet address being monitored.
      */
     getWalletAddress(): string;
+    getAssetSymbol(): string;
     /** Fetch balance from RPC */
     private fetchBalance;
     /** Build BalanceInfo from raw balance */
     private buildInfo;
+    private toUsdMicros;
 }
 
 /**
@@ -468,6 +507,7 @@ declare class BalanceMonitor {
 type SolanaBalanceInfo = {
     balance: bigint;
     balanceUSD: string;
+    assetSymbol: string;
     isLow: boolean;
     isEmpty: boolean;
     walletAddress: string;
@@ -497,6 +537,7 @@ declare class SolanaBalanceMonitor {
      */
     formatUSDC(amountMicros: bigint): string;
     getWalletAddress(): string;
+    getAssetSymbol(): string;
     /**
      * Check native SOL balance (in lamports). Useful for detecting users who
      * funded with SOL instead of USDC.
@@ -652,12 +693,14 @@ declare function getProxyPort(): number;
 type LowBalanceInfo = {
     balanceUSD: string;
     walletAddress: string;
+    assetSymbol: string;
 };
 /** Callback info for insufficient funds error */
 type InsufficientFundsInfo = {
     balanceUSD: string;
     requiredUSD: string;
     walletAddress: string;
+    assetSymbol: string;
 };
 /**
  * Wallet config: either a plain EVM private key string, or the full
@@ -744,6 +787,8 @@ type ProxyHandle = {
     baseUrl: string;
     walletAddress: string;
     solanaAddress?: string;
+    paymentAsset?: BasePaymentAsset;
+    paymentAssets?: BasePaymentAsset[];
     balanceMonitor: AnyBalanceMonitor;
     close: () => Promise<void>;
 };
@@ -1382,4 +1427,4 @@ declare function buildPartnerTools(proxyBaseUrl: string): PartnerToolDefinition[
 
 declare const plugin: OpenClawPluginDefinition;
 
-export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, type BalanceInfo, BalanceMonitor, type CachedLLMResponse, type CachedResponse, type CheckResult, DEFAULT_RETRY_CONFIG, DEFAULT_ROUTING_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, type DerivedKeys, EmptyWalletError, FileSpendControlStorage, InMemorySpendControlStorage, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, OPENCLAW_MODELS, PARTNER_SERVICES, type PartnerServiceDefinition, type PartnerToolDefinition, type PaymentChain, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, type RoutingConfig, type RoutingDecision, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SolanaBalanceInfo, SolanaBalanceMonitor, SpendControl, type SpendControlOptions, type SpendControlStorage, type SpendLimits, type SpendRecord, type SpendWindow, type SpendingStatus, type SufficiencyResult, type Tier, type UsageEntry, type WalletConfig, type WalletResolution, blockrunProvider, buildPartnerTools, buildProviderModels, calculateModelCost, clearStats, plugin as default, deriveAllKeys, deriveEvmKey, deriveSolanaKeyBytes, fetchWithRetry, formatDuration, formatStatsAscii, generateWalletMnemonic, getAgenticModels, getFallbackChain, getFallbackChainFiltered, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, isAgenticModel, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, isValidMnemonic, loadPaymentChain, logUsage, resolveModelAlias, resolvePaymentChain, route, savePaymentChain, setupSolana, startProxy };
+export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, type BalanceInfo, BalanceMonitor, type BasePaymentAsset, type CachedLLMResponse, type CachedResponse, type CheckResult, DEFAULT_BASE_PAYMENT_ASSET, DEFAULT_RETRY_CONFIG, DEFAULT_ROUTING_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, type DerivedKeys, EmptyWalletError, FileSpendControlStorage, InMemorySpendControlStorage, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, OPENCLAW_MODELS, PARTNER_SERVICES, type PartnerServiceDefinition, type PartnerToolDefinition, type PaymentChain, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, type RoutingConfig, type RoutingDecision, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SolanaBalanceInfo, SolanaBalanceMonitor, SpendControl, type SpendControlOptions, type SpendControlStorage, type SpendLimits, type SpendRecord, type SpendWindow, type SpendingStatus, type SufficiencyResult, type Tier, type UsageEntry, type WalletConfig, type WalletResolution, blockrunProvider, buildPartnerTools, buildProviderModels, calculateModelCost, clearStats, plugin as default, deriveAllKeys, deriveEvmKey, deriveSolanaKeyBytes, fetchBasePaymentAsset, fetchWithRetry, formatDuration, formatStatsAscii, generateWalletMnemonic, getAgenticModels, getFallbackChain, getFallbackChainFiltered, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, isAgenticModel, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, isValidMnemonic, loadPaymentChain, logUsage, normalizeBasePaymentAsset, resolveModelAlias, resolvePaymentChain, route, savePaymentChain, setupSolana, startProxy };