helius-python 0.1.1__tar.gz → 0.3.0__tar.gz

{helius_python-0.1.1 → helius_python-0.3.0}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -24,7 +24,7 @@ body:
         your API key.
       render: python
       placeholder: |
-        from helius.client import HeliusClient
+        from helius.solana_rpc import HeliusClient
 
         with HeliusClient(api_key="...") as c:
             c.get_balance(public_key="...")

{helius_python-0.1.1 → helius_python-0.3.0}/AGENTS.md

@@ -1,84 +1,3 @@
-When implementing a function for a RPC method in the HeliusClient class, read the docs for the specific RPC method. For example, for the get_supply function (getSupply RPC method) you should read https://www.helius.dev/docs/rpc/guides/getsupply and https://www.helius.dev/docs/api-reference/rpc/http/getsupply.
-
-# API Reference
-
-The API reference is generated from **Google-style docstrings** on every public symbol in `src/helius/`. Whenever you add or modify a public method, model, or class, you MUST write or update its docstring following the rules below. The README's "Supported methods" table is a quick index only — the docstring is the source of truth.
-
-## Where docstrings live
-
-- **Client methods** (`HeliusClient.get_*`, `is_*`, `request_*`, etc.) — every public method gets a docstring. Private methods (`_send`, dunders) do not need one.
-- **Models** (`src/helius/models.py`) — every public model class gets a docstring describing what it represents. Individual fields don't need per-field docstrings if their names and types are self-explanatory; only document fields where the meaning, units, or nullability isn't obvious from the type alone.
-- **Builders / helpers** (`RpcRequest`) — class docstring describing purpose, plus one-line docstrings on each public method.
-
-## Client method docstring format
-
-Use Google-style sections. Order matters; omit any section that doesn't apply.
-
-```python
-def method_name(self, ...) -> ReturnType:
-    """One-line summary in the imperative mood, ending with a period.
-
-    Optional longer description: a paragraph or two on what the method does,
-    when to use it, and any non-obvious behavior. Keep this short — link to
-    the upstream Helius docs rather than restating them.
-
-    Args:
-        param_one: Description of the first parameter, including units
-            (lamports vs. SOL, slot vs. block height) when relevant. Mention
-            the upstream JSON field name only if it differs in a non-obvious
-            way from the snake_case Python name.
-        param_two: Description. Note constraints like "must be base-58
-            encoded" or "max 500_000 slots from `start_slot`".
-        commitment: Optional commitment level. Defaults to the node's default
-            when omitted.
-
-    Returns:
-        Describe the return shape. For tuples, describe each element in
-        order. For models, name the model and what it represents. For
-        primitives, name the unit (e.g. "Balance in lamports.").
-
-    Raises:
-        ValueError: When the arguments violate the documented constraints
-            (e.g. mutually exclusive params, mismatched pairs).
-
-    Note:
-        Only available on Devnet and Testnet, not Mainnet Beta.
-
-    See Also:
-        - Helius guide: https://www.helius.dev/docs/rpc/guides/<method>
-        - Helius API reference: https://www.helius.dev/docs/api-reference/rpc/http/<method>
-    """
-```
-
-Rules:
-
-- **Summary line** is one sentence, imperative mood, ≤ 88 chars, ends with a period. Example: `"Return the SOL balance of an account in lamports."`
-- **`Args:`** documents every parameter, even `commitment` and `min_context_slot`. One entry per param. Don't re-state the type — basedpyright already shows it.
-- **`Returns:`** is mandatory unless the method returns `None`.
-- **`Raises:`** is required if the method calls `raise` directly. Don't document exceptions that bubble up from `httpx` — those are covered by the library-wide error-handling docs.
-- **`Note:`** for network restrictions, version requirements, pagination limits, deprecation warnings, etc. One section per concern.
-- **`See Also:`** ALWAYS includes the Helius guide and API reference URLs for the underlying RPC method. This is the contract for an RPC wrapper — the docstring tells you what we do, the upstream docs tell you what the network does.
-- Keep prose tight. The docstring should be readable in `help(client.method)` without scrolling forever.
-
-## Model docstring format
-
-```python
-class Supply(BaseModel):
-    """Total, circulating, and non-circulating SOL supply, in lamports.
-
-    Returned as the `value` field of `getSupply`. All amounts are in
-    lamports (1 SOL = 1_000_000_000 lamports).
-
-    See Also:
-        - Helius API reference: https://www.helius.dev/docs/api-reference/rpc/http/getsupply
-    """
-    ...
-```
-
-Rules:
-
-- One-line summary + optional paragraph + `See Also:` linking the upstream docs that define the shape.
-- If a field has surprising semantics (e.g. `ui_amount` can be `None` when the mint has too many decimals, `non_circulating_accounts` is only populated when not excluded), document it inline with `Field(..., description="...")` or in the class docstring.
 
 ## Conventions
 
@@ -98,11 +17,10 @@ Rules:
 
 ## Checklist for adding a new client method
 
-1. Read both Helius doc URLs for the RPC method (see the top of this file).
+1. Read the docs. The user should provide the relevant URLs. If they don't, ask them to do so.
 2. Implement the method, following the **Implementation conventions** above — in particular, return `(context, value)` if the upstream response is wrapped.
-3. Add a docstring with `Args`, `Returns`, `Raises` (if any), `Note` (if any), and `See Also` with both Helius URLs.
-4. Add the method to the "Supported methods" table in `README.md`.
-5. Add tests per the Testing section.
+3. Add the method to the "Supported methods" table in `README.md`.
+4. Add tests per the Testing section.
 
 # Testing
 
@@ -123,7 +41,7 @@ tests/
   unit/
     test_rpc_request.py  # RpcRequest builder
     test_models.py       # pydantic model validation against fixtures
-    test_client.py       # one test (or small group) per client method
+    test_solana_rpc.py       # one test (or small group) per client method
 ```
 
 ## Three Layers
@@ -154,7 +72,7 @@ One fixture per model is enough. The goal is to catch schema mismatches (missing
 
 ### 3. Client methods — `respx`-mocked tests
 
-For each method on `HeliusClient`, write at least one test that asserts **both** sides of the wire:
+For each method on `SolanaRpcClient`, write at least one test that asserts **both** sides of the wire:
 
 - **Outgoing request:** the JSON body sent to Helius matches the JSON-RPC payload you expect — correct `method`, correct positional `params`, correct config object with snake → camel mapping, and optional arguments omitted when `None`.
 - **Return value:** the method correctly parses a canned response into the documented return shape (model, tuple, primitive, etc.).
@@ -169,7 +87,7 @@ Skeleton:
 import json
 import httpx
 import respx
-from helius.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
 @respx.mock
 def test_get_balance():
@@ -183,7 +101,7 @@ def test_get_balance():
             },
         )
     )
-    with HeliusClient(api_key="test") as c:
+    with SolanaRpcClient(api_key="test") as c:
         assert c.get_balance("So11...112", commitment="finalized") == 42
 
     sent = route.calls.last.request
@@ -197,9 +115,9 @@ For methods with branching logic (e.g. `get_block_production`, `get_token_accoun
 
 ## Conventions
 
-- Construct `HeliusClient` in tests with an explicit `api_key="test"` (or similar). Never rely on a real `.env` file.
-- Use the context-manager form (`with HeliusClient(...) as c:`) in tests so the `httpx.Client` is closed cleanly.
-- Group tests in `tests/unit/test_client.py` by method, but a single file is fine until it grows unwieldy.
+- Construct `SolanaRpcClient` in tests with an explicit `api_key="test"` (or similar). Never rely on a real `.env` file.
+- Use the context-manager form (`with SolanaRpcClient(...) as c:`) in tests so the `httpx.Client` is closed cleanly.
+- Group tests in `tests/unit/test_solana_rpc.py` by method, but a single file is fine until it grows unwieldy.
 - Test names should describe the behavior, not the implementation: `test_get_balance_includes_commitment_in_config`, not `test_get_balance_calls_set`.
 - When adding a new client method, the PR must include: (a) a `respx` test asserting the request payload, and (b) a fixture-based model test if the method introduces or uses a model. This is enforced in `CONTRIBUTING.md`.
 

{helius_python-0.1.1 → helius_python-0.3.0}/CONTRIBUTING.md

@@ -44,6 +44,7 @@ easiest to most involved:
 - **Improve docs and examples.** Clearer docstrings, better README snippets,
   more realistic examples.
 - **Create an example or refine an existing one.** Examples make it easier for developers to get started.
+- **Improve test coverage** Write a missing test or improve an existing one.
 
 If you're not sure where to start, browse the
 [open issues](https://github.com/markosnarinian/helius-python/issues).
@@ -66,7 +67,7 @@ prior discussion; just send them.
 ## Codebase Conventions
 
 Please match the existing style of the codebase. Skim
-[`src/helius/client.py`](src/helius/client.py) and
+[`src/helius/solana_rpc.py`](src/helius/solana_rpc.py) and
 [`src/helius/models.py`](src/helius/models.py) before writing new code. In
 particular:
 

{helius_python-0.1.1 → helius_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: helius-python
-Version: 0.1.1
+Version: 0.3.0
 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
@@ -13,6 +13,7 @@ Requires-Python: >=3.10
 Requires-Dist: httpx
 Requires-Dist: pydantic
 Requires-Dist: python-dotenv
+Requires-Dist: websockets
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: respx; extra == 'dev'
@@ -118,55 +119,6 @@ Description-Content-Type: text/markdown
   </p>
   
 **A complete, typed Python client for [Helius](https://helius.dev) — the Solana developer platform.**
-<br />
-
-## TL;DR
-
-```bash
-pip install helius-python
-```
-
-```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`](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)
-
-```bash
-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
 
@@ -186,11 +138,16 @@ wraps it.
   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)**
+  capability Helius adds to its API. The full WebSocket subscription
+  surface (`accountSubscribe`, `transactionSubscribe`, `logsSubscribe`,
+  `programSubscribe`, and the rest) is **supported today**; other
+  platform features are **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.
+> **Current status:** the standard Solana JSON-RPC surface, the
+> WebSocket subscription surface, and the Admin (account management)
+> usage endpoint are implemented today. Support for Helius RPC
+> extensions and the remaining REST endpoints is actively being worked
+> on.
 
 ## Goals
 
@@ -201,14 +158,19 @@ wraps it.
 4. **Zero magic** — thin, predictable wrappers that map directly to the
    documented Helius API.
 
+## Installation via PyPI
+```bash
+pip install helius-python
+```
+
 ## Authentication
 
 Pass your Helius API key explicitly:
 
 ```python
-from helius.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")
+client = SolanaRpcClient(api_key="YOUR_HELIUS_API_KEY")
 ```
 
 or set `HELIUS_API_KEY` as an environment variable:
@@ -225,9 +187,9 @@ HELIUS_API_KEY=your_helius_api_key
 ```
 
 ```python
-from helius.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-client = HeliusClient()  # reads HELIUS_API_KEY from the environment or .env
+client = SolanaRpcClient()  # reads HELIUS_API_KEY from the environment or .env
 ```
 
 ## Usage
@@ -235,9 +197,9 @@ client = HeliusClient()  # reads HELIUS_API_KEY from the environment or .env
 ### As a context manager (recommended)
 
 ```python
-from helius.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-with HeliusClient(api_key="YOUR_HELIUS_API_KEY") as client:
+with SolanaRpcClient(api_key="YOUR_HELIUS_API_KEY") as client:
     _ctx, balance = client.get_balance("So11111111111111111111111111111111111111112")
     _ctx, supply  = client.get_supply()
     nodes         = client.get_cluster_nodes()
@@ -245,7 +207,7 @@ with HeliusClient(api_key="YOUR_HELIUS_API_KEY") as client:
     tx            = client.get_transaction("5j7s...signature...")
 ```
 
-`HeliusClient` implements the context-manager protocol via `__enter__` /
+`SolanaRpcClient` implements the context-manager protocol via `__enter__` /
 `__exit__`, so the underlying `httpx.Client` is closed cleanly when the
 `with` block exits.
 
@@ -255,9 +217,9 @@ 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.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")
+client = SolanaRpcClient(api_key="YOUR_HELIUS_API_KEY")
 try:
     _ctx, balance = client.get_balance("So11111111111111111111111111111111111111112")
     _ctx, supply  = client.get_supply()
@@ -303,7 +265,7 @@ The method names map 1:1 to the Solana JSON-RPC spec, just converted to
 ## Status
 
 Actively expanding toward full coverage of the Helius API. See
-[`src/helius/client.py`](src/helius/client.py) for the current list of
+[`src/helius/solana_rpc.py`](src/helius/solana_rpc.py) for the current list of
 implemented methods; missing endpoints are tracked as issues and added
 continuously.
 
@@ -359,6 +321,73 @@ continuously.
 | `isBlockhashValid`                  | `is_blockhash_valid(...)`                     | [guide](https://www.helius.dev/docs/rpc/guides/isblockhashvalid), [reference](https://www.helius.dev/docs/api-reference/rpc/http/isblockhashvalid)                                   |
 | `minimumLedgerSlot`                 | `minimum_ledger_slot()`                       | [guide](https://www.helius.dev/docs/rpc/guides/minimumledgerslot), [reference](https://www.helius.dev/docs/api-reference/rpc/http/minimumledgerslot)                                 |
 | `requestAirdrop`                    | `request_airdrop(...)`                        | [guide](https://www.helius.dev/docs/rpc/guides/requestairdrop), [reference](https://www.helius.dev/docs/api-reference/rpc/http/requestairdrop)                                       |
+| `sendTransaction`                   | `send_transaction(...)`                       | [guide](https://www.helius.dev/docs/rpc/guides/sendtransaction), [reference](https://www.helius.dev/docs/api-reference/rpc/http/sendtransaction)                                     |
+
+## WebSocket subscriptions
+
+`WebSocketClient` wraps the Solana/Helius WebSocket subscription surface.
+It connects over `wss://` on construction, exposes one `*_subscribe` /
+`*_unsubscribe` pair per subscription type, and parses incoming
+notifications into typed pydantic models.
+
+```python
+from helius.laserstream.websockets import WebSocketClient
+
+with WebSocketClient(api_key="YOUR_HELIUS_API_KEY") as ws:
+    subscription = ws.account_subscribe(
+        pubkey="So11111111111111111111111111111111111111112",
+        commitment="confirmed",
+    )
+
+    for context, notification, sub in ws.listen():
+        print(notification)  # typed AccountNotification
+
+    ws.account_unsubscribe(subscription)
+```
+
+Like `SolanaRpcClient`, it supports the context-manager protocol and a
+manual `close()`. The constructor defaults to
+`wss://mainnet.helius-rpc.com` and reads `HELIUS_API_KEY` from the
+environment or `.env` when `api_key` is omitted; an optional `proxy` is
+also accepted.
+
+Each `*_subscribe` call returns the integer subscription id. Use
+`receive()` to read a single notification or `listen()` to iterate over
+them; both yield a `(context, notification, subscription)` tuple where
+`notification` is the model below.
+
+| Subscribe method                | Unsubscribe method                | Notification model            | Helius docs                                                                                                                                       |
+| ------------------------------- | --------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `account_subscribe(...)`        | `account_unsubscribe(...)`        | `AccountNotification`         | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/accountsubscribe)                                                             |
+| `block_subscribe(...)`          | `block_unsubscribe(...)`          | `BlockNotification`           | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/blocksubscribe)                                                               |
+| `logs_subscribe(...)`           | `logs_unsubscribe(...)`           | `LogsNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/logssubscribe)                                                                |
+| `program_subscribe(...)`        | `program_unsubscribe(...)`        | `ProgramNotification`         | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/programsubscribe)                                                             |
+| `root_subscribe()`              | `root_unsubscribe(...)`           | `RootNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/rootsubscribe)                                                                |
+| `signature_subscribe(...)`      | `signature_unsubscribe(...)`      | `SignatureNotification`       | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/signaturesubscribe)                                                           |
+| `slot_subscribe()`              | `slot_unsubscribe(...)`           | `SlotNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/slotsubscribe)                                                                |
+| `slots_updates_subscribe()`     | `slots_updates_unsubscribe(...)`  | `SlotsUpdatesNotification`    | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/slotsupdatessubscribe)                                                        |
+| `vote_subscribe()`              | `vote_unsubscribe(...)`           | `VoteNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/votesubscribe)                                                                |
+| `transaction_subscribe(...)`    | `transaction_unsubscribe(...)`    | `TransactionNotification`     | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/slotunsubscribe)                                                                                       |
+
+## Admin API
+
+`AccountManagementClient` wraps the Helius admin API. Today it exposes
+project credit usage via `get_project_usage(...)`, which returns a typed
+`ProjectUsage` model.
+
+```python
+from helius.admin.admin import AccountManagementClient
+
+with AccountManagementClient(api_key="YOUR_HELIUS_API_KEY") as admin:
+    usage = admin.get_project_usage(project_id="YOUR_PROJECT_ID")
+    print(usage.credits_remaining, usage.usage.rpc)
+```
+
+The `project_id` can be passed per call or set once on the constructor;
+if neither is provided, `get_project_usage` raises `ValueError`. The
+client defaults to `https://admin-api.helius.xyz` and, like the others,
+supports the context-manager protocol, a manual `close()`, and reads
+`HELIUS_API_KEY` from the environment or `.env`.
 
 ## License
 

{helius_python-0.1.1 → helius_python-0.3.0}/README.md

@@ -98,55 +98,6 @@
   </p>
   
 **A complete, typed Python client for [Helius](https://helius.dev) — the Solana developer platform.**
-<br />
-
-## TL;DR
-
-```bash
-pip install helius-python
-```
-
-```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`](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)
-
-```bash
-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
 
@@ -166,11 +117,16 @@ wraps it.
   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)**
+  capability Helius adds to its API. The full WebSocket subscription
+  surface (`accountSubscribe`, `transactionSubscribe`, `logsSubscribe`,
+  `programSubscribe`, and the rest) is **supported today**; other
+  platform features are **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.
+> **Current status:** the standard Solana JSON-RPC surface, the
+> WebSocket subscription surface, and the Admin (account management)
+> usage endpoint are implemented today. Support for Helius RPC
+> extensions and the remaining REST endpoints is actively being worked
+> on.
 
 ## Goals
 
@@ -181,14 +137,19 @@ wraps it.
 4. **Zero magic** — thin, predictable wrappers that map directly to the
    documented Helius API.
 
+## Installation via PyPI
+```bash
+pip install helius-python
+```
+
 ## Authentication
 
 Pass your Helius API key explicitly:
 
 ```python
-from helius.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")
+client = SolanaRpcClient(api_key="YOUR_HELIUS_API_KEY")
 ```
 
 or set `HELIUS_API_KEY` as an environment variable:
@@ -205,9 +166,9 @@ HELIUS_API_KEY=your_helius_api_key
 ```
 
 ```python
-from helius.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-client = HeliusClient()  # reads HELIUS_API_KEY from the environment or .env
+client = SolanaRpcClient()  # reads HELIUS_API_KEY from the environment or .env
 ```
 
 ## Usage
@@ -215,9 +176,9 @@ client = HeliusClient()  # reads HELIUS_API_KEY from the environment or .env
 ### As a context manager (recommended)
 
 ```python
-from helius.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-with HeliusClient(api_key="YOUR_HELIUS_API_KEY") as client:
+with SolanaRpcClient(api_key="YOUR_HELIUS_API_KEY") as client:
     _ctx, balance = client.get_balance("So11111111111111111111111111111111111111112")
     _ctx, supply  = client.get_supply()
     nodes         = client.get_cluster_nodes()
@@ -225,7 +186,7 @@ with HeliusClient(api_key="YOUR_HELIUS_API_KEY") as client:
     tx            = client.get_transaction("5j7s...signature...")
 ```
 
-`HeliusClient` implements the context-manager protocol via `__enter__` /
+`SolanaRpcClient` implements the context-manager protocol via `__enter__` /
 `__exit__`, so the underlying `httpx.Client` is closed cleanly when the
 `with` block exits.
 
@@ -235,9 +196,9 @@ 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.client import HeliusClient
+from helius.solana_rpc import SolanaRpcClient
 
-client = HeliusClient(api_key="YOUR_HELIUS_API_KEY")
+client = SolanaRpcClient(api_key="YOUR_HELIUS_API_KEY")
 try:
     _ctx, balance = client.get_balance("So11111111111111111111111111111111111111112")
     _ctx, supply  = client.get_supply()
@@ -283,7 +244,7 @@ The method names map 1:1 to the Solana JSON-RPC spec, just converted to
 ## Status
 
 Actively expanding toward full coverage of the Helius API. See
-[`src/helius/client.py`](src/helius/client.py) for the current list of
+[`src/helius/solana_rpc.py`](src/helius/solana_rpc.py) for the current list of
 implemented methods; missing endpoints are tracked as issues and added
 continuously.
 
@@ -339,6 +300,73 @@ continuously.
 | `isBlockhashValid`                  | `is_blockhash_valid(...)`                     | [guide](https://www.helius.dev/docs/rpc/guides/isblockhashvalid), [reference](https://www.helius.dev/docs/api-reference/rpc/http/isblockhashvalid)                                   |
 | `minimumLedgerSlot`                 | `minimum_ledger_slot()`                       | [guide](https://www.helius.dev/docs/rpc/guides/minimumledgerslot), [reference](https://www.helius.dev/docs/api-reference/rpc/http/minimumledgerslot)                                 |
 | `requestAirdrop`                    | `request_airdrop(...)`                        | [guide](https://www.helius.dev/docs/rpc/guides/requestairdrop), [reference](https://www.helius.dev/docs/api-reference/rpc/http/requestairdrop)                                       |
+| `sendTransaction`                   | `send_transaction(...)`                       | [guide](https://www.helius.dev/docs/rpc/guides/sendtransaction), [reference](https://www.helius.dev/docs/api-reference/rpc/http/sendtransaction)                                     |
+
+## WebSocket subscriptions
+
+`WebSocketClient` wraps the Solana/Helius WebSocket subscription surface.
+It connects over `wss://` on construction, exposes one `*_subscribe` /
+`*_unsubscribe` pair per subscription type, and parses incoming
+notifications into typed pydantic models.
+
+```python
+from helius.laserstream.websockets import WebSocketClient
+
+with WebSocketClient(api_key="YOUR_HELIUS_API_KEY") as ws:
+    subscription = ws.account_subscribe(
+        pubkey="So11111111111111111111111111111111111111112",
+        commitment="confirmed",
+    )
+
+    for context, notification, sub in ws.listen():
+        print(notification)  # typed AccountNotification
+
+    ws.account_unsubscribe(subscription)
+```
+
+Like `SolanaRpcClient`, it supports the context-manager protocol and a
+manual `close()`. The constructor defaults to
+`wss://mainnet.helius-rpc.com` and reads `HELIUS_API_KEY` from the
+environment or `.env` when `api_key` is omitted; an optional `proxy` is
+also accepted.
+
+Each `*_subscribe` call returns the integer subscription id. Use
+`receive()` to read a single notification or `listen()` to iterate over
+them; both yield a `(context, notification, subscription)` tuple where
+`notification` is the model below.
+
+| Subscribe method                | Unsubscribe method                | Notification model            | Helius docs                                                                                                                                       |
+| ------------------------------- | --------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `account_subscribe(...)`        | `account_unsubscribe(...)`        | `AccountNotification`         | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/accountsubscribe)                                                             |
+| `block_subscribe(...)`          | `block_unsubscribe(...)`          | `BlockNotification`           | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/blocksubscribe)                                                               |
+| `logs_subscribe(...)`           | `logs_unsubscribe(...)`           | `LogsNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/logssubscribe)                                                                |
+| `program_subscribe(...)`        | `program_unsubscribe(...)`        | `ProgramNotification`         | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/programsubscribe)                                                             |
+| `root_subscribe()`              | `root_unsubscribe(...)`           | `RootNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/rootsubscribe)                                                                |
+| `signature_subscribe(...)`      | `signature_unsubscribe(...)`      | `SignatureNotification`       | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/signaturesubscribe)                                                           |
+| `slot_subscribe()`              | `slot_unsubscribe(...)`           | `SlotNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/slotsubscribe)                                                                |
+| `slots_updates_subscribe()`     | `slots_updates_unsubscribe(...)`  | `SlotsUpdatesNotification`    | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/slotsupdatessubscribe)                                                        |
+| `vote_subscribe()`              | `vote_unsubscribe(...)`           | `VoteNotification`            | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/votesubscribe)                                                                |
+| `transaction_subscribe(...)`    | `transaction_unsubscribe(...)`    | `TransactionNotification`     | [reference](https://www.helius.dev/docs/api-reference/rpc/websocket/slotunsubscribe)                                                                                       |
+
+## Admin API
+
+`AccountManagementClient` wraps the Helius admin API. Today it exposes
+project credit usage via `get_project_usage(...)`, which returns a typed
+`ProjectUsage` model.
+
+```python
+from helius.admin.admin import AccountManagementClient
+
+with AccountManagementClient(api_key="YOUR_HELIUS_API_KEY") as admin:
+    usage = admin.get_project_usage(project_id="YOUR_PROJECT_ID")
+    print(usage.credits_remaining, usage.usage.rpc)
+```
+
+The `project_id` can be passed per call or set once on the constructor;
+if neither is provided, `get_project_usage` raises `ValueError`. The
+client defaults to `https://admin-api.helius.xyz` and, like the others,
+supports the context-manager protocol, a manual `close()`, and reads
+`HELIUS_API_KEY` from the environment or `.env`.
 
 ## License
 

helius_python-0.3.0/TODO.md

@@ -0,0 +1,3 @@
+- Mangling __
+- WebSocket subscription manager
+- Use typeddicts where useful