Helius TypeScript SDK

The Helius TypeScript SDK provides access to Helius APIs and enhanced Solana RPC functionality, making building on Solana as easy as possible.

Agent Account Sign Up

For AI Agents: You can create a Helius account and generate an API key programmatically using the helius-cli. See the agent signup guide or helius-cli agent file for complete details.

Documentation

API reference documentation is available at helius.dev/docs.

See the CHANGELOG for version history and release notes.

Contributions

Interested in contributing? Read the following contributions guide before opening a PR.

Installation

Using pnpm (recommended):

pnpm add helius-sdk
Copy

Using npm:

npm install helius-sdk
Copy

Using yarn:

yarn add helius-sdk
Copy

Usage

The package needs to be configured with your account's API key, which is available in the Helius Dashboard.

import { createHelius } from "helius-sdk";

(async () => {
  const apiKey = ""; // From Helius dashboard
  const helius = createHelius({ apiKey });

  try {
    const assets = await helius.getAssetsByOwner({
      ownerAddress: "owner_address_goes_here",
      page: 1,
      limit: 50,
      sortBy: { sortBy: "created", sortDirection: "asc" },
    });

    console.log("Fetched assets:", assets);
  } catch (error) {
    console.error("Error:", error);
  }
})();
Copy

Migrating to helius-sdk 2.0.0

The Helius Node.js SDK has been rewritten from the ground up in version 2.0.0 to use @solana/kit (i.e., Kit) under the hood, replacing the dependency on @solana/web3.js versions higher than 1.73.2.

We've gone to great lengths to ensure that the developer experience remains largely the same, with minimal impact on existing code. The API methods and namespaces are designed to be intuitive and an improvement on previous versions, so migrating to the latest version is relatively straightforward. There are a plethora of examples found in the examples directory, organized by namespace, to aid in this migration.

For more detailed migration help, refer to the following migration guide

For general help with Kit, please refer to Kit's new documentation site

Handling errors

When the API returns a non-success status code (4xx or 5xx response), an error message will be thrown:

try {
  const assets = await helius.getAssetsByOwner({
    ownerAddress: "owner_address_goes_here",
    page: 1,
    limit: 50,
    sortBy: { sortBy: "created", sortDirection: "asc" },
  });

  console.log("Fetched assets:", assets);
} catch (error) {
  console.error("Error:", error);
}
Copy

Common Error Codes

When working with the Helius SDK, you may encounter several error codes. Below is a table detailing some of the common error codes along with additional information to help you troubleshoot:

Error Code	Error Message	More Information
401	Unauthorized	This occurs when an invalid API key is provided or access is restricted due to RPC rules.
429	Too Many Requests	This indicates that the user has exceeded the request limit in a given timeframe or is out of credits.
5XX	Internal Server Error	This is a generic error message for server-side issues. Please contact Helius support for assistance.

If you encounter any of these errors, refer to the Helius documentation for further guidance, or reach out to the Helius support team for more detailed assistance.

Using the Helius SDK

Our SDK is designed to give you a seamless experience when building on Solana. We've separated the core functionality into various segments. Examples for individual methods can be found in the examples directory, with examples organized by namespace.

DAS API

Comprehensive and performant API for tokens, NFTs, and compressed NFTs on Solana. Available on the helius namespace.

• getAsset(): Get an asset by its ID.
• getAssetBatch(): Get multiple assets by their IDs (up to 1k).
• getAssetProof(): Get a Merkle proof for a compressed asset by its ID.
• getAssetProofBatch(): Get Merkle proofs for a set of compressed assets by their IDs.
• getAssetsByAuthority(): Get a list of assets with a specific authority.
• getAssetsByCreator(): Get a list of assets created by an address.
• getAssetsByGroup(): Get a list of assets by a group key and value. This endpoint is very useful for getting the mint list for NFT Collections.
• getAssetsByOwner(): Get a list of assets owned by an address. This is the fastest way to get all the NFTs and fungible tokens that are owned by a wallet on Solana.
• getNftEditions(): Get information about all the edition NFTs for a specific master NFT.
• getTokenAccounts(): Get information about all token accounts for a specific mint or a specific owner.
• searchAssets(): Search for assets by a variety of parameters. This is very useful for token-gating.

RPC V2 Methods

Enhanced RPC methods, available only with Helius.

• getProgramAccountsV2(): Enhanced version of getProgramAccounts with cursor-based pagination and changedSinceSlot support for efficiently querying large sets of accounts owned by specific Solana programs with incremental updates.
• getAllProgramAccounts(): Auto-paginates through all program accounts. Use with caution on larger programs.
• getTokenAccountsByOwnerV2(): An enhanced version of getTokenAccountsByOwner with cursor-based pagination and changedSinceSlot support to incrementally retrieve SPL token accounts owned by a given mint.
• getAllTokenAccountsByOwner(): Auto-paginates all token accounts for a given owner.
• getTransactionsForAddress(): Get transaction history for an address with advanced filtering by slot, time, and bidirectional sorting options. Supports both signature-only and full transaction details. Optionally include transactions from associated token accounts.

Staking

The easiest way to stake with Helius programmatically. Available on the helius.staking namespace.

• createStakeTransaction(): Generate a transaction to create + delegate a new stake account to the Helius validator.
• createUnstakeTransaction(): Generate a transaction to deactivate a stake account.
• createWithdrawTransaction(): Generate a transaction to withdraw lamports from a stake account (after cooldown).
• getStakeInstructions(): Return only the instructions for creating and delegating a stake account.
• getUnstakeInstruction(): Return the instruction to deactivate a stake account.
• getWithdrawInstruction(): Return the instruction to withdraw lamports from a stake account.
• getWithdrawableAmount(): Determine how many lamports are withdrawable (with optional rent-exempt inclusion).
• getHeliusStakeAccounts(): Return all stake accounts delegated to the Helius validator for a given wallet.

Transactions

Simply create, send, and land transactions as fast as possible. Available on the helius.tx namespace.

• getComputeUnits(): Fetches the total compute units the transaction provided is expected to consume
• broadcastTransaction(): Broadcasts a fully signed transaction (object or serialized) and polls for its confirmation.
• pollTransactionConfirmation(): Polls a transaction to check whether it has been confirmed
• createSmartTransaction(): Creates a smart transaction with the provided configuration
• sendSmartTransaction(): Builds and sends an optimized transaction
• sendTransaction(): Wrapper for sendTransaction RPC call that includes support for a validatorAcls parameter (i.e., JSON-based allow and deny lists).
• sendTransactionWithSender(): Ultra-low latency Solana transaction submission with dual routing to validators and Jito infra via Helius Sender.

Priority Fee API

Estimate optimal priority fees for Solana transactions. Available on the helius namespace.

• getPriorityFeeEstimate(): Returns an estimated priority fee based on a set of predefined priority levels (percentiles).

Enhanced Transactions API

Transform complex Solana transactions into human-readable data. Available on the helius.enhanced namespace.

• getTransactions(): Converts raw Solana transactions into enhanced, human-readable formats with decoded instruction data and contextual information.
• getTransactionsByAddress(): Retrieves a comprehensive transaction history for a given address with human-readable decoded data.

Webhooks

Provides methods for setting up, editing, and managing webhooks, crucial for listening to on-chain Solana events (e.g., sales, listings, swaps) and triggering actions when these events happen. Available on the helius.webhooks namespace.

• createWebhook(): Creates a new webhook with the provided request.
• getWebhookByID(): Retrieves a single webhook by its ID.
• getAllWebhooks(): Retrieves a list of all webhooks.
• updateWebhook(): Edits an existing webhook by its ID with the provided request.
• deleteWebhook(): Deletes a webhook by its ID.

WebSockets

Stream real-time data with WebSockets using Kit's subscription methods. Available on the helius.ws namespace.

• logsNotifications(): Streams transaction logs for all transactions, all transactions including votes, or transactions that mention a specific set of addresses.
• slotNotifications(): Streams notifications any time a slot is processed by a validator.
• signatureNotifications(): Streams notifications when a transaction with the provided signature reaches the specified commitment level.
• programNotifications(): Streams notifications when the lamports or data for an account owned by the specified program changes.
• accountNotifications(): Streams notifications when the lamports or data for the specified account changes.
• close(): Closes an open WebSocket connection via Kit's dispose method, falling back to .close().

ZK Compression

Estimate optimal priority fees for Solana transactions. Available on the helius.zk namespace.

• getSignaturesForAsset(): Retrieves a complete chronological history of all transactions involving the provided compressed NFT (cNFT).
• getCompressedAccount(): Returns the compressed account for the address or hash provided.
• getCompressedAccountProof(): Returns a proof the compression program uses to verify that the given account is valid.
• getCompressedAccountsByOwner(): Returns the owner’s compressed accounts.
• getCompressedBalance(): Returns the balance for the compressed account with the given address or hash.
• getCompressedBalanceByOwner(): Returns the total balance of the owner’s compressed accounts.
• getCompressedMintTokenHolders(): Returns the owner balances for a given mint in descending order.
• getCompressedTokenAccountBalance(): Returns the balance for a given token account.
• getCompressedTokenAccountsByDelegate(): Returns the compressed token accounts that are partially or fully delegated to the given delegate.
• getCompressedTokenAccountsByOwner(): Returns the compressed token accounts owned by a certain account.
• getCompressedTokenBalancesByOwner(): Returns the token balances for a given owner.
• getCompressedTokenBalancesByOwnerV2(): Returns the token balances for a given owner. The V2 version solves a minor naming issue.
• getCompressionSignaturesForAccount(): Return the signatures of the transactions that closed or opened a compressed account with the given hash.
• getCompressionSignaturesForAddress(): Return the signatures of the transactions that closed or opened a compressed account with the given address.
• getCompressionSignaturesForOwner(): Returns the signatures of the transactions that have modified an owner’s compressed accounts.
• getCompressionSignaturesForTokenOwner(): Returns the signatures of the transactions that have modified an owner’s compressed token accounts.
• getIndexerHealth(): Returns an error if the indexer is stale by more than a configurable number of blocks. Otherwise, it returns ok.
• getIndexerSlot(): Returns the slot of the last block indexed by the indexer.
• getLatestCompressionSignatures(): Returns the signatures of the latest transactions that used the compression program.
• getLatestNonVotingSignatures(): Returns the signatures of the latest transactions that are not voting transactions.
• getMultipleCompressedAccountProofs(): Returns multiple proofs used by the compression program to verify the accounts’ validity.
• getMultipleCompressedAccounts(): Returns multiple compressed accounts with the given addresses or hashes.
• getMultipleNewAddressProofs(): Returns proofs that the new addresses are not taken already and can be created.
• getMultipleNewAddressProofsV2(): Returns proofs that the new addresses are not taken already and can be created.
• getTransactionWithCompressionInfo(): Returns the transaction data for the transaction with the given signature along with parsed compression info.
• getValidityProof(): Returns a single ZK Proof used by the compression program to verify that the given accounts are valid and that the new addresses can be created.

Wallet API (Beta)

Query wallet data including identity, balances, history, and transfers. Available on the helius.wallet namespace.

• getIdentity(): Get wallet identity for known addresses (e.g., exchanges, protocols)
• getBatchIdentity(): Batch identity lookup for up to 100 addresses
• getBalances(): Get all token and NFT balances with USD values and pagination
• getHistory(): Fetch transaction history with balance changes and pagination
• getTransfers(): Get all token transfer activity with sender/recipient information
• getFundedBy(): Discover the original funding source for a wallet