helius-python 0.2.0__tar.gz → 0.3.1__tar.gz

{helius_python-0.2.0 → helius_python-0.3.1}/AGENTS.md

@@ -1,84 +1,3 @@
-When implementing a function for a RPC method in the SolanaRpcClient 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** (`SolanaRpcClient.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
 

{helius_python-0.2.0 → helius_python-0.3.1}/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).

{helius_python-0.2.0 → helius_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: helius-python
-Version: 0.2.0
+Version: 0.3.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
@@ -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'
@@ -137,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
 
@@ -152,6 +158,11 @@ 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:
@@ -312,6 +323,72 @@ continuously.
 | `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
 
 [MIT](LICENSE)

{helius_python-0.2.0 → helius_python-0.3.1}/README.md

@@ -117,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
 
@@ -132,6 +137,11 @@ 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:
@@ -292,6 +302,72 @@ continuously.
 | `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
 
 [MIT](LICENSE)

helius_python-0.3.1/TODO.md

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

{helius_python-0.2.0 → helius_python-0.3.1}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "helius-python"
-version = "0.2.0"
+version = "0.3.1"
 authors = [
   { name="Markos Narinian", email="manarinian@gmail.com" },
 ]
@@ -21,6 +21,7 @@ dependencies = [
   "httpx",
   "pydantic",
   "python-dotenv",
+  "websockets",
 ]
 classifiers = [
     "Programming Language :: Python :: 3",
@@ -41,3 +42,6 @@ dev = [
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/helius"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

{helius_python-0.2.0 → helius_python-0.3.1}/requirements.txt

@@ -3,3 +3,4 @@ pydantic
 python-dotenv
 respx
 pytest
+websockets

helius_python-0.3.1/src/helius/admin/__init__.py

@@ -0,0 +1,15 @@
+from helius.admin.admin import (
+    AccountManagementClient,
+    BillingCycle,
+    ProjectUsage,
+    SubscriptionDetails,
+    Usage,
+)
+
+__all__ = [
+    "AccountManagementClient",
+    "BillingCycle",
+    "ProjectUsage",
+    "SubscriptionDetails",
+    "Usage",
+]

helius_python-0.3.1/src/helius/admin/admin.py

@@ -0,0 +1,95 @@
+from os import environ
+
+import httpx
+from dotenv import dotenv_values
+from pydantic import AliasGenerator, BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class BillingCycle(BaseModel):
+    start: str
+    end: str
+
+
+class SubscriptionDetails(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    billing_cycle: BillingCycle
+    credits_limit: float
+    plan: str
+
+
+class Usage(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    api: int
+    archival: int
+    das: int
+    grpc: int
+    grpc_geyser: int
+    photon: int
+    rpc: int
+    stream: int
+    webhook: int
+    websocket: int
+
+
+class ProjectUsage(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    credits_remaining: float
+    credits_used: float
+    prepaid_credits_remaining: float
+    prepaid_credits_used: float
+    subscription_details: SubscriptionDetails
+    usage: Usage
+
+
+class AccountManagementClient:
+    def __init__(
+        self,
+        *,
+        base_url: str = "https://admin-api.helius.xyz/v0/admin/projects/{id}/usage",
+        api_key: str | None = None,
+        project_id: str | None = None,
+        headers: dict[str, str] | None = None,
+        proxy: str | None = None,
+    ) -> None:
+        base_url = base_url
+        api_key = (
+            api_key
+            or environ.get("HELIUS_API_KEY")
+            or dotenv_values().get("HELIUS_API_KEY")
+            or None
+        )
+        self.project_id = project_id
+        client_options: dict = {
+            "base_url": base_url,
+            "headers": headers,
+            "proxy": proxy,
+        }
+        if api_key is not None:
+            client_options.update({"params": {"api-key": api_key}})
+        self._client = httpx.Client(**client_options)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+    def __del__(self):
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def get_project_usage(self, project_id: str | None = None) -> ProjectUsage:
+        project_id = project_id or self.project_id or None
+        if project_id is None:
+            raise ValueError("No project ID provided.")
+        response = self._client.request(
+            method="GET", url="/", params={"id": project_id}
+        )
+        response.raise_for_status()
+        return ProjectUsage.model_validate(response.json())