helius-python 0.0.1__py3-none-any.whl

helius/models.py

@@ -0,0 +1,206 @@
+from typing import Literal
+
+from pydantic import AliasGenerator, BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class Account(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    lamports: int
+    owner: str
+    data: list | dict | str
+    executable: bool
+    rent_epoch: int
+    space: int | None = None
+
+
+class Rewards(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    pubkey: str
+    lamports: int
+    post_balance: int
+    reward_type: str
+    commission: int
+
+
+class Block(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    blockhash: str
+    previous_blockhash: str
+    parent_slot: int
+    transactions: list[dict]
+    block_time: int | None
+    block_height: int | None
+    rewards: list[Rewards] | None = None
+
+
+class BlockCommitment(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    commitment: list[int] | None
+    total_stake: int
+
+
+class ClusterNode(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    pubkey: str
+    gossip: str | None
+    tpu: str | None
+    rpc: str | None
+    version: str | None
+    feature_set: int | None
+    shred_version: int | None
+
+
+class EpochInfo(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    absolute_slot: int
+    block_height: int
+    epoch: int
+    slot_index: int
+    slots_in_epoch: int
+    transaction_count: int
+
+
+class EpochSchedule(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    slots_per_epoch: int
+    leader_schedule_slot_offset: int
+    warmup: bool
+    first_normal_epoch: int
+    first_normal_slot: int
+
+
+class InflationGovernor(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    initial: float
+    terminal: float
+    taper: float
+    foundation: float
+    foundation_term: float
+
+
+class InflationRate(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    total: float
+    validator: float
+    foundation: float
+    epoch: int
+
+
+class PerformanceSample(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    slot: int
+    num_transactions: int
+    num_non_vote_transactions: int
+    sample_period_secs: int
+    num_slots: int
+
+
+class LamportAccount(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    address: str
+    lamports: int
+
+
+class SignatureStatus(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    slot: int
+    confirmations: int | None
+    err: dict | None
+    confirmation_status: str | None
+
+
+class TransactionSignature(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    signature: str
+    slot: int
+    err: dict | None
+    memo: str | None
+    block_time: int | None
+    confirmation_status: str | None
+
+
+class Supply(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    total: int
+    circulating: int
+    non_circulating: int
+    non_circulating_accounts: list[str] | None = None
+
+
+class TokenAccountBalance(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    amount: str
+    decimals: int
+    ui_amount: float | None
+    ui_amount_string: str
+
+
+class TokenAccount(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    address: str
+    amount: str
+    decimals: int
+    ui_amount: float | None
+    ui_amount_string: str
+
+
+class TokenSupply(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    amount: str
+    decimals: int
+    ui_amount: float | None
+    ui_amount_string: str
+
+
+class VotingAccount(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    vote_pubkey: str
+    node_pubkey: str
+    activated_stake: int
+    epoch_vote_account: bool
+    commission: int
+    last_vote: int
+    root_slot: int
+    epoch_credits: list[list[int]]
+
+
+class TransactionMetadata(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    err: dict | None
+    fee: int
+    pre_balances: list[int]
+    post_balances: list[int]
+    pre_token_balances: list[dict] | None
+    post_token_balances: list[dict] | None
+    inner_instructions: list[dict] | None
+    log_messages: list[str] | None
+
+
+class Transaction(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    slot: int
+    block_time: int | None
+    meta: TransactionMetadata | None
+    transaction: dict | list
+    version: Literal["legacy"] | int | None = None

helius_python-0.0.1.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: helius-python
+Version: 0.0.1
+Summary: Typed Python client for the Helius API
+Project-URL: Homepage, https://github.com/markosnarinian/helius-python
+Project-URL: Issues, https://github.com/markosnarinian/helius-python/issues
+Author-email: Markos Narinian <manarinian@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# helius-python
+
+A **complete, typed Python client for [Helius](https://helius.dev)** — the
+Solana developer platform.
+
+The goal of this library is simple: **support every function, method,
+endpoint, and feature that Helius exposes.** If Helius ships it, this client
+wraps it.
+
+That includes:
+
+- ✅ **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.
+
+Every method has typed parameters, typed return values, and dedicated model
+classes built on `pydantic`, so you get full editor autocomplete and static
+type checking.
+
+## 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.
+
+## Installation
+
+```bash
+pip install helius-python
+```
+
+## Authentication
+
+Pass your Helius API key explicitly:
+
+```python
+from helius import HeliusClient
+
+client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")
+```
+
+or set it in a `.env` file at the project root and let the client pick it up
+automatically:
+
+```env
+HELIUS_API_KEY=your_helius_api_key
+```
+
+```python
+from helius import HeliusClient
+
+client = HeliusClient()  # reads HELIUS_API_KEY from .env
+```
+
+## Usage
+
+### As a context manager (recommended)
+
+```python
+from helius import HeliusClient
+
+with HeliusClient(api_key="YOUR_HELIUS_API_KEY") as client:
+    balance = client.get_balance("So11111111111111111111111111111111111111112")
+    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:
+
+```python
+from helius import HeliusClient
+
+client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")
+try:
+    balance = client.get_balance("So11111111111111111111111111111111111111112")
+    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` in a `.env` file | If neither 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.
+
+### 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.
+
+| Solana JSON-RPC method            | Python method                              |
+| --------------------------------- | ------------------------------------------ |
+| `getAccountInfo`                  | `client.get_account_info(...)`             |
+| `getBalance`                      | `client.get_balance(...)`                  |
+| `getBlock`                        | `client.get_block(...)`                    |
+| `getBlockCommitment`              | `client.get_block_commitment(...)`         |
+| `getBlockHeight`                  | `client.get_block_height(...)`             |
+| `getBlockProduction`              | `client.get_block_production(...)`         |
+| `getBlocks`                       | `client.get_blocks(...)`                   |
+| `getBlocksWithLimit`              | `client.get_blocks_with_limit(...)`        |
+| `getBlockTime`                    | `client.get_block_time(...)`               |
+| `getClusterNodes`                 | `client.get_cluster_nodes()`               |
+| `getEpochInfo`                    | `client.get_epoch_info(...)`               |
+| `getEpochSchedule`                | `client.get_epoch_schedule()`              |
+| `getFeeForMessage`                | `client.get_fee_for_message(...)`          |
+| `getFirstAvailableBlock`          | `client.get_first_available_block()`       |
+| `getGenesisHash`                  | `client.get_genesis_hash()`                |
+| `getHealth`                       | `client.get_health()`                      |
+| `getHighestSnapshotSlot`          | `client.get_highest_snapshot_slot()`       |
+| `getIdentity`                     | `client.get_identity()`                    |
+| `getInflationGovernor`            | `client.get_inflation_governor(...)`       |
+| `getInflationRate`                | `client.get_inflation_rate()`              |
+| `getLargestAccounts`              | `client.get_largest_accounts(...)`         |
+| `getLatestBlockhash`              | `client.get_latest_blockhash(...)`         |
+| `getLeaderSchedule`               | `client.get_leader_schedule(...)`          |
+| `getMaxRetransmitSlot`            | `client.get_max_retransmit_slot()`         |
+| `getMaxShredInsertSlot`           | `client.get_max_shred_insert_slot()`       |
+| `getMinimumBalanceForRentExemption` | `client.get_minimum_balance_for_rent_exemption(...)` |
+| `getMultipleAccounts`             | `client.get_multiple_accounts(...)`        |
+| `getProgramAccounts`              | `client.get_program_accounts(...)`         |
+| `getRecentPerformanceSamples`     | `client.get_recent_performance_samples(...)` |
+| `getRecentPrioritizationFees`     | `client.get_recent_prioritization_fees(...)` |
+| `getSignaturesForAddress`         | `client.get_signatures_for_address(...)`   |
+| `getSignatureStatuses`            | `client.get_signature_statuses(...)`       |
+| `getSlot`                         | `client.get_slot(...)`                     |
+| `getSlotLeader`                   | `client.get_slot_leader(...)`              |
+| `getSlotLeaders`                  | `client.get_slot_leaders(...)`             |
+| `getStakeMinimumDelegation`       | `client.get_stake_minimum_delegation(...)` |
+| `getSupply`                       | `client.get_supply(...)`                   |
+| `getTokenAccountBalance`          | `client.get_token_account_balance(...)`    |
+| `getTokenAccountsByDelegate`      | `client.get_token_accounts_by_delegate(...)` |
+| `getTokenAccountsByOwner`         | `client.get_token_accounts_by_owner(...)`  |
+| `getTokenLargestAccounts`         | `client.get_token_largest_accounts(...)`   |
+| `getTokenSupply`                  | `client.get_token_supply(...)`             |
+| `getTransaction`                  | `client.get_transaction(...)`              |
+| `getTransactionCount`             | `client.get_transaction_count(...)`        |
+| `getVersion`                      | `client.get_version()`                     |
+| `getVoteAccounts`                  | `client.get_vote_accounts(...)`            |
+| `isBlockhashValid`                 | `client.is_blockhash_valid(...)`           |
+| `minimumLedgerSlot`                | `client.minimum_ledger_slot()`             |
+| `requestAirdrop`                   | `client.request_airdrop(...)`              |
+
+### Reference
+
+The table above is a quick index of what's implemented. For each method's
+parameters, semantics, return shape, edge cases, and links to the underlying
+Helius docs, see the **API reference** (🚧 hosted version coming soon).
+
+In the meantime, every public method and model carries a Google-style
+docstring that is the source of truth for that symbol. You can read it
+straight from a REPL:
+
+```python
+from helius import HeliusClient
+help(HeliusClient.get_balance)
+```
+
+or from your editor's inline help / hover. Each docstring links back to the
+relevant [Helius RPC guide](https://www.helius.dev/docs/rpc) and
+[Helius API reference](https://www.helius.dev/docs/api-reference) page so you
+can always confirm behavior against upstream.
+
+If you hit a bug, a missing parameter, or surprising behavior, please
+[open an issue](https://github.com/markosnarinian/helius-python/issues).
+
+## Status
+
+Actively expanding toward full coverage of the Helius API. See
+[`src/helius/client.py`](src/helius/client.py) for the current list of
+implemented methods; missing endpoints are tracked as issues and added
+continuously.
+
+## License
+
+[MIT](LICENSE)

helius_python-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+helius/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+helius/client.py,sha256=SIczNqX2U_3ULM9-yO3ba3MOWMog4rtS6qkvXoDH_mQ,33229
+helius/models.py,sha256=X6aLhpAIvVccgCIJE_h2TO0RRdBI26EmaGNylT11Y3A,5082
+helius_python-0.0.1.dist-info/METADATA,sha256=knkLVOWYaVDKLPAeBdh5Pi0smm0Hn3viIwvhsNHHPmU,10671
+helius_python-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+helius_python-0.0.1.dist-info/licenses/LICENSE,sha256=bZc2EDmq_GsWH77uK8LBn1kqqrOPcp2f9p-ys9bYa1E,1072
+helius_python-0.0.1.dist-info/RECORD,,

helius_python-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

helius_python-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Markos Narinian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.