helius-python 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

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/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())

helius/laserstream/websockets.py

@@ -0,0 +1,398 @@
+import json
+from os import environ
+from typing import Annotated, Literal, TypedDict
+
+import httpx
+from dotenv import dotenv_values
+from pydantic import AliasGenerator, BaseModel, ConfigDict, Field, model_validator
+from pydantic.alias_generators import to_camel
+from websockets.sync.client import connect
+
+from helius.rpc import JsonRpcRequest
+
+
+class Notification(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+
+class TransactionNotification(Notification):
+    transaction: dict
+    signature: str
+    slot: int
+
+
+class AccountNotification(Notification):
+    lamports: int
+    owner: str
+    data: list | dict | str
+    executable: bool
+    rent_epoch: int
+    space: int | None = None
+
+
+class BlockNotification(Notification):
+    slot: int
+    err: dict | None
+    block: dict | None
+
+
+class LogsNotification(Notification):
+    signature: str
+    err: dict | str | None
+    logs: list[str]
+
+
+class ProgramNotification(Notification):
+    pubkey: str
+    account: AccountNotification
+
+
+class RootNotification(Notification):
+    root: int
+
+    @model_validator(mode="before")
+    @classmethod
+    def wrap_scalar(cls, data):
+        if not isinstance(data, dict):
+            return {"root": data}
+        return data
+
+
+class SignatureNotification(Notification):
+    value: dict[str, None | str]
+
+    @model_validator(mode="before")
+    @classmethod
+    def wrap_value(cls, data):
+        return {"value": data}
+
+
+class SlotNotification(Notification):
+    parent: int
+    root: int
+    slot: int
+
+
+class SlotsUpdatesNotification(Notification):
+    err: str | None = None
+    parent: int | None = None
+    slot: int
+    stats: dict[str, int] | None = None
+    timestamp: int
+    type: Literal[
+        "firstShredReceived",
+        "completed",
+        "createdBank",
+        "frozen",
+        "dead",
+        "optimisticConfirmation",
+        "root",
+    ]
+
+
+class VoteNotification(Notification):
+    hash: str
+    slots: list[int]
+    timestamp: int | None
+    signature: str
+    vote_pubkey: str
+
+
+class WebSocketClient:
+    class MentionsFilter(TypedDict):
+        mentions: Annotated[list[str], Field(min_length=1, max_length=1)]
+
+    class BlockMentionsFilter(TypedDict):
+        mentionsAccountOrProgram: str
+
+    class MemcmpFilter(TypedDict):
+        offset: int
+        bytes: str
+
+    class DataSizeFilter(TypedDict):
+        dataSize: int
+
+    MODELS = {
+        "transactionNotification": TransactionNotification,
+        "accountNotification": AccountNotification,
+        "blockNotification": BlockNotification,
+        "logsNotification": LogsNotification,
+        "programNotification": ProgramNotification,
+        "rootNotification": RootNotification,
+        "signatureNotification": SignatureNotification,
+        "slotNotification": SlotNotification,
+        "slotsUpdatesNotification": SlotsUpdatesNotification,
+        "voteNotification": VoteNotification,
+    }
+
+    def __init__(
+        self,
+        *,
+        base_url="wss://mainnet.helius-rpc.com",
+        api_key: str | None = None,
+        proxy: str | 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
+        )
+        if not api_key:
+            raise ValueError("No API key provided.")
+        uri = httpx.URL(base_url).copy_with(path="/", params={"api-key": api_key})
+        self._websocket = connect(str(uri), proxy=proxy)
+
+    def close(self):
+        self._websocket.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+    def _send(self, request) -> dict:
+        self._websocket.send(json.dumps(request))
+        return json.loads(self._websocket.recv())
+
+    def _recv(self):
+        response = self._websocket.recv()
+        return json.loads(response)
+
+    def _unsubscribe(self, subscription_type, subscription) -> bool:
+        request = (
+            JsonRpcRequest(method=f"{subscription_type}Unsubscribe")
+            .add(subscription)
+            .build()
+        )
+        response = self._send(request)
+        return response["result"]
+
+    def transaction_subscribe(
+        self,
+        *,
+        vote: bool | None = None,
+        failed: bool | None = None,
+        signature: str | None = None,
+        account_include: list[str] | None = None,
+        account_exclude: list[str] | None = None,
+        account_required: list[str] | None = None,
+        commitment: Literal["finalized", "confirmed", "processed"] | None = None,
+        encoding: Literal["base58", "base64", "jsonParsed"] | None = None,
+        transaction_details: (
+            Literal["full", "signatures", "accounts", "none"] | None
+        ) = None,
+        show_rewards: bool | None = None,
+        max_supported_transaction_version: int | None = None,
+    ) -> int:
+        if max_supported_transaction_version is None and transaction_details in [
+            "accounts",
+            "full",
+        ]:
+            raise ValueError(
+                'max_supported_transaction_version is required when transaction_details is set to "accounts" or "full".'
+            )
+        filter = {
+            key: value
+            for key, value in {
+                "vote": vote,
+                "failed": failed,
+                "signature": signature,
+                "accountInclude": account_include,
+                "accountExclude": account_exclude,
+                "accountRequired": account_required,
+            }.items()
+            if value is not None
+        }
+        request = (
+            JsonRpcRequest(method="transactionSubscribe")
+            .add(filter if filter else None)
+            .set("commitment", commitment)
+            .set("encoding", encoding)
+            .set("transactionDetails", transaction_details)
+            .set("showRewards", show_rewards)
+            .set("maxSupportedTransactionVersion", max_supported_transaction_version)
+            .build()
+        )
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def account_subscribe(
+        self,
+        *,
+        pubkey: str,
+        encoding: Literal["base58", "base64", "base64+zstd", "jsonParsed"]
+        | None = None,
+        commitment: Literal["finalized", "confirmed", "processed"] | None = None,
+    ) -> int:
+        request = (
+            JsonRpcRequest(method="accountSubscribe")
+            .add(pubkey)
+            .set("commitment", commitment)
+            .set("encoding", encoding)
+            .build()
+        )
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def block_subscribe(
+        self,
+        *,
+        filter: Literal["all"] | BlockMentionsFilter,
+        commitment: Literal["finalized", "confirmed", "processed"] | None = None,
+        encoding: Literal["base58", "base64", "base64+zstd", "jsonParsed"]
+        | None = None,
+        transaction_details: (
+            Literal["full", "signatures", "accounts", "none"] | None
+        ) = None,
+        max_supported_transaction_version: int | None = None,
+        show_rewards: bool | None = None,
+    ) -> int:
+        request = (
+            JsonRpcRequest(method="blockSubscribe")
+            .add(filter)
+            .set("commitment", commitment)
+            .set("encoding", encoding)
+            .set("transactionDetails", transaction_details)
+            .set("maxSupportedTransactionVersion", max_supported_transaction_version)
+            .set("showRewards", show_rewards)
+            .build()
+        )
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def logs_subscribe(
+        self,
+        *,
+        filter: Literal["all", "allWithVotes"] | MentionsFilter,
+        commitment: Literal["finalized", "confirmed", "processed"] | None = None,
+    ):
+        request = (
+            JsonRpcRequest(method="logsSubscribe")
+            .add(filter)
+            .set("commitment", commitment)
+            .build()
+        )
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def program_subscribe(
+        self,
+        *,
+        program_id: str,
+        commitment: Literal["finalized", "confirmed", "processed"] | None = None,
+        encoding: Literal["base58", "base64", "base64+zstd", "jsonParsed"]
+        | None = None,
+        filters: list[MemcmpFilter | DataSizeFilter] | None = None,
+    ) -> int:
+        request = (
+            JsonRpcRequest(method="programSubscribe")
+            .add(program_id)
+            .set("commitment", commitment)
+            .set("encoding", encoding)
+            .set("filters", filters)
+            .build()
+        )
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def root_subscribe(self) -> int:
+        request = JsonRpcRequest(method="rootSubscribe").build()
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def signature_subscribe(
+        self,
+        *,
+        signature: str,
+        commitment: Literal["finalized", "confirmed", "processed"] | None = None,
+        enable_received_notification: bool | None = None,
+    ) -> int:
+        request = (
+            JsonRpcRequest(method="signatureSubscribe")
+            .add(signature)
+            .set("commitment", commitment)
+            .set("enableReceivedNotification", enable_received_notification)
+            .build()
+        )
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def slot_subscribe(self) -> int:
+        request = JsonRpcRequest(method="slotSubscribe").build()
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def slots_updates_subscribe(self) -> int:
+        request = JsonRpcRequest(method="slotsUpdatesSubscribe").build()
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def vote_subscribe(self) -> int:
+        request = JsonRpcRequest(method="voteSubscribe").build()
+        response = self._send(request)
+        subscription = response["result"]
+        return subscription
+
+    def transaction_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("transaction", subscription)
+
+    def account_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("account", subscription)
+
+    def block_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("block", subscription)
+
+    def logs_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("logs", subscription)
+
+    def program_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("program", subscription)
+
+    def root_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("root", subscription)
+
+    def signature_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("signature", subscription)
+
+    def slot_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("slot", subscription)
+
+    def slots_updates_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("slotsUpdates", subscription)
+
+    def vote_unsubscribe(self, subscription) -> bool:
+        return self._unsubscribe("vote", subscription)
+
+    def receive(self) -> tuple[dict | None, Notification, int]:
+        response = json.loads(self._websocket.recv())
+        model = self.MODELS[response["method"]]
+        result = response["params"]["result"]
+        subscription = response["params"]["subscription"]
+        if isinstance(result, dict):
+            context = result.get("context")
+            value = result.get("value")
+        else:
+            context, value = None, None
+        if value is not None:
+            notification = model.model_validate(value)
+        else:
+            notification = model.model_validate(result)
+        return context, notification, subscription
+
+    def listen(self):
+        while True:
+            context, notification, subscription = self.receive()
+            yield context, notification, subscription

helius/rpc/__init__.py

@@ -0,0 +1,3 @@
+from helius.rpc.json_rpc_request import JsonRpcRequest
+
+__all__ = ["JsonRpcRequest"]

helius/rpc/json_rpc_request.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class JsonRpcRequest:
+    class Request(BaseModel):
+        jsonrpc: str
+        method: str
+        params: list[Any] | None = None
+        id: str | int | None
+
+    def __init__(
+        self,
+        *,
+        jsonrpc: str = "2.0",
+        method: str,
+        id: str | int | None = 1,
+    ):
+        self._jsonrpc = jsonrpc
+        self._method = method
+        self._id = id
+        self._positional: list[Any] = []
+        self._config: dict[str, Any] = {}
+
+    def add(self, value, can_be_none: bool = False):
+        # If dict (for example) strip none values to remove the building burden from the function that calls it
+        if value is not None:
+            self._positional.append(value)
+        elif can_be_none:
+            self._positional.append(None)
+        return self
+
+    def set(self, key: str, value, can_be_none: bool = False):
+        if value is not None:
+            self._config.update({key: value})
+        elif can_be_none:
+            self._config.update({key: None})
+        return self
+
+    def build(self):
+        params = self._positional if self._positional else []
+        if self._config:
+            params.append(self._config)
+        request = {
+            "jsonrpc": self._jsonrpc,
+            "method": self._method,
+            "id": self._id,
+        }
+        if params:
+            request.update({"params": params})
+        return self.Request(**request).model_dump()

helius/solana_rpc/__init__.py

@@ -0,0 +1,51 @@
+from helius.solana_rpc.client import SolanaRpcClient
+from helius.solana_rpc.models import (
+    Account,
+    Block,
+    BlockCommitment,
+    ClusterNode,
+    EpochInfo,
+    EpochSchedule,
+    InflationGovernor,
+    InflationRate,
+    InflationReward,
+    LamportAccount,
+    PerformanceSample,
+    ProgramAccount,
+    Rewards,
+    SignatureStatus,
+    Supply,
+    TokenAccount,
+    TokenAccountBalance,
+    TokenSupply,
+    Transaction,
+    TransactionMetadata,
+    TransactionSignature,
+    VotingAccount,
+)
+
+__all__ = [
+    "Account",
+    "Block",
+    "BlockCommitment",
+    "ClusterNode",
+    "EpochInfo",
+    "EpochSchedule",
+    "InflationGovernor",
+    "InflationRate",
+    "InflationReward",
+    "LamportAccount",
+    "PerformanceSample",
+    "ProgramAccount",
+    "Rewards",
+    "SignatureStatus",
+    "SolanaRpcClient",
+    "Supply",
+    "TokenAccount",
+    "TokenAccountBalance",
+    "TokenSupply",
+    "Transaction",
+    "TransactionMetadata",
+    "TransactionSignature",
+    "VotingAccount",
+]

helius/{solana_rpc.py → solana_rpc/client.py}

@@ -1,11 +1,12 @@
-import os
-from typing import Annotated, Any, Literal
+from os import environ
+from typing import Annotated, Literal
 
 import httpx
 from dotenv import dotenv_values
-from pydantic import BaseModel, Field, TypeAdapter, validate_call
+from pydantic import Field, TypeAdapter, validate_call
 
-from helius.models import (
+from helius.rpc import JsonRpcRequest
+from helius.solana_rpc.models import (
     Account,
     Block,
     BlockCommitment,
@@ -17,6 +18,7 @@ from helius.models import (
     InflationReward,
     LamportAccount,
     PerformanceSample,
+    ProgramAccount,
     SignatureStatus,
     Supply,
     TokenAccount,
@@ -28,24 +30,27 @@ from helius.models import (
 )
 
 
+# TODO: Use Pydantic typed dict where useful
 class SolanaRpcClient:
     def __init__(
         self,
         *,
         base_url: str = "https://mainnet.helius-rpc.com",
         api_key: str | None = None,
+        headers: dict[str, str] | None = None,
+        proxy: str | None = None,
     ) -> None:
-        self.base_url = base_url
-        self.api_key = (
+        base_url = base_url
+        api_key = (
             api_key
-            or os.environ.get("HELIUS_API_KEY")
+            or environ.get("HELIUS_API_KEY")
             or dotenv_values().get("HELIUS_API_KEY")
+            or None
         )
-        if not self.api_key:
+        if not api_key:
             raise ValueError("No API key provided.")
         self._client = httpx.Client(
-            base_url=self.base_url,
-            params={"api-key": self.api_key},
+            base_url=base_url, params={"api-key": api_key}, headers=headers, proxy=proxy
         )
 
     def __enter__(self):
@@ -82,7 +87,7 @@ class SolanaRpcClient:
                 "Set both data_slice_length and data_slice_offset or neither."
             )
         request = (
-            RpcRequest(method="getAccountInfo")
+            JsonRpcRequest(method="getAccountInfo")
             .add(public_key)
             .set("commitment", commitment)
             .set("encoding", encoding)
@@ -111,7 +116,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> tuple[dict, int]:
         request = (
-            RpcRequest(method="getBalance")
+            JsonRpcRequest(method="getBalance")
             .add(public_key)
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
@@ -135,7 +140,7 @@ class SolanaRpcClient:
         max_supported_transcation_version: int | None = None,
     ) -> Block | None:
         request = (
-            RpcRequest(method="getBlock")
+            JsonRpcRequest(method="getBlock")
             .add(slot)
             .set("commitment", commitment)
             .set("encoding", encoding)
@@ -153,7 +158,7 @@ class SolanaRpcClient:
         *,
         slot: int,
     ) -> BlockCommitment:
-        request = RpcRequest(method="getBlockCommitment").add(slot).build()
+        request = JsonRpcRequest(method="getBlockCommitment").add(slot).build()
         response = self._send(request)
         block_commitment = BlockCommitment.model_validate(response["result"])
         return block_commitment
@@ -165,7 +170,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> int:
         request = (
-            RpcRequest(method="getBlockHeight")
+            JsonRpcRequest(method="getBlockHeight")
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
             .build()
@@ -198,7 +203,7 @@ class SolanaRpcClient:
             if last_slot is not None:
                 range.update({"lastSlot": last_slot})
         request = (
-            RpcRequest(method="getBlockProduction")
+            JsonRpcRequest(method="getBlockProduction")
             .set("commitment", commitment)
             .set("range", range)
             .set("identity", identity)
@@ -221,7 +226,7 @@ class SolanaRpcClient:
         The range between start_slot and end_slot (or latest slot if end_slot is omitted) must not exceed 500,000 slots.
         """
         request = (
-            RpcRequest(method="getBlocks")
+            JsonRpcRequest(method="getBlocks")
             .add(start_slot)
             .add(end_slot)
             .set("commitment", commitment)
@@ -238,7 +243,7 @@ class SolanaRpcClient:
         commitment: Literal["finalized", "confirmed", "processed"] | None = None,
     ) -> list[int]:
         request = (
-            RpcRequest(method="getBlocksWithLimit")
+            JsonRpcRequest(method="getBlocksWithLimit")
             .add(start_slot)
             .add(limit)
             .set("commitment", commitment)
@@ -248,12 +253,12 @@ class SolanaRpcClient:
         return response["result"]
 
     def get_block_time(self, *, slot: int) -> int | None:
-        request = RpcRequest(method="getBlockTime").add(slot).build()
+        request = JsonRpcRequest(method="getBlockTime").add(slot).build()
         response = self._send(request)
         return response["result"]
 
     def get_cluster_nodes(self) -> list[ClusterNode]:
-        request = RpcRequest(method="getClusterNodes").build()
+        request = JsonRpcRequest(method="getClusterNodes").build()
         response = self._send(request)
         ta = TypeAdapter(list[ClusterNode])
         cluster_nodes = ta.validate_python(response["result"])
@@ -266,7 +271,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> EpochInfo:
         request = (
-            RpcRequest(method="getEpochInfo")
+            JsonRpcRequest(method="getEpochInfo")
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
             .build()
@@ -276,7 +281,7 @@ class SolanaRpcClient:
         return epoch_info
 
     def get_epoch_schedule(self) -> EpochSchedule:
-        request = RpcRequest(method="getEpochSchedule").build()
+        request = JsonRpcRequest(method="getEpochSchedule").build()
         response = self._send(request)
         epoch_schedule = EpochSchedule.model_validate(response["result"])
         return epoch_schedule
@@ -289,7 +294,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> tuple[dict, int | None]:
         request = (
-            RpcRequest(method="getFeeForMessage")
+            JsonRpcRequest(method="getFeeForMessage")
             .add(message)
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
@@ -301,17 +306,17 @@ class SolanaRpcClient:
         return context, value
 
     def get_first_available_block(self) -> int:
-        request = RpcRequest(method="getFirstAvailableBlock").build()
+        request = JsonRpcRequest(method="getFirstAvailableBlock").build()
         response = self._send(request)
         return response["result"]
 
     def get_genesis_hash(self) -> str:
-        request = RpcRequest(method="getGenesisHash").build()
+        request = JsonRpcRequest(method="getGenesisHash").build()
         response = self._send(request)
         return response["result"]
 
     def get_health(self) -> bool:
-        request = RpcRequest(method="getHealth").build()
+        request = JsonRpcRequest(method="getHealth").build()
         response = self._send(request)
         if "result" in response and response["result"] == "ok":
             return True
@@ -319,12 +324,12 @@ class SolanaRpcClient:
             return False
 
     def get_highest_snapshot_slot(self) -> dict:
-        request = RpcRequest(method="getHighestSnapshotSlot").build()
+        request = JsonRpcRequest(method="getHighestSnapshotSlot").build()
         response = self._send(request)
         return response["result"]
 
     def get_identity(self) -> str:
-        request = RpcRequest(method="getIdentity").build()
+        request = JsonRpcRequest(method="getIdentity").build()
         response = self._send(request)
         identity = response["result"]["identity"]
         return identity
@@ -335,7 +340,7 @@ class SolanaRpcClient:
         commitment: Literal["finalized", "confirmed", "processed"] | None = None,
     ) -> InflationGovernor:
         request = (
-            RpcRequest(method="getInflationGovernor")
+            JsonRpcRequest(method="getInflationGovernor")
             .set("commitment", commitment)
             .build()
         )
@@ -344,7 +349,7 @@ class SolanaRpcClient:
         return inflation_governor
 
     def get_inflation_rate(self) -> InflationRate:
-        request = RpcRequest(method="getInflationRate").build()
+        request = JsonRpcRequest(method="getInflationRate").build()
         response = self._send(request)
         inflation_rate = InflationRate.model_validate(response["result"])
         return inflation_rate
@@ -358,7 +363,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> list[InflationReward | None]:
         request = (
-            RpcRequest(method="getInflationReward")
+            JsonRpcRequest(method="getInflationReward")
             .add(addresses)
             .set("commitment", commitment)
             .set("epoch", epoch)
@@ -377,7 +382,7 @@ class SolanaRpcClient:
         filter: Literal["circulating", "nonCirculating"] | None = None,
     ) -> tuple[dict, list[LamportAccount]]:
         request = (
-            RpcRequest(method="getLargestAccounts")
+            JsonRpcRequest(method="getLargestAccounts")
             .set("commitment", commitment)
             .set("filter", filter)
             .build()
@@ -396,7 +401,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> tuple[dict, str, int]:
         request = (
-            RpcRequest(method="getLatestBlockhash")
+            JsonRpcRequest(method="getLatestBlockhash")
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
             .build()
@@ -416,7 +421,7 @@ class SolanaRpcClient:
         identity: str | None = None,
     ) -> dict[str, list[int]] | None:
         request = (
-            RpcRequest(method="getLeaderSchedule")
+            JsonRpcRequest(method="getLeaderSchedule")
             .add(slot)
             .set("commitment", commitment)
             .set("identity", identity)
@@ -427,13 +432,13 @@ class SolanaRpcClient:
         return result
 
     def get_max_retransmit_slot(self) -> int:
-        request = RpcRequest(method="getMaxRetransmitSlot").build()
+        request = JsonRpcRequest(method="getMaxRetransmitSlot").build()
         response = self._send(request)
         result = response["result"]
         return result
 
     def get_max_shred_insert_slot(self) -> int:
-        request = RpcRequest(method="getMaxShredInsertSlot").build()
+        request = JsonRpcRequest(method="getMaxShredInsertSlot").build()
         response = self._send(request)
         result = response["result"]
         return result
@@ -445,7 +450,7 @@ class SolanaRpcClient:
         commitment: Literal["finalized", "confirmed", "processed"] | None = None,
     ) -> int:
         request = (
-            RpcRequest(method="getMinimumBalanceForRentExemption")
+            JsonRpcRequest(method="getMinimumBalanceForRentExemption")
             .add(data_length)
             .set("commitment", commitment)
             .build()
@@ -478,7 +483,7 @@ class SolanaRpcClient:
                 "Data slice is only available for base58, base64, or base64+zstd encodings."
             )
         request = (
-            RpcRequest(method="getMultipleAccounts")
+            JsonRpcRequest(method="getMultipleAccounts")
             .add(pubkeys)
             .set("commitment", commitment)
             .set("encoding", encoding)
@@ -513,13 +518,13 @@ class SolanaRpcClient:
         data_slice_length: int | None = None,
         changed_since_slot: int | None = None,
         filters: list[dict] | None = None,
-    ) -> list[tuple[str, Account]]:
+    ) -> list[ProgramAccount]:
         if (data_slice_offset is None) != (data_slice_length is None):
             raise ValueError(
                 "Set both data_slice_length and data_slice_offset or neither."
             )
         request = (
-            RpcRequest(method="getProgramAccounts")
+            JsonRpcRequest(method="getProgramAccounts")
             .add(program_id)
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
@@ -538,15 +543,18 @@ class SolanaRpcClient:
             .build()
         )
         response = self._send(request)
-        result = response["result"]
-        return [(i["pubkey"], Account.model_validate(i["account"])) for i in result]
+        ta = TypeAdapter(list[ProgramAccount])
+        program_accounts = ta.validate_python(response["result"])
+        return program_accounts
 
     def get_recent_performance_samples(
         self,
         *,
         limit: int | None = None,
     ) -> list[PerformanceSample]:
-        request = RpcRequest(method="getRecentPerformanceSamples").add(limit).build()
+        request = (
+            JsonRpcRequest(method="getRecentPerformanceSamples").add(limit).build()
+        )
         response = self._send(request)
         ta = TypeAdapter(list[PerformanceSample])
         return ta.validate_python(response["result"])
@@ -557,7 +565,7 @@ class SolanaRpcClient:
         locked_writable_accounts: list[str] | None = None,
     ) -> list[tuple[int, int]]:
         request = (
-            RpcRequest(method="getRecentPrioritizationFees")
+            JsonRpcRequest(method="getRecentPrioritizationFees")
             .add(locked_writable_accounts)
             .build()
         )
@@ -576,7 +584,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> list[TransactionSignature]:
         request = (
-            RpcRequest(method="getSignaturesForAddress")
+            JsonRpcRequest(method="getSignaturesForAddress")
             .add(address)
             .set("limit", limit)
             .set("before", before)
@@ -597,7 +605,7 @@ class SolanaRpcClient:
         search_transaction_history: bool | None = None,
     ) -> tuple[dict, list[SignatureStatus | None]]:
         request = (
-            RpcRequest(method="getSignatureStatuses")
+            JsonRpcRequest(method="getSignatureStatuses")
             .add(signatures)
             .set("searchTransactionHistory", search_transaction_history)
             .build()
@@ -617,7 +625,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> int:
         request = (
-            RpcRequest(method="getSlot")
+            JsonRpcRequest(method="getSlot")
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
             .build()
@@ -632,7 +640,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> str:
         request = (
-            RpcRequest(method="getSlotLeader")
+            JsonRpcRequest(method="getSlotLeader")
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
             .build()
@@ -647,7 +655,9 @@ class SolanaRpcClient:
         start_slot: int,
         limit: Annotated[int, Field(ge=1, le=5000)],
     ) -> list[str]:
-        request = RpcRequest(method="getSlotLeaders").add(start_slot).add(limit).build()
+        request = (
+            JsonRpcRequest(method="getSlotLeaders").add(start_slot).add(limit).build()
+        )
         response = self._send(request)
         return response["result"]
 
@@ -657,7 +667,7 @@ class SolanaRpcClient:
         commitment: Literal["finalized", "confirmed", "processed"] | None = None,
     ) -> tuple[dict, int]:
         request = (
-            RpcRequest(method="getStakeMinimumDelegation")
+            JsonRpcRequest(method="getStakeMinimumDelegation")
             .set("commitment", commitment)
             .build()
         )
@@ -673,7 +683,7 @@ class SolanaRpcClient:
         exclude_non_circulating_accounts_list: bool | None = None,
     ) -> tuple[dict, Supply]:
         request = (
-            RpcRequest(method="getSupply")
+            JsonRpcRequest(method="getSupply")
             .set("commitment", commitment)
             .set(
                 "excludeNonCirculatingAccountsList",
@@ -695,7 +705,7 @@ class SolanaRpcClient:
         commitment: Literal["finalized", "confirmed", "processed"] | None = None,
     ) -> tuple[dict, TokenAccountBalance]:
         request = (
-            RpcRequest(method="getTokenAccountBalance")
+            JsonRpcRequest(method="getTokenAccountBalance")
             .add(token_account)
             .set("commitment", commitment)
             .build()
@@ -731,7 +741,7 @@ class SolanaRpcClient:
             )
         filter = {"mint": mint} if mint is not None else {"programId": program_id}
         request = (
-            RpcRequest(method="getTokenAccountsByDelegate")
+            JsonRpcRequest(method="getTokenAccountsByDelegate")
             .add(delegate_pub_key)
             .add(filter)
             .set("commitment", commitment)
@@ -781,7 +791,7 @@ class SolanaRpcClient:
             )
         filter = {"mint": mint} if mint is not None else {"programId": program_id}
         request = (
-            RpcRequest(method="getTokenAccountsByOwner")
+            JsonRpcRequest(method="getTokenAccountsByOwner")
             .add(owner_pub_key)
             .add(filter)
             .set("commitment", commitment)
@@ -814,7 +824,7 @@ class SolanaRpcClient:
         commitment: Literal["finalized", "confirmed", "processed"] | None = None,
     ) -> tuple[dict, list[TokenAccount]]:
         request = (
-            RpcRequest(method="getTokenLargestAccounts")
+            JsonRpcRequest(method="getTokenLargestAccounts")
             .add(mint)
             .set("commitment", commitment)
             .build()
@@ -832,7 +842,7 @@ class SolanaRpcClient:
         commitment: Literal["finalized", "confirmed", "processed"] | None = None,
     ) -> tuple[dict, TokenSupply]:
         request = (
-            RpcRequest(method="getTokenSupply")
+            JsonRpcRequest(method="getTokenSupply")
             .add(mint_address)
             .set("commitment", commitment)
             .build()
@@ -851,7 +861,7 @@ class SolanaRpcClient:
         max_supported_transaction_version: int | None = None,
     ) -> Transaction:
         request = (
-            RpcRequest(method="getTransaction")
+            JsonRpcRequest(method="getTransaction")
             .add(transaction_signature)
             .set("commitment", commitment)
             .set("encoding", encoding)
@@ -869,7 +879,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> int:
         request = (
-            RpcRequest(method="getTransactionCount")
+            JsonRpcRequest(method="getTransactionCount")
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
             .build()
@@ -878,7 +888,7 @@ class SolanaRpcClient:
         return response["result"]
 
     def get_version(self) -> tuple[str, int]:
-        request = RpcRequest(method="getVersion").build()
+        request = JsonRpcRequest(method="getVersion").build()
         response = self._send(request)
         result = response["result"]
         return result["solana-core"], result["feature-set"]
@@ -892,7 +902,7 @@ class SolanaRpcClient:
         delinquent_slot_distance: int | None = None,
     ) -> tuple[list[VotingAccount], list[VotingAccount]]:
         request = (
-            RpcRequest(method="getVoteAccounts")
+            JsonRpcRequest(method="getVoteAccounts")
             .set("commitment", commitment)
             .set("votePubkey", vote_pubkey)
             .set("keepUnstakedDelinquents", keep_unstaked_delinquents)
@@ -913,7 +923,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> tuple[dict, bool]:
         request = (
-            RpcRequest(method="isBlockhashValid")
+            JsonRpcRequest(method="isBlockhashValid")
             .add(blockhash)
             .set("commitment", commitment)
             .set("minContextSlot", min_context_slot)
@@ -925,7 +935,7 @@ class SolanaRpcClient:
         return context, value
 
     def minimum_ledger_slot(self) -> int:
-        request = RpcRequest(method="minimumLedgerSlot").build()
+        request = JsonRpcRequest(method="minimumLedgerSlot").build()
         response = self._send(request)
         return response["result"]
 
@@ -940,7 +950,7 @@ class SolanaRpcClient:
         Only available on Devnet and Testnet, not Mainnet Beta.
         """
         request = (
-            RpcRequest(method="requestAirdrop")
+            JsonRpcRequest(method="requestAirdrop")
             .add(public_key)
             .add(lamports)
             .set("commitment", commitment)
@@ -962,7 +972,7 @@ class SolanaRpcClient:
         min_context_slot: int | None = None,
     ) -> str:
         request = (
-            RpcRequest(method="sendTransaction")
+            JsonRpcRequest(method="sendTransaction")
             .add(transaction)
             .set("encoding", encoding)
             .set("skipPreflight", skip_preflight)
@@ -973,51 +983,3 @@ class SolanaRpcClient:
         )
         response = self._send(request)
         return response["result"]
-
-
-class RpcRequest:
-    class Request(BaseModel):
-        jsonrpc: str
-        method: str
-        params: list[Any] | None = None
-        id: str | int | None
-
-    def __init__(
-        self,
-        *,
-        jsonrpc: str = "2.0",
-        method: str,
-        id: str | int | None = 1,
-    ):
-        self._jsonrpc = jsonrpc
-        self._method = method
-        self._id = id
-        self._positional: list[Any] = []
-        self._config: dict[str, Any] = {}
-
-    def add(self, value, can_be_none: bool = False):
-        if value is not None:
-            self._positional.append(value)
-        elif can_be_none:
-            self._positional.append(None)
-        return self
-
-    def set(self, key: str, value, can_be_none: bool = False):
-        if value is not None:
-            self._config.update({key: value})
-        elif can_be_none:
-            self._config.update({key: None})
-        return self
-
-    def build(self):
-        params = self._positional if self._positional else []
-        if self._config:
-            params.append(self._config)
-        request = {
-            "jsonrpc": self._jsonrpc,
-            "method": self._method,
-            "id": self._id,
-        }
-        if params:
-            request.update({"params": params})
-        return self.Request(**request).model_dump()

helius/{models.py → solana_rpc/models.py}

@@ -15,6 +15,13 @@ class Account(BaseModel):
     space: int | None = None
 
 
+class ProgramAccount(BaseModel):
+    model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
+
+    pubkey: str
+    account: Account
+
+
 class Rewards(BaseModel):
     model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))
 

{helius_python-0.2.0.dist-info → helius_python-0.3.1.dist-info}/METADATA

@@ -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.3.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+helius/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+helius/admin/__init__.py,sha256=HboRJXZNzuDAc6r3kj2QZtEcu2U3EWJHv81dYDJGjaA,262
+helius/admin/admin.py,sha256=dcmOgeu10Q43QZC8K-a25vp2JNAb4hs5gu3YWaovV4Y,2541
+helius/laserstream/websockets.py,sha256=ASAltIRlfWKgjkAwox8xbYqULsU6GtJd7TN_nX_F8jA,12417
+helius/rpc/__init__.py,sha256=ciwM1KfBNyZwCeqOmlWTcSrUD03cbrzgeeEZsn9msi0,85
+helius/rpc/json_rpc_request.py,sha256=hm7WkPo0CnwMnuHE4qR-d93wGArZRPRm-B3uueykL3E,1479
+helius/solana_rpc/__init__.py,sha256=Mfhb6ibrCqAX6AchtL3ViBlpCi9RKP8uhT9e_S5_Wb0,1006
+helius/solana_rpc/client.py,sha256=8WDsBqFYlRcnAYiGB2_gPOm3UuQSSV4JlEY9qwpr63s,34116
+helius/solana_rpc/models.py,sha256=ywzdyUNrJ4mPxwjuntsmJT-tBcHE64pkG96--jKAgIw,5474
+helius_python-0.3.1.dist-info/METADATA,sha256=rtSGuVYxo8jVc1BSiBOBm0ysq0eMrPOb4EafQ4bpDWY,34392
+helius_python-0.3.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+helius_python-0.3.1.dist-info/licenses/LICENSE,sha256=bZc2EDmq_GsWH77uK8LBn1kqqrOPcp2f9p-ys9bYa1E,1072
+helius_python-0.3.1.dist-info/RECORD,,

helius_python-0.2.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-helius/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-helius/models.py,sha256=O_T8WQB_C4AFXCs6CU2ges5CUxoOPahUkf9Z6S_AEnQ,5312
-helius/solana_rpc.py,sha256=yzxQqsx7UIJ295m366Oh6ZDdUwhXsrkJ99emAEEE9JM,34952
-helius_python-0.2.0.dist-info/METADATA,sha256=wxBqRq8eDo6a6DGYr3daRBgCB7dul4dfoVUS4YwoP_8,28985
-helius_python-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-helius_python-0.2.0.dist-info/licenses/LICENSE,sha256=bZc2EDmq_GsWH77uK8LBn1kqqrOPcp2f9p-ys9bYa1E,1072
-helius_python-0.2.0.dist-info/RECORD,,