solana_kit_helius

pub package docs website CI coverage

A Dart client for the Helius API, covering the DAS API, enhanced transactions, webhooks, smart transactions, ZK compression, staking, the wallet API, WebSocket subscriptions, and auth.

What you get

  • DAS API: query assets, proofs, and metadata
  • Enhanced transactions: parsed transaction history with human-readable types
  • Webhooks: create, manage, and delete webhook subscriptions
  • Transaction utilities: priority fee policies, signed transaction broadcasting, and confirmation polling
  • ZK compression: compressed account and token operations via Light Protocol
  • Staking: create stake, unstake, and withdraw transactions via Helius validators
  • Wallet API: identity resolution, balances, history, and transfers
  • WebSockets: real-time subscription support
  • Auth: project and API key management
  • Priority fees: estimate priority fees for transactions
  • RPC V2: enhanced RPC methods with pagination

Upstream compatibility

This package was audited against helius-labs/helius-sdk v3.0.0 at commit 4c0c55b86eab0e3abde7896c0aa23c4b6515e9b0 (chore(release): Update CHANGELOG (#330), 2026-05-30). Helius has not published a Git tag for that release, so this commit is the comparison baseline.

The package covers the broad v3 surface: DAS, priority fees, RPC v2 including getTransfersByAddress, enhanced transactions, webhook CRUD/toggle, ZK compression, staking, wallet operations, Sender, the v3 JWT-based signup/checkout/payment flow, Admin project usage, and WebSocket subscriptions. The mainnet REST default follows v3's https://api-mainnet.helius-rpc.com/v0 host, while devnet enhanced REST continues to use https://api-devnet.helius.xyz/v0.

The legacy smart-transaction facade does not yet implement the v3 transaction-building contract: createSmartTransaction only fetches a blockhash, sendSmartTransaction does not compile or sign instructions, and getComputeUnits does not serialize a transaction for simulation. These three helpers cannot complete their advertised transaction flows. Prefer Solana Kit's transaction-message, signer, and Sender APIs until that surface is replaced. Remaining v3 gaps also include smart-transaction tip helpers and enhanced WebSocket account/transaction subscriptions.

pollTransactionConfirmation and sendBundleWithSender check on-chain execution errors before accepting confirmation. A failed transaction throws its corresponding SolanaError, even when its signature is confirmed or finalized. A higher commitment satisfies a lower requested commitment; confirmation alone never establishes that the intended transfer executed successfully.

The JSON-RPC and REST transports sanitize connection exceptions so API keys and URL user credentials are omitted from their messages. WebSocket connection errors also omit URL user credentials.

Preconfirmation subscriptions wait for WebSocket readiness. Connection failure or closure rejects pending requests and closes notification streams without exposing endpoint credentials. PreconfWsClient accepts channelFactory for custom connectors; close() is safe to repeat, including before connection readiness.

Installation

Install the package directly:

dependencies:
  "solana_kit_helius": ^0.6.3

If your app uses several Solana Kit packages together, you can also depend on the umbrella package instead:

dart pub add solana_kit

Inside this monorepo, Dart workspace resolution uses the local package automatically.

Documentation

For architecture notes, getting-started guides, and cross-package examples, start with the workspace docs site and then drill down into the package README and API reference.

Usage

Create a client with your API key, then call the sub-clients:

import 'package:solana_kit_helius/solana_kit_helius.dart';

Future<void> main() async {
  final helius = createHelius(HeliusConfig(apiKey: 'your-api-key'));

  // DAS API
  final asset = await helius.das.getAsset(
    GetAssetRequest(id: 'asset-id'),
  );

  // Priority fees
  final fees = await helius.priorityFee.getPriorityFeeEstimate(
    GetPriorityFeeEstimateRequest(
      accountKeys: ['account-key'],
    ),
  );

  // Enhanced transactions
  final txns = await helius.enhanced.getTransactions(
    GetTransactionsRequest(transactions: ['tx-sig']),
  );

  print(asset);
  print(fees);
  print(txns);
}

Authenticated signup

signup uses the developer API's wallet-signup response as a bearer JWT, then uses that JWT for project and checkout calls. Project API keys are only returned after subscription provisioning and are never reused as bearer tokens.

import 'package:solana_kit_helius/solana_kit_helius.dart';

Future<void> main() async {
  final helius = createHelius(HeliusConfig(apiKey: 'your-api-key'));

  final base64EncodedSolanaCliKeypair = 'base64-encoded-keypair';
  final result = await helius.auth.signup(
    SignupRequest.secretKey(
      secretKey: base64EncodedSolanaCliKeypair,
      plan: 'developer',
      email: 'ada@example.com',
      firstName: 'Ada',
      lastName: 'Lovelace',
    ),
  );

  print(result);
}

Only pay PaymentLink values received from a trusted Helius developer API. The payment helper rejects non-positive amounts, mismatched memo/intent IDs, and non-payment link kinds before constructing a transfer.

Configuration

import 'package:http/http.dart' as http;
import 'package:solana_kit_helius/solana_kit_helius.dart';

void main() {
  // Mainnet (default)
  final mainnet = createHelius(HeliusConfig(apiKey: 'your-api-key'));

  // Devnet
  final devnet = createHelius(
    HeliusConfig(
      apiKey: 'your-api-key',
      cluster: HeliusCluster.devnet,
    ),
  );

  // Custom HTTP client (useful for testing)
  final withClient = createHelius(
    HeliusConfig(apiKey: 'your-api-key'),
    client: http.Client(),
  );

  print(mainnet);
  print(devnet);
  print(withClient);
}

WebSocket security defaults

HeliusWebSocket enforces wss:// URLs and rejects localhost plus non-public IP literals by default. Use allowInsecureWs: true and allowPrivateHosts: true only for local development and controlled tests. The private-host check does not resolve DNS names, so do not accept arbitrary WebSocket URLs from untrusted input.

Testing strategy

The Helius package keeps DTO smoke coverage, but long-term confidence should come from higher-level contracts:

  • shared REST and JSON-RPC client contract tests cover request shaping, headers, query merging, and error mapping
  • endpoint tests focus on user-facing request/response behavior
  • websocket session tests cover subscribe, notification routing, unsubscribe, and close boundaries across concurrent subscriptions

When adding a new Helius surface, prefer extending one of these boundaries before adding large amounts of DTO-only roundtrip coverage.

Example

Use example/main.dart as a runnable starting point for solana_kit_helius.

  • Import path: package:solana_kit_helius/solana_kit_helius.dart
  • This section is centrally maintained with mdt to keep package guidance aligned.
  • After updating shared docs templates, run docs:update from the repo root.

Maintenance

  • Validate docs in CI and locally with docs:check.
  • Keep examples focused on one workflow and reference package README sections for deeper API details.

Libraries

solana_kit_helius
Helius client package for Solana Kit Dart.