helius-python 0.1.1

Typed Python client for the Helius API

helius-python

A complete, typed Python client for Helius — the Solana developer platform.

TL;DR

pip install helius-python

# export HELIUS_API_KEY=your_key   (or put it in .env)

from helius.client import HeliusClient

with HeliusClient() as helius:
    _ctx, lamports = helius.get_balance("7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU")
    print(f"{lamports / 1_000_000_000:.4f} SOL")

    for sig in helius.get_signatures_for_address(
        "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", limit=5
    ):
        print(sig.slot, "ERR" if sig.err else "OK ", sig.signature)

HELIUS_API_KEY is read from the environment (or .env), the client is a context manager, and every return value is fully typed.

Why this over solana-py / solders?

solders is for building and signing transactions. solana-py is a generic Solana RPC client. Use them for that.

This library is for talking to Helius specifically — typed pydantic responses, snake_case, and (eventually) the Helius-only endpoints (DAS, Enhanced Transactions, Webhooks, priority fees) the others don't cover. Plays nicely alongside solders: sign with solders, read with helius-python.

Example: wallet tracker

See examples/wallet_tracker.py for a runnable script that takes a wallet address and prints:

• SOL balance
• All non-empty SPL token accounts (mint, balance, account)
• The last N transactions (timestamp, slot, success/error, signature)

export HELIUS_API_KEY=your_helius_api_key
python examples/wallet_tracker.py 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU --limit 20

It uses get_balance, get_token_accounts_by_owner (with encoding="jsonParsed"), and get_signatures_for_address — pure stdlib plus this library, no solana-py or solders needed.

Coverage

The goal of this library is support every function, method, endpoint, and feature that Helius exposes. If Helius ships it, this client wraps it.

• ✅ The full Solana JSON-RPC surface proxied by Helius — getAccountInfo, getBalance, getBlock, getTransaction, getProgramAccounts, getTokenAccountsByOwner, getSignaturesForAddress, and every other standard RPC method. (supported today)
• 🚧 All Helius-specific RPC extensions — enhanced transactions, DAS (Digital Asset Standard) methods, priority fee estimation, and the rest of the Helius-only RPC namespace. (in progress)
• 🚧 Every Helius REST endpoint — Enhanced Transactions API, Webhooks API, Mint API, token metadata, address lookups, and beyond. (in progress)
• 🚧 Platform features — streaming, websockets, and any new capability Helius adds to its API. (in progress)

Current status: only the standard Solana JSON-RPC surface is implemented today. Support for Helius RPC extensions, REST endpoints, and platform features is actively being worked on.

Goals

1. Completeness — 1:1 coverage of the entire Helius API surface.
2. Type safety — fully typed responses.
3. Pythonic ergonomics — get_account_info(...) instead of getAccountInfo(...), context managers.
4. Zero magic — thin, predictable wrappers that map directly to the documented Helius API.

Authentication

Pass your Helius API key explicitly:

from helius.client import HeliusClient

client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")

or set HELIUS_API_KEY as an environment variable:

export HELIUS_API_KEY=your_helius_api_key

You can also set it in a .env file at the project root and let the client pick it up automatically:

HELIUS_API_KEY=your_helius_api_key

from helius.client import HeliusClient

client = HeliusClient()  # reads HELIUS_API_KEY from the environment or .env

Usage

As a context manager (recommended)

from helius.client import HeliusClient

with HeliusClient(api_key="YOUR_HELIUS_API_KEY") as client:
    _ctx, balance = client.get_balance("So11111111111111111111111111111111111111112")
    _ctx, supply  = client.get_supply()
    nodes         = client.get_cluster_nodes()
    block         = client.get_block(slot=250_000_000)
    tx            = client.get_transaction("5j7s...signature...")

HeliusClient implements the context-manager protocol via __enter__ / __exit__, so the underlying httpx.Client is closed cleanly when the with block exits.

With an explicit close() call

If a with block doesn't fit your code structure (e.g. the client lives on a long-lived object), call close() yourself when you're done:

from helius.client import HeliusClient

client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")
try:
    _ctx, balance = client.get_balance("So11111111111111111111111111111111111111112")
    _ctx, supply  = client.get_supply()
finally:
    client.close()

Client classes also implement __del__ as a safety net — if you forget to close() or use with, the underlying HTTP client is still closed when the instance is garbage-collected. Prefer with or close() regardless.

🚧 Exception & error handling is a work in progress. Today, transport errors surface as raw httpx exceptions and Helius/Solana RPC errors are not yet wrapped in typed exception classes. A consistent error hierarchy is being worked on.

Defaults

Argument	Default	Notes
base_url	"https://mainnet.helius-rpc.com"	Override to point at devnet, staging, or a custom Helius endpoint.
api_key	None → falls back to HELIUS_API_KEY from the environment, then .env	If none is provided, the constructor raises ValueError.

Per-method RPC parameters (commitment, encoding, min_context_slot, etc.) are left unset by default — the Helius/Solana server defaults apply unless you pass them explicitly.

Reference

For parameters, semantics, and return shapes, see the official Helius docs: RPC guide and API reference.

If you hit a bug, a missing parameter, or surprising behavior, please open an issue.

Supported methods

The method names map 1:1 to the Solana JSON-RPC spec, just converted to snake_case. If you know the RPC method name, you know the Python function.

Status

Actively expanding toward full coverage of the Helius API. See src/helius/client.py for the current list of implemented methods; missing endpoints are tracked as issues and added continuously.

Solana JSON-RPC method	Python method	Helius docs
getAccountInfo	get_account_info(...)	guide, reference
getBalance	get_balance(...)	guide, reference
getBlock	get_block(...)	guide, reference
getBlockCommitment	get_block_commitment(...)	guide, reference
getBlockHeight	get_block_height(...)	guide, reference
getBlockProduction	get_block_production(...)	guide, reference
getBlocks	get_blocks(...)	guide, reference
getBlocksWithLimit	get_blocks_with_limit(...)	guide, reference
getBlockTime	get_block_time(...)	guide, reference
getClusterNodes	get_cluster_nodes()	guide, reference
getEpochInfo	get_epoch_info(...)	guide, reference
getEpochSchedule	get_epoch_schedule()	guide, reference
getFeeForMessage	get_fee_for_message(...)	guide, reference
getFirstAvailableBlock	get_first_available_block()	guide, reference
getGenesisHash	get_genesis_hash()	guide, reference
getHealth	get_health()	guide, reference
getHighestSnapshotSlot	get_highest_snapshot_slot()	guide, reference
getIdentity	get_identity()	guide, reference
getInflationGovernor	get_inflation_governor(...)	guide, reference
getInflationRate	get_inflation_rate()	guide, reference
getInflationReward	get_inflation_reward(...)	guide, reference
getLargestAccounts	get_largest_accounts(...)	guide, reference
getLatestBlockhash	get_latest_blockhash(...)	guide, reference
getLeaderSchedule	client.get_leader_schedule(...)	guide, reference
getMaxRetransmitSlot	client.get_max_retransmit_slot()	guide, reference
getMaxShredInsertSlot	get_max_shred_insert_slot()	guide, reference
getMinimumBalanceForRentExemption	get_minimum_balance_for_rent_exemption(...)	guide, reference
getMultipleAccounts	get_multiple_accounts(...)	guide, reference
getProgramAccounts	get_program_accounts(...)	guide, reference
getRecentPerformanceSamples	get_recent_performance_samples(...)	guide, reference
getRecentPrioritizationFees	get_recent_prioritization_fees(...)	guide, reference
getSignaturesForAddress	get_signatures_for_address(...)	guide, reference
getSignatureStatuses	get_signature_statuses(...)	guide, reference
getSlot	get_slot(...)	guide, reference
getSlotLeader	get_slot_leader(...)	guide, reference
getSlotLeaders	get_slot_leaders(...)	guide, reference
getStakeMinimumDelegation	get_stake_minimum_delegation(...)	guide, reference
getSupply	get_supply(...)	guide, reference
getTokenAccountBalance	get_token_account_balance(...)	guide, reference
getTokenAccountsByDelegate	get_token_accounts_by_delegate(...)	guide, reference
getTokenAccountsByOwner	get_token_accounts_by_owner(...)	guide, reference
getTokenLargestAccounts	get_token_largest_accounts(...)	guide, reference
getTokenSupply	get_token_supply(...)	guide, reference
getTransaction	get_transaction(...)	guide, reference
getTransactionCount	get_transaction_count(...)	guide, reference
getVersion	get_version()	guide, reference
getVoteAccounts	get_vote_accounts(...)	guide, reference
isBlockhashValid	is_blockhash_valid(...)	guide, reference
minimumLedgerSlot	minimum_ledger_slot()	guide, reference
requestAirdrop	request_airdrop(...)	guide, reference

License

MIT