helius-mcp 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -7,10 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+## [helius-mcp@2.1.0](https://github.com/helius-labs/core-ai/compare/helius-mcp@2.0.0...helius-mcp@2.1.0) - 2026-06-24
+
+### Merged
+
+- feat(wallet): Add balance-at Support to MCP and CLI [`#138`](https://github.com/helius-labs/core-ai/pull/138)
+- feat(mcp): Add Timeout and Retry With Backoff For MCP RPC Reads [`#136`](https://github.com/helius-labs/core-ai/pull/136)
+- feat(mcp): Add `simulateTransaction` Tool For Pre-Send Transaction Dry-Runs [`#135`](https://github.com/helius-labs/core-ai/pull/135)
+- feat(cli): Add Confirmation Prompt Before Submitting Transactions [`#134`](https://github.com/helius-labs/core-ai/pull/134)
+- feat(cli): Add Confirmation Prompts For Destructive Commands [`#133`](https://github.com/helius-labs/core-ai/pull/133)
+- feat(ci): Harden Release Pipeline and Add Dependency/Security Automation [`#128`](https://github.com/helius-labs/core-ai/pull/128)
+- fix(deps): Patch High-Severity Security Advisories in the MCP and CLI [`#127`](https://github.com/helius-labs/core-ai/pull/127)
+- fix(cli): exit non-zero when reclaim batches fail to land [`#126`](https://github.com/helius-labs/core-ai/pull/126)
+
+## [helius-mcp@2.0.0](https://github.com/helius-labs/core-ai/compare/helius-mcp@1.3.0...helius-mcp@2.0.0) - 2026-06-15
+
+### Merged
+
+- chore(mcp): 2.0.0 Release [`#124`](https://github.com/helius-labs/core-ai/pull/124)
+- fix(cli): Store Config With Owner-only Permissions [`#121`](https://github.com/helius-labs/core-ai/pull/121)
+- feat(helius-cli): OAuth/PKCE login + logout + whoami (v2.0.0) [`#118`](https://github.com/helius-labs/core-ai/pull/118)
+- feat(ci): Require and Enforce Signed Commits Repo-wide [`#119`](https://github.com/helius-labs/core-ai/pull/119)
+- feat(cli+mcp): unified crypto checkout — signup / upgrade / credits / pay [`#109`](https://github.com/helius-labs/core-ai/pull/109)
+- fix(cli): tx history --before now uses beforeSignature [`#116`](https://github.com/helius-labs/core-ai/pull/116)
+- Add package.json Metadata and Bundle LICENSE [`#117`](https://github.com/helius-labs/core-ai/pull/117)
+- fix(jupiter-skill): Sender/Jito tip recipe + Trigger V2 vault onboarding [`#115`](https://github.com/helius-labs/core-ai/pull/115)
+- feat(mcp+cli): expose getTransfersByAddress RPC method [`#112`](https://github.com/helius-labs/core-ai/pull/112)
+- docs(plugin): Advertise Jupiter/OKX/SVM Skills and Bump to 1.1 [`#114`](https://github.com/helius-labs/core-ai/pull/114)
+- feat(security): Enforce 7-day Minimum Release Age For Deps [`#113`](https://github.com/helius-labs/core-ai/pull/113)
+- feat(cli): Add Reclaim Command [`#101`](https://github.com/helius-labs/core-ai/pull/101)
+- fix mcp config recovery, telemetry, and laserstream api handling [`#108`](https://github.com/helius-labs/core-ai/pull/108)
+- feat(cli): Always emit suggestion in JSON error envelopes [`#107`](https://github.com/helius-labs/core-ai/pull/107)
+- feat(cli)!: Uniform JSON envelope for all --json output (v2.0) [`#106`](https://github.com/helius-labs/core-ai/pull/106)
+- feat(cli): Add Error Category to JSON Output [`#103`](https://github.com/helius-labs/core-ai/pull/103)
+- feat(cli,mcp): Add SNS/ANS domain resolution to wallet identity [`#105`](https://github.com/helius-labs/core-ai/pull/105)
+- feat(cli): Add `--amount` and `--raw-amount` Flags for Stake Commands [`#104`](https://github.com/helius-labs/core-ai/pull/104)
+- feat(skill): Add DFlow Agent CLI Coverage to Skill [`#102`](https://github.com/helius-labs/core-ai/pull/102)
+- feat(cli): Add Pre-Input Validation For Addresses, Sigs, and Slots [`#100`](https://github.com/helius-labs/core-ai/pull/100)
+- feat(cli): Add `--dry-run` Flag For Transaction and Webhook Commands [`#99`](https://github.com/helius-labs/core-ai/pull/99)
+- feat(cli): Add Debug Flag For HTTP Req and Res Troubleshooting [`#98`](https://github.com/helius-labs/core-ai/pull/98)
+- feat(skill): Add Jupiter [`#59`](https://github.com/helius-labs/core-ai/pull/59)
+- feat(cli): Add `llms.txt` File [`#96`](https://github.com/helius-labs/core-ai/pull/96)
+- feat(cli): Add Usage Examples to All Command `--help` Output [`#97`](https://github.com/helius-labs/core-ai/pull/97)
+- feat(cli): Add `--retry` Flag For Transient Error Recovery With Exponential Backoff [`#94`](https://github.com/helius-labs/core-ai/pull/94)
+- fix(skill): Make Helius Skill Interface-Agnostic  [`#95`](https://github.com/helius-labs/core-ai/pull/95)
+- Update Sender docs: clarify tip accounts and add pre-serialized tx guide [`#80`](https://github.com/helius-labs/core-ai/pull/80)
+- feat(cli): Extract Duplicated Setup Helper to Shared `setupClient` [`#93`](https://github.com/helius-labs/core-ai/pull/93)
+- fix(cli): Recover Corrupted Config Instead of Silently Ignoring [`#91`](https://github.com/helius-labs/core-ai/pull/91)
+- feat(skills): Refactor OKX Skill to Thin Integration-only Layer [`#92`](https://github.com/helius-labs/core-ai/pull/92)
+- feat(cli): Add Shell Completion Support [`#90`](https://github.com/helius-labs/core-ai/pull/90)
+- fix(cli): Extract Duplicate Confirm Prompt to Shared Output Util [`#89`](https://github.com/helius-labs/core-ai/pull/89)
+- fix(cli): `exitWithError` Outputting JSON in Non-JSON Mode [`#88`](https://github.com/helius-labs/core-ai/pull/88)
+- fix(cli): Improve WS Error Handling With Guidance Hints and Telemetry [`#87`](https://github.com/helius-labs/core-ai/pull/87)
+- fix(cli): Standardize Keygen Command  [`#86`](https://github.com/helius-labs/core-ai/pull/86)
+- feat(docs): Update Streaming Pricing and Plan Access [`#62`](https://github.com/helius-labs/core-ai/pull/62)
+- feat(cli): Add `helius update` Self-update Command [`#84`](https://github.com/helius-labs/core-ai/pull/84)
+- test(mcp): add unit tests for router/responses.ts [`#82`](https://github.com/helius-labs/core-ai/pull/82)
+- feat(cli+mcp): Add Optional OWS Wallet Signing [`#83`](https://github.com/helius-labs/core-ai/pull/83)
+- feat(skill): Add OKX [`#65`](https://github.com/helius-labs/core-ai/pull/65)
+- Add glama.json to Repo Root [`#81`](https://github.com/helius-labs/core-ai/pull/81)
+- feat(docs): Add MIT License [`#78`](https://github.com/helius-labs/core-ai/pull/78)
+- Reduce Helius MCP context bloat with routed public surface [`#76`](https://github.com/helius-labs/core-ai/pull/76)
+- feat(mcp): Make `getNetworkStatus` TPS Configurable [`#79`](https://github.com/helius-labs/core-ai/pull/79)
+- feat(cli): Add NO_DNA Support [`#74`](https://github.com/helius-labs/core-ai/pull/74)
+- feat(mcp): add ZK Compression support (23 tools) [`#69`](https://github.com/helius-labs/core-ai/pull/69)
+- feat(mcp): add staking tools [`#68`](https://github.com/helius-labs/core-ai/pull/68)
+- fix: add missing MCP parameter descriptions [`#67`](https://github.com/helius-labs/core-ai/pull/67)
+- feat(mcp): add getAccountPlan tool [`#71`](https://github.com/helius-labs/core-ai/pull/71)
+- fix(mcp): unify error responses with structured metadata [`#70`](https://github.com/helius-labs/core-ai/pull/70)
+- fix(cli): Make WebSocket Commands Agent-Friendly [`#66`](https://github.com/helius-labs/core-ai/pull/66)
+- chore: update CHANGELOG.md for helius-mcp@1.3.0 [`#64`](https://github.com/helius-labs/core-ai/pull/64)
+
 ## [helius-mcp@1.3.0](https://github.com/helius-labs/core-ai/compare/helius-mcp@1.2.0...helius-mcp@1.3.0) - 2026-03-12
 
 ### Merged
 
+- feat(mcp): Bump to v1.3.0 [`#63`](https://github.com/helius-labs/core-ai/pull/63)
 - feat(skills): Add Skill Versioning [`#61`](https://github.com/helius-labs/core-ai/pull/61)
 - fix(mcp): Add Escalating Retry Guidance For Agents [`#60`](https://github.com/helius-labs/core-ai/pull/60)
 - feat(cli): Unify Error Handling Across Commands [`#57`](https://github.com/helius-labs/core-ai/pull/57)

package/README.md

@@ -78,7 +78,7 @@ Helius MCP exposes 10 public tools total: 9 routed domain tools plus `expandResu
 - `heliusWallet` — wallet balances, holdings, wallet history, identity
 - `heliusAsset` — assets, NFTs, collections, token holders
 - `heliusTransaction` — transaction parsing and wallet transaction history
-- `heliusChain` — chain state, token accounts, blocks, network status, stake reads
+- `heliusChain` — chain state, token accounts, blocks, network status, stake reads, transaction simulation
 - `heliusStreaming` — webhook CRUD and subscription config
 - `heliusKnowledge` — docs, guides, pricing, troubleshooting, source, blog, SIMDs
 - `heliusWrite` — transfers and staking mutations

package/dist/http.d.ts

@@ -1 +1 @@
-export declare const MCP_USER_AGENT = "helius-mcp/2.0.0";
+export declare const MCP_USER_AGENT = "helius-mcp/2.1.0";

package/dist/router/actions.d.ts

@@ -1,12 +1,12 @@
 export declare const HELIUS_ACCOUNT_ACTIONS: readonly ["getStarted", "setHeliusApiKey", "generateKeypair", "signup", "getAccountStatus", "getAccountPlan", "getHeliusPlanInfo", "compareHeliusPlans", "previewUpgrade", "upgradePlan", "payRenewal", "purchaseCredits"];
-export declare const HELIUS_WALLET_ACTIONS: readonly ["getBalance", "getTokenBalances", "getWalletBalances", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy"];
+export declare const HELIUS_WALLET_ACTIONS: readonly ["getBalance", "getTokenBalances", "getWalletBalances", "getWalletBalanceAt", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy"];
 export declare const HELIUS_ASSET_ACTIONS: readonly ["getAsset", "getAssetsByOwner", "searchAssets", "getAssetsByGroup", "getAssetProof", "getAssetProofBatch", "getSignaturesForAsset", "getNftEditions", "getTokenHolders"];
 export declare const HELIUS_TRANSACTION_ACTIONS: readonly ["parseTransactions", "getTransactionHistory", "getTransfersByAddress"];
-export declare const HELIUS_CHAIN_ACTIONS: readonly ["getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "getStakeAccounts", "getWithdrawableAmount"];
+export declare const HELIUS_CHAIN_ACTIONS: readonly ["getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "simulateTransaction", "getStakeAccounts", "getWithdrawableAmount"];
 export declare const HELIUS_STREAMING_ACTIONS: readonly ["createWebhook", "getAllWebhooks", "getWebhookByID", "updateWebhook", "deleteWebhook", "transactionSubscribe", "accountSubscribe", "laserstreamSubscribe"];
 export declare const HELIUS_KNOWLEDGE_ACTIONS: readonly ["lookupHeliusDocs", "listHeliusDocTopics", "getHeliusCreditsInfo", "getRateLimitInfo", "troubleshootError", "recommendStack", "getSIMD", "listSIMDs", "searchSolanaDocs", "readSolanaSourceFile", "fetchHeliusBlog", "getPumpFunGuide", "getSenderInfo", "getWebhookGuide", "getLatencyComparison", "getEnhancedWebSocketInfo", "getLaserstreamInfo"];
 export declare const HELIUS_WRITE_ACTIONS: readonly ["transferSol", "transferToken", "stakeSOL", "unstakeSOL", "withdrawStake"];
 export declare const HELIUS_COMPRESSION_ACTIONS: readonly ["getCompressedAccount", "getCompressedAccountsByOwner", "getMultipleCompressedAccounts", "getCompressedBalance", "getCompressedBalanceByOwner", "getCompressedMintTokenHolders", "getCompressedTokenAccountBalance", "getCompressedTokenAccountsByOwner", "getCompressedTokenAccountsByDelegate", "getCompressedTokenBalancesByOwnerV2", "getCompressedAccountProof", "getMultipleCompressedAccountProofs", "getMultipleNewAddressProofs", "getCompressionSignaturesForAccount", "getCompressionSignaturesForAddress", "getCompressionSignaturesForOwner", "getCompressionSignaturesForTokenOwner", "getLatestCompressionSignatures", "getLatestNonVotingSignatures", "getTransactionWithCompressionInfo", "getValidityProof", "getIndexerHealth", "getIndexerSlot"];
-export declare const ACTION_NAMES: readonly ["getStarted", "setHeliusApiKey", "generateKeypair", "signup", "getAccountStatus", "getAccountPlan", "getHeliusPlanInfo", "compareHeliusPlans", "previewUpgrade", "upgradePlan", "payRenewal", "purchaseCredits", "getBalance", "getTokenBalances", "getWalletBalances", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy", "getAsset", "getAssetsByOwner", "searchAssets", "getAssetsByGroup", "getAssetProof", "getAssetProofBatch", "getSignaturesForAsset", "getNftEditions", "getTokenHolders", "parseTransactions", "getTransactionHistory", "getTransfersByAddress", "getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "getStakeAccounts", "getWithdrawableAmount", "createWebhook", "getAllWebhooks", "getWebhookByID", "updateWebhook", "deleteWebhook", "transactionSubscribe", "accountSubscribe", "laserstreamSubscribe", "lookupHeliusDocs", "listHeliusDocTopics", "getHeliusCreditsInfo", "getRateLimitInfo", "troubleshootError", "recommendStack", "getSIMD", "listSIMDs", "searchSolanaDocs", "readSolanaSourceFile", "fetchHeliusBlog", "getPumpFunGuide", "getSenderInfo", "getWebhookGuide", "getLatencyComparison", "getEnhancedWebSocketInfo", "getLaserstreamInfo", "transferSol", "transferToken", "stakeSOL", "unstakeSOL", "withdrawStake", "getCompressedAccount", "getCompressedAccountsByOwner", "getMultipleCompressedAccounts", "getCompressedBalance", "getCompressedBalanceByOwner", "getCompressedMintTokenHolders", "getCompressedTokenAccountBalance", "getCompressedTokenAccountsByOwner", "getCompressedTokenAccountsByDelegate", "getCompressedTokenBalancesByOwnerV2", "getCompressedAccountProof", "getMultipleCompressedAccountProofs", "getMultipleNewAddressProofs", "getCompressionSignaturesForAccount", "getCompressionSignaturesForAddress", "getCompressionSignaturesForOwner", "getCompressionSignaturesForTokenOwner", "getLatestCompressionSignatures", "getLatestNonVotingSignatures", "getTransactionWithCompressionInfo", "getValidityProof", "getIndexerHealth", "getIndexerSlot"];
+export declare const ACTION_NAMES: readonly ["getStarted", "setHeliusApiKey", "generateKeypair", "signup", "getAccountStatus", "getAccountPlan", "getHeliusPlanInfo", "compareHeliusPlans", "previewUpgrade", "upgradePlan", "payRenewal", "purchaseCredits", "getBalance", "getTokenBalances", "getWalletBalances", "getWalletBalanceAt", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy", "getAsset", "getAssetsByOwner", "searchAssets", "getAssetsByGroup", "getAssetProof", "getAssetProofBatch", "getSignaturesForAsset", "getNftEditions", "getTokenHolders", "parseTransactions", "getTransactionHistory", "getTransfersByAddress", "getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "simulateTransaction", "getStakeAccounts", "getWithdrawableAmount", "createWebhook", "getAllWebhooks", "getWebhookByID", "updateWebhook", "deleteWebhook", "transactionSubscribe", "accountSubscribe", "laserstreamSubscribe", "lookupHeliusDocs", "listHeliusDocTopics", "getHeliusCreditsInfo", "getRateLimitInfo", "troubleshootError", "recommendStack", "getSIMD", "listSIMDs", "searchSolanaDocs", "readSolanaSourceFile", "fetchHeliusBlog", "getPumpFunGuide", "getSenderInfo", "getWebhookGuide", "getLatencyComparison", "getEnhancedWebSocketInfo", "getLaserstreamInfo", "transferSol", "transferToken", "stakeSOL", "unstakeSOL", "withdrawStake", "getCompressedAccount", "getCompressedAccountsByOwner", "getMultipleCompressedAccounts", "getCompressedBalance", "getCompressedBalanceByOwner", "getCompressedMintTokenHolders", "getCompressedTokenAccountBalance", "getCompressedTokenAccountsByOwner", "getCompressedTokenAccountsByDelegate", "getCompressedTokenBalancesByOwnerV2", "getCompressedAccountProof", "getMultipleCompressedAccountProofs", "getMultipleNewAddressProofs", "getCompressionSignaturesForAccount", "getCompressionSignaturesForAddress", "getCompressionSignaturesForOwner", "getCompressionSignaturesForTokenOwner", "getLatestCompressionSignatures", "getLatestNonVotingSignatures", "getTransactionWithCompressionInfo", "getValidityProof", "getIndexerHealth", "getIndexerSlot"];
 export type ActionName = typeof ACTION_NAMES[number];
 export declare const ACTION_NAME_SET: Set<string>;

package/dist/router/actions.js

@@ -16,6 +16,7 @@ export const HELIUS_WALLET_ACTIONS = [
     'getBalance',
     'getTokenBalances',
     'getWalletBalances',
+    'getWalletBalanceAt',
     'getWalletHistory',
     'getWalletTransfers',
     'getWalletIdentity',
@@ -45,6 +46,7 @@ export const HELIUS_CHAIN_ACTIONS = [
     'getBlock',
     'getNetworkStatus',
     'getPriorityFeeEstimate',
+    'simulateTransaction',
     'getStakeAccounts',
     'getWithdrawableAmount',
 ];

package/dist/router/catalog.js

@@ -287,6 +287,12 @@ catalog.getWalletBalances = makeEntry('getWalletBalances', {
     responseFamily: 'list',
     defaultDetail: 'standard',
 });
+catalog.getWalletBalanceAt = makeEntry('getWalletBalanceAt', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
 catalog.getWalletHistory = makeEntry('getWalletHistory', {
     capabilityGate: developerWalletGate,
     responseFamily: 'history',

package/dist/router/instructions.d.ts

@@ -1 +1 @@
-export declare const ROUTER_INSTRUCTIONS = "Helius MCP exposes 10 public tools total: 9 routed domain tools plus `expandResult`.\n\nChoose tools by user intent, not by name similarity.\n\nRouting:\n- Account setup, API keys, signup, plans, billing: `heliusAccount`\n- Wallet-centric balances, holdings, identity, wallet history: `heliusWallet`\n- Assets, NFTs, collections, token holders: `heliusAsset`\n- Parsed transactions or wallet transaction history: `heliusTransaction`\n- Raw chain state, token accounts, stake reads, blocks, network status, priority fees: `heliusChain`\n- Webhook CRUD or live subscription configuration: `heliusStreaming`\n- Docs, guides, pricing references, troubleshooting, source, blog, SIMDs: `heliusKnowledge`\n- SOL/token transfers or staking mutations: `heliusWrite`\n- Compressed account, proof, balance, compression history: `heliusCompression`\n\nRules:\n- Use the chosen routed tool plus the Helius action name in `action`.\n- Wallet holdings use `heliusWallet.getTokenBalances`; raw token accounts use `heliusChain.getTokenAccounts`.\n- Parsed transaction details use `heliusTransaction.parseTransactions`; wallet activity listing uses `heliusTransaction.getTransactionHistory`; per-transfer rows (token + SOL with mint/direction/counterparty filters) use `heliusTransaction.getTransfersByAddress`.\n- Streaming or webhook setup guides live under `heliusKnowledge`; actual webhook/subscription config lives under `heliusStreaming`.\n- Pricing and plan selection start with `heliusAccount.getHeliusPlanInfo`; per-method credit costs or rate limits use `heliusKnowledge.getRateLimitInfo` or `heliusKnowledge.getHeliusCreditsInfo`.\n- Read queries stay on domain tools; sends and staking mutations use `heliusWrite`.\n- Heavy content is summary-first. Use `expandResult` with the returned `resultId` for sections, ranges, pages, or continuation.\n- Set `_feedback` to a short reason for the call or takeaway from the previous result. Avoid placeholders like `first_call`.\n- Set `_feedbackTool` to the current `publicTool.action`, e.g. `heliusWallet.getBalance`. Always send `_model`.";
+export declare const ROUTER_INSTRUCTIONS = "Helius MCP exposes 10 public tools total: 9 routed domain tools plus `expandResult`.\n\nChoose tools by user intent, not by name similarity.\n\nRouting:\n- Account setup, API keys, signup, plans, billing: `heliusAccount`\n- Wallet-centric balances, holdings, identity, wallet history: `heliusWallet`\n- Assets, NFTs, collections, token holders: `heliusAsset`\n- Parsed transactions or wallet transaction history: `heliusTransaction`\n- Raw chain state, token accounts, stake reads, blocks, network status, priority fees, transaction simulation: `heliusChain`\n- Webhook CRUD or live subscription configuration: `heliusStreaming`\n- Docs, guides, pricing references, troubleshooting, source, blog, SIMDs: `heliusKnowledge`\n- SOL/token transfers or staking mutations: `heliusWrite`\n- Compressed account, proof, balance, compression history: `heliusCompression`\n\nRules:\n- Use the chosen routed tool plus the Helius action name in `action`.\n- Wallet holdings use `heliusWallet.getTokenBalances`; raw token accounts use `heliusChain.getTokenAccounts`.\n- Parsed transaction details use `heliusTransaction.parseTransactions`; wallet activity listing uses `heliusTransaction.getTransactionHistory`; per-transfer rows (token + SOL with mint/direction/counterparty filters) use `heliusTransaction.getTransfersByAddress`.\n- Streaming or webhook setup guides live under `heliusKnowledge`; actual webhook/subscription config lives under `heliusStreaming`.\n- Pricing and plan selection start with `heliusAccount.getHeliusPlanInfo`; per-method credit costs or rate limits use `heliusKnowledge.getRateLimitInfo` or `heliusKnowledge.getHeliusCreditsInfo`.\n- Read queries stay on domain tools; sends and staking mutations use `heliusWrite`.\n- Heavy content is summary-first. Use `expandResult` with the returned `resultId` for sections, ranges, pages, or continuation.\n- Set `_feedback` to a short reason for the call or takeaway from the previous result. Avoid placeholders like `first_call`.\n- Set `_feedbackTool` to the current `publicTool.action`, e.g. `heliusWallet.getBalance`. Always send `_model`.";

package/dist/router/instructions.js

@@ -7,7 +7,7 @@ Routing:
 - Wallet-centric balances, holdings, identity, wallet history: \`heliusWallet\`
 - Assets, NFTs, collections, token holders: \`heliusAsset\`
 - Parsed transactions or wallet transaction history: \`heliusTransaction\`
-- Raw chain state, token accounts, stake reads, blocks, network status, priority fees: \`heliusChain\`
+- Raw chain state, token accounts, stake reads, blocks, network status, priority fees, transaction simulation: \`heliusChain\`
 - Webhook CRUD or live subscription configuration: \`heliusStreaming\`
 - Docs, guides, pricing references, troubleshooting, source, blog, SIMDs: \`heliusKnowledge\`
 - SOL/token transfers or staking mutations: \`heliusWrite\`

package/dist/router/register.js

@@ -6,7 +6,7 @@ export function registerRouterTools(server) {
     server.tool('heliusWallet', 'Wallet-centric balances, holdings, identity, and wallet history. Use for portfolio views, not raw token accounts.', HELIUS_WALLET_SCHEMA, withTelemetryHandler('heliusWallet', (params, extra) => dispatchRoutedTool('heliusWallet', params, extra)));
     server.tool('heliusAsset', 'Assets, NFTs, collections, proofs, and token holders. Use for DAS ownership or metadata, not transaction history.', HELIUS_ASSET_SCHEMA, withTelemetryHandler('heliusAsset', (params, extra) => dispatchRoutedTool('heliusAsset', params, extra)));
     server.tool('heliusTransaction', 'Parsed transactions and wallet transaction history. Use for activity analysis, not raw account state.', HELIUS_TRANSACTION_SCHEMA, withTelemetryHandler('heliusTransaction', (params, extra) => dispatchRoutedTool('heliusTransaction', params, extra)));
-    server.tool('heliusChain', 'Raw chain state, token accounts, stake reads, blocks, network status, and priority fees. Use for token accounts or blocks, not wallet portfolio summaries.', HELIUS_CHAIN_SCHEMA, withTelemetryHandler('heliusChain', (params, extra) => dispatchRoutedTool('heliusChain', params, extra)));
+    server.tool('heliusChain', 'Raw chain state, token accounts, stake reads, blocks, network status, priority fees, and transaction simulation. Use for token accounts or blocks, not wallet portfolio summaries.', HELIUS_CHAIN_SCHEMA, withTelemetryHandler('heliusChain', (params, extra) => dispatchRoutedTool('heliusChain', params, extra)));
     server.tool('heliusStreaming', 'Webhook CRUD and live subscription configuration. Use for actual webhook/subscription setup, not how-to guides.', HELIUS_STREAMING_SCHEMA, withTelemetryHandler('heliusStreaming', (params, extra) => dispatchRoutedTool('heliusStreaming', params, extra)));
     server.tool('heliusKnowledge', 'Docs, guides, pricing references, troubleshooting, source, blog, and SIMD research. Use for guides, rate limits, or errors, not live mutations.', HELIUS_KNOWLEDGE_SCHEMA, withTelemetryHandler('heliusKnowledge', (params, extra) => dispatchRoutedTool('heliusKnowledge', params, extra)));
     server.tool('heliusWrite', 'Mutating SOL/token transfer and staking actions. Use for sends or staking, not read-only queries.', HELIUS_WRITE_SCHEMA, withTelemetryHandler('heliusWrite', (params, extra) => dispatchRoutedTool('heliusWrite', params, extra)));

package/dist/router/required-params.js

@@ -10,6 +10,7 @@ export const ACTION_REQUIRED_PARAMS = {
     getBalance: ['address'],
     getTokenBalances: ['address'],
     getWalletBalances: ['address'],
+    getWalletBalanceAt: ['address', 'mint'],
     getWalletHistory: ['address'],
     getWalletTransfers: ['address'],
     getWalletIdentity: ['address'],
@@ -30,6 +31,7 @@ export const ACTION_REQUIRED_PARAMS = {
     getTokenHolders: ['mint'],
     getProgramAccounts: ['programId'],
     getBlock: ['slot'],
+    simulateTransaction: ['transaction'],
     getWithdrawableAmount: ['stakeAccount'],
     // Streaming
     createWebhook: ['webhookURL', 'accountAddresses'],

package/dist/router/schemas.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 export declare const HeliusAccountActionSchema: z.ZodEnum<["getStarted", "setHeliusApiKey", "generateKeypair", "signup", "getAccountStatus", "getAccountPlan", "getHeliusPlanInfo", "compareHeliusPlans", "previewUpgrade", "upgradePlan", "payRenewal", "purchaseCredits"]>;
-export declare const HeliusWalletActionSchema: z.ZodEnum<["getBalance", "getTokenBalances", "getWalletBalances", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy"]>;
+export declare const HeliusWalletActionSchema: z.ZodEnum<["getBalance", "getTokenBalances", "getWalletBalances", "getWalletBalanceAt", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy"]>;
 export declare const HeliusAssetActionSchema: z.ZodEnum<["getAsset", "getAssetsByOwner", "searchAssets", "getAssetsByGroup", "getAssetProof", "getAssetProofBatch", "getSignaturesForAsset", "getNftEditions", "getTokenHolders"]>;
 export declare const HeliusTransactionActionSchema: z.ZodEnum<["parseTransactions", "getTransactionHistory", "getTransfersByAddress"]>;
-export declare const HeliusChainActionSchema: z.ZodEnum<["getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "getStakeAccounts", "getWithdrawableAmount"]>;
+export declare const HeliusChainActionSchema: z.ZodEnum<["getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "simulateTransaction", "getStakeAccounts", "getWithdrawableAmount"]>;
 export declare const HeliusStreamingActionSchema: z.ZodEnum<["createWebhook", "getAllWebhooks", "getWebhookByID", "updateWebhook", "deleteWebhook", "transactionSubscribe", "accountSubscribe", "laserstreamSubscribe"]>;
 export declare const HeliusKnowledgeActionSchema: z.ZodEnum<["lookupHeliusDocs", "listHeliusDocTopics", "getHeliusCreditsInfo", "getRateLimitInfo", "troubleshootError", "recommendStack", "getSIMD", "listSIMDs", "searchSolanaDocs", "readSolanaSourceFile", "fetchHeliusBlog", "getPumpFunGuide", "getSenderInfo", "getWebhookGuide", "getLatencyComparison", "getEnhancedWebSocketInfo", "getLaserstreamInfo"]>;
 export declare const HeliusWriteActionSchema: z.ZodEnum<["transferSol", "transferToken", "stakeSOL", "unstakeSOL", "withdrawStake"]>;
@@ -29,11 +29,15 @@ export declare const HELIUS_ACCOUNT_SCHEMA: {
     readonly _model: z.ZodString;
 };
 export declare const HELIUS_WALLET_SCHEMA: {
-    action: z.ZodEnum<["getBalance", "getTokenBalances", "getWalletBalances", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy"]>;
+    action: z.ZodEnum<["getBalance", "getTokenBalances", "getWalletBalances", "getWalletBalanceAt", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy"]>;
     detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
     args: z.ZodOptional<z.ZodUnion<[z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>, z.ZodPipeline<z.ZodEffects<z.ZodString, any, string>, z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>]>>;
     address: z.ZodOptional<z.ZodString>;
     addresses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    mint: z.ZodOptional<z.ZodString>;
+    time: z.ZodOptional<z.ZodNumber>;
+    datetime: z.ZodOptional<z.ZodString>;
+    slot: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
     page: z.ZodOptional<z.ZodNumber>;
     cursor: z.ZodOptional<z.ZodString>;
@@ -94,7 +98,7 @@ export declare const HELIUS_TRANSACTION_SCHEMA: {
     readonly _model: z.ZodString;
 };
 export declare const HELIUS_CHAIN_SCHEMA: {
-    action: z.ZodEnum<["getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "getStakeAccounts", "getWithdrawableAmount"]>;
+    action: z.ZodEnum<["getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "simulateTransaction", "getStakeAccounts", "getWithdrawableAmount"]>;
     detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
     args: z.ZodOptional<z.ZodUnion<[z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>, z.ZodPipeline<z.ZodEffects<z.ZodString, any, string>, z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>]>>;
     address: z.ZodOptional<z.ZodString>;
@@ -111,6 +115,10 @@ export declare const HELIUS_CHAIN_SCHEMA: {
     dataSize: z.ZodOptional<z.ZodNumber>;
     owner: z.ZodOptional<z.ZodString>;
     mint: z.ZodOptional<z.ZodString>;
+    transaction: z.ZodOptional<z.ZodString>;
+    sigVerify: z.ZodOptional<z.ZodBoolean>;
+    replaceRecentBlockhash: z.ZodOptional<z.ZodBoolean>;
+    commitment: z.ZodOptional<z.ZodString>;
 } & {
     readonly _feedback: z.ZodString;
     readonly _feedbackTool: z.ZodString;

package/dist/router/schemas.js

@@ -49,6 +49,10 @@ export const HELIUS_WALLET_SCHEMA = withTelemetry({
     args: argsField,
     address: optionalString(),
     addresses: stringArray(),
+    mint: optionalString(),
+    time: optionalNumber(),
+    datetime: optionalString(),
+    slot: optionalNumber(),
     limit: optionalNumber(),
     page: optionalNumber(),
     cursor: optionalString(),
@@ -114,6 +118,11 @@ export const HELIUS_CHAIN_SCHEMA = withTelemetry({
     dataSize: optionalNumber(),
     owner: optionalString(),
     mint: optionalString(),
+    // simulateTransaction
+    transaction: optionalString(),
+    sigVerify: optionalBoolean(),
+    replaceRecentBlockhash: optionalBoolean(),
+    commitment: optionalString(),
 });
 export const HELIUS_STREAMING_SCHEMA = withTelemetry({
     action: HeliusStreamingActionSchema,

package/dist/tools/product-catalog.js

@@ -37,7 +37,7 @@ export const PRODUCT_CATALOG = {
     },
     'wallet-api': {
         name: 'Wallet API',
-        mcpTools: ['getWalletBalances', 'getWalletHistory', 'getWalletTransfers', 'getWalletIdentity', 'batchWalletIdentity', 'getWalletFundedBy'],
+        mcpTools: ['getWalletBalances', 'getWalletBalanceAt', 'getWalletHistory', 'getWalletTransfers', 'getWalletIdentity', 'batchWalletIdentity', 'getWalletFundedBy'],
         creditCostPerCall: '100 credits',
         minimumPlan: 'developer',
         docKey: 'wallet-api',

package/dist/tools/transactions.js

@@ -352,6 +352,95 @@ export function registerTransactionTools(server) {
         const fullText = outputLines.join('\n');
         return mcpText(truncateResponse(fullText));
     });
+    // Simulate Transaction (preflight dry-run — does NOT submit on-chain)
+    server.tool('simulateTransaction', 'BEST FOR: dry-running a transaction before sending. Simulates a base64-encoded transaction against current chain state and returns whether it would succeed/fail, the program error (if any), compute units consumed, program logs, return data, and — when `addresses` are provided — post-simulation account state. Does NOT submit anything on-chain. Defaults: replaces the recent blockhash (so unsigned or stale-blockhash transactions can still be simulated) and skips signature verification. Set sigVerify=true to verify signatures (requires a valid recent blockhash; mutually exclusive with replaceRecentBlockhash). Credit cost: 1 credit/call.', {
+        transaction: z.string().describe('Base64-encoded serialized transaction (not base58). Signed or unsigned.'),
+        sigVerify: z.boolean().optional().default(false).describe('Verify transaction signatures. Requires a valid recent blockhash. Mutually exclusive with replaceRecentBlockhash (sigVerify wins if both set).'),
+        replaceRecentBlockhash: z.boolean().optional().default(true).describe('Replace the recent blockhash with the latest before simulating (default true) so unsigned/stale transactions can be simulated. Ignored when sigVerify=true.'),
+        commitment: z.string().optional().describe('Commitment level: "processed" | "confirmed" | "finalized".'),
+        addresses: z.array(z.string()).optional().describe('Optional account addresses (base58) to return post-simulation state for.')
+    }, async ({ transaction, sigVerify, replaceRecentBlockhash, commitment, addresses }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        if (typeof transaction !== 'string' || transaction.trim().length === 0) {
+            return mcpError('A base64-encoded transaction string is required.', {
+                type: 'VALIDATION',
+                code: 'INVALID_TRANSACTION',
+                retryable: false,
+                recovery: 'Pass the base64-encoded (not base58) serialized transaction in the `transaction` field.',
+            });
+        }
+        if (commitment) {
+            const err = validateEnum(commitment, ['processed', 'confirmed', 'finalized'], 'Simulate Transaction Error', 'commitment');
+            if (err)
+                return err;
+        }
+        const helius = getHeliusClient();
+        // sigVerify and replaceRecentBlockhash are mutually exclusive at the RPC layer.
+        const verify = sigVerify === true;
+        const replaceBlockhash = verify ? false : replaceRecentBlockhash !== false;
+        const config = {
+            encoding: 'base64',
+            sigVerify: verify,
+            replaceRecentBlockhash: replaceBlockhash,
+        };
+        if (commitment)
+            config.commitment = commitment;
+        if (addresses && addresses.length > 0) {
+            config.accounts = { encoding: 'base64', addresses };
+        }
+        let result;
+        try {
+            result = await helius.simulateTransaction(transaction, config);
+        }
+        catch (err) {
+            return handleToolError(err, 'Simulate Transaction Error', [
+                http400Error('Simulate Transaction Error'),
+            ]);
+        }
+        const value = result?.value;
+        if (!value) {
+            return mcpText('**Transaction Simulation**\n\nNo simulation result was returned by the RPC.');
+        }
+        const failed = value.err != null;
+        const lines = ['**Transaction Simulation**', ''];
+        if (result.context?.slot != null) {
+            lines.push(`**Simulated at slot:** ${Number(result.context.slot).toLocaleString()}`);
+        }
+        lines.push(`**Status:** ${failed ? '❌ Would fail' : '✅ Would succeed'}`);
+        if (failed) {
+            const errStr = typeof value.err === 'object' ? JSON.stringify(value.err) : String(value.err);
+            lines.push(`**Error:** ${errStr}`);
+        }
+        if (value.unitsConsumed != null) {
+            lines.push(`**Compute Units Consumed:** ${Number(value.unitsConsumed).toLocaleString()}`);
+        }
+        lines.push(`**Signature verification:** ${verify ? 'on' : 'off'} | **Replace blockhash:** ${replaceBlockhash ? 'on' : 'off'}`);
+        if (value.returnData?.data?.[0]) {
+            lines.push('', `**Return Data** (program \`${value.returnData.programId}\`):`, `\`${value.returnData.data[0]}\``);
+        }
+        if (value.logs && value.logs.length > 0) {
+            lines.push('', `**Program Logs (${value.logs.length}):**`, '```');
+            value.logs.forEach((log) => lines.push(log));
+            lines.push('```');
+        }
+        else {
+            lines.push('', '_No program logs returned._');
+        }
+        if (config.accounts && Array.isArray(value.accounts)) {
+            lines.push('', '**Post-Simulation Account State:**');
+            addresses.forEach((addr, i) => {
+                const acc = value.accounts[i];
+                if (!acc) {
+                    lines.push(`- ${formatAddress(addr)}: (not found or empty)`);
+                }
+                else {
+                    lines.push(`- ${formatAddress(addr)}: ${formatSol(Number(acc.lamports))}, owner ${acc.owner}${acc.executable ? ' (executable)' : ''}`);
+                }
+            });
+        }
+        return mcpText(truncateResponse(lines.join('\n')));
+    });
     // Get Transaction History (unified: parsed, signatures, or raw mode)
     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)'),

package/dist/tools/wallet.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getHeliusClient, hasApiKey } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey, restRequest } from '../utils/helius.js';
 import { formatAddress, formatTimestamp } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
 import { mcpText, mcpError, validateEnum, handleToolError, http404Error, addressError } from '../utils/errors.js';
@@ -143,6 +143,55 @@ export function registerWalletTools(server) {
             ]);
         }
     });
+    // ─── Get Historical Token Balance ───
+    server.tool('getWalletBalanceAt', 'BEST FOR: a wallet\'s exact balance of a specific token (or native SOL) at a past timestamp, datetime, or slot. PREFER getWalletBalances for current holdings. Reads the post-transaction balance from the wallet\'s most recent transaction at or before the requested point — an exact value, not an estimate. Provide exactly ONE of time, datetime, or slot. For native SOL pass mint=So11111111111111111111111111111111111111111. Credit cost: 100 credits. Requires Developer+ plan.', {
+        address: z.string().describe('Solana wallet address (base58 encoded)'),
+        mint: z.string().describe('Token mint address. For native SOL use So11111111111111111111111111111111111111111'),
+        time: z.number().optional().describe('Unix timestamp in seconds. Provide exactly one of time, datetime, or slot'),
+        datetime: z.string().optional().describe('Datetime string (e.g. "2025-01-10" or "2025-01-10T19:20:00Z"). Interpreted as UTC unless an explicit timezone is included. Provide exactly one of time, datetime, or slot'),
+        slot: z.number().optional().describe('Slot number — exact and deterministic. Provide exactly one of time, datetime, or slot')
+    }, async ({ address, mint, time, datetime, slot }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
+        const provided = [time !== undefined, datetime !== undefined, slot !== undefined].filter(Boolean).length;
+        if (provided !== 1) {
+            return mcpError('Provide exactly one of `time`, `datetime`, or `slot`.', { type: 'VALIDATION', code: 'INVALID_TIME_SELECTOR', retryable: false, recovery: 'Pass a single point in time: a Unix timestamp (time), a datetime string (datetime), or a slot number (slot).' });
+        }
+        try {
+            const params = new URLSearchParams({ mint });
+            if (time !== undefined)
+                params.set('time', String(time));
+            if (datetime !== undefined)
+                params.set('datetime', datetime);
+            if (slot !== undefined)
+                params.set('slot', String(slot));
+            const data = await restRequest(`/v1/wallet/${address}/balance-at?${params.toString()}`);
+            const symbol = data.isNative ? 'SOL' : formatAddress(data.mint || mint);
+            const lines = ['**Historical Token Balance**', ''];
+            lines.push(`**Wallet:** ${formatAddress(data.wallet || address)}`);
+            lines.push(`**Token:** ${symbol}${data.isNative ? '' : ` (\`${data.mint || mint}\`)`}`);
+            lines.push(`**Balance:** ${data.balance} ${symbol}`);
+            lines.push(`**Raw:** ${data.balanceRaw} (decimals: ${data.decimals})`);
+            // For datetime queries, echo the resolved epoch so the UTC interpretation is visible.
+            if (datetime !== undefined && data.requested?.time != null) {
+                lines.push('', `**Resolved:** \`${datetime}\` → ${formatTimestamp(data.requested.time)} (epoch ${data.requested.time})`);
+            }
+            if (data.asOf) {
+                const asOfTime = data.asOf.blockTime ? formatTimestamp(data.asOf.blockTime) : 'N/A';
+                lines.push('', `**As of:** slot ${data.asOf.slot} — ${asOfTime}`);
+                lines.push(`Signature: \`${data.asOf.signature}\``);
+            }
+            else {
+                lines.push('', '*No matching activity at or before the requested point — the wallet had not held this token yet, so the balance is genuinely 0.*');
+            }
+            return mcpText(lines.join('\n'));
+        }
+        catch (err) {
+            return handleToolError(err, 'Error fetching historical balance', [
+                addressError('Historical Balance'),
+            ]);
+        }
+    });
     // ─── Get Wallet History ───
     server.tool('getWalletHistory', 'BEST FOR: balance change deltas per transaction. PREFER getTransactionHistory for general history, getWalletTransfers for sends/receives. Get transaction history with balance changes per transaction. Credit cost: 100 credits. Requires Developer+ plan.', {
         address: z.string().describe('Solana wallet address (base58 encoded)'),

package/dist/utils/helius.js

@@ -1,6 +1,7 @@
 import { createHelius } from 'helius-sdk';
 import { MCP_USER_AGENT } from '../http.js';
 import { getSharedApiKey } from './config.js';
+import { wrapClientWithResilience, withResilience, READ_TIMEOUT_MS } from './resilience.js';
 let sessionApiKey = null;
 let sessionNetwork = 'mainnet-beta';
 let heliusClient = null;
@@ -36,7 +37,9 @@ export function hasApiKey() {
 export function getHeliusClient() {
     if (!heliusClient) {
         const apiKey = getApiKey();
-        heliusClient = createHelius({ apiKey, userAgent: MCP_USER_AGENT });
+        // Wrap so idempotent reads get a timeout + retry-with-backoff; writes,
+        // sends, and streaming pass through untouched. See utils/resilience.ts.
+        heliusClient = wrapClientWithResilience(createHelius({ apiKey, userAgent: MCP_USER_AGENT }));
     }
     return heliusClient;
 }
@@ -109,17 +112,24 @@ export async function restRequest(endpoint, options = {}) {
     if (options.body) {
         headers['Content-Type'] ??= 'application/json';
     }
-    const response = await fetch(url, {
-        ...options,
-        headers,
-    });
-    if (!response.ok) {
+    // Reads here are idempotent: retry transient failures, and abort (not just
+    // race) a hung request via AbortSignal so the socket is released.
+    return withResilience(async () => {
+        const response = await fetch(url, {
+            ...options,
+            headers,
+            signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            const error = new Error(`HTTP ${response.status}: ${text}`);
+            error.statusCode = response.status;
+            throw error;
+        }
         const text = await response.text();
-        throw new Error(`HTTP ${response.status}: ${text}`);
-    }
-    const text = await response.text();
-    if (!text || text === 'null') {
-        return null;
-    }
-    return JSON.parse(text);
+        if (!text || text === 'null') {
+            return null;
+        }
+        return JSON.parse(text);
+    }, `restRequest ${endpoint}`, { timeoutMs: 0 });
 }

package/dist/utils/resilience.d.ts

@@ -0,0 +1,39 @@
+/**
+ * RPC resilience for the Helius client: a per-call timeout plus retry-with-backoff
+ * for transient failures (HTTP 429/502/503/504 and network resets).
+ *
+ * Only idempotent reads are wrapped — methods whose name matches `READ_METHOD_RE`
+ * (`get*` / `search*` / `simulate*`). Everything else passes through untouched:
+ * sends (`sendTransactionWithSender`, `sendSmartTransaction`, `broadcastTransaction`),
+ * webhook `create`/`update`/`delete`, `pollTransactionConfirmation`, and streaming
+ * (`ws`). This guarantees we never retry a non-idempotent write or abandon a
+ * transaction that is still confirming — sends self-bound via the SDK's poll timeout.
+ *
+ * Client-side timeouts fail fast (no retry): retrying a hung call just hangs again.
+ * Only fast-failing transients (429/5xx/network reset) are retried.
+ */
+/** Default per-attempt timeout for idempotent reads. */
+export declare const READ_TIMEOUT_MS = 30000;
+export interface ResilienceOptions {
+    /** Total attempts including the first. */
+    attempts?: number;
+    baseDelayMs?: number;
+    factor?: number;
+    maxDelayMs?: number;
+    /** Fractional jitter, 0..1. */
+    jitter?: number;
+    /** Per-attempt timeout in ms. 0 disables the timeout race. */
+    timeoutMs?: number;
+}
+/** True when an error is a transient failure worth retrying. */
+export declare function isRetryable(err: unknown): boolean;
+/** Race a promise-returning fn against a timeout. `ms <= 0` disables the race. */
+export declare function withTimeout<T>(fn: () => Promise<T>, ms: number, label?: string): Promise<T>;
+/** Run `fn` with a timeout and exponential backoff on transient errors. */
+export declare function withResilience<T>(fn: () => Promise<T>, label?: string, opts?: ResilienceOptions): Promise<T>;
+/**
+ * Wrap a Helius client so idempotent reads get timeout + retry. Recurses into the
+ * `enhanced`/`webhooks`/`tx`/`wallet`/`zk` namespaces; leaves `ws` (streaming) and
+ * all non-read methods (sends, webhook mutations) untouched.
+ */
+export declare function wrapClientWithResilience<T extends object>(client: T, opts?: ResilienceOptions): T;

package/dist/utils/resilience.js

@@ -0,0 +1,130 @@
+/**
+ * RPC resilience for the Helius client: a per-call timeout plus retry-with-backoff
+ * for transient failures (HTTP 429/502/503/504 and network resets).
+ *
+ * Only idempotent reads are wrapped — methods whose name matches `READ_METHOD_RE`
+ * (`get*` / `search*` / `simulate*`). Everything else passes through untouched:
+ * sends (`sendTransactionWithSender`, `sendSmartTransaction`, `broadcastTransaction`),
+ * webhook `create`/`update`/`delete`, `pollTransactionConfirmation`, and streaming
+ * (`ws`). This guarantees we never retry a non-idempotent write or abandon a
+ * transaction that is still confirming — sends self-bound via the SDK's poll timeout.
+ *
+ * Client-side timeouts fail fast (no retry): retrying a hung call just hangs again.
+ * Only fast-failing transients (429/5xx/network reset) are retried.
+ */
+const READ_METHOD_RE = /^(get|search|simulate)/;
+const WRAPPED_NAMESPACES = new Set(['enhanced', 'webhooks', 'tx', 'wallet', 'zk']);
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+const NETWORK_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ECONNREFUSED',
+    'EPIPE',
+]);
+/** Default per-attempt timeout for idempotent reads. */
+export const READ_TIMEOUT_MS = 30_000;
+const DEFAULTS = {
+    attempts: 3,
+    baseDelayMs: 400,
+    factor: 2,
+    maxDelayMs: 5_000,
+    jitter: 0.2,
+    timeoutMs: READ_TIMEOUT_MS,
+};
+class TimeoutError extends Error {
+    constructor(ms, label) {
+        super(`Request timed out after ${ms}ms${label ? ` (${label})` : ''}`);
+        this.name = 'TimeoutError';
+    }
+}
+function statusOf(err) {
+    return err?.context?.statusCode ?? err?.statusCode ?? err?.status;
+}
+/** True when an error is a transient failure worth retrying. */
+export function isRetryable(err) {
+    if (err && typeof err === 'object') {
+        const e = err;
+        // Client-side timeout/abort: fail fast (retrying a hung call just hangs again).
+        if (e.name === 'TimeoutError' || e.name === 'AbortError')
+            return false;
+        const status = statusOf(e);
+        if (typeof status === 'number' && RETRYABLE_STATUS.has(status))
+            return true;
+        const code = e.code ?? e.cause?.code;
+        if (typeof code === 'string' && NETWORK_ERROR_CODES.has(code))
+            return true;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    // Match a bare status code (kit: "HTTP error (429): ...", restRequest: "HTTP 429: ...").
+    if (/(?:^|[^\d])(429|502|503|504)(?:[^\d]|$)/.test(msg))
+        return true;
+    if (/fetch failed|socket hang up|network error|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND/i.test(msg))
+        return true;
+    return false;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Race a promise-returning fn against a timeout. `ms <= 0` disables the race. */
+export async function withTimeout(fn, ms, label = '') {
+    if (!ms || ms <= 0)
+        return fn();
+    let timer;
+    try {
+        return await Promise.race([
+            fn(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new TimeoutError(ms, label)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Run `fn` with a timeout and exponential backoff on transient errors. */
+export async function withResilience(fn, label = '', opts = {}) {
+    const o = { ...DEFAULTS, ...opts };
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await withTimeout(fn, o.timeoutMs, label);
+        }
+        catch (err) {
+            if (attempt >= o.attempts || !isRetryable(err))
+                throw err;
+            const base = Math.min(o.maxDelayMs, o.baseDelayMs * o.factor ** (attempt - 1));
+            const jittered = base * (1 + (Math.random() * 2 - 1) * o.jitter);
+            await sleep(Math.max(0, Math.round(jittered)));
+        }
+    }
+}
+/**
+ * Wrap a Helius client so idempotent reads get timeout + retry. Recurses into the
+ * `enhanced`/`webhooks`/`tx`/`wallet`/`zk` namespaces; leaves `ws` (streaming) and
+ * all non-read methods (sends, webhook mutations) untouched.
+ */
+export function wrapClientWithResilience(client, opts = {}) {
+    const makeHandler = (prefix) => ({
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof prop !== 'string')
+                return value;
+            // Recurse into request/response namespaces. `ws` is intentionally excluded.
+            if (WRAPPED_NAMESPACES.has(prop) && value && typeof value === 'object') {
+                return new Proxy(value, makeHandler(`${prop}.`));
+            }
+            if (typeof value !== 'function')
+                return value;
+            const retry = READ_METHOD_RE.test(prop);
+            const label = `${prefix}${prop}`;
+            const fn = value;
+            return (...args) => {
+                const invoke = () => fn.apply(target, args);
+                // Reads: timeout + retry. Everything else: untouched passthrough.
+                return retry ? withResilience(() => Promise.resolve(invoke()), label, opts) : invoke();
+            };
+        },
+    });
+    return new Proxy(client, makeHandler(''));
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.0.0";
+export declare const version = "2.1.0";

package/dist/version.js

@@ -1 +1 @@
-export const version = '2.0.0';
+export const version = '2.1.0';

package/package.json

@@ -1,22 +1,12 @@
 {
   "name": "helius-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Official Helius MCP Server - Complete Solana blockchain data access for AI assistants",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "helius-mcp": "dist/index.js"
   },
-  "scripts": {
-    "prebuild": "node -p \"'export const version = \\'' + require('./package.json').version + '\\';'\" > src/version.ts",
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "validate": "node dist/scripts/validate-catalog.js",
-    "test": "pnpm build && pnpm validate && vitest run",
-    "changelog": "auto-changelog --tag-prefix helius-mcp@",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "helius",
     "solana",
@@ -40,7 +30,7 @@
   },
   "homepage": "https://github.com/helius-labs/core-ai#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@solana-program/system": "^0.10.0",
     "@solana-program/token": "^0.9.0",
     "@solana/kit": "^5.0.0",
@@ -60,5 +50,14 @@
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
-  ]
-}
+  ],
+  "scripts": {
+    "prebuild": "node -p \"'export const version = \\'' + require('./package.json').version + '\\';'\" > src/version.ts",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "validate": "node dist/scripts/validate-catalog.js",
+    "test": "pnpm build && pnpm validate && vitest run",
+    "changelog": "auto-changelog --tag-prefix helius-mcp@"
+  }
+}

package/system-prompts/helius/claude.system.md

@@ -90,9 +90,9 @@ Enhanced WebSockets (Developer+) for most needs; Laserstream gRPC (Business+ mai
 
 ### Wallet Analysis
 **Reference**: See wallet-api.md
-**APIs**: Wallet API (`getWalletIdentity`, `getWalletBalances`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`)
-**MCP tools** (if available): `getWalletIdentity`, `batchWalletIdentity`, `getWalletBalances`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`
-**When**: wallet identity lookup, portfolio/balance breakdowns, fund flow tracing, wallet analytics, tax reporting, investigation tools
+**APIs**: Wallet API (`getWalletIdentity`, `getWalletBalances`, `getWalletBalanceAt`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`)
+**MCP tools** (if available): `getWalletIdentity`, `batchWalletIdentity`, `getWalletBalances`, `getWalletBalanceAt`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`
+**When**: wallet identity lookup, portfolio/balance breakdowns, historical balance at a past time/slot, fund flow tracing, wallet analytics, tax reporting, investigation tools
 
 ### Account & Token Data
 **APIs**: Standard RPC (`getBalance`, `getAccountInfo`, `getBlock`), Token API (`getTokenBalances`, `getTokenAccounts`, `getTokenHolders`)

package/system-prompts/helius/full.md

@@ -80,9 +80,9 @@ Enhanced WebSockets (Developer+) for most needs; Laserstream gRPC (Business+ mai
 
 ### Wallet Analysis
 **Reference**: See wallet-api.md (inlined below)
-**APIs**: Wallet API (`getWalletIdentity`, `getWalletBalances`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`)
-**MCP tools** (if available): `getWalletIdentity`, `batchWalletIdentity`, `getWalletBalances`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`
-**When**: wallet identity lookup, portfolio/balance breakdowns, fund flow tracing, wallet analytics, tax reporting, investigation tools
+**APIs**: Wallet API (`getWalletIdentity`, `getWalletBalances`, `getWalletBalanceAt`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`)
+**MCP tools** (if available): `getWalletIdentity`, `batchWalletIdentity`, `getWalletBalances`, `getWalletBalanceAt`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`
+**When**: wallet identity lookup, portfolio/balance breakdowns, historical balance at a past time/slot, fund flow tracing, wallet analytics, tax reporting, investigation tools
 
 ### Account & Token Data
 **APIs**: Standard RPC (`getBalance`, `getAccountInfo`, `getBlock`), Token API (`getTokenBalances`, `getTokenAccounts`, `getTokenHolders`)
@@ -2266,6 +2266,7 @@ All Wallet API endpoints have direct MCP tools. ALWAYS use these instead of gene
 | `getWalletIdentity` | `GET /v1/wallet/{wallet}/identity` | Identify known wallets (exchanges, protocols, institutions). Accepts an address or an SNS/ANS domain (mainnet only). |
 | `batchWalletIdentity` | `POST /v1/wallet/batch-identity` | Bulk lookup up to 100 entries in one request. Entries may be addresses or SNS/ANS domains (mainnet only). |
 | `getWalletBalances` | `GET /v1/wallet/{wallet}/balances` | Token + NFT balances with USD values, sorted by value |
+| `getWalletBalanceAt` | `GET /v1/wallet/{wallet}/balance-at` | Exact historical balance of a single token (or SOL) at a past time, datetime, or slot |
 | `getWalletHistory` | `GET /v1/wallet/{wallet}/history` | Transaction history with balance changes per tx |
 | `getWalletTransfers` | `GET /v1/wallet/{wallet}/transfers` | Token transfers with direction (in/out) and counterparty |
 | `getWalletFundedBy` | `GET /v1/wallet/{wallet}/funded-by` | Original funding source (first incoming SOL transfer) |
@@ -2279,6 +2280,7 @@ When the user asks to investigate a wallet, identify an address, check balances,
 | Check if a wallet is a known entity | `getWalletIdentity` |
 | Label many addresses at once | `batchWalletIdentity` (up to 100) |
 | See token holdings with USD values | `getWalletBalances` |
+| Know a token/SOL balance at a past time or slot | `getWalletBalanceAt` |
 | View recent transaction activity | `getWalletHistory` |
 | Track incoming/outgoing transfers | `getWalletTransfers` |
 | Find who funded a wallet | `getWalletFundedBy` |
@@ -2360,6 +2362,28 @@ Response includes:
 
 **Pricing notes**: USD values sourced from DAS, updated hourly, covers top 10K tokens. `pricePerToken` and `usdValue` may be `null` for unlisted tokens. These are estimates, not real-time market rates.
 
+## Historical Token Balance
+
+`getWalletBalanceAt` returns a wallet's exact balance of a **single** token (or native SOL) at a past point in time. The balance is read from the wallet's most recent transaction involving the token **at or before** the requested point — its post-transaction balance, which held until the wallet's next transaction. This is an exact value, not an estimate. Like the other Wallet API endpoints, it costs 100 credits and requires a Developer plan or higher.
+
+**Parameters**:
+- `mint` (required) — token mint address. For native SOL use the pseudo-mint `So11111111111111111111111111111111111111111`.
+- **Exactly one** of:
+  - `time` — Unix timestamp in **seconds**
+  - `datetime` — datetime string (`2025-01-10`, `2025-01-10 19:20:00`, `2025-01-10T19:20:00Z`, `...+02:00`). Interpreted as **UTC** unless an explicit timezone is included.
+  - `slot` — slot number. Exact and deterministic; prefer this since validator block times can drift by a few seconds.
+
+**Response** (`balance` and `balanceRaw` are strings to avoid precision loss):
+- `balance` — human-readable amount (trailing zeros trimmed)
+- `balanceRaw` — exact amount in smallest unit (lamports for SOL)
+- `decimals`, `isNative`
+- `requested` — echo of the query (when `datetime` is used, `time` is also populated with the resolved epoch seconds)
+- `asOf` — the transaction the balance was read from (`slot`, `blockTime`, `signature`), or **`null`** when the wallet had no matching transaction at or before the requested point. `asOf: null` is **not an error** — it means the balance is genuinely `0` (the wallet had not held the token by then).
+
+**Notes**:
+- Providing zero or more than one of `time`/`datetime`/`slot` is a 400 error.
+- `502` indicates an upstream RPC error/timeout — retryable with exponential backoff.
+
 ## Transaction History
 
 `getWalletHistory` returns parsed, human-readable transactions with balance changes.

package/system-prompts/helius/openai.developer.md

@@ -90,9 +90,9 @@ Enhanced WebSockets (Developer+) for most needs; Laserstream gRPC (Business+ mai
 
 ### Wallet Analysis
 **Reference**: See wallet-api.md
-**APIs**: Wallet API (`getWalletIdentity`, `getWalletBalances`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`)
-**MCP tools** (if available): `getWalletIdentity`, `batchWalletIdentity`, `getWalletBalances`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`
-**When**: wallet identity lookup, portfolio/balance breakdowns, fund flow tracing, wallet analytics, tax reporting, investigation tools
+**APIs**: Wallet API (`getWalletIdentity`, `getWalletBalances`, `getWalletBalanceAt`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`)
+**MCP tools** (if available): `getWalletIdentity`, `batchWalletIdentity`, `getWalletBalances`, `getWalletBalanceAt`, `getWalletHistory`, `getWalletTransfers`, `getWalletFundedBy`
+**When**: wallet identity lookup, portfolio/balance breakdowns, historical balance at a past time/slot, fund flow tracing, wallet analytics, tax reporting, investigation tools
 
 ### Account & Token Data
 **APIs**: Standard RPC (`getBalance`, `getAccountInfo`, `getBlock`), Token API (`getTokenBalances`, `getTokenAccounts`, `getTokenHolders`)

package/system-prompts/helius-dflow/full.md

@@ -2992,6 +2992,7 @@ All Wallet API endpoints have direct MCP tools. ALWAYS use these instead of gene
 | `getWalletIdentity` | `GET /v1/wallet/{wallet}/identity` | Identify known wallets (exchanges, protocols, institutions). Accepts an address or an SNS/ANS domain (mainnet only). |
 | `batchWalletIdentity` | `POST /v1/wallet/batch-identity` | Bulk lookup up to 100 entries in one request. Entries may be addresses or SNS/ANS domains (mainnet only). |
 | `getWalletBalances` | `GET /v1/wallet/{wallet}/balances` | Token + NFT balances with USD values, sorted by value |
+| `getWalletBalanceAt` | `GET /v1/wallet/{wallet}/balance-at` | Exact historical balance of a single token (or SOL) at a past time, datetime, or slot |
 | `getWalletHistory` | `GET /v1/wallet/{wallet}/history` | Transaction history with balance changes per tx |
 | `getWalletTransfers` | `GET /v1/wallet/{wallet}/transfers` | Token transfers with direction (in/out) and counterparty |
 | `getWalletFundedBy` | `GET /v1/wallet/{wallet}/funded-by` | Original funding source (first incoming SOL transfer) |
@@ -3005,6 +3006,7 @@ When the user asks to investigate a wallet, identify an address, check balances,
 | Check if a wallet is a known entity | `getWalletIdentity` |
 | Label many addresses at once | `batchWalletIdentity` (up to 100) |
 | See token holdings with USD values | `getWalletBalances` |
+| Know a token/SOL balance at a past time or slot | `getWalletBalanceAt` |
 | View recent transaction activity | `getWalletHistory` |
 | Track incoming/outgoing transfers | `getWalletTransfers` |
 | Find who funded a wallet | `getWalletFundedBy` |
@@ -3086,6 +3088,28 @@ Response includes:
 
 **Pricing notes**: USD values sourced from DAS, updated hourly, covers top 10K tokens. `pricePerToken` and `usdValue` may be `null` for unlisted tokens. These are estimates, not real-time market rates.
 
+## Historical Token Balance
+
+`getWalletBalanceAt` returns a wallet's exact balance of a **single** token (or native SOL) at a past point in time. The balance is read from the wallet's most recent transaction involving the token **at or before** the requested point — its post-transaction balance, which held until the wallet's next transaction. This is an exact value, not an estimate. Like the other Wallet API endpoints, it costs 100 credits and requires a Developer plan or higher.
+
+**Parameters**:
+- `mint` (required) — token mint address. For native SOL use the pseudo-mint `So11111111111111111111111111111111111111111`.
+- **Exactly one** of:
+  - `time` — Unix timestamp in **seconds**
+  - `datetime` — datetime string (`2025-01-10`, `2025-01-10 19:20:00`, `2025-01-10T19:20:00Z`, `...+02:00`). Interpreted as **UTC** unless an explicit timezone is included.
+  - `slot` — slot number. Exact and deterministic; prefer this since validator block times can drift by a few seconds.
+
+**Response** (`balance` and `balanceRaw` are strings to avoid precision loss):
+- `balance` — human-readable amount (trailing zeros trimmed)
+- `balanceRaw` — exact amount in smallest unit (lamports for SOL)
+- `decimals`, `isNative`
+- `requested` — echo of the query (when `datetime` is used, `time` is also populated with the resolved epoch seconds)
+- `asOf` — the transaction the balance was read from (`slot`, `blockTime`, `signature`), or **`null`** when the wallet had no matching transaction at or before the requested point. `asOf: null` is **not an error** — it means the balance is genuinely `0` (the wallet had not held the token by then).
+
+**Notes**:
+- Providing zero or more than one of `time`/`datetime`/`slot` is a 400 error.
+- `502` indicates an upstream RPC error/timeout — retryable with exponential backoff.
+
 ## Transaction History
 
 `getWalletHistory` returns parsed, human-readable transactions with balance changes.

package/system-prompts/helius-jupiter/full.md

@@ -1898,6 +1898,7 @@ All Wallet API endpoints have direct MCP tools. ALWAYS use these instead of gene
 | `getWalletIdentity` | `GET /v1/wallet/{wallet}/identity` | Identify known wallets (exchanges, protocols, institutions). Accepts an address or an SNS/ANS domain (mainnet only). |
 | `batchWalletIdentity` | `POST /v1/wallet/batch-identity` | Bulk lookup up to 100 entries in one request. Entries may be addresses or SNS/ANS domains (mainnet only). |
 | `getWalletBalances` | `GET /v1/wallet/{wallet}/balances` | Token + NFT balances with USD values, sorted by value |
+| `getWalletBalanceAt` | `GET /v1/wallet/{wallet}/balance-at` | Exact historical balance of a single token (or SOL) at a past time, datetime, or slot |
 | `getWalletHistory` | `GET /v1/wallet/{wallet}/history` | Transaction history with balance changes per tx |
 | `getWalletTransfers` | `GET /v1/wallet/{wallet}/transfers` | Token transfers with direction (in/out) and counterparty |
 | `getWalletFundedBy` | `GET /v1/wallet/{wallet}/funded-by` | Original funding source (first incoming SOL transfer) |
@@ -1911,6 +1912,7 @@ When the user asks to investigate a wallet, identify an address, check balances,
 | Check if a wallet is a known entity | `getWalletIdentity` |
 | Label many addresses at once | `batchWalletIdentity` (up to 100) |
 | See token holdings with USD values | `getWalletBalances` |
+| Know a token/SOL balance at a past time or slot | `getWalletBalanceAt` |
 | View recent transaction activity | `getWalletHistory` |
 | Track incoming/outgoing transfers | `getWalletTransfers` |
 | Find who funded a wallet | `getWalletFundedBy` |
@@ -1992,6 +1994,28 @@ Response includes:
 
 **Pricing notes**: USD values sourced from DAS, updated hourly, covers top 10K tokens. `pricePerToken` and `usdValue` may be `null` for unlisted tokens. These are estimates, not real-time market rates.
 
+## Historical Token Balance
+
+`getWalletBalanceAt` returns a wallet's exact balance of a **single** token (or native SOL) at a past point in time. The balance is read from the wallet's most recent transaction involving the token **at or before** the requested point — its post-transaction balance, which held until the wallet's next transaction. This is an exact value, not an estimate. Like the other Wallet API endpoints, it costs 100 credits and requires a Developer plan or higher.
+
+**Parameters**:
+- `mint` (required) — token mint address. For native SOL use the pseudo-mint `So11111111111111111111111111111111111111111`.
+- **Exactly one** of:
+  - `time` — Unix timestamp in **seconds**
+  - `datetime` — datetime string (`2025-01-10`, `2025-01-10 19:20:00`, `2025-01-10T19:20:00Z`, `...+02:00`). Interpreted as **UTC** unless an explicit timezone is included.
+  - `slot` — slot number. Exact and deterministic; prefer this since validator block times can drift by a few seconds.
+
+**Response** (`balance` and `balanceRaw` are strings to avoid precision loss):
+- `balance` — human-readable amount (trailing zeros trimmed)
+- `balanceRaw` — exact amount in smallest unit (lamports for SOL)
+- `decimals`, `isNative`
+- `requested` — echo of the query (when `datetime` is used, `time` is also populated with the resolved epoch seconds)
+- `asOf` — the transaction the balance was read from (`slot`, `blockTime`, `signature`), or **`null`** when the wallet had no matching transaction at or before the requested point. `asOf: null` is **not an error** — it means the balance is genuinely `0` (the wallet had not held the token by then).
+
+**Notes**:
+- Providing zero or more than one of `time`/`datetime`/`slot` is a 400 error.
+- `502` indicates an upstream RPC error/timeout — retryable with exponential backoff.
+
 ## Transaction History
 
 `getWalletHistory` returns parsed, human-readable transactions with balance changes.

package/system-prompts/helius-phantom/full.md

@@ -2639,6 +2639,7 @@ All Wallet API endpoints have direct MCP tools. ALWAYS use these instead of gene
 | `getWalletIdentity` | `GET /v1/wallet/{wallet}/identity` | Identify known wallets (exchanges, protocols, institutions). Accepts an address or an SNS/ANS domain (mainnet only). |
 | `batchWalletIdentity` | `POST /v1/wallet/batch-identity` | Bulk lookup up to 100 entries in one request. Entries may be addresses or SNS/ANS domains (mainnet only). |
 | `getWalletBalances` | `GET /v1/wallet/{wallet}/balances` | Token + NFT balances with USD values, sorted by value |
+| `getWalletBalanceAt` | `GET /v1/wallet/{wallet}/balance-at` | Exact historical balance of a single token (or SOL) at a past time, datetime, or slot |
 | `getWalletHistory` | `GET /v1/wallet/{wallet}/history` | Transaction history with balance changes per tx |
 | `getWalletTransfers` | `GET /v1/wallet/{wallet}/transfers` | Token transfers with direction (in/out) and counterparty |
 | `getWalletFundedBy` | `GET /v1/wallet/{wallet}/funded-by` | Original funding source (first incoming SOL transfer) |
@@ -2652,6 +2653,7 @@ When the user asks to investigate a wallet, identify an address, check balances,
 | Check if a wallet is a known entity | `getWalletIdentity` |
 | Label many addresses at once | `batchWalletIdentity` (up to 100) |
 | See token holdings with USD values | `getWalletBalances` |
+| Know a token/SOL balance at a past time or slot | `getWalletBalanceAt` |
 | View recent transaction activity | `getWalletHistory` |
 | Track incoming/outgoing transfers | `getWalletTransfers` |
 | Find who funded a wallet | `getWalletFundedBy` |
@@ -2733,6 +2735,28 @@ Response includes:
 
 **Pricing notes**: USD values sourced from DAS, updated hourly, covers top 10K tokens. `pricePerToken` and `usdValue` may be `null` for unlisted tokens. These are estimates, not real-time market rates.
 
+## Historical Token Balance
+
+`getWalletBalanceAt` returns a wallet's exact balance of a **single** token (or native SOL) at a past point in time. The balance is read from the wallet's most recent transaction involving the token **at or before** the requested point — its post-transaction balance, which held until the wallet's next transaction. This is an exact value, not an estimate. Like the other Wallet API endpoints, it costs 100 credits and requires a Developer plan or higher.
+
+**Parameters**:
+- `mint` (required) — token mint address. For native SOL use the pseudo-mint `So11111111111111111111111111111111111111111`.
+- **Exactly one** of:
+  - `time` — Unix timestamp in **seconds**
+  - `datetime` — datetime string (`2025-01-10`, `2025-01-10 19:20:00`, `2025-01-10T19:20:00Z`, `...+02:00`). Interpreted as **UTC** unless an explicit timezone is included.
+  - `slot` — slot number. Exact and deterministic; prefer this since validator block times can drift by a few seconds.
+
+**Response** (`balance` and `balanceRaw` are strings to avoid precision loss):
+- `balance` — human-readable amount (trailing zeros trimmed)
+- `balanceRaw` — exact amount in smallest unit (lamports for SOL)
+- `decimals`, `isNative`
+- `requested` — echo of the query (when `datetime` is used, `time` is also populated with the resolved epoch seconds)
+- `asOf` — the transaction the balance was read from (`slot`, `blockTime`, `signature`), or **`null`** when the wallet had no matching transaction at or before the requested point. `asOf: null` is **not an error** — it means the balance is genuinely `0` (the wallet had not held the token by then).
+
+**Notes**:
+- Providing zero or more than one of `time`/`datetime`/`slot` is a 400 error.
+- `502` indicates an upstream RPC error/timeout — retryable with exponential backoff.
+
 ## Transaction History
 
 `getWalletHistory` returns parsed, human-readable transactions with balance changes.