helius-mcp 0.5.3 → 1.2.0

package/dist/tools/transactions.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { getHeliusClient, hasApiKey, getRpcUrl } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatSol, formatAddress, formatTimestamp } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
+import { mcpText, validateEnum, handleToolError, http400Error } from '../utils/errors.js';
 import bs58 from 'bs58';
 // ─── Helpers ───
 const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
@@ -30,9 +31,8 @@ function decodeComputeBudget(dataBase58) {
         return null;
     }
 }
-// Shared helper: call getTransactionsForAddress (Helius JSON-RPC) — supports native sortOrder asc/desc
-async function fetchTransactionsForAddress(address, params) {
-    const url = getRpcUrl();
+// Shared helper: call getTransactionsForAddress via SDK (Helius custom RPC method)
+async function fetchTransactionsForAddress(helius, address, params) {
     const reqParams = {
         transactionDetails: params.transactionDetails,
         sortOrder: params.sortOrder,
@@ -43,17 +43,8 @@ async function fetchTransactionsForAddress(address, params) {
         reqParams.paginationToken = params.paginationToken;
     if (params.filters && Object.keys(params.filters).length > 0)
         reqParams.filters = params.filters;
-    const response = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            jsonrpc: '2.0',
-            id: 'get-transactions-for-address',
-            method: 'getTransactionsForAddress',
-            params: [address, reqParams]
-        })
-    });
-    return await response.json();
+    // SDK returns { data, paginationToken } directly
+    return await helius.getTransactionsForAddress([address, reqParams]);
 }
 const BASE58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{86,88}$/;
 function validateSignatures(sigs) {
@@ -79,10 +70,21 @@ async function fetchTokenMetadata(helius, mints) {
     const metadata = new Map();
     if (mints.size === 0)
         return metadata;
-    const assets = await helius.getAssetBatch({ ids: [...mints] });
-    for (const asset of assets) {
-        if (asset?.id)
-            metadata.set(asset.id, asset);
+    // Filter out empty/invalid mint strings before calling the API
+    const validMints = [...mints].filter(m => m && m.trim().length > 0);
+    if (validMints.length === 0)
+        return metadata;
+    try {
+        const assets = await helius.getAssetBatch({ ids: validMints });
+        for (const asset of assets) {
+            if (asset?.id)
+                metadata.set(asset.id, asset);
+        }
+    }
+    catch {
+        // If batch fails (e.g. invalid pubkeys in mint list), return empty metadata
+        // rather than crashing the entire tool call
+        return metadata;
     }
     // Enrich tokens missing symbol/name (batch response can have incomplete metadata)
     const unknownMints = [...metadata.entries()]
@@ -149,8 +151,8 @@ function formatSwapSummary(swap, tokenMetadata) {
 }
 export function registerTransactionTools(server) {
     // Parse Transactions (Enhanced API)
-    server.tool('parseTransactions', 'Parse one or more Solana transactions into human-readable format. Returns transaction type (SWAP, TRANSFER, NFT_SALE, etc.), source program (Jupiter, Raydium, Magic Eden, etc.), SOL and token transfers with token names and proper decimal formatting, fees (in both SOL and lamports), timestamp, program IDs involved, and a plain-English description. Use showRaw=true to see all program IDs, instruction accounts, instruction data bytes, inner instructions, and auto-decoded ComputeBudget instructions (CU limit, priority fee, heap frame).', {
-        signatures: z.array(z.string()).describe('Array of transaction signatures (base58 encoded). Can be 1 or more.'),
+    server.tool('parseTransactions', 'BEST FOR: decoding specific transaction(s) by signature. Parse one or more Solana transactions into human-readable format. Returns type, source, transfers, fees, timestamp, and description. Use showRaw=true for full instruction data. Credit cost: 100 credits/call.', {
+        signatures: z.array(z.string()).describe('Array of transaction signatures (base58 encoded, 86-88 characters). Can be 1 or more.'),
         showRaw: z.boolean().optional().default(false).describe('Include raw instruction data: program IDs, accounts, inner instructions. Useful for debugging or tracing fund flows.')
     }, async ({ signatures, showRaw }) => {
         if (!hasApiKey())
@@ -161,12 +163,7 @@ export function registerTransactionTools(server) {
         if (validSigs.length === 0) {
             const lines = ['**Invalid Signature Format**', '', 'None of the provided signatures are valid base58-encoded transaction signatures (expected 86-88 characters).', ''];
             invalidSigs.forEach(sig => lines.push(`- \`${sig}\``));
-            return {
-                content: [{
-                        type: 'text',
-                        text: lines.join('\n')
-                    }]
-            };
+            return mcpText(lines.join('\n'));
         }
         let transactions;
         try {
@@ -175,12 +172,9 @@ export function registerTransactionTools(server) {
             });
         }
         catch (err) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error fetching transactions:** ${err instanceof Error ? err.message : String(err)}`
-                    }]
-            };
+            return handleToolError(err, 'Error fetching transactions', [
+                http400Error('Parse Transactions Error'),
+            ]);
         }
         // Identify valid signatures that weren't returned (not found on-chain)
         const returnedSigs = new Set((transactions || []).map(tx => tx.signature));
@@ -196,12 +190,7 @@ export function registerTransactionTools(server) {
                 lines.push('**Not found on Solana mainnet** (may be pending, very old, or nonexistent):');
                 notFoundSigs.forEach(sig => lines.push(`- \`${sig}\``));
             }
-            return {
-                content: [{
-                        type: 'text',
-                        text: lines.join('\n')
-                    }]
-            };
+            return mcpText(lines.join('\n'));
         }
         const tokenMetadata = await fetchTokenMetadata(helius, collectMints(transactions));
         const outputLines = [];
@@ -212,7 +201,7 @@ export function registerTransactionTools(server) {
             const feeDisplay = tx.fee
                 ? `${formatSol(tx.fee)} (${tx.fee.toLocaleString()} lamports)`
                 : 'N/A';
-            outputLines.push(`**Transaction: ${tx.signature}**`, '', `**Type:** ${tx.type || 'UNKNOWN'}`, `**Source:** ${tx.source || 'N/A'}`, `**Fee:** ${feeDisplay}`, `**Fee Payer:** ${tx.feePayer || 'N/A'}`, `**Timestamp:** ${tx.timestamp ? formatTimestamp(tx.timestamp) : 'N/A'}`, `**Status:** ${tx.transactionError ? 'Failed' : 'Success'}`);
+            outputLines.push(`**Transaction: ${tx.signature}**`, '', `**Type:** ${tx.type || 'UNKNOWN'}`, `**Source:** ${tx.source || 'N/A'}`, `**Fee:** ${feeDisplay}`, `**Fee Payer:** ${tx.feePayer || 'N/A'}`, `**Timestamp:** ${tx.timestamp ? formatTimestamp(tx.timestamp) : 'N/A'}`, `**Status:** ${tx.transactionError ? '❌ Failed' : '✅ Success'}`);
             // Show error details for failed transactions
             if (tx.transactionError) {
                 let errDetail;
@@ -232,7 +221,7 @@ export function registerTransactionTools(server) {
             if (tx.description) {
                 outputLines.push('', `**Description:** ${tx.description}`);
             }
-            // Extract unique program IDs from instructions
+            // Extract unique program IDs from instructions (only show when ≤5 to reduce noise)
             if (tx.instructions && tx.instructions.length > 0) {
                 const programIds = new Set();
                 const collectProgramIds = (instructions) => {
@@ -244,9 +233,14 @@ export function registerTransactionTools(server) {
                 };
                 collectProgramIds(tx.instructions);
                 outputLines.push('', '**Programs Involved:**');
-                programIds.forEach(pid => {
+                const pidArray = Array.from(programIds);
+                const shown = pidArray.slice(0, 5);
+                shown.forEach(pid => {
                     outputLines.push(`- ${pid}`);
                 });
+                if (programIds.size > 5) {
+                    outputLines.push(`_(Showing 5 of ${programIds.size} programs)_`);
+                }
             }
             // Swap summary from events.swap
             if (tx.events?.swap) {
@@ -269,13 +263,16 @@ export function registerTransactionTools(server) {
                     outputLines.push(`- ${from} → ${to}: ${formattedAmount} ${tokenDisplay}`);
                 });
             }
+            // Skip SOL transfers when there's only 1 and a description already covers it
             if (tx.nativeTransfers && tx.nativeTransfers.length > 0) {
-                outputLines.push('', '**SOL Transfers:**');
-                tx.nativeTransfers.forEach((t) => {
-                    const from = t.fromUserAccount || 'unknown';
-                    const to = t.toUserAccount || 'unknown';
-                    outputLines.push(`- ${from} → ${to}: ${formatSol(t.amount)} (${t.amount.toLocaleString()} lamports)`);
-                });
+                if (!(tx.nativeTransfers.length === 1 && tx.description)) {
+                    outputLines.push('', '**SOL Transfers:**');
+                    tx.nativeTransfers.forEach((t) => {
+                        const from = t.fromUserAccount || 'unknown';
+                        const to = t.toUserAccount || 'unknown';
+                        outputLines.push(`- ${from} → ${to}: ${formatSol(t.amount)} (${t.amount.toLocaleString()} lamports)`);
+                    });
+                }
             }
             // Show raw instruction data if requested
             if (showRaw && tx.instructions) {
@@ -328,7 +325,7 @@ export function registerTransactionTools(server) {
                 const significantChanges = tx.accountData
                     .filter(a => a.nativeBalanceChange !== 0)
                     .sort((a, b) => Math.abs(b.nativeBalanceChange) - Math.abs(a.nativeBalanceChange))
-                    .slice(0, 10);
+                    .slice(0, 5);
                 if (significantChanges.length > 0) {
                     outputLines.push('', '**Account Balance Changes:**');
                     significantChanges.forEach(a => {
@@ -353,25 +350,20 @@ export function registerTransactionTools(server) {
             }
         }
         const fullText = outputLines.join('\n');
-        return {
-            content: [{
-                    type: 'text',
-                    text: truncateResponse(fullText)
-                }]
-        };
+        return mcpText(truncateResponse(fullText));
     });
     // Get Transaction History (unified: parsed, signatures, or raw mode)
-    server.tool('getTransactionHistory', 'Get transaction history for a Solana wallet. Supports three modes: "parsed" (default) returns human-readable decoded data with types, descriptions, actions, and fees. "signatures" returns a lightweight list of transaction signatures with slot/time/status. "raw" returns full raw data with advanced Helius filters (time/slot ranges, status, token accounts). All modes support sortOrder="asc" for finding wallet funding sources — no pagination needed. By default only successful transactions are shown; set status="any" or status="failed" to include failed ones.', {
+    server.tool('getTransactionHistory', 'BEST FOR: general-purpose transaction history. PREFER getWalletTransfers for sends/receives, getWalletHistory for balance deltas. Get transaction history for a wallet. Modes: "parsed" (~110 credits), "signatures" (~10 credits), "raw" (~10 credits). Supports sortOrder, status filters, and time/slot ranges.', {
         address: z.string().describe('Solana wallet address (base58 encoded)'),
-        mode: z.enum(['parsed', 'signatures', 'raw']).optional().default('parsed').describe('"parsed" = decoded human-readable history (default), "signatures" = lightweight signature list, "raw" = full data with advanced Helius filters'),
+        mode: z.string().optional().default('parsed').describe('"parsed" = decoded human-readable history (default), "signatures" = lightweight signature list, "raw" = full data with advanced Helius filters'),
         limit: z.number().optional().default(10).describe('Number of results (1-1000 for signatures, 1-100 for full/parsed)'),
-        sortOrder: z.enum(['asc', 'desc']).optional().default('desc').describe('"desc" = newest first (default), "asc" = oldest first (great for finding funding sources)'),
-        before: z.string().optional().describe('[signatures mode, desc only] Cursor: start searching backwards from this signature'),
-        until: z.string().optional().describe('[signatures mode, desc only] Cursor: search until this signature'),
+        sortOrder: z.string().optional().default('desc').describe('"desc" = newest first (default), "asc" = oldest first (great for finding funding sources)'),
+        before: z.string().optional().describe('[signatures mode, desc only] Cursor: transaction signature (base58 encoded, 86-88 characters) to start searching backwards from'),
+        until: z.string().optional().describe('[signatures mode, desc only] Cursor: transaction signature (base58 encoded, 86-88 characters) to search until'),
         paginationToken: z.string().optional().describe('Pagination token from previous response for fetching next page'),
-        transactionDetails: z.enum(['signatures', 'full']).optional().default('signatures').describe('[raw mode] "signatures" for basic info (up to 1000), "full" for complete transaction data (up to 100)'),
-        status: z.enum(['succeeded', 'failed', 'any']).optional().default('succeeded').describe('Filter by transaction status. Defaults to "succeeded" — set to "failed" or "any" to include failed transactions.'),
-        tokenAccounts: z.enum(['none', 'balanceChanged', 'all']).optional().describe('"none" = only direct transactions, "balanceChanged" = include token transfers, "all" = all token account activity'),
+        transactionDetails: z.string().optional().default('signatures').describe('[raw mode] "signatures" for basic info (up to 1000), "full" for complete transaction data (up to 100)'),
+        status: z.string().optional().default('succeeded').describe('Filter by transaction status. Defaults to "succeeded" — set to "failed" or "any" to include failed transactions.'),
+        tokenAccounts: z.string().optional().describe('"none" = only direct transactions, "balanceChanged" = include token transfers, "all" = all token account activity'),
         blockTimeGte: z.number().optional().describe('Filter: block time >= this Unix timestamp'),
         blockTimeLte: z.number().optional().describe('Filter: block time <= this Unix timestamp'),
         slotGte: z.number().optional().describe('Filter: slot >= this value'),
@@ -379,6 +371,25 @@ export function registerTransactionTools(server) {
     }, async ({ address, mode, limit, sortOrder, before, until, paginationToken, transactionDetails, status, tokenAccounts, blockTimeGte, blockTimeLte, slotGte, slotLte }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
+        const helius = getHeliusClient();
+        let err;
+        err = validateEnum(mode, ['parsed', 'signatures', 'raw'], 'Transaction History Error', 'mode');
+        if (err)
+            return err;
+        err = validateEnum(sortOrder, ['asc', 'desc'], 'Transaction History Error', 'sortOrder');
+        if (err)
+            return err;
+        err = validateEnum(transactionDetails, ['signatures', 'full'], 'Transaction History Error', 'transactionDetails');
+        if (err)
+            return err;
+        err = validateEnum(status, ['succeeded', 'failed', 'any'], 'Transaction History Error', 'status');
+        if (err)
+            return err;
+        if (tokenAccounts) {
+            err = validateEnum(tokenAccounts, ['none', 'balanceChanged', 'all'], 'Transaction History Error', 'tokenAccounts');
+            if (err)
+                return err;
+        }
         const filters = {};
         if (status)
             filters.status = status;
@@ -406,284 +417,203 @@ export function registerTransactionTools(server) {
             // Fast path: getSignaturesForAddress — cheap RPC call for latest sigs (desc only, no filters)
             if (useQuickPath) {
                 try {
-                    const url = getRpcUrl();
                     const rpcParams = { limit };
                     if (before)
                         rpcParams.before = before;
                     if (until)
                         rpcParams.until = until;
-                    const response = await fetch(url, {
-                        method: 'POST',
-                        headers: { 'Content-Type': 'application/json' },
-                        body: JSON.stringify({
-                            jsonrpc: '2.0',
-                            id: 'get-signatures-for-address',
-                            method: 'getSignaturesForAddress',
-                            params: [address, rpcParams]
-                        })
-                    });
-                    const json = await response.json();
-                    if (json.error) {
-                        return {
-                            content: [{
-                                    type: 'text',
-                                    text: `Error fetching signatures: ${json.error.message}`
-                                }]
-                        };
-                    }
-                    const sigs = json.result || [];
-                    if (sigs.length === 0) {
-                        return {
-                            content: [{
-                                    type: 'text',
-                                    text: `**Signatures for ${formatAddress(address)}**\n\nNo signatures found.`
-                                }]
-                        };
+                    // Kit returns bigint for slot/blockTime fields
+                    const sigs = await helius.getSignaturesForAddress(address, rpcParams);
+                    if (!sigs || sigs.length === 0) {
+                        return mcpText(`**Signatures for ${formatAddress(address)}**\n\nNo signatures found.`);
                     }
                     const lines = [`**Signatures for ${formatAddress(address)}** (${sigs.length} results, newest first${statusNote})`, ''];
                     sigs.forEach((sig) => {
-                        const sigStatus = sig.err ? '[FAILED]' : '[OK]';
-                        const time = sig.blockTime ? new Date(sig.blockTime * 1000).toISOString() : 'N/A';
+                        const sigStatus = sig.err ? '❌' : '✅';
+                        const blockTime = sig.blockTime != null ? Number(sig.blockTime) : null;
+                        const time = blockTime ? new Date(blockTime * 1000).toISOString() : 'N/A';
                         lines.push(`${sigStatus} ${sig.signature}`);
-                        lines.push(`   Slot: ${sig.slot.toLocaleString()} | Time: ${time}`);
+                        lines.push(`   Slot: ${Number(sig.slot).toLocaleString()} | Time: ${time}`);
                         if (sig.memo) {
                             lines.push(`   Memo: ${sig.memo}`);
                         }
                     });
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: lines.join('\n')
-                            }]
-                    };
+                    return mcpText(lines.join('\n'));
                 }
                 catch (err) {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: `Error fetching signatures: ${err instanceof Error ? err.message : String(err)}`
-                            }]
-                    };
+                    return handleToolError(err, 'Error fetching signatures');
                 }
             }
             // Full path: getTransactionsForAddress — needed for asc sort, filters, or paginationToken
-            const data = await fetchTransactionsForAddress(address, {
-                transactionDetails: 'signatures',
-                sortOrder,
-                limit,
-                ...(paginationToken && { paginationToken }),
-                ...(Object.keys(filters).length > 0 && { filters })
-            });
-            if (data.error) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Error**\n\n${data.error.message}`
-                        }]
-                };
-            }
-            const result = data.result;
-            if (!result || !result.data || result.data.length === 0) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Signatures for ${formatAddress(address)}**\n\nNo signatures found.`
-                        }]
-                };
-            }
-            const items = result.data;
-            const orderLabel = sortOrder === 'asc' ? 'oldest first' : 'newest first';
-            const lines = [`**Signatures for ${formatAddress(address)}** (${items.length} results, ${orderLabel}${statusNote})`, ''];
-            items.forEach((item) => {
-                const txStatus = item.err ? '[FAILED]' : '[OK]';
-                const time = item.blockTime ? new Date(item.blockTime * 1000).toISOString() : 'N/A';
-                lines.push(`${txStatus} ${item.signature}`);
-                lines.push(`   Slot: ${item.slot.toLocaleString()} | Time: ${time}`);
-                if (item.memo) {
-                    lines.push(`   Memo: ${item.memo}`);
+            try {
+                const result = await fetchTransactionsForAddress(helius, address, {
+                    transactionDetails: 'signatures',
+                    sortOrder,
+                    limit,
+                    ...(paginationToken && { paginationToken }),
+                    ...(Object.keys(filters).length > 0 && { filters })
+                });
+                if (!result || !result.data || result.data.length === 0) {
+                    return mcpText(`**Signatures for ${formatAddress(address)}**\n\nNo signatures found.`);
                 }
-            });
-            if (result.paginationToken) {
-                lines.push('', `**Next Page Token:** \`${result.paginationToken}\``);
-            }
-            return {
-                content: [{
-                        type: 'text',
-                        text: lines.join('\n')
-                    }]
-            };
-        }
-        // ─── RAW MODE ───
-        if (mode === 'raw') {
-            const data = await fetchTransactionsForAddress(address, {
-                transactionDetails: transactionDetails,
-                sortOrder,
-                limit,
-                ...(paginationToken && { paginationToken }),
-                ...(Object.keys(filters).length > 0 && { filters })
-            });
-            if (data.error) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Error**\n\n${data.error.message}`
-                        }]
-                };
-            }
-            const result = data.result;
-            if (!result || !result.data || result.data.length === 0) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Transactions for ${formatAddress(address)}**\n\nNo transactions found.`
-                        }]
-                };
-            }
-            const orderLabel = sortOrder === 'asc' ? 'oldest first' : 'newest first';
-            const lines = [`**Transactions for ${formatAddress(address)}** (${result.data.length} results, ${orderLabel}${statusNote})`, ''];
-            if (transactionDetails === 'signatures') {
                 const items = result.data;
+                const orderLabel = sortOrder === 'asc' ? 'oldest first' : 'newest first';
+                const lines = [`**Signatures for ${formatAddress(address)}** (${items.length} results, ${orderLabel}${statusNote})`, ''];
                 items.forEach((item) => {
-                    const txStatus = item.err ? '[FAILED]' : '[OK]';
+                    const txStatus = item.err ? '❌' : '✅';
                     const time = item.blockTime ? new Date(item.blockTime * 1000).toISOString() : 'N/A';
                     lines.push(`${txStatus} ${item.signature}`);
-                    lines.push(`   Slot: ${item.slot.toLocaleString()} | Index: ${item.transactionIndex} | Time: ${time}`);
+                    lines.push(`   Slot: ${item.slot.toLocaleString()} | Time: ${time}`);
                     if (item.memo) {
                         lines.push(`   Memo: ${item.memo}`);
                     }
                 });
+                if (result.paginationToken) {
+                    lines.push('', `**Next Page Token:** \`${result.paginationToken}\``);
+                }
+                return mcpText(lines.join('\n'));
             }
-            else {
-                const items = result.data;
-                items.forEach((item) => {
-                    const sig = item.transaction.signatures[0];
-                    const txStatus = item.meta.err ? '[FAILED]' : '[OK]';
-                    const time = item.blockTime ? new Date(item.blockTime * 1000).toISOString() : 'N/A';
-                    const fee = formatSol(item.meta.fee);
-                    lines.push(`${txStatus} ${sig}`);
-                    lines.push(`   Slot: ${item.slot.toLocaleString()} | Index: ${item.transactionIndex} | Time: ${time}`);
-                    lines.push(`   Fee: ${fee}`);
-                    // Show balance changes
-                    const balanceChanges = [];
-                    item.meta.preBalances.forEach((pre, idx) => {
-                        const post = item.meta.postBalances[idx];
-                        const change = post - pre;
-                        if (change !== 0) {
-                            const changeStr = change > 0 ? `+${formatSol(change)}` : formatSol(change);
-                            balanceChanges.push(changeStr);
+            catch (err) {
+                return handleToolError(err, 'Error fetching signatures');
+            }
+        }
+        // ─── RAW MODE ───
+        if (mode === 'raw') {
+            try {
+                const result = await fetchTransactionsForAddress(helius, address, {
+                    transactionDetails: transactionDetails,
+                    sortOrder,
+                    limit,
+                    ...(paginationToken && { paginationToken }),
+                    ...(Object.keys(filters).length > 0 && { filters })
+                });
+                if (!result || !result.data || result.data.length === 0) {
+                    return mcpText(`**Transactions for ${formatAddress(address)}**\n\nNo transactions found.`);
+                }
+                const orderLabel = sortOrder === 'asc' ? 'oldest first' : 'newest first';
+                const lines = [`**Transactions for ${formatAddress(address)}** (${result.data.length} results, ${orderLabel}${statusNote})`, ''];
+                if (transactionDetails === 'signatures') {
+                    const items = result.data;
+                    items.forEach((item) => {
+                        const txStatus = item.err ? '❌' : '✅';
+                        const time = item.blockTime ? new Date(item.blockTime * 1000).toISOString() : 'N/A';
+                        lines.push(`${txStatus} ${item.signature}`);
+                        lines.push(`   Slot: ${item.slot.toLocaleString()} | Index: ${item.transactionIndex} | Time: ${time}`);
+                        if (item.memo) {
+                            lines.push(`   Memo: ${item.memo}`);
                         }
                     });
-                    if (balanceChanges.length > 0) {
-                        lines.push(`   Balance changes: ${balanceChanges.slice(0, 3).join(', ')}${balanceChanges.length > 3 ? '...' : ''}`);
-                    }
-                });
+                }
+                else {
+                    const items = result.data;
+                    items.forEach((item) => {
+                        const sig = item.transaction.signatures[0];
+                        const txStatus = item.meta.err ? '❌' : '✅';
+                        const time = item.blockTime ? new Date(item.blockTime * 1000).toISOString() : 'N/A';
+                        const fee = formatSol(item.meta.fee);
+                        lines.push(`${txStatus} ${sig}`);
+                        lines.push(`   Slot: ${item.slot.toLocaleString()} | Index: ${item.transactionIndex} | Time: ${time}`);
+                        lines.push(`   Fee: ${fee}`);
+                        // Show balance changes
+                        const balanceChanges = [];
+                        item.meta.preBalances.forEach((pre, idx) => {
+                            const post = item.meta.postBalances[idx];
+                            const change = post - pre;
+                            if (change !== 0) {
+                                const changeStr = change > 0 ? `+${formatSol(change)}` : formatSol(change);
+                                balanceChanges.push(changeStr);
+                            }
+                        });
+                        if (balanceChanges.length > 0) {
+                            lines.push(`   Balance changes: ${balanceChanges.slice(0, 3).join(', ')}${balanceChanges.length > 3 ? '...' : ''}`);
+                        }
+                    });
+                }
+                if (result.paginationToken) {
+                    lines.push('', `**Next Page Token:** \`${result.paginationToken}\``);
+                }
+                return mcpText(lines.join('\n'));
             }
-            if (result.paginationToken) {
-                lines.push('', `**Next Page Token:** \`${result.paginationToken}\``);
+            catch (err) {
+                return handleToolError(err, 'Error fetching transactions');
             }
-            return {
-                content: [{
-                        type: 'text',
-                        text: lines.join('\n')
-                    }]
-            };
         }
         // ─── PARSED MODE (default) ───
-        // Step 1: Use getTransactionsForAddress to get sorted signatures in one call
-        const sigData = await fetchTransactionsForAddress(address, {
-            transactionDetails: 'signatures',
-            sortOrder,
-            limit: Math.min(limit, 100),
-            ...(paginationToken && { paginationToken }),
-            ...(Object.keys(filters).length > 0 && { filters })
-        });
-        if (sigData.error) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error**\n\n${sigData.error.message}`
-                    }]
-            };
-        }
-        const sigResult = sigData.result;
-        if (!sigResult || !sigResult.data || sigResult.data.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Transaction History for ${formatAddress(address)}**\n\nNo transactions found.`
-                    }]
-            };
-        }
-        const sortedSigs = sigResult.data.map(item => item.signature);
-        // Step 2: Send sorted signatures to Enhanced API for rich data
-        const helius = getHeliusClient();
-        // Batch in chunks of 100 (Enhanced API limit)
-        const allTransactions = [];
-        for (let i = 0; i < sortedSigs.length; i += 100) {
-            const batch = sortedSigs.slice(i, i + 100);
-            const enriched = await helius.enhanced.getTransactions({
-                transactions: batch
+        try {
+            // Step 1: Use getTransactionsForAddress to get sorted signatures in one call
+            const sigResult = await fetchTransactionsForAddress(helius, address, {
+                transactionDetails: 'signatures',
+                sortOrder,
+                limit: Math.min(limit, 100),
+                ...(paginationToken && { paginationToken }),
+                ...(Object.keys(filters).length > 0 && { filters })
             });
-            if (enriched)
-                allTransactions.push(...enriched);
-        }
-        if (allTransactions.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Transaction History for ${formatAddress(address)}**\n\nNo transactions could be enriched.`
-                    }]
-            };
-        }
-        // Re-sort to match original order (Enhanced API may return in different order)
-        const sigOrder = new Map(sortedSigs.map((sig, idx) => [sig, idx]));
-        allTransactions.sort((a, b) => (sigOrder.get(a.signature) ?? 999) - (sigOrder.get(b.signature) ?? 999));
-        const tokenMetadata = await fetchTokenMetadata(helius, collectMints(allTransactions));
-        const orderLabel = sortOrder === 'asc' ? 'oldest first' : 'newest first';
-        const lines = [`**Transaction History for ${formatAddress(address)}** (${allTransactions.length} transactions, ${orderLabel}${statusNote})`, ''];
-        allTransactions.forEach((tx) => {
-            const time = tx.timestamp ? formatTimestamp(tx.timestamp) : 'N/A';
-            const txStatus = tx.transactionError ? '[FAILED]' : '[OK]';
-            const type = tx.type || 'UNKNOWN';
-            const source = tx.source || '';
-            lines.push(`${txStatus} **${type}**${source ? ` (${source})` : ''} - ${time}`);
-            lines.push(`   Sig: \`${tx.signature}\``);
-            if (tx.description) {
-                lines.push(`   ${tx.description}`);
-            }
-            // Swap summary
-            if (tx.events?.swap) {
-                const swapSummary = formatSwapSummary(tx.events.swap, tokenMetadata);
-                if (swapSummary) {
-                    lines.push(`   Swap: ${swapSummary}`);
-                }
+            if (!sigResult || !sigResult.data || sigResult.data.length === 0) {
+                return mcpText(`**Transaction History for ${formatAddress(address)}**\n\nNo transactions found.`);
             }
-            // Compact token transfer summary (for non-swap transactions)
-            if (!tx.events?.swap && tx.tokenTransfers && tx.tokenTransfers.length > 0) {
-                const transferParts = tx.tokenTransfers.slice(0, 3).map((t) => {
-                    const asset = tokenMetadata.get(t.mint);
-                    const symbol = asset?.token_info?.symbol || asset?.content?.metadata?.symbol || asset?.content?.metadata?.name || formatAddress(t.mint);
-                    const decimals = asset?.token_info?.decimals ?? t.decimals ?? 0;
-                    const amount = t.tokenAmount.toLocaleString(undefined, { maximumFractionDigits: Math.min(decimals || 4, 4) });
-                    return `${amount} ${symbol}`;
+            const sortedSigs = sigResult.data.map(item => item.signature);
+            // Step 2: Send sorted signatures to Enhanced API for rich data
+            // Batch in chunks of 100 (Enhanced API limit)
+            const allTransactions = [];
+            for (let i = 0; i < sortedSigs.length; i += 100) {
+                const batch = sortedSigs.slice(i, i + 100);
+                const enriched = await helius.enhanced.getTransactions({
+                    transactions: batch
                 });
-                const moreCount = tx.tokenTransfers.length > 3 ? ` +${tx.tokenTransfers.length - 3} more` : '';
-                lines.push(`   Transfers: ${transferParts.join(', ')}${moreCount}`);
+                if (enriched)
+                    allTransactions.push(...enriched);
             }
-            if (tx.fee) {
-                lines.push(`   Fee: ${formatSol(tx.fee)}`);
+            if (allTransactions.length === 0) {
+                return mcpText(`**Transaction History for ${formatAddress(address)}**\n\nNo transactions could be enriched.`);
             }
-            lines.push('');
-        });
-        if (sigResult.paginationToken) {
-            lines.push(`**Next Page Token:** \`${sigResult.paginationToken}\``);
+            // Re-sort to match original order (Enhanced API may return in different order)
+            const sigOrder = new Map(sortedSigs.map((sig, idx) => [sig, idx]));
+            allTransactions.sort((a, b) => (sigOrder.get(a.signature) ?? 999) - (sigOrder.get(b.signature) ?? 999));
+            const tokenMetadata = await fetchTokenMetadata(helius, collectMints(allTransactions));
+            const orderLabel = sortOrder === 'asc' ? 'oldest first' : 'newest first';
+            const lines = [`**Transaction History for ${formatAddress(address)}** (${allTransactions.length} transactions, ${orderLabel}${statusNote})`, ''];
+            allTransactions.forEach((tx) => {
+                const time = tx.timestamp ? formatTimestamp(tx.timestamp) : 'N/A';
+                const txStatus = tx.transactionError ? '❌' : '✅';
+                const type = tx.type || 'UNKNOWN';
+                const source = tx.source || '';
+                lines.push(`${txStatus} **${type}**${source ? ` (${source})` : ''} - ${time}`);
+                lines.push(`   Sig: \`${tx.signature}\``);
+                if (tx.description) {
+                    lines.push(`   ${tx.description}`);
+                }
+                // Swap summary
+                if (tx.events?.swap) {
+                    const swapSummary = formatSwapSummary(tx.events.swap, tokenMetadata);
+                    if (swapSummary) {
+                        lines.push(`   Swap: ${swapSummary}`);
+                    }
+                }
+                // Compact token transfer summary (for non-swap transactions)
+                if (!tx.events?.swap && tx.tokenTransfers && tx.tokenTransfers.length > 0) {
+                    const transferParts = tx.tokenTransfers.slice(0, 3).map((t) => {
+                        const asset = tokenMetadata.get(t.mint);
+                        const symbol = asset?.token_info?.symbol || asset?.content?.metadata?.symbol || asset?.content?.metadata?.name || formatAddress(t.mint);
+                        const decimals = asset?.token_info?.decimals ?? t.decimals ?? 0;
+                        const amount = t.tokenAmount.toLocaleString(undefined, { maximumFractionDigits: Math.min(decimals || 4, 4) });
+                        return `${amount} ${symbol}`;
+                    });
+                    const moreCount = tx.tokenTransfers.length > 3 ? ` +${tx.tokenTransfers.length - 3} more` : '';
+                    lines.push(`   Transfers: ${transferParts.join(', ')}${moreCount}`);
+                }
+                if (tx.fee) {
+                    lines.push(`   Fee: ${formatSol(tx.fee)}`);
+                }
+                lines.push('');
+            });
+            if (sigResult.paginationToken) {
+                lines.push(`**Next Page Token:** \`${sigResult.paginationToken}\``);
+            }
+            const fullText = lines.join('\n');
+            return mcpText(truncateResponse(fullText));
+        }
+        catch (err) {
+            return handleToolError(err, 'Error fetching transaction history');
         }
-        const fullText = lines.join('\n');
-        return {
-            content: [{
-                    type: 'text',
-                    text: truncateResponse(fullText)
-                }]
-        };
     });
 }