keyring-agent-core 0.1.0

package/dist/services/MoralisService.js

@@ -0,0 +1,1364 @@
+"use strict";
+/**
+ * MoralisService — Moralis Web3 API + Cortex AI proxy.
+ *
+ * Adapted from keyring-chatbot-agent-sdk moralis service.
+ * Uses native fetch — no SDK dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MoralisService = void 0;
+const web3_1 = require("../functions/web3");
+const PantographService_1 = require("./PantographService");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_BASE_URL = 'https://nft.keyring.app';
+const DEFAULT_V1_BASE_URL = ' https://ed64-113-161-74-234.ngrok-free.app';
+const DEFAULT_CORTEX_MODEL = 'gpt-4.1-mini';
+const MINIMUM_TOKEN_BALANCE_PRICE_USD = 0.01;
+const MAX_RETRIES = 5;
+const RETRY_DELAY_MS = 1000;
+/** Moralis uses 0xEeee…EE for native ETH; we normalise to 0x000…000 */
+const ETH_SENTINEL = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** AI always provides hex chain IDs; default to Base (0x2105). */
+function toMoralisChain(chain) {
+    return chain || '0x2105';
+}
+function buildQueryString(params) {
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value == null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value) {
+                parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
+            }
+        }
+        else {
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        }
+    }
+    return parts.join('&');
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Coerce the `/wallets/{address}/defi/positions` payload into an array.
+ *
+ * The proxy sometimes serialises the Moralis response as a plain object with
+ * stringified numeric keys (`{"0": {...}, "1": {...}}`) instead of a real
+ * JSON array. We accept both shapes and drop anything that doesn't look like
+ * a position row.
+ */
+function normalizeDefiPositionsPayload(payload) {
+    if (Array.isArray(payload))
+        return payload;
+    if (payload && typeof payload === 'object') {
+        const obj = payload;
+        // v1 response shape: { meta, result: [...] }
+        if (Array.isArray(obj['result'])) {
+            return obj['result'].map((item) => ({
+                protocol_id: item.protocolId,
+                protocol_name: item.protocolName,
+                protocol_url: item.protocolUrl ?? '',
+                protocol_logo: item.protocolLogo ?? '',
+                position: {
+                    label: item.position.label,
+                    address: item.position.address,
+                    balance_usd: item.position.balanceUsd ?? 0,
+                    total_unclaimed_usd_value: item.position.unclaimedUsd ?? 0,
+                    position_details: item.position.details,
+                    tokens: item.position.tokens.map((t) => ({
+                        token_type: t.tokenType,
+                        address: t.address,
+                        contract_address: t.address,
+                        name: t.name ?? '',
+                        symbol: t.symbol ?? '',
+                        decimals: t.decimals ?? 18,
+                        logo: t.logo,
+                        balance: t.balance ?? '0',
+                        balance_formatted: t.balanceFormatted ?? '0',
+                        usd_price: t.usdPrice,
+                        usd_value: t.usdValue,
+                    })),
+                },
+            }));
+        }
+        // Proxy response shape: { "0": {...}, "1": {...} }
+        return Object.keys(obj)
+            .filter((k) => /^\d+$/.test(k))
+            .sort((a, b) => Number(a) - Number(b))
+            .map((k) => obj[k])
+            .filter((row) => !!row && typeof row === 'object');
+    }
+    return [];
+}
+/**
+ * Coerce a Moralis array response into a real array.
+ *
+ * Upstream returns a JSON array, but our proxy occasionally serialises it as
+ * `{ "0": {...}, "1": {...} }` (stringified numeric keys), or wraps it as
+ * `{ result: [...] }`. Accept all three shapes and drop anything that isn't a
+ * plain object row.
+ */
+function normalizeArrayLikePayload(payload) {
+    if (Array.isArray(payload))
+        return payload;
+    if (payload && typeof payload === 'object') {
+        const obj = payload;
+        if (Array.isArray(obj.result))
+            return obj.result;
+        return Object.keys(obj)
+            .filter((k) => /^\d+$/.test(k))
+            .sort((a, b) => Number(a) - Number(b))
+            .map((k) => obj[k])
+            .filter((row) => !!row && typeof row === 'object');
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Service class
+// ---------------------------------------------------------------------------
+class MoralisService {
+    baseUrl;
+    v1BaseUrl;
+    cortexModel;
+    pantograph;
+    constructor(config) {
+        this.baseUrl = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.v1BaseUrl = (config?.v1BaseUrl ?? DEFAULT_V1_BASE_URL).replace(/\/+$/, '');
+        this.cortexModel = config?.cortexModel ?? DEFAULT_CORTEX_MODEL;
+        this.pantograph = new PantographService_1.PantographService({ baseUrl: config?.pantographUrl });
+    }
+    // =========================================================================
+    // Token Balances
+    // =========================================================================
+    /**
+     * Get token balances for a wallet.
+     * Automatically enriches prices via Pantograph and filters dust.
+     */
+    async getWalletTokenBalances(params) {
+        const { address, chain, tokenAddresses, excludeSpam = false, excludeUnverifiedContracts = false } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if ((0, web3_1.isSolanaAddress)(address) && (chain?.toLowerCase() === 'solana' || chain === '0x736f6c')) {
+            return await this.getWalletTokenBalancesSolanaAddress({ address });
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {
+                    chain: moralisChain,
+                    exclude_spam: excludeSpam,
+                    exclude_unverified_contracts: excludeUnverifiedContracts,
+                    limit: 100,
+                };
+                if (tokenAddresses)
+                    query.token_addresses = tokenAddresses;
+                const allResults = [];
+                let cursor = null;
+                do {
+                    if (cursor)
+                        query.cursor = cursor;
+                    const qs = buildQueryString(query);
+                    const url = `${this.baseUrl}/api/moralis/proxy/wallets/${encodeURIComponent(address)}/tokens?${qs}`;
+                    const res = await fetch(url);
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    const json = (await res.json());
+                    const page = (json?.data ?? json);
+                    if (page?.result?.length > 0)
+                        allResults.push(...page.result);
+                    cursor = page?.cursor ?? null;
+                } while (cursor);
+                const data = { result: allResults };
+                if (data?.result?.length > 0) {
+                    // Filter by positive balance
+                    data.result = data.result.filter((t) => parseFloat(t.balance || '0') > 0);
+                    // Normalise ETH sentinel → zero address
+                    data.result = data.result.map((t) => ({
+                        ...t,
+                        token_address: t.token_address.toLowerCase() === ETH_SENTINEL ? ZERO_ADDRESS : t.token_address,
+                    }));
+                    // Enrich prices from Pantograph
+                    await this.enrichTokenPrices(data.result, moralisChain);
+                    // Drop tokens whose value is known AND below minimum
+                    data.result = data.result.filter((t) => t.usd_value == null || t.usd_value >= MINIMUM_TOKEN_BALANCE_PRICE_USD);
+                }
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    /**
+     * Get token balances for a Solana wallet address via Moralis Cortex AI.
+     * Since Moralis REST proxy does not natively support Solana token balances,
+     * we leverage Cortex AI to retrieve and structure the data.
+     */
+    async getWalletTokenBalancesSolanaAddress(params) {
+        const { address } = params;
+        if (!address)
+            return { success: false, error: 'Solana address is required' };
+        const prompt = [
+            `Retrieve all SPL token balances and the native SOL balance for the Solana wallet address: ${address}.`,
+            '',
+            'Return the data as a valid JSON array (no markdown, no explanation, no commentary).',
+            'Each element must be an object with exactly these fields:',
+            '- "token_address": string (the token mint address, or "So11111111111111111111111111111111111111112" for native SOL)',
+            '- "symbol": string (token ticker symbol)',
+            '- "name": string (full token name)',
+            '- "decimals": number',
+            '- "balance": string (raw balance as a string, without decimal formatting)',
+            '- "balance_formatted": string (human-readable balance with decimals applied)',
+            '- "usd_price": number or null (current USD price per token)',
+            '- "usd_value": number or null (total USD value = balance_formatted × usd_price)',
+            '- "possible_spam": boolean (true if the token is likely spam or a scam)',
+            '- "native_token": boolean (true only for native SOL)',
+            '- "logo": string or null (token logo URL if available)',
+            '',
+            'Rules:',
+            '- Include ONLY tokens with a balance greater than 0.',
+            '- Always include native SOL if the wallet holds any.',
+            '- Sort by usd_value descending (highest value first), with null values at the end.',
+            '- Respond with ONLY the JSON array. No extra text.',
+        ].join('\n');
+        const cortexResult = await this.chatWithCortex({ prompt });
+        if (!cortexResult.success || !cortexResult.data?.text) {
+            return { success: false, error: cortexResult.error ?? 'Failed to get Solana token balances from Cortex AI' };
+        }
+        try {
+            // Extract JSON array from the response (strip potential markdown fences)
+            const raw = cortexResult.data.text
+                .replace(/```(?:json)?\s*/g, '')
+                .replace(/```/g, '')
+                .trim();
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed)) {
+                return { success: false, error: 'Cortex AI returned non-array response' };
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let result = parsed.map((t) => ({
+                token_address: t.token_address ?? '',
+                symbol: t.symbol ?? '',
+                name: t.name ?? '',
+                logo: t.logo ?? undefined,
+                thumbnail: t.logo ?? undefined,
+                decimals: t.decimals ?? 0,
+                balance: String(t.balance ?? '0'),
+                balance_formatted: String(t.balance_formatted ?? '0'),
+                possible_spam: t.possible_spam ?? false,
+                verified_contract: false,
+                native_token: t.native_token ?? false,
+                usd_price: t.usd_price ?? undefined,
+                usd_value: t.usd_value ?? undefined,
+            }));
+            // Enrich prices & logos from Pantograph (Solana chain)
+            await this.enrichTokenPrices(result, 'solana');
+            // Drop tokens whose value is known AND below minimum
+            result = result.filter((t) => t.usd_value == null || t.usd_value >= MINIMUM_TOKEN_BALANCE_PRICE_USD);
+            return { success: true, data: { result } };
+        }
+        catch {
+            return { success: false, error: 'Failed to parse Cortex AI response as token balances' };
+        }
+    }
+    // =========================================================================
+    // Token Metadata
+    // =========================================================================
+    /**
+     * Get metadata + price for a single token by contract address.
+     */
+    async getTokenMetadata(params) {
+        const { address, chain } = params;
+        if (!address)
+            return { success: false, error: 'Token address is required' };
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        // Try Pantograph first (single source for metadata + price)
+        const pantographMeta = await this.pantograph.getTokenMetadata(address, moralisChain);
+        if (pantographMeta)
+            return { success: true, data: pantographMeta };
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                // Fallback to Moralis proxy
+                const [metaRes, priceRes] = await Promise.allSettled([
+                    fetch(`${this.baseUrl}/api/moralis/proxy/erc20/metadata?${buildQueryString({ chain: moralisChain, addresses: [address] })}`),
+                    fetch(`${this.baseUrl}/api/moralis/proxy/erc20/${encodeURIComponent(address)}/price?${buildQueryString({ chain: moralisChain, include: 'percent_change' })}`),
+                ]);
+                let meta = null;
+                if (metaRes.status === 'fulfilled' && metaRes.value.ok) {
+                    const metaJson = (await metaRes.value.json());
+                    const metaList = Array.isArray(metaJson?.data) ? metaJson.data : Array.isArray(metaJson) ? metaJson : [];
+                    meta = metaList[0];
+                }
+                if (!meta) {
+                    lastError = 'Token metadata not found';
+                    if (attempt < MAX_RETRIES)
+                        await delay(RETRY_DELAY_MS);
+                    continue;
+                }
+                let priceData = null;
+                if (priceRes.status === 'fulfilled' && priceRes.value.ok) {
+                    const priceJson = (await priceRes.value.json());
+                    priceData = priceJson?.data ?? priceJson;
+                }
+                return {
+                    success: true,
+                    data: {
+                        ...meta,
+                        ...(priceData?.usd_price ? { usd_price: priceData?.usd_price } : {}),
+                        ...(priceData?.usd_price_change_percentage_24h
+                            ? { usd_price_change_percentage_24h: priceData?.usd_price_change_percentage_24h }
+                            : {}),
+                    },
+                };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet NFTs
+    // =========================================================================
+    /**
+     * Get NFTs owned by a wallet.
+     */
+    async getWalletNFTs(params) {
+        const { address, chain, limit = 10, excludeSpam = true, cursor, tokenAddresses, includePrices, format = 'decimal', } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {
+                    chain: moralisChain,
+                    format,
+                    limit,
+                    exclude_spam: excludeSpam,
+                    media_items: true,
+                    normalizeMetadata: true,
+                };
+                if (cursor)
+                    query.cursor = cursor;
+                if (includePrices)
+                    query.include_prices = true;
+                if (tokenAddresses && tokenAddresses.length > 0) {
+                    query['token_addresses'] = tokenAddresses;
+                }
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/${encodeURIComponent(address)}/nft?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const data = (json?.data ?? json);
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // NFT Metadata (by contract + tokenId)
+    // =========================================================================
+    /**
+     * Get the full metadata for a single NFT identified by its contract address
+     * and token id via the Moralis `GET /nft/{address}/{token_id}` endpoint.
+     *
+     * Returns normalized metadata (name, description, image, attributes),
+     * media variants, floor-price, rarity, collection socials and sync
+     * timestamps. Only supported on EVM chains.
+     *
+     * Moralis docs: https://docs.moralis.com/data-api/evm/nft/metadata/nft-metadata
+     */
+    async getNftMetadata(params) {
+        const { address, tokenId, chain, format = 'decimal', normalizeMetadata = true, mediaItems = true, include, } = params;
+        if (!address)
+            return { success: false, error: 'NFT contract address is required' };
+        if (tokenId == null || tokenId === '')
+            return { success: false, error: 'Token ID is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'NFT metadata lookup by token ID is only supported on EVM chains' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {
+                    chain: moralisChain,
+                    format,
+                    normalizeMetadata,
+                    media_items: mediaItems,
+                };
+                if (include)
+                    query.include = include;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/nft/${encodeURIComponent(address)}/${encodeURIComponent(tokenId)}?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const data = (json?.data ?? json);
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // NFT Contract Metadata
+    // =========================================================================
+    /**
+     * Get metadata for an NFT contract (name, symbol, contract_type).
+     *
+     * For EVM addresses, queries the Moralis REST proxy directly.
+     * For non-EVM addresses (e.g. Solana), delegates to Cortex AI.
+     */
+    async getNftContractMetadata(params) {
+        const { address, chain } = params;
+        if (!address)
+            return { success: false, error: 'Contract address is required' };
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chain: moralisChain });
+                const url = `${this.baseUrl}/api/moralis/proxy/nft/${encodeURIComponent(address)}/metadata?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const data = (json?.data ?? json);
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet Transaction History (Moralis REST)
+    // =========================================================================
+    /**
+     * Get a wallet's decoded on-chain transaction history via the Moralis
+     * `GET /wallets/{address}/history` endpoint.
+     *
+     * Moralis returns each transaction already categorised (send, token swap,
+     * nft purchase, airdrop, mint, contract interaction, …) with a human-readable
+     * summary and decoded native / ERC-20 / NFT transfer arrays attached.
+     *
+     * Pagination is supported via `cursor`. Pass the cursor from a previous
+     * response back in to fetch the next page.
+     *
+     * Solana is not supported by this REST endpoint. Only EVM addresses are
+     * accepted.
+     */
+    async getWalletHistory(params) {
+        const { address, chain, limit = 25, fromDate, toDate, fromBlock, toBlock, cursor, order = 'DESC', includeInternalTransactions, nftMetadata, } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet history is only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        const safeLimit = Math.max(1, Math.min(100, Math.floor(limit)));
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {
+                    chain: moralisChain,
+                    limit: safeLimit,
+                    order,
+                };
+                if (fromDate)
+                    query.from_date = fromDate;
+                if (toDate)
+                    query.to_date = toDate;
+                if (fromBlock != null)
+                    query.from_block = fromBlock;
+                if (toBlock != null)
+                    query.to_block = toBlock;
+                if (cursor)
+                    query.cursor = cursor;
+                if (includeInternalTransactions != null) {
+                    query.include_internal_transactions = includeInternalTransactions;
+                }
+                if (nftMetadata != null)
+                    query.nft_metadata = nftMetadata;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/wallets/${encodeURIComponent(address)}/history?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet ERC-20 Transfers  (GET /{address}/erc20/transfers)
+    // =========================================================================
+    /**
+     * Get every ERC-20 transfer involving a wallet, optionally filtered by one
+     * or more token contract addresses.
+     *
+     * Use this to answer questions like:
+     *   - "When did I last send USDC and to whom?"
+     *   - "Who have I sent token 0x… to?"
+     *   - "Who sent me USDC?"
+     *   - "Show all USDT transfers for my wallet"
+     */
+    async getWalletTokenTransfers(params) {
+        const { address, chain, contractAddresses, limit = 25, fromDate, toDate, fromBlock, toBlock, cursor, order = 'DESC', } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'ERC-20 transfers are only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        const safeLimit = Math.max(1, Math.min(100, Math.floor(limit)));
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {
+                    chain: moralisChain,
+                    limit: safeLimit,
+                    order,
+                };
+                if (fromDate)
+                    query.from_date = fromDate;
+                if (toDate)
+                    query.to_date = toDate;
+                if (fromBlock != null)
+                    query.from_block = fromBlock;
+                if (toBlock != null)
+                    query.to_block = toBlock;
+                if (cursor)
+                    query.cursor = cursor;
+                if (contractAddresses?.length)
+                    query.contract_addresses = contractAddresses;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/${encodeURIComponent(address)}/erc20/transfers?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet NFT Transfers  (GET /{address}/nft/transfers)
+    // =========================================================================
+    /**
+     * Get every NFT transfer involving a wallet, optionally filtered by one
+     * or more NFT contract addresses.
+     *
+     * Use this to answer questions like:
+     *   - "Which NFTs did I sell?"
+     *   - "Who did I send my NFTs to?"
+     *   - "Who sent me NFTs from collection 0x…?"
+     *   - "Show all NFT transfers with last sale price"
+     */
+    async getWalletNftTransfers(params) {
+        const { address, chain, contractAddresses, limit = 25, fromDate, toDate, fromBlock, toBlock, cursor, order = 'DESC', includePrices, format = 'decimal', } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'NFT transfers are only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        const safeLimit = Math.max(1, Math.min(100, Math.floor(limit)));
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {
+                    chain: moralisChain,
+                    limit: safeLimit,
+                    order,
+                    format,
+                };
+                if (fromDate)
+                    query.from_date = fromDate;
+                if (toDate)
+                    query.to_date = toDate;
+                if (fromBlock != null)
+                    query.from_block = fromBlock;
+                if (toBlock != null)
+                    query.to_block = toBlock;
+                if (cursor)
+                    query.cursor = cursor;
+                if (contractAddresses?.length)
+                    query.contract_addresses = contractAddresses;
+                if (includePrices != null)
+                    query.include_prices = includePrices;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/${encodeURIComponent(address)}/nft/transfers?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Token Holders  (GET /erc20/{address}/holders)
+    // =========================================================================
+    /**
+     * Get the paginated list of holders for an ERC-20 token.
+     *
+     * URL: GET /api/moralis/proxy/erc20/{contractAddress}/holders
+     *
+     * Use to answer questions like:
+     *   - "Who holds USDC?"
+     *   - "Show top holders of 0x…"
+     *   - "How many wallets hold this token?"
+     *   - "What % does the biggest holder control?"
+     */
+    async getTokenHolders(params) {
+        const { address, chain } = params;
+        if (!address)
+            return { success: false, error: 'Contract address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Token holders is only supported for EVM contract addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chain: moralisChain });
+                const url = `${this.baseUrl}/api/moralis/proxy/erc20/${encodeURIComponent(address)}/holders?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet Net Worth
+    // =========================================================================
+    /**
+     * Get a wallet's total net worth in USD, broken down per chain.
+     *
+     * URL: GET /api/moralis/proxy/wallets/{address}/net-worth
+     *
+     * Use to answer questions like:
+     *   - "What's my total wallet value?"
+     *   - "How much is my portfolio worth on each chain?"
+     */
+    async getWalletNetWorth(params) {
+        const { address, chains, excludeSpam, excludeUnverifiedContracts, maxTokenInactivity, minPairSideLiquidityUsd } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet net worth is only supported for EVM addresses' };
+        }
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {};
+                if (chains && chains.length > 0)
+                    query.chains = chains.map((c) => toMoralisChain(c));
+                if (excludeSpam != null)
+                    query.exclude_spam = excludeSpam;
+                if (excludeUnverifiedContracts != null)
+                    query.exclude_unverified_contracts = excludeUnverifiedContracts;
+                if (maxTokenInactivity != null)
+                    query.max_token_inactivity = maxTokenInactivity;
+                if (minPairSideLiquidityUsd != null)
+                    query.min_pair_side_liquidity_usd = minPairSideLiquidityUsd;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/wallets/${encodeURIComponent(address)}/net-worth${qs ? `?${qs}` : ''}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet PnL (Profitability)
+    // =========================================================================
+    /**
+     * Get aggregate profit-and-loss summary for a wallet.
+     *
+     * URL: GET /api/moralis/proxy/wallets/{address}/profitability/summary
+     *
+     * Mainnet only. Moralis supports: Ethereum (0x1), Base (0x2105), Polygon (0x89).
+     */
+    async getWalletPnlSummary(params) {
+        const { address, chain, days } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet PnL summary is only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = { chain: moralisChain };
+                if (days)
+                    query.days = days;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/wallets/${encodeURIComponent(address)}/profitability/summary?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    /**
+     * Get per-token profit-and-loss breakdown for a wallet.
+     *
+     * URL: GET /api/moralis/proxy/wallets/{address}/profitability
+     *
+     * Mainnet only. Moralis supports: Ethereum (0x1), Base (0x2105), Polygon (0x89).
+     * tokenAddresses supports up to 25 addresses.
+     */
+    async getWalletPnl(params) {
+        const { address, chain, days, tokenAddresses } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet PnL is only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = { chain: moralisChain };
+                if (days)
+                    query.days = days;
+                if (tokenAddresses && tokenAddresses.length > 0) {
+                    query.token_addresses = tokenAddresses.slice(0, 25);
+                }
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/wallets/${encodeURIComponent(address)}/profitability?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Transaction by Hash  (GET /transaction/{hash}?decode=true)
+    // =========================================================================
+    /**
+     * Get a decoded transaction by its hash.
+     *
+     * URL: GET /api/moralis/proxy/transaction/{transactionHash}?chain=…&decode=true
+     *
+     * Returns full transaction details including decoded function call and
+     * decoded event logs, along with address labels and entity names.
+     */
+    async getTransactionByHash(params) {
+        const { transactionHash, chain } = params;
+        if (!transactionHash)
+            return { success: false, error: 'Transaction hash is required' };
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chain: moralisChain });
+                const url = `${this.baseUrl}/api/moralis/proxy/transaction/${encodeURIComponent(transactionHash)}/verbose?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet Approvals — active ERC-20 token approvals
+    // =========================================================================
+    /**
+     * List every active ERC-20 token approval granted by a wallet, paginated.
+     *
+     * URL: GET /api/moralis/proxy/wallets/{address}/approvals?chain=…&limit=…&cursor=…
+     *
+     * Moralis docs: https://docs.moralis.com/data-api/evm/wallet/approvals
+     *
+     * Mainnet EVM only. Each row includes the approved token (with current
+     * balance, USD price, `usd_at_risk`) and the spender (address, label,
+     * entity).
+     */
+    async getWalletApprovals(params) {
+        const { address, chain, limit, cursor } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet approvals are only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = { chain: moralisChain };
+                if (limit != null)
+                    query.limit = limit;
+                if (cursor)
+                    query.cursor = cursor;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/wallets/${encodeURIComponent(address)}/approvals?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Wallet DeFi — Protocols summary & positions
+    // =========================================================================
+    /**
+     * Get a DeFi summary for a wallet: aggregate USD value, unclaimed rewards
+     * and a per-protocol breakdown of where the wallet has positions.
+     *
+     * URL: GET /api/moralis/proxy/wallets/{address}/defi/summary?chain=…
+     *
+     * Moralis docs: https://docs.moralis.com/data-api/evm/wallet/wallet-protocols
+     *
+     * Mainnet EVM only.
+     */
+    async getWalletDefiSummary(params) {
+        const { address, chain } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet DeFi summary is only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chains: moralisChain });
+                const url = `${this.v1BaseUrl}/api/moralis-v1/proxy/wallets/${encodeURIComponent(address)}/defi/summary?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    /**
+     * Get every DeFi position a wallet holds across all supported protocols,
+     * each enriched with the owning protocol's identity.
+     *
+     * URL: GET /api/moralis/proxy/wallets/{address}/defi/positions?chain=…
+     *
+     * Moralis docs: https://docs.moralis.com/data-api/evm/wallet/wallet-positions
+     */
+    async getWalletDefiPositions(params) {
+        const { address, chain } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet DeFi positions are only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chains: moralisChain });
+                const url = `${this.v1BaseUrl}/api/moralis-v1/proxy/wallets/${encodeURIComponent(address)}/defi/positions?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = normalizeDefiPositionsPayload(payload);
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    /**
+     * Get detailed positions a wallet holds inside a specific protocol
+     * (e.g. `uniswap-v3`, `aave-v3`, `lido`).
+     *
+     * URL: GET /api/moralis/proxy/wallets/{address}/defi/{protocol}/positions?chain=…
+     *
+     * Moralis docs: https://docs.moralis.com/data-api/evm/wallet/detailed-positions
+     */
+    async getWalletDefiProtocolPositions(params) {
+        const { address, protocol, chain } = params;
+        if (!address)
+            return { success: false, error: 'Address is required' };
+        if (!protocol)
+            return { success: false, error: 'Protocol identifier is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Wallet DeFi protocol positions are only supported for EVM addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chains: moralisChain });
+                const url = `${this.v1BaseUrl}/api/moralis-v1/proxy/wallets/${encodeURIComponent(address)}/defi/${encodeURIComponent(protocol)}/positions?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const raw = json;
+                const r = raw.result;
+                const data = {
+                    protocol_id: r.protocolId,
+                    protocol_name: r.protocolName,
+                    protocol_url: r.protocolUrl ?? '',
+                    protocol_logo: r.protocolLogo ?? '',
+                    total_usd_value: r.totalUsd ?? 0,
+                    total_unclaimed_usd_value: r.totalUnclaimedUsd ?? null,
+                    positions: r.positions.map((p) => ({
+                        label: p.label,
+                        address: p.address,
+                        balance_usd: p.balanceUsd ?? 0,
+                        total_unclaimed_usd_value: p.unclaimedUsd ?? 0,
+                        position_details: p.details,
+                        tokens: p.tokens.map((t) => ({
+                            token_type: t.tokenType,
+                            address: t.address,
+                            contract_address: t.address,
+                            name: t.name ?? '',
+                            symbol: t.symbol ?? '',
+                            decimals: t.decimals ?? 18,
+                            logo: t.logo,
+                            balance: t.balance ?? '0',
+                            balance_formatted: t.balanceFormatted ?? '0',
+                            usd_price: t.usdPrice,
+                            usd_value: t.usdValue,
+                        })),
+                    })),
+                };
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Cortex AI Chat
+    // =========================================================================
+    /**
+     * Chat with Moralis Cortex AI for blockchain insights.
+     */
+    async chatWithCortex(params) {
+        const { prompt, model, systemPrompt, maxRetries = 5 } = params;
+        if (!prompt)
+            return { success: false, error: 'Prompt is required' };
+        const fullPrompt = systemPrompt ? `${systemPrompt}\n\n---\n\nCurrent User's question: ${prompt}` : prompt;
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                const url = `${this.baseUrl}/api/moralis-cortex/proxy/chat`;
+                const res = await fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Accept: 'application/json',
+                    },
+                    body: JSON.stringify({
+                        prompt: fullPrompt,
+                        model: model ?? this.cortexModel,
+                        stream: false,
+                    }),
+                });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const data = (json?.data ?? json);
+                if (!data?.text?.trim()) {
+                    lastError = 'Empty response from Cortex AI';
+                    if (attempt < maxRetries)
+                        await delay(RETRY_DELAY_MS);
+                    continue;
+                }
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < maxRetries)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Search Tokens by Key — delegates to PantographService
+    // =========================================================================
+    /** Search for tokens by symbol or name keyword on a specific chain. */
+    async searchTokensByKey(params) {
+        return this.pantograph.searchTokensByKey(params);
+    }
+    // =========================================================================
+    // Token Analytics
+    // =========================================================================
+    /**
+     * Detailed trading analytics for a single token: buy/sell volume, unique
+     * buyers/sellers, transaction counts, unique wallets, price change,
+     * current USD price, total liquidity and FDV — all broken down across
+     * 5min / 1h / 6h / 24h windows.
+     *
+     * URL: GET /api/moralis/proxy/tokens/{tokenAddress}/analytics
+     * Upstream: GET https://deep-index.moralis.io/api/v2.2/tokens/{tokenAddress}/analytics
+     *
+     * Use to answer questions like:
+     *   - "How is PEPE trading today?"
+     *   - "What's the 24h buy vs sell volume for USDC?"
+     *   - "How many unique wallets interacted with this token in the last hour?"
+     *   - "Is buying or selling pressure stronger for this token?"
+     */
+    async getTokenAnalytics(params) {
+        const { address, chain } = params;
+        if (!address)
+            return { success: false, error: 'Token contract address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Token analytics is only supported for EVM contract addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chain: moralisChain });
+                const url = `${this.baseUrl}/api/moralis/proxy/tokens/${encodeURIComponent(address)}/analytics?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Token Score
+    // =========================================================================
+    /**
+     * Composite 0–100 health/safety score for a single token, plus the
+     * underlying metrics Moralis uses to compute it: current USD price, paired
+     * liquidity, multi-timeframe volume and transaction counts (10m / 30m /
+     * 1h / 4h / 12h / 1d / 7d / 30d), and supply concentration (total + % held
+     * by the top 10 wallets).
+     *
+     * URL: GET /api/moralis/proxy/tokens/{tokenAddress}/score
+     * Upstream: GET https://deep-index.moralis.io/api/v2.2/tokens/{tokenAddress}/score
+     *
+     * Use to answer questions like:
+     *   - "Is PEPE a safe token?" (→ score)
+     *   - "What's the health score of this token?"
+     *   - "How concentrated is X's supply among top holders?" (→ metrics.supply.top10Percent)
+     *   - "How much volume did this token do over the last 7 days?" (→ metrics.volumeUsd.7d)
+     */
+    async getTokenScore(params) {
+        const { address, chain } = params;
+        if (!address)
+            return { success: false, error: 'Token contract address is required' };
+        if (!(0, web3_1.isAddressEVM)(address)) {
+            return { success: false, error: 'Token score is only supported for EVM contract addresses' };
+        }
+        const moralisChain = toMoralisChain(chain);
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const qs = buildQueryString({ chain: moralisChain });
+                const url = `${this.baseUrl}/api/moralis/proxy/tokens/${encodeURIComponent(address)}/score?${qs}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = payload;
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Trending Tokens
+    // =========================================================================
+    /**
+     * List tokens trending on-chain based on trading activity, volume, liquidity
+     * and holder growth. Moralis returns cross-chain results by default; pass a
+     * `chain` to scope to a single network.
+     *
+     * URL: GET /api/moralis/proxy/tokens/trending
+     * Upstream: GET https://deep-index.moralis.io/api/v2.2/tokens/trending
+     *
+     * Use to answer questions like:
+     *   - "What tokens are trending right now?"
+     *   - "Show me the hottest tokens on Base"
+     *   - "Which tokens have the most trading activity today?"
+     */
+    async getTrendingTokens(params) {
+        const chain = params?.chain;
+        const limit = params?.limit;
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {};
+                if (chain)
+                    query.chain = toMoralisChain(chain);
+                if (limit != null)
+                    query.limit = limit;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/tokens/trending${qs ? `?${qs}` : ''}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = normalizeArrayLikePayload(payload);
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Top Gainers (Discovery)
+    // =========================================================================
+    /**
+     * List tokens with the highest USD price increase over a given timeframe.
+     * Supports optional filters for minimum market cap and security score.
+     *
+     * URL: GET /api/moralis/proxy/discovery/tokens/top-gainers
+     * Upstream: GET https://deep-index.moralis.io/api/v2.2/discovery/tokens/top-gainers
+     *
+     * Use to answer questions like:
+     *   - "What are today's top gainers?"
+     *   - "Which tokens pumped the most this week on Arbitrum?"
+     *   - "Show me safe tokens (security score ≥ 80) that gained in the last hour"
+     */
+    async getTopGainers(params) {
+        const { chain, timeFrame, minMarketCap, securityScore } = params ?? {};
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {};
+                if (chain)
+                    query.chain = toMoralisChain(chain);
+                if (timeFrame)
+                    query.time_frame = timeFrame;
+                if (minMarketCap != null)
+                    query.min_market_cap = minMarketCap;
+                if (securityScore != null)
+                    query.security_score = securityScore;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/discovery/tokens/top-gainers${qs ? `?${qs}` : ''}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = normalizeArrayLikePayload(payload);
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Top Losers (Discovery)
+    // =========================================================================
+    /**
+     * List tokens with the largest USD price decrease over a given timeframe.
+     * Same filter set as top-gainers (min market cap, security score) and
+     * identical response shape — only the ranking direction differs.
+     *
+     * URL: GET /api/moralis/proxy/discovery/tokens/top-losers
+     * Upstream: GET https://deep-index.moralis.io/api/v2.2/discovery/tokens/top-losers
+     *
+     * Use to answer questions like:
+     *   - "What are today's biggest losers?"
+     *   - "Which tokens dumped the most this week on BSC?"
+     *   - "Worst performers in the last 24h with market cap over $50M"
+     */
+    async getTopLosers(params) {
+        const { chain, timeFrame, minMarketCap, securityScore } = params ?? {};
+        let lastError = 'Unknown error';
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const query = {};
+                if (chain)
+                    query.chain = toMoralisChain(chain);
+                if (timeFrame)
+                    query.time_frame = timeFrame;
+                if (minMarketCap != null)
+                    query.min_market_cap = minMarketCap;
+                if (securityScore != null)
+                    query.security_score = securityScore;
+                const qs = buildQueryString(query);
+                const url = `${this.baseUrl}/api/moralis/proxy/discovery/tokens/top-losers${qs ? `?${qs}` : ''}`;
+                const res = await fetch(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const json = (await res.json());
+                const payload = json?.data ?? json;
+                const data = normalizeArrayLikePayload(payload);
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : 'Unknown error';
+                if (attempt < MAX_RETRIES)
+                    await delay(RETRY_DELAY_MS);
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    // =========================================================================
+    // Private helpers
+    // =========================================================================
+    /** Enrich token balances with price/logo data. Delegates to PantographService. */
+    async enrichTokenPrices(tokens, moralisChain) {
+        return this.pantograph.enrichTokenPrices(tokens, moralisChain);
+    }
+}
+exports.MoralisService = MoralisService;
+//# sourceMappingURL=MoralisService.js.map