@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.1

package/dist/packages/agent/src/api/wallet-evm-balance.js

@@ -0,0 +1,663 @@
+/**
+ * EVM balance fetching — Alchemy, Ankr, and direct-RPC fallback paths.
+ *
+ * Handles multi-chain EVM balance + NFT retrieval with provider-key resolution
+ * and automatic fallback to public RPC endpoints when premium APIs are unavailable.
+ */
+import { logger } from "@elizaos/core";
+import { computeValueUsd, fetchDexPrices, WRAPPED_NATIVE, } from "./wallet-dex-prices.js";
+import { resolveAvalancheRpcUrls, resolveBaseRpcUrls, resolveBscRpcUrls, resolveEthereumRpcUrls, } from "./wallet-rpc.js";
+// ── Constants ─────────────────────────────────────────────────────────
+const FETCH_TIMEOUT_MS = 15_000;
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+// ── Default chain configuration ───────────────────────────────────────
+export const DEFAULT_EVM_CHAINS = [
+    {
+        name: "Ethereum",
+        subdomain: "eth-mainnet",
+        chainId: 1,
+        nativeSymbol: "ETH",
+        provider: "alchemy",
+    },
+    {
+        name: "Base",
+        subdomain: "base-mainnet",
+        chainId: 8453,
+        nativeSymbol: "ETH",
+        provider: "alchemy",
+    },
+    {
+        name: "Arbitrum",
+        subdomain: "arb-mainnet",
+        chainId: 42161,
+        nativeSymbol: "ETH",
+        provider: "alchemy",
+    },
+    {
+        name: "Optimism",
+        subdomain: "opt-mainnet",
+        chainId: 10,
+        nativeSymbol: "ETH",
+        provider: "alchemy",
+    },
+    {
+        name: "Polygon",
+        subdomain: "polygon-mainnet",
+        chainId: 137,
+        nativeSymbol: "POL",
+        provider: "alchemy",
+    },
+    {
+        name: "BSC",
+        subdomain: "bnb-mainnet",
+        chainId: 56,
+        nativeSymbol: "BNB",
+        provider: "alchemy",
+    },
+    {
+        name: "Avalanche",
+        subdomain: "avax-mainnet",
+        chainId: 43114,
+        nativeSymbol: "AVAX",
+        provider: "alchemy",
+    },
+];
+// ── Internal helpers ──────────────────────────────────────────────────
+/** Parse JSON from a fetch response. If the body isn't JSON, throw with the raw text. */
+async function jsonOrThrow(res) {
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(text.slice(0, 200) || `HTTP ${res.status}`);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(text.slice(0, 200) || "Invalid JSON");
+    }
+}
+function normalizeApiKey(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeStringArray(values) {
+    return [
+        ...new Set((values ?? [])
+            .map((value) => normalizeApiKey(value))
+            .filter((value) => Boolean(value))),
+    ];
+}
+export function resolveEvmProviderKeys(alchemyOrKeys, maybeAnkrKey) {
+    if (typeof alchemyOrKeys === "string" || alchemyOrKeys == null) {
+        const alchemyKey = typeof alchemyOrKeys === "string" ? alchemyOrKeys : null;
+        return {
+            alchemyKey: normalizeApiKey(alchemyKey),
+            ankrKey: normalizeApiKey(maybeAnkrKey),
+            cloudManagedAccess: false,
+            bscRpcUrls: resolveBscRpcUrls({ cloudManagedAccess: false }),
+            ethereumRpcUrls: resolveEthereumRpcUrls({ cloudManagedAccess: false }),
+            baseRpcUrls: resolveBaseRpcUrls({ cloudManagedAccess: false }),
+            avaxRpcUrls: resolveAvalancheRpcUrls({ cloudManagedAccess: false }),
+            nodeRealBscRpcUrl: normalizeApiKey(process.env.NODEREAL_BSC_RPC_URL ?? null),
+            quickNodeBscRpcUrl: normalizeApiKey(process.env.QUICKNODE_BSC_RPC_URL ?? null),
+            bscRpcUrl: normalizeApiKey(process.env.BSC_RPC_URL ?? null),
+            ethereumRpcUrl: normalizeApiKey(process.env.ETHEREUM_RPC_URL ?? null),
+            baseRpcUrl: normalizeApiKey(process.env.BASE_RPC_URL ?? null),
+            avaxRpcUrl: normalizeApiKey(process.env.AVALANCHE_RPC_URL ?? null),
+        };
+    }
+    const cloudManagedAccess = Boolean(alchemyOrKeys.cloudManagedAccess);
+    return {
+        alchemyKey: normalizeApiKey(alchemyOrKeys.alchemyKey),
+        ankrKey: normalizeApiKey(alchemyOrKeys.ankrKey ?? maybeAnkrKey),
+        cloudManagedAccess,
+        bscRpcUrls: normalizeStringArray([
+            ...(alchemyOrKeys.bscRpcUrls ?? []),
+            alchemyOrKeys.nodeRealBscRpcUrl ?? process.env.NODEREAL_BSC_RPC_URL,
+            alchemyOrKeys.quickNodeBscRpcUrl ?? process.env.QUICKNODE_BSC_RPC_URL,
+            alchemyOrKeys.bscRpcUrl ?? process.env.BSC_RPC_URL,
+            ...resolveBscRpcUrls({ cloudManagedAccess }),
+        ]),
+        ethereumRpcUrls: normalizeStringArray([
+            ...(alchemyOrKeys.ethereumRpcUrls ?? []),
+            alchemyOrKeys.ethereumRpcUrl ?? process.env.ETHEREUM_RPC_URL,
+            ...resolveEthereumRpcUrls({ cloudManagedAccess }),
+        ]),
+        baseRpcUrls: normalizeStringArray([
+            ...(alchemyOrKeys.baseRpcUrls ?? []),
+            alchemyOrKeys.baseRpcUrl ?? process.env.BASE_RPC_URL,
+            ...resolveBaseRpcUrls({ cloudManagedAccess }),
+        ]),
+        avaxRpcUrls: normalizeStringArray([
+            ...(alchemyOrKeys.avaxRpcUrls ?? []),
+            alchemyOrKeys.avaxRpcUrl ?? process.env.AVALANCHE_RPC_URL,
+            ...resolveAvalancheRpcUrls({ cloudManagedAccess }),
+        ]),
+        nodeRealBscRpcUrl: normalizeApiKey(alchemyOrKeys.nodeRealBscRpcUrl ?? process.env.NODEREAL_BSC_RPC_URL),
+        quickNodeBscRpcUrl: normalizeApiKey(alchemyOrKeys.quickNodeBscRpcUrl ?? process.env.QUICKNODE_BSC_RPC_URL),
+        bscRpcUrl: normalizeApiKey(alchemyOrKeys.bscRpcUrl ?? process.env.BSC_RPC_URL),
+        ethereumRpcUrl: normalizeApiKey(alchemyOrKeys.ethereumRpcUrl ?? process.env.ETHEREUM_RPC_URL),
+        baseRpcUrl: normalizeApiKey(alchemyOrKeys.baseRpcUrl ?? process.env.BASE_RPC_URL),
+        avaxRpcUrl: normalizeApiKey(alchemyOrKeys.avaxRpcUrl ?? process.env.AVALANCHE_RPC_URL),
+    };
+}
+function isBscChain(chain) {
+    return (chain.chainId === 56 || (chain.ankrChain ?? "").toLowerCase() === "bsc");
+}
+function describeRpcEndpoint(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "rpc";
+    }
+}
+function makeEvmChainFailure(chain, message) {
+    return {
+        chain: chain.name,
+        chainId: chain.chainId,
+        nativeBalance: "0",
+        nativeSymbol: chain.nativeSymbol,
+        nativeValueUsd: "0",
+        tokens: [],
+        error: message,
+    };
+}
+function rpcJsonRequest(body) {
+    return {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        body,
+    };
+}
+function asString(value) {
+    if (typeof value === "string")
+        return value.trim();
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return "";
+}
+function parseTokenDecimals(value, fallback = 18) {
+    const num = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number.parseInt(value, 10)
+            : Number.NaN;
+    if (!Number.isFinite(num) || num < 0)
+        return fallback;
+    return Math.trunc(num);
+}
+function parseAnkrBalance(asset, decimals) {
+    const tokenBalance = asString(asset.tokenBalance);
+    if (tokenBalance) {
+        if (/^\d+$/.test(tokenBalance))
+            return formatWei(BigInt(tokenBalance), decimals);
+        return tokenBalance;
+    }
+    const displayBalance = asString(asset.balance);
+    if (displayBalance) {
+        if (/^\d+$/.test(displayBalance))
+            return formatWei(BigInt(displayBalance), decimals);
+        return displayBalance;
+    }
+    const rawBalance = asString(asset.balanceRawInteger);
+    if (rawBalance && /^\d+$/.test(rawBalance))
+        return formatWei(BigInt(rawBalance), decimals);
+    return "0";
+}
+function isZeroBalance(balance) {
+    if (!balance)
+        return true;
+    if (/^0+(\.0+)?$/.test(balance))
+        return true;
+    const parsed = Number.parseFloat(balance);
+    return Number.isFinite(parsed) ? parsed <= 0 : false;
+}
+function isAnkrNativeAsset(asset) {
+    const tokenType = (asset.tokenType ?? "").toUpperCase();
+    const symbol = (asset.tokenSymbol ?? "").toUpperCase();
+    const contract = (asset.contractAddress ?? "").toLowerCase();
+    if (tokenType === "NATIVE")
+        return true;
+    return symbol === "BNB" && (!contract || contract === ZERO_ADDRESS);
+}
+function formatWei(wei, decimals) {
+    if (wei <= 0n || decimals <= 0)
+        return wei <= 0n ? "0" : wei.toString();
+    const divisor = 10n ** BigInt(decimals);
+    const whole = wei / divisor;
+    const rem = wei % divisor;
+    if (rem === 0n)
+        return whole.toString();
+    return `${whole}.${rem.toString().padStart(decimals, "0").replace(/0+$/, "")}`;
+}
+// ── Alchemy balance fetching ──────────────────────────────────────────
+async function fetchAlchemyChainBalances(chain, address, alchemyKey) {
+    const url = `https://${chain.subdomain}.g.alchemy.com/v2/${alchemyKey}`;
+    const nativeData = await jsonOrThrow(await fetch(url, rpcJsonRequest(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "eth_getBalance",
+        params: [address, "latest"],
+    }))));
+    const nativeBalance = formatWei(nativeData.result ? BigInt(nativeData.result) : 0n, 18);
+    const tokenData = await jsonOrThrow(await fetch(url, rpcJsonRequest(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "alchemy_getTokenBalances",
+        params: [address, "DEFAULT_TOKENS"],
+    }))));
+    const nonZero = (tokenData.result?.tokenBalances ?? []).filter((t) => t.tokenBalance && t.tokenBalance !== "0x0" && t.tokenBalance !== "0x");
+    const metaResults = await Promise.allSettled(nonZero.slice(0, 50).map(async (tok) => {
+        const meta = (await jsonOrThrow(await fetch(url, rpcJsonRequest(JSON.stringify({
+            jsonrpc: "2.0",
+            id: 3,
+            method: "alchemy_getTokenMetadata",
+            params: [tok.contractAddress],
+        }))))).result;
+        const decimals = meta?.decimals ?? 18;
+        return {
+            symbol: meta?.symbol ?? "???",
+            name: meta?.name ?? "Unknown Token",
+            contractAddress: tok.contractAddress,
+            balance: formatWei(BigInt(tok.tokenBalance), decimals),
+            decimals,
+            valueUsd: "0",
+            logoUrl: meta?.logo ?? "",
+        };
+    }));
+    const tokens = metaResults
+        .filter((r) => r.status === "fulfilled")
+        .map((r) => r.value);
+    // Fetch DEX prices for all tokens + native token.
+    const allAddresses = tokens.map((t) => t.contractAddress);
+    const wrappedNative = WRAPPED_NATIVE[chain.chainId];
+    if (wrappedNative)
+        allAddresses.push(wrappedNative);
+    const dexPrices = await fetchDexPrices(chain.chainId, allAddresses);
+    for (const tok of tokens) {
+        const meta = dexPrices.get(tok.contractAddress.toLowerCase());
+        if (meta) {
+            tok.valueUsd = computeValueUsd(tok.balance, meta.price);
+            if (meta.logoUrl && !tok.logoUrl)
+                tok.logoUrl = meta.logoUrl;
+        }
+    }
+    const nativeMeta = wrappedNative
+        ? dexPrices.get(wrappedNative.toLowerCase())
+        : undefined;
+    const nativeValueUsd = nativeMeta
+        ? computeValueUsd(nativeBalance, nativeMeta.price)
+        : "0";
+    return {
+        chain: chain.name,
+        chainId: chain.chainId,
+        nativeBalance,
+        nativeSymbol: chain.nativeSymbol,
+        nativeValueUsd,
+        tokens,
+        error: null,
+    };
+}
+// ── Ankr balance fetching ─────────────────────────────────────────────
+async function fetchAnkrChainBalances(chain, address, ankrKey) {
+    const res = await fetch(`https://rpc.ankr.com/multichain/${ankrKey}`, rpcJsonRequest(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "ankr_getAccountBalance",
+        params: {
+            walletAddress: address,
+            blockchain: [chain.ankrChain ?? "bsc"],
+            onlyWhitelisted: false,
+        },
+    })));
+    const data = await jsonOrThrow(res);
+    const assets = data.result?.assets ?? [];
+    const nativeAsset = assets.find(isAnkrNativeAsset);
+    const nativeBalance = nativeAsset
+        ? parseAnkrBalance(nativeAsset, parseTokenDecimals(nativeAsset.tokenDecimals))
+        : "0";
+    const tokens = [];
+    for (const asset of assets) {
+        if (isAnkrNativeAsset(asset))
+            continue;
+        const decimals = parseTokenDecimals(asset.tokenDecimals);
+        const balance = parseAnkrBalance(asset, decimals);
+        if (isZeroBalance(balance))
+            continue;
+        tokens.push({
+            symbol: asset.tokenSymbol ?? "???",
+            name: asset.tokenName ?? "Unknown Token",
+            contractAddress: asset.contractAddress ?? "",
+            balance,
+            decimals,
+            valueUsd: "0",
+            logoUrl: asset.thumbnail ?? "",
+        });
+    }
+    // All pricing via DexScreener/DexPaprika (Ankr only provides balances).
+    const allAddresses = tokens
+        .filter((t) => t.contractAddress)
+        .map((t) => t.contractAddress);
+    const wrappedNative = WRAPPED_NATIVE[chain.chainId];
+    if (wrappedNative)
+        allAddresses.push(wrappedNative);
+    logger.info(`[wallet] Fetching DEX prices for ${chain.name}: ${allAddresses.length} addresses (native=${nativeBalance})`);
+    const dexPrices = await fetchDexPrices(chain.chainId, allAddresses);
+    logger.info(`[wallet] DEX prices result for ${chain.name}: ${dexPrices.size} prices found`);
+    for (const tok of tokens) {
+        const meta = dexPrices.get(tok.contractAddress.toLowerCase());
+        if (meta) {
+            tok.valueUsd = computeValueUsd(tok.balance, meta.price);
+            if (meta.logoUrl && !tok.logoUrl)
+                tok.logoUrl = meta.logoUrl;
+        }
+    }
+    const nativeMeta = wrappedNative
+        ? dexPrices.get(wrappedNative.toLowerCase())
+        : undefined;
+    const nativeValueUsd = nativeMeta
+        ? computeValueUsd(nativeBalance, nativeMeta.price)
+        : "0";
+    return {
+        chain: chain.name,
+        chainId: chain.chainId,
+        nativeBalance,
+        nativeSymbol: chain.nativeSymbol,
+        nativeValueUsd,
+        tokens,
+        error: null,
+    };
+}
+// ── Direct RPC balance fetching ───────────────────────────────────────
+export async function fetchEvmNativeBalanceViaRpc(rpcUrl, address) {
+    const data = await jsonOrThrow(await fetch(rpcUrl, rpcJsonRequest(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "eth_getBalance",
+        params: [address, "latest"],
+    }))));
+    if (data.error?.message) {
+        throw new Error(data.error.message);
+    }
+    const raw = typeof data.result === "string" ? data.result : "0x0";
+    const wei = raw.startsWith("0x") ? BigInt(raw) : BigInt(raw || "0");
+    return formatWei(wei, 18);
+}
+/**
+ * Query ERC-20 balanceOf, symbol, and decimals for a single token via RPC.
+ * Returns null if the token has zero balance or the call fails.
+ */
+async function fetchErc20BalanceViaRpc(rpcUrl, walletAddress, contractAddress) {
+    const paddedWallet = walletAddress
+        .toLowerCase()
+        .replace("0x", "")
+        .padStart(64, "0");
+    // balanceOf(address) — paddedWallet is already 64 hex chars (24 zero prefix + 40 addr)
+    const balanceOfData = `0x70a08231${paddedWallet}`;
+    // symbol()
+    const symbolData = "0x95d89b41";
+    // decimals()
+    const decimalsData = "0x313ce567";
+    const makeCall = (to, data) => fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_call",
+            params: [{ to, data }, "latest"],
+        }),
+        signal: AbortSignal.timeout(8_000),
+    }).then((r) => r.json());
+    try {
+        const [balRes, symRes, decRes] = await Promise.all([
+            makeCall(contractAddress, balanceOfData),
+            makeCall(contractAddress, symbolData),
+            makeCall(contractAddress, decimalsData),
+        ]);
+        const rawBal = balRes.result;
+        if (!rawBal || rawBal === "0x" || rawBal === "0x0" || BigInt(rawBal) === 0n)
+            return null;
+        let decimals = 18;
+        if (decRes.result && decRes.result !== "0x") {
+            const d = Number(BigInt(decRes.result));
+            if (Number.isFinite(d) && d >= 0 && d <= 36)
+                decimals = d;
+        }
+        let symbol = "TOKEN";
+        if (symRes.result && symRes.result.length > 2) {
+            try {
+                // ABI-encoded string: offset (32 bytes) + length (32 bytes) + data
+                const hex = symRes.result.slice(2);
+                if (hex.length >= 128) {
+                    const len = Number(BigInt(`0x${hex.slice(64, 128)}`));
+                    const bytes = Buffer.from(hex.slice(128, 128 + len * 2), "hex");
+                    const decoded = bytes.toString("utf-8").replace(/\0/g, "").trim();
+                    if (decoded)
+                        symbol = decoded;
+                }
+            }
+            catch {
+                // Fall through with default symbol.
+            }
+        }
+        const balance = formatWei(BigInt(rawBal), decimals);
+        return {
+            symbol,
+            name: symbol,
+            contractAddress,
+            balance,
+            decimals,
+            valueUsd: "0",
+            logoUrl: "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchEvmChainBalancesViaRpc(chain, address, rpcUrls, knownTokenAddresses) {
+    const errors = [];
+    for (const rpcUrl of rpcUrls) {
+        try {
+            const nativeBalance = await fetchEvmNativeBalanceViaRpc(rpcUrl, address);
+            // Query known ERC-20 tokens (e.g. from trade ledger).
+            const tokens = [];
+            if (knownTokenAddresses && knownTokenAddresses.length > 0) {
+                const results = await Promise.allSettled(knownTokenAddresses
+                    .slice(0, 30)
+                    .map((addr) => fetchErc20BalanceViaRpc(rpcUrl, address, addr)));
+                for (const r of results) {
+                    if (r.status === "fulfilled" && r.value)
+                        tokens.push(r.value);
+                }
+            }
+            // Price native + tokens via DEX.
+            const wrappedNative = WRAPPED_NATIVE[chain.chainId];
+            const priceAddresses = tokens.map((t) => t.contractAddress);
+            if (wrappedNative)
+                priceAddresses.push(wrappedNative);
+            const dexPrices = priceAddresses.length > 0
+                ? await fetchDexPrices(chain.chainId, priceAddresses)
+                : new Map();
+            let nativeValueUsd = "0";
+            if (wrappedNative) {
+                const nativeMeta = dexPrices.get(wrappedNative.toLowerCase());
+                if (nativeMeta)
+                    nativeValueUsd = computeValueUsd(nativeBalance, nativeMeta.price);
+                logger.info(`[wallet] RPC path: ${chain.name} native=${nativeBalance} price=${nativeMeta?.price ?? "none"} value=$${nativeValueUsd}`);
+            }
+            for (const tok of tokens) {
+                const meta = dexPrices.get(tok.contractAddress.toLowerCase());
+                if (meta) {
+                    tok.valueUsd = computeValueUsd(tok.balance, meta.price);
+                    if (meta.logoUrl)
+                        tok.logoUrl = meta.logoUrl;
+                }
+            }
+            if (tokens.length > 0) {
+                logger.info(`[wallet] RPC path: ${chain.name} found ${tokens.length} tokens with balance`);
+            }
+            return {
+                chain: chain.name,
+                chainId: chain.chainId,
+                nativeBalance,
+                nativeSymbol: chain.nativeSymbol,
+                nativeValueUsd,
+                tokens,
+                error: null,
+            };
+        }
+        catch (err) {
+            const msg = String(err);
+            errors.push(`${describeRpcEndpoint(rpcUrl)}: ${msg}`);
+        }
+    }
+    throw new Error(errors.join(" | ").slice(0, 400) || `${chain.name} RPC unavailable`);
+}
+// ── Alchemy NFT fetching ──────────────────────────────────────────────
+async function fetchAlchemyChainNfts(chain, address, alchemyKey) {
+    const res = await fetch(`https://${chain.subdomain}.g.alchemy.com/nft/v3/${alchemyKey}/getNFTsForOwner?owner=${address}&withMetadata=true&pageSize=50`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    const data = await jsonOrThrow(res);
+    return {
+        chain: chain.name,
+        nfts: (data.ownedNfts ?? []).map((nft) => ({
+            contractAddress: nft.contract?.address ?? "",
+            tokenId: nft.tokenId ?? "",
+            name: nft.name ?? "Untitled",
+            description: (nft.description ?? "").slice(0, 200),
+            imageUrl: nft.image?.cachedUrl ??
+                nft.image?.thumbnailUrl ??
+                nft.image?.originalUrl ??
+                "",
+            collectionName: nft.contract?.openSeaMetadata?.collectionName ??
+                nft.contract?.name ??
+                "",
+            tokenType: nft.tokenType ?? "ERC721",
+        })),
+    };
+}
+// ── Ankr NFT fetching ─────────────────────────────────────────────────
+async function fetchAnkrChainNfts(chain, address, ankrKey) {
+    const res = await fetch(`https://rpc.ankr.com/multichain/${ankrKey}`, rpcJsonRequest(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "ankr_getNFTsByOwner",
+        params: {
+            walletAddress: address,
+            blockchain: [chain.ankrChain ?? "bsc"],
+            pageSize: 50,
+        },
+    })));
+    const data = await jsonOrThrow(res);
+    return {
+        chain: chain.name,
+        nfts: (data.result?.assets ?? []).map((nft) => ({
+            contractAddress: nft.contractAddress ?? "",
+            tokenId: String(nft.tokenId ?? ""),
+            name: nft.name ?? "Untitled",
+            description: (nft.description ?? "").slice(0, 200),
+            imageUrl: nft.imageUrl ?? nft.imagePreviewUrl ?? nft.imageOriginalUrl ?? "",
+            collectionName: nft.collectionName ?? nft.contractName ?? "",
+            tokenType: nft.tokenType ?? "ERC721",
+        })),
+    };
+}
+// ── Public API ────────────────────────────────────────────────────────
+export async function fetchEvmBalances(address, alchemyOrKeys, maybeAnkrKey, knownTokenAddresses) {
+    const keys = resolveEvmProviderKeys(alchemyOrKeys, maybeAnkrKey);
+    const bscRpcUrls = keys.bscRpcUrls;
+    const ethRpcUrls = keys.ethereumRpcUrls;
+    const baseRpcUrls = keys.baseRpcUrls;
+    const avaxRpcUrls = keys.avaxRpcUrls;
+    const hasManagedBscRpc = bscRpcUrls.length > 0;
+    const activeChains = DEFAULT_EVM_CHAINS.filter((chain) => {
+        if (chain.provider === "ankr") {
+            return Boolean(keys.ankrKey) || (isBscChain(chain) && hasManagedBscRpc);
+        }
+        // Prefer Alchemy when available (tokens + USD value). Otherwise, fall back to
+        // public RPC for native balances on the chains we support out-of-box.
+        if (keys.alchemyKey)
+            return true;
+        if (chain.chainId === 1)
+            return ethRpcUrls.length > 0;
+        if (chain.chainId === 8453)
+            return baseRpcUrls.length > 0;
+        if (chain.chainId === 56)
+            return hasManagedBscRpc;
+        if (chain.chainId === 43114)
+            return avaxRpcUrls.length > 0;
+        return false;
+    });
+    return Promise.all(activeChains.map(async (chain) => {
+        try {
+            if (chain.provider === "ankr") {
+                if (keys.ankrKey) {
+                    return await fetchAnkrChainBalances(chain, address, keys.ankrKey);
+                }
+                if (isBscChain(chain) && hasManagedBscRpc) {
+                    return await fetchEvmChainBalancesViaRpc(chain, address, bscRpcUrls, knownTokenAddresses);
+                }
+                return makeEvmChainFailure(chain, "Missing ANKR_API_KEY");
+            }
+            if (!keys.alchemyKey) {
+                if (chain.chainId === 1 && ethRpcUrls.length > 0) {
+                    return await fetchEvmChainBalancesViaRpc(chain, address, ethRpcUrls, knownTokenAddresses);
+                }
+                if (chain.chainId === 8453 && baseRpcUrls.length > 0) {
+                    return await fetchEvmChainBalancesViaRpc(chain, address, baseRpcUrls, knownTokenAddresses);
+                }
+                if (chain.chainId === 56 && hasManagedBscRpc) {
+                    return await fetchEvmChainBalancesViaRpc(chain, address, bscRpcUrls, knownTokenAddresses);
+                }
+                if (chain.chainId === 43114 && avaxRpcUrls.length > 0) {
+                    return await fetchEvmChainBalancesViaRpc(chain, address, avaxRpcUrls, knownTokenAddresses);
+                }
+                return makeEvmChainFailure(chain, "Missing ALCHEMY_API_KEY");
+            }
+            return await fetchAlchemyChainBalances(chain, address, keys.alchemyKey);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn(`EVM balance fetch failed for ${chain.name}: ${msg}`);
+            return makeEvmChainFailure(chain, msg);
+        }
+    }));
+}
+export async function fetchEvmNfts(address, alchemyOrKeys, maybeAnkrKey) {
+    const keys = resolveEvmProviderKeys(alchemyOrKeys, maybeAnkrKey);
+    const hasManagedBscRpc = keys.bscRpcUrls.length > 0;
+    const activeChains = DEFAULT_EVM_CHAINS.filter((chain) => {
+        if (chain.provider === "ankr") {
+            return (isBscChain(chain) && hasManagedBscRpc) || Boolean(keys.ankrKey);
+        }
+        if (keys.alchemyKey)
+            return true;
+        // BSC without Alchemy: include if managed RPC exists (NFTs will be empty)
+        if (chain.chainId === 56)
+            return hasManagedBscRpc;
+        return false;
+    });
+    return Promise.all(activeChains.map(async (chain) => {
+        try {
+            if (chain.provider === "ankr") {
+                if (!keys.ankrKey) {
+                    // Managed NodeReal/QuickNode mode currently provides native-balance
+                    // readiness only; token/NFT indexing is added in later phases.
+                    return { chain: chain.name, nfts: [] };
+                }
+                return await fetchAnkrChainNfts(chain, address, keys.ankrKey);
+            }
+            if (!keys.alchemyKey)
+                return { chain: chain.name, nfts: [] };
+            return await fetchAlchemyChainNfts(chain, address, keys.alchemyKey);
+        }
+        catch (err) {
+            logger.warn(`EVM NFT fetch failed for ${chain.name}: ${err}`);
+            return { chain: chain.name, nfts: [] };
+        }
+    }));
+}