@exagent/agent 0.1.31 → 0.1.33

package/dist/cli.mjs

@@ -6,7 +6,7 @@ import {
   loadConfig,
   loadSecureEnv,
   validateConfig
-} from "./chunk-4NASRDHJ.mjs";
+} from "./chunk-Q23UPFHO.mjs";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Address, Hash, WalletClient } from 'viem';
+import { Address, Hash, PublicClient, WalletClient } from 'viem';
 import { ExagentClient } from '@exagent/sdk';
 
 /** Risk state persisted across restarts */
@@ -1426,30 +1426,101 @@ declare class RiskManager {
     private calculateLiquidationProximity;
 }
 
+/**
+ * TokenResolver — bulletproof token metadata resolution with 3-tier fallback.
+ *
+ * Resolution chain:
+ *   1. Hardcoded map (39 whitelisted tokens — instant)
+ *   2. Multicall3 batch on-chain (decimals + symbol in 1 RPC call)
+ *   3. Blockscout API (free, near-universal coverage for Base tokens)
+ *
+ * If ALL tiers fail, the token is marked "unresolvable" and skipped from
+ * portfolio calculations. This is better than silently defaulting to 18
+ * decimals, which causes 10^9–10^12 errors for tokens with 6/8/9 decimals.
+ *
+ * Resolved metadata is persisted to FileStore and never re-fetched (ERC-20
+ * decimals are immutable by convention).
+ */
+declare class TokenResolver {
+    private client;
+    private store;
+    private cache;
+    private unresolvable;
+    constructor(client: PublicClient, store?: StrategyStore);
+    /**
+     * Get decimals for a token (synchronous).
+     * Returns undefined if the token has never been resolved and is not hardcoded.
+     * Call resolve() first for unknown tokens.
+     */
+    getDecimals(address: string): number | undefined;
+    /**
+     * Get symbol for a token (synchronous).
+     */
+    getSymbol(address: string): string | undefined;
+    /**
+     * Set symbol for a token (used when DexScreener returns symbol data).
+     */
+    setSymbol(address: string, symbol: string): void;
+    /**
+     * Check if a token has been marked as unresolvable by all tiers.
+     */
+    isUnresolvable(address: string): boolean;
+    /**
+     * Batch-resolve metadata for a list of token addresses.
+     *
+     * Skips already-resolved tokens. For unknown tokens:
+     * 1. Multicall3 on-chain batch (decimals + symbol)
+     * 2. Blockscout API for any multicall failures
+     * 3. Mark remaining as unresolvable
+     */
+    resolve(addresses: string[]): Promise<void>;
+    /**
+     * Tier 2: Batch-fetch decimals + symbol via Multicall3.
+     * Returns addresses that failed (for next tier).
+     */
+    private resolveViaMulticall;
+    /**
+     * Tier 3: Fetch token metadata from Blockscout (Base's block explorer API).
+     * Free, no API key, near-universal coverage for any token indexed by the explorer.
+     * Returns addresses that failed (truly unresolvable).
+     */
+    private resolveViaBlockscout;
+    /**
+     * Persist resolved metadata to FileStore.
+     */
+    private persist;
+    /**
+     * Persist unresolvable token list to FileStore.
+     */
+    private persistUnresolvable;
+}
+
 /**
  * Market Data Service
  * Fetches real prices from CoinGecko and on-chain balances for strategy analysis.
  *
- * Queries real on-chain balances for:
- * - Native ETH (via eth_getBalance)
- * - ERC-20 tokens (via balanceOf)
+ * Uses TokenResolver for bulletproof token metadata resolution:
+ *   1. Hardcoded map (39 whitelisted tokens)
+ *   2. Multicall3 batch on-chain (1 RPC call for N tokens)
+ *   3. Blockscout API (free, near-universal coverage)
  *
- * Fetches real prices from CoinGecko free API.
- * Refuses to return data if prices are stale (>60s old) to prevent
- * agents from making decisions with outdated price information.
+ * Uses Multicall3 for batched balance fetching (1 RPC call for N balanceOf).
  */
 declare class MarketDataService {
     private rpcUrl;
     private client;
+    private resolver;
     /** Cached prices from last fetch */
     private cachedPrices;
     /** Timestamp of last successful price fetch */
     private lastPriceFetchAt;
-    constructor(rpcUrl: string);
     /** Cached volume data */
     private cachedVolume24h;
     /** Cached price change data */
     private cachedPriceChange24h;
+    constructor(rpcUrl: string, store?: StrategyStore);
+    /** Get the underlying TokenResolver for direct access */
+    getResolver(): TokenResolver;
     /**
      * Fetch current market data for the agent
      */
@@ -1464,11 +1535,17 @@ declare class MarketDataService {
      */
     private fetchPrices;
     /**
-     * Fetch real on-chain balances: native ETH + ERC-20 tokens
+     * Fetch real on-chain balances: native ETH + ERC-20 tokens.
+     * Uses Multicall3 to batch all balanceOf calls into a single RPC request.
      */
     private fetchBalances;
     /**
-     * Calculate total portfolio value in USD
+     * Fallback: fetch ERC-20 balances individually (if multicall fails).
+     */
+    private fetchBalancesIndividual;
+    /**
+     * Calculate total portfolio value in USD.
+     * Skips tokens with unresolvable decimals to avoid corrupted calculations.
      */
     private calculatePortfolioValue;
 }
@@ -2114,6 +2191,6 @@ declare function decryptEnvFile(encPath: string, passphrase: string): Record<str
 declare function loadSecureEnv(basePath: string, passphrase?: string): boolean;
 
 /** @exagent/agent package version — update alongside package.json */
-declare const AGENT_VERSION = "0.1.31";
+declare const AGENT_VERSION = "0.1.32";
 
 export { AGENT_VERSION, type AccountSummary, type AgentConfig, AgentConfigSchema, type AgentMode, AgentRuntime, type AgentStatusPayload, AnthropicAdapter, BaseLLMAdapter, type CommandType, DeepSeekAdapter, FileStore, type FillCallback, type FundingCallback, type FundingPayment, GoogleAdapter, GroqAdapter, HYPERLIQUID_DOMAIN, HyperliquidClient, HyperliquidSigner, HyperliquidWebSocket, type LLMAdapter, type LLMConfig, LLMConfigSchema, type LLMMessage, type LLMMetadata, type LLMProvider, LLMProviderSchema, type LLMResponse, type LiquidationCallback, type MarketData, MarketDataService, type MessageLevel, type MessageType, MistralAdapter, OllamaAdapter, type OnboardingStatus, OpenAIAdapter, OrderManager, type OrderResult, type PerpAction, type PerpConfig$1 as PerpConfig, PerpConfigSchema, type PerpFill, type PerpMarketData, PerpOnboarding, type PerpPosition, type PerpStrategyFunction, PerpTradeRecorder, type PerpTradeSignal, type PerpConfig as PerpTradingConfig, PositionManager, type PositionSummary, PositionTracker, type RecordPerpTradeParams, RelayClient, type RelayCommand, type RelayConfig$1 as RelayConfig, RelayConfigSchema, RiskManager, type RiskState, type RiskUniverse, RiskUniverseSchema, type RuntimeConfig, STRATEGY_TEMPLATES, type StrategyContext, type StrategyFunction, type StrategyStore, type StrategyTemplate, TogetherAdapter, type TrackedPosition, TradeExecutor, type TradeRecord, type TradeSignal, type TradingConfig, TradingConfigSchema, type VaultConfig, VaultConfigSchema, VaultManager, type VaultManagerConfig, type VaultPolicy, VaultPolicySchema, type VaultStatus, createLLMAdapter, createSampleConfig, decryptEnvFile, encryptEnvFile, fillHashToBytes32, fillOidToBytes32, getAllStrategyTemplates, getNextNonce, getStrategyTemplate, loadConfig, loadSecureEnv, loadStrategy, validateConfig, validateStrategy };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Address, Hash, WalletClient } from 'viem';
+import { Address, Hash, PublicClient, WalletClient } from 'viem';
 import { ExagentClient } from '@exagent/sdk';
 
 /** Risk state persisted across restarts */
@@ -1426,30 +1426,101 @@ declare class RiskManager {
     private calculateLiquidationProximity;
 }
 
+/**
+ * TokenResolver — bulletproof token metadata resolution with 3-tier fallback.
+ *
+ * Resolution chain:
+ *   1. Hardcoded map (39 whitelisted tokens — instant)
+ *   2. Multicall3 batch on-chain (decimals + symbol in 1 RPC call)
+ *   3. Blockscout API (free, near-universal coverage for Base tokens)
+ *
+ * If ALL tiers fail, the token is marked "unresolvable" and skipped from
+ * portfolio calculations. This is better than silently defaulting to 18
+ * decimals, which causes 10^9–10^12 errors for tokens with 6/8/9 decimals.
+ *
+ * Resolved metadata is persisted to FileStore and never re-fetched (ERC-20
+ * decimals are immutable by convention).
+ */
+declare class TokenResolver {
+    private client;
+    private store;
+    private cache;
+    private unresolvable;
+    constructor(client: PublicClient, store?: StrategyStore);
+    /**
+     * Get decimals for a token (synchronous).
+     * Returns undefined if the token has never been resolved and is not hardcoded.
+     * Call resolve() first for unknown tokens.
+     */
+    getDecimals(address: string): number | undefined;
+    /**
+     * Get symbol for a token (synchronous).
+     */
+    getSymbol(address: string): string | undefined;
+    /**
+     * Set symbol for a token (used when DexScreener returns symbol data).
+     */
+    setSymbol(address: string, symbol: string): void;
+    /**
+     * Check if a token has been marked as unresolvable by all tiers.
+     */
+    isUnresolvable(address: string): boolean;
+    /**
+     * Batch-resolve metadata for a list of token addresses.
+     *
+     * Skips already-resolved tokens. For unknown tokens:
+     * 1. Multicall3 on-chain batch (decimals + symbol)
+     * 2. Blockscout API for any multicall failures
+     * 3. Mark remaining as unresolvable
+     */
+    resolve(addresses: string[]): Promise<void>;
+    /**
+     * Tier 2: Batch-fetch decimals + symbol via Multicall3.
+     * Returns addresses that failed (for next tier).
+     */
+    private resolveViaMulticall;
+    /**
+     * Tier 3: Fetch token metadata from Blockscout (Base's block explorer API).
+     * Free, no API key, near-universal coverage for any token indexed by the explorer.
+     * Returns addresses that failed (truly unresolvable).
+     */
+    private resolveViaBlockscout;
+    /**
+     * Persist resolved metadata to FileStore.
+     */
+    private persist;
+    /**
+     * Persist unresolvable token list to FileStore.
+     */
+    private persistUnresolvable;
+}
+
 /**
  * Market Data Service
  * Fetches real prices from CoinGecko and on-chain balances for strategy analysis.
  *
- * Queries real on-chain balances for:
- * - Native ETH (via eth_getBalance)
- * - ERC-20 tokens (via balanceOf)
+ * Uses TokenResolver for bulletproof token metadata resolution:
+ *   1. Hardcoded map (39 whitelisted tokens)
+ *   2. Multicall3 batch on-chain (1 RPC call for N tokens)
+ *   3. Blockscout API (free, near-universal coverage)
  *
- * Fetches real prices from CoinGecko free API.
- * Refuses to return data if prices are stale (>60s old) to prevent
- * agents from making decisions with outdated price information.
+ * Uses Multicall3 for batched balance fetching (1 RPC call for N balanceOf).
  */
 declare class MarketDataService {
     private rpcUrl;
     private client;
+    private resolver;
     /** Cached prices from last fetch */
     private cachedPrices;
     /** Timestamp of last successful price fetch */
     private lastPriceFetchAt;
-    constructor(rpcUrl: string);
     /** Cached volume data */
     private cachedVolume24h;
     /** Cached price change data */
     private cachedPriceChange24h;
+    constructor(rpcUrl: string, store?: StrategyStore);
+    /** Get the underlying TokenResolver for direct access */
+    getResolver(): TokenResolver;
     /**
      * Fetch current market data for the agent
      */
@@ -1464,11 +1535,17 @@ declare class MarketDataService {
      */
     private fetchPrices;
     /**
-     * Fetch real on-chain balances: native ETH + ERC-20 tokens
+     * Fetch real on-chain balances: native ETH + ERC-20 tokens.
+     * Uses Multicall3 to batch all balanceOf calls into a single RPC request.
      */
     private fetchBalances;
     /**
-     * Calculate total portfolio value in USD
+     * Fallback: fetch ERC-20 balances individually (if multicall fails).
+     */
+    private fetchBalancesIndividual;
+    /**
+     * Calculate total portfolio value in USD.
+     * Skips tokens with unresolvable decimals to avoid corrupted calculations.
      */
     private calculatePortfolioValue;
 }
@@ -2114,6 +2191,6 @@ declare function decryptEnvFile(encPath: string, passphrase: string): Record<str
 declare function loadSecureEnv(basePath: string, passphrase?: string): boolean;
 
 /** @exagent/agent package version — update alongside package.json */
-declare const AGENT_VERSION = "0.1.31";
+declare const AGENT_VERSION = "0.1.32";
 
 export { AGENT_VERSION, type AccountSummary, type AgentConfig, AgentConfigSchema, type AgentMode, AgentRuntime, type AgentStatusPayload, AnthropicAdapter, BaseLLMAdapter, type CommandType, DeepSeekAdapter, FileStore, type FillCallback, type FundingCallback, type FundingPayment, GoogleAdapter, GroqAdapter, HYPERLIQUID_DOMAIN, HyperliquidClient, HyperliquidSigner, HyperliquidWebSocket, type LLMAdapter, type LLMConfig, LLMConfigSchema, type LLMMessage, type LLMMetadata, type LLMProvider, LLMProviderSchema, type LLMResponse, type LiquidationCallback, type MarketData, MarketDataService, type MessageLevel, type MessageType, MistralAdapter, OllamaAdapter, type OnboardingStatus, OpenAIAdapter, OrderManager, type OrderResult, type PerpAction, type PerpConfig$1 as PerpConfig, PerpConfigSchema, type PerpFill, type PerpMarketData, PerpOnboarding, type PerpPosition, type PerpStrategyFunction, PerpTradeRecorder, type PerpTradeSignal, type PerpConfig as PerpTradingConfig, PositionManager, type PositionSummary, PositionTracker, type RecordPerpTradeParams, RelayClient, type RelayCommand, type RelayConfig$1 as RelayConfig, RelayConfigSchema, RiskManager, type RiskState, type RiskUniverse, RiskUniverseSchema, type RuntimeConfig, STRATEGY_TEMPLATES, type StrategyContext, type StrategyFunction, type StrategyStore, type StrategyTemplate, TogetherAdapter, type TrackedPosition, TradeExecutor, type TradeRecord, type TradeSignal, type TradingConfig, TradingConfigSchema, type VaultConfig, VaultConfigSchema, VaultManager, type VaultManagerConfig, type VaultPolicy, VaultPolicySchema, type VaultStatus, createLLMAdapter, createSampleConfig, decryptEnvFile, encryptEnvFile, fillHashToBytes32, fillOidToBytes32, getAllStrategyTemplates, getNextNonce, getStrategyTemplate, loadConfig, loadSecureEnv, loadStrategy, validateConfig, validateStrategy };