@pioneer-platform/pioneer-cache 1.22.0 → 1.24.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
 
-> @pioneer-platform/pioneer-cache@1.21.0 build /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/modules/pioneer/pioneer-cache
+> @pioneer-platform/pioneer-cache@1.24.0 build /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/modules/pioneer/pioneer-cache
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @pioneer-platform/pioneer-cache
 
+## 1.24.0
+
+### Minor Changes
+
+- chore: feat(e2e): add --blue and --production flags to pioneer-sdk test
+
+### Patch Changes
+
+- Updated dependencies
+  - @pioneer-platform/pioneer-discovery@8.47.0
+  - @pioneer-platform/pioneer-caip@9.23.0
+
+## 1.23.0
+
+### Minor Changes
+
+- feat(e2e): add --blue and --production flags to pioneer-sdk test
+
+### Patch Changes
+
+- Updated dependencies
+  - @pioneer-platform/pioneer-caip@9.22.0
+  - @pioneer-platform/pioneer-discovery@8.46.0
+
+## 1.22.1
+
+### Patch Changes
+
+- fix(cache-worker): fix balance module import and initialization
+- Updated dependencies
+  - @pioneer-platform/pioneer-discovery@8.45.1
+
 ## 1.22.0
 
 ### Minor Changes

package/dist/core/base-cache.d.ts

@@ -5,11 +5,12 @@ export declare abstract class BaseCache<T> {
     protected config: CacheConfig;
     protected queueInitialized: boolean;
     protected TAG: string;
+    protected redisPublisher?: any;
     private cachedStats;
     private cachedStatsTimestamp;
     private readonly STATS_CACHE_TTL;
     private pendingFetches;
-    constructor(redis: any, config: CacheConfig);
+    constructor(redis: any, config: CacheConfig, redisPublisher?: any);
     /**
      * Initialize Redis queue for background refresh
      */

package/dist/core/base-cache.js

@@ -29,7 +29,7 @@ const MAJOR_CRYPTO_WHITELIST = new Set([
     'bip122:000000000000000000651ef99cb9fcbe/slip44:145', // Bitcoin Cash
 ]);
 class BaseCache {
-    constructor(redis, config) {
+    constructor(redis, config, redisPublisher) {
         this.queueInitialized = false;
         // Cache for stats (to avoid expensive SCAN operations on every health check)
         this.cachedStats = null;
@@ -40,6 +40,7 @@ class BaseCache {
         this.pendingFetches = new Map();
         this.redis = redis;
         this.config = config;
+        this.redisPublisher = redisPublisher;
         this.TAG = ` | ${config.name}Cache | `;
         // Initialize queue if enabled
         if (config.enableQueue) {

package/dist/core/cache-manager.d.ts

@@ -12,6 +12,7 @@ import type { CacheAlertHandler } from '../types';
 export interface CacheManagerConfig {
     redis: any;
     redisQueue?: any;
+    redisPublisher?: any;
     balanceModule?: any;
     markets?: any;
     networkModules?: Map<string, any>;

package/dist/core/cache-manager.js

@@ -29,7 +29,7 @@ class CacheManager {
         if (config.enableBalanceCache !== false && config.balanceModule) {
             this.balanceCache = new balance_cache_1.BalanceCache(this.redis, config.balanceModule, {
                 alertHandler: config.alertHandler
-            });
+            }, config.redisPublisher);
             log.info(TAG, '✅ Balance cache initialized');
         }
         // Initialize Price Cache

package/dist/stores/balance-cache.d.ts

@@ -28,7 +28,7 @@ export interface BalanceData {
  */
 export declare class BalanceCache extends BaseCache<BalanceData> {
     private balanceModule;
-    constructor(redis: any, balanceModule: any, config?: Partial<CacheConfig>);
+    constructor(redis: any, balanceModule: any, config?: Partial<CacheConfig>, redisPublisher?: any);
     /**
      * Build Redis key for balance data
      * Format: balance_v2:caip:hashedPubkey

package/dist/stores/balance-cache.js

@@ -47,7 +47,7 @@ function sanitizePubkey(pubkey) {
  * BalanceCache - Caches blockchain balance data
  */
 class BalanceCache extends base_cache_1.BaseCache {
-    constructor(redis, balanceModule, config) {
+    constructor(redis, balanceModule, config, redisPublisher) {
         const defaultConfig = {
             name: 'balance',
             keyPrefix: 'balance_v2:',
@@ -71,7 +71,7 @@ class BalanceCache extends base_cache_1.BaseCache {
             logCacheMisses: true,
             logRefreshJobs: true
         };
-        super(redis, { ...defaultConfig, ...config });
+        super(redis, { ...defaultConfig, ...config }, redisPublisher);
         this.balanceModule = balanceModule;
     }
     /**
@@ -298,6 +298,21 @@ class BalanceCache extends base_cache_1.BaseCache {
                         const parsed = JSON.parse(cached);
                         if (parsed.value && parsed.value.caip && parsed.value.pubkey) {
                             results[i] = parsed.value;
+                            // CRITICAL FIX: Check staleness and trigger background refresh for stale cache hits
+                            if (this.config.staleThreshold && parsed.timestamp) {
+                                const age = Date.now() - parsed.timestamp;
+                                if (age > this.config.staleThreshold) {
+                                    // Stale! Trigger background refresh (stale-while-revalidate pattern)
+                                    log.info(tag, `🔄 [STALE HIT] ${item.caip} is ${Math.floor(age / 1000 / 60)}m old (threshold: ${this.config.staleThreshold / 1000 / 60}m) - queueing refresh`);
+                                    if (!skipAsyncRefresh) {
+                                        log.info(tag, `[DEBUG] Calling triggerAsyncRefresh for ${item.caip}, queueInit=${this.queueInitialized}, enableQueue=${this.config.enableQueue}`);
+                                        this.triggerAsyncRefresh({ caip: item.caip, pubkey: item.pubkey }, 'normal');
+                                    }
+                                    else {
+                                        log.info(tag, `[DEBUG] skipAsyncRefresh=true, NOT calling triggerAsyncRefresh for ${item.caip}`);
+                                    }
+                                }
+                            }
                             continue;
                         }
                     }

package/dist/stores/portfolio-cache.d.ts

@@ -61,6 +61,11 @@ export declare class PortfolioCache extends BaseCache<PortfolioData> {
      * INTEGRATED: Part of portfolio background refresh, no direct blockchain queries from endpoints
      */
     private fetchStableCoins;
+    /**
+     * Fetch custom tokens for a user address
+     * INTEGRATED: Part of portfolio background refresh, no direct blockchain queries from endpoints
+     */
+    private fetchCustomTokens;
     /**
      * Fetch portfolio from blockchain APIs
      *
@@ -69,6 +74,10 @@ export declare class PortfolioCache extends BaseCache<PortfolioData> {
      * INTEGRATED: Now includes stable coin balances automatically
      */
     protected fetchFromSource(params: Record<string, any>): Promise<PortfolioData>;
+    /**
+     * Apply Redis overlays to adjust balances for pending transactions
+     */
+    private applyRedisOverlays;
     /**
      * No legacy cache format for portfolios
      */

package/dist/stores/portfolio-cache.js

@@ -198,6 +198,103 @@ class PortfolioCache extends base_cache_1.BaseCache {
             return stableCharts;
         }
     }
+    /**
+     * Fetch custom tokens for a user address
+     * INTEGRATED: Part of portfolio background refresh, no direct blockchain queries from endpoints
+     */
+    async fetchCustomTokens(primaryAddress, pubkeys) {
+        const tag = this.TAG + 'fetchCustomTokens | ';
+        const customCharts = [];
+        try {
+            log.info(tag, `Fetching custom tokens for address: ${primaryAddress.substring(0, 10)}...`);
+            // Get custom tokens from MongoDB
+            // Note: This creates a soft dependency on the server service layer
+            // In production, this would be better implemented as a shared service
+            const { CustomTokenService } = require('../../../../../services/pioneer-server/src/services/custom-token.service');
+            // Get custom tokens for all EVM networks the user might have
+            const evmNetworks = ['eip155:1', 'eip155:137', 'eip155:56', 'eip155:43114', 'eip155:42161', 'eip155:8453'];
+            let allCustomTokens = [];
+            for (const networkId of evmNetworks) {
+                try {
+                    const networkTokens = await CustomTokenService.getTokens(primaryAddress, networkId);
+                    allCustomTokens.push(...networkTokens);
+                }
+                catch (error) {
+                    log.debug(tag, `No custom tokens for ${networkId}: ${error.message}`);
+                }
+            }
+            if (allCustomTokens.length === 0) {
+                log.info(tag, 'No custom tokens found for user');
+                return customCharts;
+            }
+            log.info(tag, `Found ${allCustomTokens.length} custom tokens, fetching balances...`);
+            // Initialize eth-network if needed
+            let ethNetwork = global.ethNetwork;
+            if (!ethNetwork) {
+                ethNetwork = require('@pioneer-platform/eth-network');
+                await ethNetwork.init({});
+                global.ethNetwork = ethNetwork;
+            }
+            // Fetch balances for each custom token
+            const tokenPromises = allCustomTokens.map(async (tokenConfig) => {
+                try {
+                    const balance = await Promise.race([
+                        ethNetwork.getBalanceTokenByNetwork(tokenConfig.networkId, primaryAddress, tokenConfig.address),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 5000))
+                    ]);
+                    const balanceNum = parseFloat(balance);
+                    // Skip zero balances
+                    if (isNaN(balanceNum) || balanceNum === 0) {
+                        return null;
+                    }
+                    // Get price from markets module
+                    let priceUsd = 0;
+                    try {
+                        priceUsd = await this.marketsModule.getAssetPriceByCaip(tokenConfig.caip);
+                        if (isNaN(priceUsd) || priceUsd < 0) {
+                            priceUsd = 0;
+                        }
+                    }
+                    catch (priceError) {
+                        log.warn(tag, `Error fetching price for ${tokenConfig.symbol}:`, priceError);
+                    }
+                    const valueUsd = balanceNum * priceUsd;
+                    const chartData = {
+                        caip: tokenConfig.caip,
+                        pubkey: primaryAddress,
+                        networkId: tokenConfig.networkId,
+                        symbol: tokenConfig.symbol,
+                        name: tokenConfig.name,
+                        balance: balance,
+                        priceUsd,
+                        valueUsd,
+                        icon: tokenConfig.icon || '',
+                        type: 'custom-token',
+                        decimal: tokenConfig.decimals
+                    };
+                    log.info(tag, `✅ ${tokenConfig.symbol}: ${balance} ($${valueUsd.toFixed(2)})`);
+                    return chartData;
+                }
+                catch (error) {
+                    const errorMsg = error.isAxiosError
+                        ? `${error.message} (${error.code}) - ${error.config?.url || 'unknown url'}`
+                        : error.message || String(error);
+                    log.error(tag, `Error fetching ${tokenConfig.symbol}: ${errorMsg}`);
+                    return null;
+                }
+            });
+            const results = await Promise.all(tokenPromises);
+            const validTokens = results.filter((t) => t !== null);
+            customCharts.push(...validTokens);
+            log.info(tag, `Fetched ${customCharts.length} custom token balances`);
+            return customCharts;
+        }
+        catch (error) {
+            const errorMsg = error.message || String(error);
+            log.error(tag, `Error fetching custom tokens: ${errorMsg}`);
+            return customCharts;
+        }
+    }
     /**
      * Fetch portfolio from blockchain APIs
      *
@@ -235,8 +332,17 @@ class PortfolioCache extends base_cache_1.BaseCache {
                             log.debug(tag, `No balance for ${item.caip}/${item.pubkey.substring(0, 10)}...`);
                             return null;
                         }
-                        // Skip zero balances
-                        const balanceNum = parseFloat(balanceInfo.balance);
+                        // Apply Redis overlays for server-side pending balance adjustments
+                        let adjustedBalance = balanceInfo.balance;
+                        try {
+                            adjustedBalance = await this.applyRedisOverlays(item.caip, item.pubkey, balanceInfo.balance);
+                        }
+                        catch (overlayError) {
+                            log.warn(tag, `Failed to apply overlays for ${item.caip}/${item.pubkey.substring(0, 10)}: ${overlayError.message}`);
+                            // Continue with original balance if overlay application fails
+                        }
+                        // Skip zero balances (use adjusted balance for check)
+                        const balanceNum = parseFloat(adjustedBalance);
                         if (isNaN(balanceNum) || balanceNum === 0) {
                             return null;
                         }
@@ -274,7 +380,7 @@ class PortfolioCache extends base_cache_1.BaseCache {
                             networkId,
                             symbol: assetInfo.symbol || 'UNKNOWN',
                             name: assetInfo.name || 'Unknown Asset',
-                            balance: balanceInfo.balance,
+                            balance: adjustedBalance,
                             priceUsd,
                             valueUsd,
                             icon: assetInfo.icon || '',
@@ -319,6 +425,17 @@ class PortfolioCache extends base_cache_1.BaseCache {
                     }
                 }
                 log.info(tag, `Added ${stableCoins.length} stable coins to portfolio`);
+                // INTEGRATED: Fetch custom tokens for EVM addresses (background operation)
+                log.info(tag, `Fetching custom tokens for EVM address: ${primaryAddress.substring(0, 10)}...`);
+                const customTokens = await this.fetchCustomTokens(primaryAddress, pubkeys);
+                // Add custom tokens to charts (deduplicate by CAIP+pubkey)
+                for (const customToken of customTokens) {
+                    const isDuplicate = charts.some(c => c.caip === customToken.caip && c.pubkey === customToken.pubkey);
+                    if (!isDuplicate) {
+                        charts.push(customToken);
+                    }
+                }
+                log.info(tag, `Added ${customTokens.length} custom tokens to portfolio`);
             }
             // Calculate total value
             const totalValueUsd = charts.reduce((sum, c) => sum + c.valueUsd, 0);
@@ -337,6 +454,52 @@ class PortfolioCache extends base_cache_1.BaseCache {
             throw error;
         }
     }
+    /**
+     * Apply Redis overlays to adjust balances for pending transactions
+     */
+    async applyRedisOverlays(caip, pubkey, originalBalance) {
+        const tag = this.TAG + 'applyRedisOverlays | ';
+        try {
+            // Normalize inputs for overlay lookup
+            const normalizedCaip = caip.toLowerCase();
+            const normalizedPubkey = pubkey.toLowerCase();
+            // Find all overlays for this asset/pubkey combination
+            const overlayPattern = `pending-overlay:*:${normalizedCaip}:${normalizedPubkey}:*`;
+            const overlayKeys = await this.redis.keys(overlayPattern);
+            if (overlayKeys.length === 0) {
+                return originalBalance; // No overlays to apply
+            }
+            let adjustedBalance = parseFloat(originalBalance);
+            log.debug(tag, `Applying ${overlayKeys.length} overlays to ${normalizedCaip}/${normalizedPubkey.substring(0, 10)} (base: ${originalBalance})`);
+            for (const overlayKey of overlayKeys) {
+                try {
+                    const overlayData = await this.redis.get(overlayKey);
+                    if (!overlayData)
+                        continue;
+                    const overlay = JSON.parse(overlayData);
+                    const overlayAmount = parseFloat(overlay.amount || '0');
+                    if (overlay.type === 'debit') {
+                        adjustedBalance -= overlayAmount;
+                        log.debug(tag, `Applied debit overlay: -${overlayAmount} (new balance: ${adjustedBalance})`);
+                    }
+                    else if (overlay.type === 'credit') {
+                        adjustedBalance += overlayAmount;
+                        log.debug(tag, `Applied credit overlay: +${overlayAmount} (new balance: ${adjustedBalance})`);
+                    }
+                }
+                catch (parseError) {
+                    log.warn(tag, `Failed to parse overlay ${overlayKey}: ${parseError.message}`);
+                }
+            }
+            const finalBalance = Math.max(0, adjustedBalance).toString(); // Ensure non-negative
+            log.debug(tag, `Final adjusted balance: ${originalBalance} -> ${finalBalance} (${overlayKeys.length} overlays)`);
+            return finalBalance;
+        }
+        catch (error) {
+            log.error(tag, `Failed to apply Redis overlays for ${caip}/${pubkey.substring(0, 10)}: ${error.message}`);
+            return originalBalance; // Return original on error
+        }
+    }
     /**
      * No legacy cache format for portfolios
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pioneer-platform/pioneer-cache",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Unified caching system for Pioneer platform with Redis backend",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,11 +14,11 @@
   "author": "Pioneer Platform",
   "license": "MIT",
   "dependencies": {
+    "@pioneer-platform/redis-queue": "8.12.17",
     "@pioneer-platform/loggerdog": "8.11.0",
-    "@pioneer-platform/pioneer-discovery": "8.44.0",
-    "@pioneer-platform/pioneer-caip": "9.21.0",
     "@pioneer-platform/default-redis": "8.11.7",
-    "@pioneer-platform/redis-queue": "8.12.17"
+    "@pioneer-platform/pioneer-discovery": "8.47.0",
+    "@pioneer-platform/pioneer-caip": "9.23.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",

package/src/core/base-cache.ts

@@ -46,6 +46,7 @@ export abstract class BaseCache<T> {
     protected config: CacheConfig;
     protected queueInitialized: boolean = false;
     protected TAG: string;
+    protected redisPublisher?: any;  // Optional Redis publisher for WebSocket events
 
     // Cache for stats (to avoid expensive SCAN operations on every health check)
     private cachedStats: CacheStats | null = null;
@@ -56,9 +57,10 @@ export abstract class BaseCache<T> {
     // Tracks in-flight network requests to prevent duplicate API calls
     private pendingFetches: Map<string, Promise<T>> = new Map();
 
-    constructor(redis: any, config: CacheConfig) {
+    constructor(redis: any, config: CacheConfig, redisPublisher?: any) {
         this.redis = redis;
         this.config = config;
+        this.redisPublisher = redisPublisher;
         this.TAG = ` | ${config.name}Cache | `;
 
         // Initialize queue if enabled

package/src/core/cache-manager.ts

@@ -27,6 +27,7 @@ import type { CacheAlertHandler } from '../types';
 export interface CacheManagerConfig {
     redis: any;
     redisQueue?: any;                      // Dedicated Redis client for blocking queue operations (brpop, etc.)
+    redisPublisher?: any;                  // Optional: Redis publisher for WebSocket balance update events
     balanceModule?: any;                   // Optional: if not provided, balance cache won't be initialized
     markets?: any;                         // Optional: if not provided, price cache won't be initialized
     networkModules?: Map<string, any>;     // Optional: network modules for staking cache (keyed by networkId)
@@ -64,7 +65,7 @@ export class CacheManager {
         if (config.enableBalanceCache !== false && config.balanceModule) {
             this.balanceCache = new BalanceCache(this.redis, config.balanceModule, {
                 alertHandler: config.alertHandler
-            });
+            }, config.redisPublisher);
             log.info(TAG, '✅ Balance cache initialized');
         }
 

package/src/stores/balance-cache.ts

@@ -75,7 +75,7 @@ export interface BalanceData {
 export class BalanceCache extends BaseCache<BalanceData> {
     private balanceModule: any;
 
-    constructor(redis: any, balanceModule: any, config?: Partial<CacheConfig>) {
+    constructor(redis: any, balanceModule: any, config?: Partial<CacheConfig>, redisPublisher?: any) {
         const defaultConfig: CacheConfig = {
             name: 'balance',
             keyPrefix: 'balance_v2:',
@@ -100,7 +100,7 @@ export class BalanceCache extends BaseCache<BalanceData> {
             logRefreshJobs: true
         };
 
-        super(redis, { ...defaultConfig, ...config });
+        super(redis, { ...defaultConfig, ...config }, redisPublisher);
         this.balanceModule = balanceModule;
     }
 
@@ -361,6 +361,22 @@ export class BalanceCache extends BaseCache<BalanceData> {
                         const parsed = JSON.parse(cached);
                         if (parsed.value && parsed.value.caip && parsed.value.pubkey) {
                             results[i] = parsed.value;
+
+                            // CRITICAL FIX: Check staleness and trigger background refresh for stale cache hits
+                            if (this.config.staleThreshold && parsed.timestamp) {
+                                const age = Date.now() - parsed.timestamp;
+                                if (age > this.config.staleThreshold) {
+                                    // Stale! Trigger background refresh (stale-while-revalidate pattern)
+                                    log.info(tag, `🔄 [STALE HIT] ${item.caip} is ${Math.floor(age / 1000 / 60)}m old (threshold: ${this.config.staleThreshold / 1000 / 60}m) - queueing refresh`);
+                                    if (!skipAsyncRefresh) {
+                                        log.info(tag, `[DEBUG] Calling triggerAsyncRefresh for ${item.caip}, queueInit=${this.queueInitialized}, enableQueue=${this.config.enableQueue}`);
+                                        this.triggerAsyncRefresh({ caip: item.caip, pubkey: item.pubkey }, 'normal');
+                                    } else {
+                                        log.info(tag, `[DEBUG] skipAsyncRefresh=true, NOT calling triggerAsyncRefresh for ${item.caip}`);
+                                    }
+                                }
+                            }
+
                             continue;
                         }
                     } catch (e) {

package/src/stores/portfolio-cache.ts

@@ -268,6 +268,125 @@ export class PortfolioCache extends BaseCache<PortfolioData> {
         }
     }
 
+    /**
+     * Fetch custom tokens for a user address
+     * INTEGRATED: Part of portfolio background refresh, no direct blockchain queries from endpoints
+     */
+    private async fetchCustomTokens(
+        primaryAddress: string,
+        pubkeys: Array<{ pubkey: string; caip: string }>
+    ): Promise<ChartData[]> {
+        const tag = this.TAG + 'fetchCustomTokens | ';
+        const customCharts: ChartData[] = [];
+
+        try {
+            log.info(tag, `Fetching custom tokens for address: ${primaryAddress.substring(0, 10)}...`);
+
+            // Get custom tokens from MongoDB
+            // Note: This creates a soft dependency on the server service layer
+            // In production, this would be better implemented as a shared service
+            const { CustomTokenService } = require('../../../../../services/pioneer-server/src/services/custom-token.service');
+            
+            // Get custom tokens for all EVM networks the user might have
+            const evmNetworks = ['eip155:1', 'eip155:137', 'eip155:56', 'eip155:43114', 'eip155:42161', 'eip155:8453'];
+            
+            let allCustomTokens: any[] = [];
+            for (const networkId of evmNetworks) {
+                try {
+                    const networkTokens = await CustomTokenService.getTokens(primaryAddress, networkId);
+                    allCustomTokens.push(...networkTokens);
+                } catch (error: any) {
+                    log.debug(tag, `No custom tokens for ${networkId}: ${error.message}`);
+                }
+            }
+
+            if (allCustomTokens.length === 0) {
+                log.info(tag, 'No custom tokens found for user');
+                return customCharts;
+            }
+
+            log.info(tag, `Found ${allCustomTokens.length} custom tokens, fetching balances...`);
+
+            // Initialize eth-network if needed
+            let ethNetwork = (global as any).ethNetwork;
+            if (!ethNetwork) {
+                ethNetwork = require('@pioneer-platform/eth-network');
+                await ethNetwork.init({});
+                (global as any).ethNetwork = ethNetwork;
+            }
+
+            // Fetch balances for each custom token
+            const tokenPromises = allCustomTokens.map(async (tokenConfig) => {
+                try {
+                    const balance = await Promise.race([
+                        ethNetwork.getBalanceTokenByNetwork(
+                            tokenConfig.networkId,
+                            primaryAddress,
+                            tokenConfig.address
+                        ),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 5000))
+                    ]);
+
+                    const balanceNum = parseFloat(balance);
+
+                    // Skip zero balances
+                    if (isNaN(balanceNum) || balanceNum === 0) {
+                        return null;
+                    }
+
+                    // Get price from markets module
+                    let priceUsd = 0;
+                    try {
+                        priceUsd = await this.marketsModule.getAssetPriceByCaip(tokenConfig.caip);
+                        if (isNaN(priceUsd) || priceUsd < 0) {
+                            priceUsd = 0;
+                        }
+                    } catch (priceError) {
+                        log.warn(tag, `Error fetching price for ${tokenConfig.symbol}:`, priceError);
+                    }
+
+                    const valueUsd = balanceNum * priceUsd;
+
+                    const chartData: ChartData = {
+                        caip: tokenConfig.caip,
+                        pubkey: primaryAddress,
+                        networkId: tokenConfig.networkId,
+                        symbol: tokenConfig.symbol,
+                        name: tokenConfig.name,
+                        balance: balance,
+                        priceUsd,
+                        valueUsd,
+                        icon: tokenConfig.icon || '',
+                        type: 'custom-token',
+                        decimal: tokenConfig.decimals
+                    };
+
+                    log.info(tag, `✅ ${tokenConfig.symbol}: ${balance} ($${valueUsd.toFixed(2)})`);
+                    return chartData;
+
+                } catch (error: any) {
+                    const errorMsg = error.isAxiosError
+                        ? `${error.message} (${error.code}) - ${error.config?.url || 'unknown url'}`
+                        : error.message || String(error);
+                    log.error(tag, `Error fetching ${tokenConfig.symbol}: ${errorMsg}`);
+                    return null;
+                }
+            });
+
+            const results = await Promise.all(tokenPromises);
+            const validTokens = results.filter((t): t is ChartData => t !== null);
+            customCharts.push(...validTokens);
+
+            log.info(tag, `Fetched ${customCharts.length} custom token balances`);
+            return customCharts;
+
+        } catch (error: any) {
+            const errorMsg = error.message || String(error);
+            log.error(tag, `Error fetching custom tokens: ${errorMsg}`);
+            return customCharts;
+        }
+    }
+
     /**
      * Fetch portfolio from blockchain APIs
      *
@@ -315,8 +434,17 @@ export class PortfolioCache extends BaseCache<PortfolioData> {
                         return null;
                     }
 
-                    // Skip zero balances
-                    const balanceNum = parseFloat(balanceInfo.balance);
+                    // Apply Redis overlays for server-side pending balance adjustments
+                    let adjustedBalance = balanceInfo.balance;
+                    try {
+                        adjustedBalance = await this.applyRedisOverlays(item.caip, item.pubkey, balanceInfo.balance);
+                    } catch (overlayError: any) {
+                        log.warn(tag, `Failed to apply overlays for ${item.caip}/${item.pubkey.substring(0, 10)}: ${overlayError.message}`);
+                        // Continue with original balance if overlay application fails
+                    }
+
+                    // Skip zero balances (use adjusted balance for check)
+                    const balanceNum = parseFloat(adjustedBalance);
                     if (isNaN(balanceNum) || balanceNum === 0) {
                         return null;
                     }
@@ -358,7 +486,7 @@ export class PortfolioCache extends BaseCache<PortfolioData> {
                         networkId,
                         symbol: assetInfo.symbol || 'UNKNOWN',
                         name: assetInfo.name || 'Unknown Asset',
-                        balance: balanceInfo.balance,
+                        balance: adjustedBalance,
                         priceUsd,
                         valueUsd,
                         icon: assetInfo.icon || '',
@@ -415,6 +543,21 @@ export class PortfolioCache extends BaseCache<PortfolioData> {
                     }
                 }
                 log.info(tag, `Added ${stableCoins.length} stable coins to portfolio`);
+
+                // INTEGRATED: Fetch custom tokens for EVM addresses (background operation)
+                log.info(tag, `Fetching custom tokens for EVM address: ${primaryAddress.substring(0, 10)}...`);
+                const customTokens = await this.fetchCustomTokens(primaryAddress, pubkeys);
+
+                // Add custom tokens to charts (deduplicate by CAIP+pubkey)
+                for (const customToken of customTokens) {
+                    const isDuplicate = charts.some(c =>
+                        c.caip === customToken.caip && c.pubkey === customToken.pubkey
+                    );
+                    if (!isDuplicate) {
+                        charts.push(customToken);
+                    }
+                }
+                log.info(tag, `Added ${customTokens.length} custom tokens to portfolio`);
             }
 
             // Calculate total value
@@ -437,6 +580,59 @@ export class PortfolioCache extends BaseCache<PortfolioData> {
         }
     }
 
+    /**
+     * Apply Redis overlays to adjust balances for pending transactions
+     */
+    private async applyRedisOverlays(caip: string, pubkey: string, originalBalance: string): Promise<string> {
+        const tag = this.TAG + 'applyRedisOverlays | ';
+        
+        try {
+            // Normalize inputs for overlay lookup
+            const normalizedCaip = caip.toLowerCase();
+            const normalizedPubkey = pubkey.toLowerCase();
+            
+            // Find all overlays for this asset/pubkey combination
+            const overlayPattern = `pending-overlay:*:${normalizedCaip}:${normalizedPubkey}:*`;
+            const overlayKeys = await this.redis.keys(overlayPattern);
+            
+            if (overlayKeys.length === 0) {
+                return originalBalance; // No overlays to apply
+            }
+            
+            let adjustedBalance = parseFloat(originalBalance);
+            log.debug(tag, `Applying ${overlayKeys.length} overlays to ${normalizedCaip}/${normalizedPubkey.substring(0, 10)} (base: ${originalBalance})`);
+            
+            for (const overlayKey of overlayKeys) {
+                try {
+                    const overlayData = await this.redis.get(overlayKey);
+                    if (!overlayData) continue;
+                    
+                    const overlay = JSON.parse(overlayData);
+                    const overlayAmount = parseFloat(overlay.amount || '0');
+                    
+                    if (overlay.type === 'debit') {
+                        adjustedBalance -= overlayAmount;
+                        log.debug(tag, `Applied debit overlay: -${overlayAmount} (new balance: ${adjustedBalance})`);
+                    } else if (overlay.type === 'credit') {
+                        adjustedBalance += overlayAmount;
+                        log.debug(tag, `Applied credit overlay: +${overlayAmount} (new balance: ${adjustedBalance})`);
+                    }
+                } catch (parseError: any) {
+                    log.warn(tag, `Failed to parse overlay ${overlayKey}: ${parseError.message}`);
+                }
+            }
+            
+            const finalBalance = Math.max(0, adjustedBalance).toString(); // Ensure non-negative
+            log.debug(tag, `Final adjusted balance: ${originalBalance} -> ${finalBalance} (${overlayKeys.length} overlays)`);
+            
+            return finalBalance;
+            
+        } catch (error: any) {
+            log.error(tag, `Failed to apply Redis overlays for ${caip}/${pubkey.substring(0, 10)}: ${error.message}`);
+            return originalBalance; // Return original on error
+        }
+    }
+
     /**
      * No legacy cache format for portfolios
      */