helius-mcp 1.2.0 → 2.0.0

package/dist/tools/staking.js

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+import { address } from '@solana/kit';
+import { getHeliusClient, hasApiKey, getSessionWalletAddress } from '../utils/helius.js';
+import { mcpText, mcpError, handleToolError, isValidAddressFormat, missingParamError } from '../utils/errors.js';
+import { noApiKeyResponse } from './shared.js';
+import { resolveOwsOrKeypairSigner } from '../utils/ows.js';
+// ── Tool Registration ──
+export function registerStakingTools(server) {
+    // ── Stake SOL ──
+    server.tool('stakeSOL', 'BEST FOR: staking native SOL to the Helius validator to earn yield. ' +
+        'PREFER getStakeAccounts to view existing stake accounts, getWithdrawableAmount to check withdrawal eligibility. ' +
+        'Creates a new stake account, delegates to the Helius validator, and sends the transaction on-chain. ' +
+        'Requires a configured keypair (call generateKeypair if needed). ' +
+        'This is an irreversible on-chain transaction. ' +
+        'The Solana runtime requires a rent-exempt reserve (~0.00228 SOL) on top of the staked amount. ' +
+        'Credit cost: ~3 credits (CU simulation + priority fee estimate + send).', {
+        amount: z.number().positive().describe('Amount of SOL to stake (e.g., 1.0 for one SOL). This is the delegation amount; a small rent-exempt reserve (~0.00228 SOL) is added automatically.'),
+        owsWallet: z.string().optional().describe('OWS wallet name for policy-gated signing (requires `ows` CLI installed).'),
+    }, async ({ amount, owsWallet }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        try {
+            const resolved = await resolveOwsOrKeypairSigner(owsWallet);
+            if (!resolved.ok)
+                return resolved.error;
+            const { signer, walletAddress } = resolved;
+            const helius = getHeliusClient();
+            // Pre-flight balance check — need amount + ~0.01 SOL for rent + fees
+            const balanceResult = await helius.getBalance(walletAddress);
+            const balanceLamports = BigInt(balanceResult.value);
+            const stakeLamports = BigInt(Math.round(amount * 1_000_000_000));
+            const reserveLamports = 10000000n; // ~0.01 SOL for rent-exempt reserve + fees
+            if (balanceLamports < stakeLamports + reserveLamports) {
+                const available = Number(balanceLamports) / 1_000_000_000;
+                return mcpError(`Insufficient SOL balance. You have ${available} SOL but need ${amount} SOL plus ~0.01 SOL for rent-exempt reserve and transaction fees.\n\n` +
+                    `Wallet: \`${walletAddress}\``, { type: 'INSUFFICIENT_FUNDS', code: 'LOW_SOL', retryable: false, recovery: 'Fund the wallet with more SOL.' });
+            }
+            // Get stake instructions (async — fetches rent-exempt minimum from RPC)
+            const { instructions, stakeAccount } = await helius.stake.getStakeInstructions(signer, amount);
+            // Send transaction — stakeAccount is a generated keypair that must co-sign
+            const signature = await helius.tx.sendTransactionWithSender({
+                signers: [signer, stakeAccount],
+                instructions: [...instructions],
+                region: 'Default',
+            });
+            const signerLabel = owsWallet ? `\`${walletAddress}\` (OWS: ${owsWallet})` : `\`${walletAddress}\``;
+            return mcpText(`**SOL Staked to Helius Validator**\n\n` +
+                `- **From:** ${signerLabel}\n` +
+                `- **Stake Account:** \`${stakeAccount.address}\`\n` +
+                `- **Amount:** ${amount} SOL\n` +
+                `- **Signature:** \`${signature}\`\n` +
+                `- **Explorer:** https://orbmarkets.io/tx/${signature}\n\n` +
+                `The stake account is now delegated to the Helius validator. ` +
+                `Staking rewards begin accruing after the activation epoch completes (~1 epoch / 2-3 days).`);
+        }
+        catch (err) {
+            return handleToolError(err, 'Error staking SOL');
+        }
+    });
+    // ── Unstake SOL ──
+    server.tool('unstakeSOL', 'BEST FOR: deactivating (unstaking) a stake account to begin the cooldown period before withdrawal. ' +
+        'PREFER getStakeAccounts to find stake account addresses first. ' +
+        'Sends a deactivation transaction for the given stake account. ' +
+        'After deactivation, wait ~1 full epoch (2-3 days) before funds become withdrawable. ' +
+        'Use withdrawStake after cooldown completes. ' +
+        'Requires a configured keypair (the stake authority). ' +
+        'This is an irreversible on-chain transaction. ' +
+        'Credit cost: ~3 credits.', {
+        stakeAccount: z.string().describe('Address of the stake account to deactivate (base58 encoded). Use getStakeAccounts to find your Helius stake accounts.'),
+        owsWallet: z.string().optional().describe('OWS wallet name for policy-gated signing (requires `ows` CLI installed).'),
+    }, async ({ stakeAccount: stakeAccountAddress, owsWallet }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        try {
+            const resolved = await resolveOwsOrKeypairSigner(owsWallet);
+            if (!resolved.ok)
+                return resolved.error;
+            const { signer, walletAddress } = resolved;
+            // Validate address
+            if (!isValidAddressFormat(stakeAccountAddress)) {
+                return mcpError(`Invalid stake account address "${stakeAccountAddress}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded Solana address.' });
+            }
+            const helius = getHeliusClient();
+            // Get deactivation instruction (synchronous)
+            const ix = helius.stake.getUnstakeInstruction(signer, address(stakeAccountAddress));
+            // Send transaction
+            const signature = await helius.tx.sendTransactionWithSender({
+                signers: [signer],
+                instructions: [ix],
+                region: 'Default',
+            });
+            const signerLabel = owsWallet ? `\`${walletAddress}\` (OWS: ${owsWallet})` : `\`${walletAddress}\``;
+            return mcpText(`**Stake Account Deactivated**\n\n` +
+                `- **Stake Account:** \`${stakeAccountAddress}\`\n` +
+                `- **Authority:** ${signerLabel}\n` +
+                `- **Signature:** \`${signature}\`\n` +
+                `- **Explorer:** https://orbmarkets.io/tx/${signature}\n\n` +
+                `The stake account is now deactivating. Funds will become withdrawable after the cooldown period (~1 full epoch / 2-3 days). ` +
+                `Use \`getWithdrawableAmount\` to check when funds are ready, then \`withdrawStake\` to withdraw.`);
+        }
+        catch (err) {
+            return handleToolError(err, 'Error deactivating stake account');
+        }
+    });
+    // ── Withdraw Stake ──
+    server.tool('withdrawStake', 'BEST FOR: withdrawing SOL from a deactivated stake account back to your wallet. ' +
+        'PREFER getWithdrawableAmount to check if funds are available before withdrawing. ' +
+        'By default withdraws the full balance (including rent-exempt reserve) and closes the stake account. ' +
+        'The stake account must be fully deactivated (cooldown complete, ~1 epoch after unstakeSOL) before withdrawal. ' +
+        'Requires a configured keypair (the withdraw authority). ' +
+        'This is an irreversible on-chain transaction. ' +
+        'Credit cost: ~3 credits.', {
+        stakeAccount: z.string().describe('Address of the deactivated stake account to withdraw from (base58 encoded).'),
+        destination: z.string().optional().describe('Destination wallet address to receive the withdrawn SOL (base58 encoded). Defaults to the MCP wallet address if omitted.'),
+        amount: z.number().positive().optional().describe('Amount of SOL to withdraw. If omitted, withdraws the entire withdrawable balance (including rent-exempt reserve, which closes the account).'),
+        owsWallet: z.string().optional().describe('OWS wallet name for policy-gated signing (requires `ows` CLI installed).'),
+    }, async ({ stakeAccount: stakeAccountAddress, destination, amount, owsWallet }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        try {
+            const resolved = await resolveOwsOrKeypairSigner(owsWallet);
+            if (!resolved.ok)
+                return resolved.error;
+            const { signer, walletAddress } = resolved;
+            // Validate addresses
+            if (!isValidAddressFormat(stakeAccountAddress)) {
+                return mcpError(`Invalid stake account address "${stakeAccountAddress}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded Solana address.' });
+            }
+            if (destination && !isValidAddressFormat(destination)) {
+                return mcpError(`Invalid destination address "${destination}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded Solana address.' });
+            }
+            const helius = getHeliusClient();
+            const dest = destination || walletAddress;
+            // Determine lamports to withdraw
+            let lamports;
+            if (amount === undefined) {
+                // Withdraw full balance including rent-exempt reserve (closes account)
+                lamports = await helius.stake.getWithdrawableAmount(stakeAccountAddress, true);
+            }
+            else {
+                lamports = Math.round(amount * 1_000_000_000);
+            }
+            if (lamports === 0) {
+                return mcpError(`No funds available to withdraw from stake account \`${stakeAccountAddress}\`. ` +
+                    `The stake may still be active or in cooldown (not yet fully deactivated). ` +
+                    `Use \`getStakeAccounts\` to check the status.`, { type: 'INSUFFICIENT_FUNDS', code: 'ZERO_BALANCE', retryable: false, recovery: 'Stake may still be active or in cooldown. Use getStakeAccounts to check status.' });
+            }
+            // Get withdraw instruction (synchronous)
+            const ix = helius.stake.getWithdrawInstruction(signer, address(stakeAccountAddress), address(dest), lamports);
+            // Send transaction
+            const signature = await helius.tx.sendTransactionWithSender({
+                signers: [signer],
+                instructions: [ix],
+                region: 'Default',
+            });
+            const solAmount = lamports / 1_000_000_000;
+            return mcpText(`**Stake Withdrawn**\n\n` +
+                `- **Stake Account:** \`${stakeAccountAddress}\`\n` +
+                `- **Destination:** \`${dest}\`\n` +
+                `- **Amount:** ${solAmount} SOL\n` +
+                `- **Signature:** \`${signature}\`\n` +
+                `- **Explorer:** https://orbmarkets.io/tx/${signature}` +
+                (amount === undefined ? `\n\nThe full balance was withdrawn and the stake account has been closed.` : ''));
+        }
+        catch (err) {
+            return handleToolError(err, 'Error withdrawing stake');
+        }
+    });
+    // ── Get Stake Accounts ──
+    server.tool('getStakeAccounts', 'BEST FOR: listing all stake accounts delegated to the Helius validator for a wallet. ' +
+        'PREFER getWithdrawableAmount to check withdrawal eligibility for a specific stake account. ' +
+        'Returns stake account addresses, delegated amounts, and activation status (active, deactivating, or inactive). ' +
+        'Does not require a keypair — any wallet address can be queried. ' +
+        'Credit cost: ~10 credits (getProgramAccounts).', {
+        wallet: z.string().optional().describe('Wallet address to query Helius stake accounts for (base58 encoded). Defaults to the MCP wallet if omitted and a keypair is configured.'),
+    }, async ({ wallet }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        try {
+            // Resolve wallet address
+            let walletAddress = wallet;
+            if (!walletAddress) {
+                walletAddress = getSessionWalletAddress() ?? undefined;
+                if (!walletAddress) {
+                    return missingParamError('getStakeAccounts', 'Pass a wallet address or call generateKeypair first.');
+                }
+            }
+            if (!isValidAddressFormat(walletAddress)) {
+                return mcpError(`Invalid wallet address "${walletAddress}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded Solana address.' });
+            }
+            const helius = getHeliusClient();
+            const accounts = await helius.stake.getHeliusStakeAccounts(walletAddress);
+            if (!accounts || accounts.length === 0) {
+                return mcpText(`**No Helius Stake Accounts Found**\n\n` +
+                    `Wallet \`${walletAddress}\` has no stake accounts delegated to the Helius validator.\n\n` +
+                    `Use \`stakeSOL\` to stake SOL to the Helius validator.`);
+            }
+            const U64_MAX = '18446744073709551615';
+            const lines = [`**Helius Stake Accounts for \`${walletAddress}\`**\n`];
+            for (const account of accounts) {
+                const pubkey = account.pubkey;
+                const lamports = account.account.lamports;
+                const solAmount = Number(lamports) / 1_000_000_000;
+                const delegation = account.account.data?.parsed?.info?.stake?.delegation;
+                let status = 'Unknown';
+                let details = '';
+                if (delegation) {
+                    const deactivationEpoch = delegation.deactivationEpoch;
+                    if (deactivationEpoch === U64_MAX) {
+                        status = 'Active';
+                        details = `Activation epoch: ${delegation.activationEpoch}`;
+                    }
+                    else {
+                        status = 'Deactivating';
+                        details = `Deactivation epoch: ${deactivationEpoch}`;
+                    }
+                }
+                else {
+                    status = 'Inactive';
+                }
+                lines.push(`### \`${pubkey}\`\n` +
+                    `- **Balance:** ${solAmount} SOL\n` +
+                    `- **Status:** ${status}\n` +
+                    (details ? `- **${details}**\n` : '') +
+                    (delegation ? `- **Delegated stake:** ${Number(delegation.stake) / 1_000_000_000} SOL\n` : ''));
+            }
+            lines.push(`---\n_${accounts.length} stake account(s) found._`);
+            return mcpText(lines.join('\n'));
+        }
+        catch (err) {
+            return handleToolError(err, 'Error fetching stake accounts');
+        }
+    });
+    // ── Get Withdrawable Amount ──
+    server.tool('getWithdrawableAmount', 'BEST FOR: checking how much SOL can be withdrawn from a stake account. ' +
+        'PREFER getStakeAccounts to find stake account addresses, withdrawStake to actually withdraw. ' +
+        'Returns 0 if the stake account is still active or in cooldown (not yet withdrawable). ' +
+        'Does not require a keypair. ' +
+        'Credit cost: ~3 credits (getAccountInfo + getEpochInfo + getMinimumBalanceForRentExemption).', {
+        stakeAccount: z.string().describe('Stake account address to check (base58 encoded). Use getStakeAccounts to find stake account addresses.'),
+        includeRentExempt: z.boolean().optional().default(false).describe('If true, includes the rent-exempt reserve (~0.00228 SOL) in the withdrawable amount. Withdrawing the full amount (with rent) closes the stake account.'),
+    }, async ({ stakeAccount: stakeAccountAddress, includeRentExempt }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        try {
+            if (!isValidAddressFormat(stakeAccountAddress)) {
+                return mcpError(`Invalid stake account address "${stakeAccountAddress}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded Solana address.' });
+            }
+            const helius = getHeliusClient();
+            const lamports = await helius.stake.getWithdrawableAmount(stakeAccountAddress, includeRentExempt);
+            const solAmount = lamports / 1_000_000_000;
+            if (lamports === 0) {
+                return mcpText(`**Withdrawable Amount: 0 SOL**\n\n` +
+                    `Stake account \`${stakeAccountAddress}\` has no withdrawable funds.\n\n` +
+                    `This usually means the stake is still active or in the cooldown period after deactivation. ` +
+                    `Use \`getStakeAccounts\` to check the current status.`);
+            }
+            return mcpText(`**Withdrawable Amount**\n\n` +
+                `- **Stake Account:** \`${stakeAccountAddress}\`\n` +
+                `- **Withdrawable:** ${solAmount} SOL (${lamports.toLocaleString()} lamports)\n` +
+                `- **Includes rent-exempt reserve:** ${includeRentExempt ? 'Yes (withdrawing closes the account)' : 'No'}\n\n` +
+                `Use \`withdrawStake\` to withdraw these funds.`);
+        }
+        catch (err) {
+            return handleToolError(err, 'Error checking withdrawable amount');
+        }
+    });
+}

package/dist/tools/transactions.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 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 { mcpText, mcpError, validateEnum, handleToolError, http400Error } from '../utils/errors.js';
 import bs58 from 'bs58';
 // ─── Helpers ───
 const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
@@ -125,7 +125,7 @@ function formatSwapSummary(swap, tokenMetadata) {
             const asset = tokenMetadata.get(input.mint);
             const symbol = asset?.token_info?.symbol || asset?.content?.metadata?.symbol || asset?.content?.metadata?.name || formatAddress(input.mint);
             const amount = Number(input.rawTokenAmount.tokenAmount) / Math.pow(10, input.rawTokenAmount.decimals);
-            parts.push(`${amount.toLocaleString(undefined, { maximumFractionDigits: 6 })} ${symbol}`);
+            parts.push(`${amount.toLocaleString(undefined, { maximumFractionDigits: 6 })} ${symbol} (${input.mint})`);
         }
     }
     if (parts.length === 0)
@@ -141,7 +141,7 @@ function formatSwapSummary(swap, tokenMetadata) {
             const asset = tokenMetadata.get(output.mint);
             const symbol = asset?.token_info?.symbol || asset?.content?.metadata?.symbol || asset?.content?.metadata?.name || formatAddress(output.mint);
             const amount = Number(output.rawTokenAmount.tokenAmount) / Math.pow(10, output.rawTokenAmount.decimals);
-            parts.push(`${amount.toLocaleString(undefined, { maximumFractionDigits: 6 })} ${symbol}`);
+            parts.push(`${amount.toLocaleString(undefined, { maximumFractionDigits: 6 })} ${symbol} (${output.mint})`);
         }
     }
     if (parts.length === 0)
@@ -616,4 +616,168 @@ export function registerTransactionTools(server) {
             return handleToolError(err, 'Error fetching transaction history');
         }
     });
+    // Get Transfers By Address — parsed token + native SOL transfers (one row per transfer)
+    server.tool('getTransfersByAddress', 'BEST FOR: parsed token + native SOL transfers for an address — one row per transfer (not per transaction). Filters: mint, direction (in/out/any), counterparty (with), time/slot/amount ranges, solMode. Use getTransactionHistory when you need whole-transaction context. Paginated via paginationToken.', {
+        address: z.string().describe('Solana address (base58 encoded)'),
+        with: z.string().optional().describe('Filter by counterparty address — returns only transfers to/from this address'),
+        direction: z.string().optional().default('any').describe('"in" | "out" | "any" — relative to the queried address'),
+        mint: z.string().optional().describe('Filter by token mint. Use the WSOL mint to filter native SOL when solMode="merged".'),
+        solMode: z.string().optional().describe('"merged" treats SOL and WSOL as one asset; "separate" keeps them distinct'),
+        limit: z.number().int().min(1).max(100).optional().default(25).describe('Max transfers per page (1-100)'),
+        sortOrder: z.string().optional().default('desc').describe('"desc" = newest first (default), "asc" = oldest first'),
+        paginationToken: z.string().optional().describe('Cursor from a previous response — pass to fetch the next page'),
+        commitment: z.string().optional().describe('"finalized" | "confirmed"'),
+        amountGte: z.string().optional().describe('Raw u64 amount (as string) lower bound — not UI amount'),
+        amountLte: z.string().optional().describe('Raw u64 amount (as string) upper bound — not UI amount'),
+        blockTimeGte: z.number().optional().describe('Filter: block time >= this Unix timestamp (seconds)'),
+        blockTimeLte: z.number().optional().describe('Filter: block time <= this Unix timestamp (seconds)'),
+        slotGte: z.number().optional().describe('Filter: slot >= this value'),
+        slotLte: z.number().optional().describe('Filter: slot <= this value'),
+    }, async ({ address, with: counterparty, direction, mint, solMode, limit, sortOrder, paginationToken, commitment, amountGte, amountLte, blockTimeGte, blockTimeLte, slotGte, slotLte, }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        const helius = getHeliusClient();
+        let err;
+        err = validateEnum(direction, ['in', 'out', 'any'], 'Transfers By Address Error', 'direction');
+        if (err)
+            return err;
+        err = validateEnum(sortOrder, ['asc', 'desc'], 'Transfers By Address Error', 'sortOrder');
+        if (err)
+            return err;
+        if (solMode) {
+            err = validateEnum(solMode, ['merged', 'separate'], 'Transfers By Address Error', 'solMode');
+            if (err)
+                return err;
+        }
+        if (commitment) {
+            err = validateEnum(commitment, ['finalized', 'confirmed'], 'Transfers By Address Error', 'commitment');
+            if (err)
+                return err;
+        }
+        // SDK's TransferComparisonFilter types amount as `number`, so values outside JS safe-integer
+        // range (>2^53) can't be passed without precision loss. u64 raw amounts on high-decimal tokens
+        // can exceed this. Surface a clear error rather than silently dropping the filter.
+        const parseAmountBound = (raw, label) => {
+            if (raw === undefined)
+                return undefined;
+            const n = Number(raw);
+            if (!Number.isFinite(n)) {
+                return { error: `${label} must be a numeric raw u64 amount (got "${raw}")` };
+            }
+            if (!Number.isSafeInteger(n) || n < 0) {
+                return {
+                    error: `${label}="${raw}" is outside JS safe integer range (>2^53) or negative. The SDK's amount filter is typed as number — pass a smaller raw amount or filter client-side. (u64 raw amounts can exceed this; high-decimal SPL tokens are the common case.)`,
+                };
+            }
+            return n;
+        };
+        const filters = {};
+        const aGte = parseAmountBound(amountGte, 'amountGte');
+        const aLte = parseAmountBound(amountLte, 'amountLte');
+        const amountErrMeta = {
+            type: 'VALIDATION',
+            code: 'INVALID_AMOUNT_BOUND',
+            retryable: false,
+            recovery: 'Pass a raw u64 amount within JS safe integer range (<= 2^53), or filter client-side after fetching.',
+        };
+        if (aGte && typeof aGte === 'object')
+            return mcpError(aGte.error, amountErrMeta);
+        if (aLte && typeof aLte === 'object')
+            return mcpError(aLte.error, amountErrMeta);
+        if (aGte !== undefined || aLte !== undefined) {
+            filters.amount = {};
+            if (typeof aGte === 'number')
+                filters.amount.gte = aGte;
+            if (typeof aLte === 'number')
+                filters.amount.lte = aLte;
+        }
+        if (blockTimeGte !== undefined || blockTimeLte !== undefined) {
+            filters.blockTime = {};
+            if (blockTimeGte !== undefined)
+                filters.blockTime.gte = blockTimeGte;
+            if (blockTimeLte !== undefined)
+                filters.blockTime.lte = blockTimeLte;
+        }
+        if (slotGte !== undefined || slotLte !== undefined) {
+            filters.slot = {};
+            if (slotGte !== undefined)
+                filters.slot.gte = slotGte;
+            if (slotLte !== undefined)
+                filters.slot.lte = slotLte;
+        }
+        const config = {
+            direction,
+            limit: Math.min(Math.max(limit, 1), 100),
+            sortOrder,
+        };
+        if (counterparty)
+            config.with = counterparty;
+        if (mint)
+            config.mint = mint;
+        if (solMode)
+            config.solMode = solMode;
+        if (paginationToken)
+            config.paginationToken = paginationToken;
+        if (commitment)
+            config.commitment = commitment;
+        if (Object.keys(filters).length > 0)
+            config.filters = filters;
+        let result;
+        try {
+            result = await helius.getTransfersByAddress(address, config);
+        }
+        catch (e) {
+            return handleToolError(e, 'Error fetching transfers');
+        }
+        if (!result || !result.data || result.data.length === 0) {
+            return mcpText(`**Transfers for ${formatAddress(address)}**\n\nNo transfers found.`);
+        }
+        const mints = new Set();
+        for (const t of result.data) {
+            if (t.mint)
+                mints.add(t.mint);
+        }
+        const tokenMetadata = await fetchTokenMetadata(helius, mints);
+        const symbolFor = (m) => {
+            const asset = tokenMetadata.get(m);
+            return asset?.token_info?.symbol || asset?.content?.metadata?.symbol || asset?.content?.metadata?.name || formatAddress(m);
+        };
+        const WSOL = 'So11111111111111111111111111111111111111112';
+        // SDK contract: native SOL transfers omit fromTokenAccount/toTokenAccount. JSON deserialization
+        // can surface either `undefined` (key absent) or `null` (key present with null value) — accept both.
+        const isNativeSol = (t) => t.mint === WSOL && t.fromTokenAccount == null && t.toTokenAccount == null;
+        const formatAmount = (t) => {
+            if (isNativeSol(t)) {
+                // amount is raw lamports as string
+                const n = Number(t.amount);
+                if (Number.isFinite(n))
+                    return formatSol(n);
+            }
+            // Use uiAmount (string, precision-preserving) directly and trim trailing zeros for readability
+            const ui = t.uiAmount ?? '';
+            if (!ui.includes('.'))
+                return ui;
+            return ui.replace(/0+$/, '').replace(/\.$/, '');
+        };
+        const orderLabel = sortOrder === 'asc' ? 'oldest first' : 'newest first';
+        const lines = [`**Transfers for ${formatAddress(address)}** (${result.data.length} transfers, ${orderLabel})`, ''];
+        for (const t of result.data) {
+            const sym = isNativeSol(t) ? 'SOL' : symbolFor(t.mint);
+            const from = t.fromUserAccount ? formatAddress(t.fromUserAccount) : (t.type === 'mint' ? 'mint' : '?');
+            const to = t.toUserAccount ? formatAddress(t.toUserAccount) : (t.type === 'burn' ? 'burn' : '?');
+            const time = t.blockTime ? formatTimestamp(Number(t.blockTime)) : 'N/A';
+            const dirArrow = '→';
+            lines.push(`${t.type.toUpperCase()} ${formatAmount(t)} ${sym} (${t.mint})`);
+            lines.push(`   ${from} ${dirArrow} ${to}`);
+            lines.push(`   Sig: \`${t.signature}\` | Slot: ${t.slot.toLocaleString()} | ${time}`);
+            if (t.feeAmount && t.feeAmount !== '0') {
+                lines.push(`   Fee: ${t.feeUiAmount ?? t.feeAmount} ${sym}`);
+            }
+            lines.push('');
+        }
+        if (result.paginationToken) {
+            lines.push(`**Next Page Token:** \`${result.paginationToken}\``);
+        }
+        return mcpText(truncateResponse(lines.join('\n')));
+    });
 }