helius 1.0.0

An asynchronous Helius Rust SDK for building the future of Solana
Documentation

Helius SDK

An asynchronous Helius Rust SDK for building the future of Solana

Documentation

The latest documentation can be found here on docs.rs

Changelog

See CHANGELOG.md for the full release history.

Contributions

Interested in contributing to the Helius Rust SDK? Read the following contributions guide before opening up a pull request!

Installation

To start using the Helius Rust SDK in your project, add it as a dependency via cargo. Open your project's Cargo.toml and add the following line under [dependencies]:

helius = "x.y.z"

where x.y.z is your desired version. Alternatively, use cargo add helius to add the dependency directly via the command line. This will automatically find the latest version compatible with your project and add it to your Cargo.toml.

Remember to run cargo update regularly to fetch the latest version of the SDK.

TLS Options

The Helius Rust SDK uses the native TLS implementation by default via:

[dependencies]

helius = "x.y.z"

However, the SDK also supports rustls. Add the following to your Cargo.toml to use rustls instead of the native TLS implementation:

[dependencies]

helius = { version = "x.y.z", default-features = false, features = ["rustls"] }

Using rustls may be preferred in environments where OpenSSL is not available or when a pure Rust TLS implementation is desired. However, it may not support all the same features as the native TLS implementation

Usage

Quick Start

The SDK provides a Helius instance that can be configured with an API key and a given Solana cluster. Developers can generate a new API key on the Helius Developer Dashboard. This instance acts as the main entry point for interacting with the SDK by providing methods to access different Solana and RPC client functionalities.

There are three simple constructors and a builder for advanced configuration:

Constructor Use Case
Helius::new(api_key, cluster) Basic RPC operations with Helius endpoints
Helius::new_async(api_key, cluster) Full-featured: async Solana client + WebSocket + confirmed commitment
Helius::new_with_url(url) Custom RPC endpoint (no API key required)
HeliusBuilder::new() Advanced configuration (custom timeouts, TLS, etc.)

Helius::new() — Basic Client

The simplest way to get started. Creates a client for standard Helius RPC operations. This constructor is synchronous:

use helius::Helius;
use helius::error::Result;
use helius::types::{Cluster, GetAssetRequest, GetAssetResponseForAsset};

#[tokio::main]
async fn main() -> Result<()> {
    let helius = Helius::new("YOUR_API_KEY", Cluster::MainnetBeta)?;

    let request = GetAssetRequest {
        id: "F9Lw3ki3hJ7PF9HQXsBzoY8GyE6sPoEZZdXJBsTTD2rk".to_string(),
        display_options: None,
    };

    let response: Result<Option<GetAssetResponseForAsset>> = helius.rpc().get_asset(request).await;

    match response {
        Ok(Some(asset)) => println!("Asset: {:?}", asset),
        Ok(None) => println!("No asset found."),
        Err(e) => println!("Error retrieving asset: {:?}", e),
    }

    Ok(())
}

Helius::new_async() — Full-Featured Client

The recommended constructor for production applications. Includes async Solana RPC, WebSocket streaming, and confirmed commitment level:

use helius::Helius;
use helius::types::Cluster;

#[tokio::main]
async fn main() {
    let helius = Helius::new_async("YOUR_API_KEY", Cluster::MainnetBeta)
        .await
        .expect("Failed to create client");

    // Async Solana RPC
    let async_client = helius.async_connection().expect("Async client available");

    // Enhanced WebSocket streaming
    let ws = helius.ws().expect("WebSocket available");
}

Helius::new_with_url() — Custom RPC Endpoint

Use your own RPC node, a third-party provider, or localhost for development. No API key required. This constructor is synchronous:

use helius::Helius;

fn main() {
    // Custom RPC provider
    let helius = Helius::new_with_url("https://my-rpc-provider.com/")
        .expect("Failed to create client");

    // Local development
    let local = Helius::new_with_url("http://localhost:8899")
        .expect("Failed to create client");
}

HeliusBuilder — Advanced Configuration

For fine-grained control over the client configuration, use the builder pattern:

use helius::HeliusBuilder;
use helius::types::Cluster;
use solana_commitment_config::CommitmentConfig;
use std::time::Duration;

#[tokio::main]
async fn main() {
    // Custom RPC with API key and specific commitment
    let helius = HeliusBuilder::new()
        .with_api_key("YOUR_API_KEY").unwrap()
        .with_cluster(Cluster::MainnetBeta)
        .with_async_solana()
        .with_commitment(CommitmentConfig::confirmed())
        .build()
        .await
        .expect("Failed to build client");

    // Custom URL with separate API and RPC endpoints
    let helius = HeliusBuilder::new()
        .with_custom_url("https://rpc.example.com/").unwrap()
        .with_custom_api_url("https://api.example.com/").unwrap()
        .with_api_key("optional-key").unwrap()
        .build()
        .await
        .expect("Failed to build client");

    // Custom HTTP client with timeouts
    let http_client = reqwest::Client::builder()
        .timeout(Duration::from_secs(30))
        .build()
        .unwrap();

    let helius = HeliusBuilder::new()
        .with_api_key("YOUR_API_KEY").unwrap()
        .with_cluster(Cluster::MainnetBeta)
        .with_http_client(http_client)
        .with_websocket(Some(5), Some(15)) // custom ping/pong timeouts
        .build()
        .await
        .expect("Failed to build client");
}

HeliusFactory

The SDK also comes equipped with HeliusFactory, a factory for creating instances of Helius. This factory allows for a centralized configuration and creation of Helius clients so work can be done across multiple clusters at the same time. Using a factory simplifies client code and enhances maintainability by ensuring that all Helius clients are configured consistently. It has the following functionality:

  • A new method used to create a new HeliusFactory capable of producing Helius clients. Note this method does not create a reqwest client
  • A with_client method used to provide a given HeliusFactory created with the new method its own reqwest client
  • A create method used to create multiple Helius clients in a thread-safe manner

Embedded Solana Client

The Helius client has an embedded Solana client that can be accessed via helius.connection().request_name() where request_name() is a given RPC method. A full list of all Solana RPC HTTP methods can be found here.

For asynchronous operations, use Helius::new_async() or HeliusBuilder with .with_async_solana(). The async client can be accessed via helius.async_connection()?.some_async_method().await? where some_async_method() is a given async RPC method.

Enhanced WebSockets

Use Helius::new_async() or HeliusBuilder with .with_websocket(None, None) to create a client with WebSocket support. This enables our Enhanced WebSocket methods transactionSubscribe and accountSubscribe

Examples

More examples of how to use the SDK can be found in the examples directory.

Error Handling

Common Error Codes

You may encounter several error codes when working with the Helius Rust SDK. Below is a table detailing some of the common error codes along with additional information to aid with troubleshooting:

Error Code Error Message More Information
401 Unauthorized This occurs when an invalid API key is provided or access is restricted
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 errors.rs for a list of all possible errors returned by the Helius client
  • Refer to the Helius documentation for further guidance
  • Reach out to the Helius support team for more detailed assistance

Result Type Alias

The SDK also has a handy type alias for Result where Result<(some type), HeliusError> and be simplified to Result<(some type)>

Methods

Our SDK is designed to provide a seamless developer experience when building on Solana. We've separated the core functionality into various segments:

DAS API

ZK Compression

Enhanced Transactions API

Webhooks

Helius Sender

Smart Transactions

RPC Methods

  • get_priority_fee_estimate - Gets an estimate of the priority fees required for a transaction to be processed more quickly
  • get_transactions_for_address - Gets transaction history for a specific address with advanced filtering, sorting, and pagination. Optionally include transactions from associated token accounts

Helper Methods

Migrating from 0.x

If you're upgrading from 0.x, see the Migration Guide for details on breaking changes and how to update your code.