helius-python 0.3.4__tar.gz → 0.4.0__tar.gz

{helius_python-0.3.4 → helius_python-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: helius-python
-Version: 0.3.4
+Version: 0.4.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
@@ -135,9 +135,10 @@ wraps it.
 - 🚧 **All Helius-specific RPC extensions** — enhanced transactions, DAS
   (Digital Asset Standard) methods, priority fee estimation, and the
   rest of the Helius-only RPC namespace. **(in progress)**
-- 🚧 **Every Helius REST endpoint** — Enhanced Transactions API,
-  Webhooks API, Mint API, token metadata, address lookups, and beyond.
-  **(in progress)**
+- ✅ **Webhooks API** — create, fetch, update, enable/disable, and delete
+  Helius webhooks. **(supported today)**
+- 🚧 **Remaining Helius REST endpoints** — Enhanced Transactions API,
+  Mint API, token metadata, address lookups, and beyond. **(in progress)**
 - 🚧 **Platform features** — streaming, websockets, and any new
   capability Helius adds to its API. The full WebSocket subscription
   surface (`accountSubscribe`, `transactionSubscribe`, `logsSubscribe`,
@@ -145,10 +146,10 @@ wraps it.
   platform features are **in progress**.
 
 **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.
+WebSocket subscription surface, the Webhooks API, 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
 
@@ -266,9 +267,9 @@ 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/solana_rpc.py`](src/helius/solana_rpc.py) for the current list of
-implemented methods; missing endpoints are tracked as issues and added
-continuously.
+[`src/helius/solana_rpc/client.py`](src/helius/solana_rpc/client.py) for the
+current Solana JSON-RPC implementation; supported surfaces are listed below,
+and missing endpoints are tracked as issues and added continuously.
 
 | Solana JSON-RPC method              | Python method                                 | Helius docs                                                                                                                                                                          |
 | ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -372,6 +373,44 @@ them; both yield a `(context, notification, subscription)` tuple where
 | `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)                                                                                       |
 
+## Webhooks API
+
+`WebhooksApiClient` wraps the Helius Webhooks REST API. It can create,
+fetch, list, update, enable/disable, and delete webhook subscriptions,
+returning typed `Webhook` models where the endpoint returns a webhook.
+
+```python
+from helius.webhooks.webhooks import WebhooksApiClient
+
+with WebhooksApiClient(api_key="YOUR_HELIUS_API_KEY") as webhooks:
+    webhook = webhooks.create_webhook(
+        webhook_url="https://example.com/helius-webhook",
+        transaction_types=["TRANSFER"],
+        account_addresses=["So11111111111111111111111111111111111111112"],
+        webhook_type="enhanced",
+        auth_header="Bearer your-shared-secret",
+        encoding="jsonParsed",
+        txn_status="all",
+    )
+
+    webhooks.toggle_webhook(webhook.webhook_id, active=False)
+```
+
+Like the other clients, it supports the context-manager protocol and a
+manual `close()`. The constructor defaults to
+`https://mainnet.helius-rpc.com/v0/webhooks` and reads `HELIUS_API_KEY`
+from the environment or `.env` when `api_key` is omitted; optional
+`headers` and `proxy` arguments are also accepted.
+
+| REST operation | Python method              | Helius docs                                                                                       |
+| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
+| Create webhook | `create_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/create-webhook)                    |
+| Get webhook    | `get_webhook(...)`         | [reference](https://www.helius.dev/docs/api-reference/webhooks/get-webhook)                       |
+| List webhooks  | `get_all_webhooks()`       | [reference](https://www.helius.dev/docs/api-reference/webhooks/get-all-webhooks)                  |
+| Update webhook | `update_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/update-webhook)                    |
+| Toggle webhook | `toggle_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/toggle-webhook)                    |
+| Delete webhook | `delete_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/delete-webhook)                    |
+
 ## Admin API
 
 `AccountManagementClient` wraps the Helius admin API. Today it exposes

{helius_python-0.3.4 → helius_python-0.4.0}/README.md

@@ -113,9 +113,10 @@ wraps it.
 - 🚧 **All Helius-specific RPC extensions** — enhanced transactions, DAS
   (Digital Asset Standard) methods, priority fee estimation, and the
   rest of the Helius-only RPC namespace. **(in progress)**
-- 🚧 **Every Helius REST endpoint** — Enhanced Transactions API,
-  Webhooks API, Mint API, token metadata, address lookups, and beyond.
-  **(in progress)**
+- ✅ **Webhooks API** — create, fetch, update, enable/disable, and delete
+  Helius webhooks. **(supported today)**
+- 🚧 **Remaining Helius REST endpoints** — Enhanced Transactions API,
+  Mint API, token metadata, address lookups, and beyond. **(in progress)**
 - 🚧 **Platform features** — streaming, websockets, and any new
   capability Helius adds to its API. The full WebSocket subscription
   surface (`accountSubscribe`, `transactionSubscribe`, `logsSubscribe`,
@@ -123,10 +124,10 @@ wraps it.
   platform features are **in progress**.
 
 **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.
+WebSocket subscription surface, the Webhooks API, 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
 
@@ -244,9 +245,9 @@ 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/solana_rpc.py`](src/helius/solana_rpc.py) for the current list of
-implemented methods; missing endpoints are tracked as issues and added
-continuously.
+[`src/helius/solana_rpc/client.py`](src/helius/solana_rpc/client.py) for the
+current Solana JSON-RPC implementation; supported surfaces are listed below,
+and missing endpoints are tracked as issues and added continuously.
 
 | Solana JSON-RPC method              | Python method                                 | Helius docs                                                                                                                                                                          |
 | ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -350,6 +351,44 @@ them; both yield a `(context, notification, subscription)` tuple where
 | `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)                                                                                       |
 
+## Webhooks API
+
+`WebhooksApiClient` wraps the Helius Webhooks REST API. It can create,
+fetch, list, update, enable/disable, and delete webhook subscriptions,
+returning typed `Webhook` models where the endpoint returns a webhook.
+
+```python
+from helius.webhooks.webhooks import WebhooksApiClient
+
+with WebhooksApiClient(api_key="YOUR_HELIUS_API_KEY") as webhooks:
+    webhook = webhooks.create_webhook(
+        webhook_url="https://example.com/helius-webhook",
+        transaction_types=["TRANSFER"],
+        account_addresses=["So11111111111111111111111111111111111111112"],
+        webhook_type="enhanced",
+        auth_header="Bearer your-shared-secret",
+        encoding="jsonParsed",
+        txn_status="all",
+    )
+
+    webhooks.toggle_webhook(webhook.webhook_id, active=False)
+```
+
+Like the other clients, it supports the context-manager protocol and a
+manual `close()`. The constructor defaults to
+`https://mainnet.helius-rpc.com/v0/webhooks` and reads `HELIUS_API_KEY`
+from the environment or `.env` when `api_key` is omitted; optional
+`headers` and `proxy` arguments are also accepted.
+
+| REST operation | Python method              | Helius docs                                                                                       |
+| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
+| Create webhook | `create_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/create-webhook)                    |
+| Get webhook    | `get_webhook(...)`         | [reference](https://www.helius.dev/docs/api-reference/webhooks/get-webhook)                       |
+| List webhooks  | `get_all_webhooks()`       | [reference](https://www.helius.dev/docs/api-reference/webhooks/get-all-webhooks)                  |
+| Update webhook | `update_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/update-webhook)                    |
+| Toggle webhook | `toggle_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/toggle-webhook)                    |
+| Delete webhook | `delete_webhook(...)`      | [reference](https://www.helius.dev/docs/api-reference/webhooks/delete-webhook)                    |
+
 ## Admin API
 
 `AccountManagementClient` wraps the Helius admin API. Today it exposes

{helius_python-0.3.4 → helius_python-0.4.0}/TODO.md

@@ -2,3 +2,5 @@
 - WebSocket subscription manager
 - Use typeddicts where useful
 - When Python 3.10 and 3.11 go out of support we should use TypedDict from typing instead of typing_extensions
+- Improve camelCase <-> snake_case in typing
+- Handle HTTP response codes and idiomatic error messages in responses

helius_python-0.4.0/examples/webhooks/webhook_crud.py

@@ -0,0 +1,190 @@
+"""Create, list, update, toggle, and delete Helius webhooks.
+
+Usage:
+
+    export HELIUS_API_KEY=your_helius_api_key
+
+    # Print all configured webhooks.
+    python examples/webhooks/webhook_crud.py list
+
+    # Inspect one webhook.
+    python examples/webhooks/webhook_crud.py show <WEBHOOK_ID>
+
+    # Create a webhook that watches one or more accounts.
+    python examples/webhooks/webhook_crud.py create \
+        https://example.com/helius/webhook \
+        <ACCOUNT_ADDRESS> [<ACCOUNT_ADDRESS> ...] \
+        --transaction-type TRANSFER \
+        --auth-header "Bearer shared-secret"
+
+    # Update every mutable field on an existing webhook.
+    python examples/webhooks/webhook_crud.py update <WEBHOOK_ID> \
+        https://example.com/helius/webhook \
+        <ACCOUNT_ADDRESS> [<ACCOUNT_ADDRESS> ...]
+
+    # Pause, resume, or delete.
+    python examples/webhooks/webhook_crud.py toggle <WEBHOOK_ID> --inactive
+    python examples/webhooks/webhook_crud.py delete <WEBHOOK_ID> --yes
+
+Docs:
+    https://www.helius.dev/docs/api-reference/webhooks/create-webhook
+    https://www.helius.dev/docs/api-reference/webhooks/get-all-webhooks
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+import httpx
+
+from helius.webhooks.webhooks import Webhook, WebhooksApiClient
+
+
+def print_webhook(webhook: Webhook) -> None:
+    print(json.dumps(webhook.model_dump(mode="json"), indent=2, sort_keys=True))
+
+
+def print_dry_run(action: str, payload: dict[str, Any]) -> int:
+    print(f"Would {action} with:")
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0
+
+
+def add_webhook_payload_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("webhook_url", help="Public HTTPS endpoint Helius will POST to")
+    parser.add_argument(
+        "account_addresses",
+        nargs="+",
+        help="One or more account addresses to watch",
+    )
+    parser.add_argument(
+        "--transaction-type",
+        dest="transaction_types",
+        action="append",
+        help="Transaction type to subscribe to; repeat for multiple (default TRANSFER)",
+    )
+    parser.add_argument(
+        "--webhook-type",
+        default="enhanced",
+        choices=(
+            "enhanced",
+            "raw",
+            "discord",
+            "enhancedDevnet",
+            "rawDevnet",
+            "discordDevnet",
+        ),
+        help="Webhook payload type (default enhanced)",
+    )
+    parser.add_argument(
+        "--auth-header",
+        default="",
+        help="Value Helius should include in the Authorization header",
+    )
+    parser.add_argument(
+        "--encoding",
+        default="jsonParsed",
+        help="Webhook transaction encoding (default jsonParsed)",
+    )
+    parser.add_argument(
+        "--txn-status",
+        default="all",
+        choices=("all", "success", "failed"),
+        help="Transaction status filter (default all)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the request payload without sending it",
+    )
+
+
+def webhook_payload(args: argparse.Namespace) -> dict[str, Any]:
+    return {
+        "webhook_url": args.webhook_url,
+        "transaction_types": args.transaction_types or ["TRANSFER"],
+        "account_addresses": args.account_addresses,
+        "webhook_type": args.webhook_type,
+        "auth_header": args.auth_header,
+        "encoding": args.encoding,
+        "txn_status": args.txn_status,
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("list", help="List all webhooks")
+
+    show = subparsers.add_parser("show", help="Show one webhook")
+    show.add_argument("webhook_id")
+
+    create = subparsers.add_parser("create", help="Create a webhook")
+    add_webhook_payload_args(create)
+
+    update = subparsers.add_parser("update", help="Replace an existing webhook")
+    update.add_argument("webhook_id")
+    add_webhook_payload_args(update)
+
+    toggle = subparsers.add_parser("toggle", help="Activate or deactivate a webhook")
+    toggle.add_argument("webhook_id")
+    status = toggle.add_mutually_exclusive_group(required=True)
+    status.add_argument("--active", action="store_true", help="Resume the webhook")
+    status.add_argument("--inactive", action="store_true", help="Pause the webhook")
+    toggle.add_argument("--dry-run", action="store_true")
+
+    delete = subparsers.add_parser("delete", help="Delete a webhook")
+    delete.add_argument("webhook_id")
+    delete.add_argument("--yes", action="store_true", help="Confirm permanent deletion")
+    delete.add_argument("--dry-run", action="store_true")
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command in {"create", "update"} and args.dry_run:
+        return print_dry_run(args.command, webhook_payload(args))
+    if args.command == "toggle" and args.dry_run:
+        return print_dry_run(
+            "toggle", {"webhook_id": args.webhook_id, "active": args.active}
+        )
+    if args.command == "delete":
+        if args.dry_run:
+            return print_dry_run("delete", {"webhook_id": args.webhook_id})
+        if not args.yes:
+            print("Refusing to delete without --yes", file=sys.stderr)
+            return 2
+
+    try:
+        with WebhooksApiClient() as client:
+            if args.command == "list":
+                webhooks = client.get_all_webhooks()
+                print(json.dumps([w.model_dump(mode="json") for w in webhooks], indent=2))
+            elif args.command == "show":
+                print_webhook(client.get_webhook(args.webhook_id))
+            elif args.command == "create":
+                print_webhook(client.create_webhook(**webhook_payload(args)))
+            elif args.command == "update":
+                print_webhook(
+                    client.update_webhook(args.webhook_id, **webhook_payload(args))
+                )
+            elif args.command == "toggle":
+                print_webhook(client.toggle_webhook(args.webhook_id, active=args.active))
+            elif args.command == "delete":
+                print(client.delete_webhook(args.webhook_id))
+    except httpx.HTTPStatusError as exc:
+        print(f"HTTP {exc.response.status_code}: {exc.response.text}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

helius_python-0.4.0/examples/webhooks/webhook_receiver.py

@@ -0,0 +1,109 @@
+"""Run a tiny local HTTP server that prints Helius webhook payloads.
+
+This receiver uses only the Python standard library. It is useful for local
+development with a tunnel such as ngrok, Cloudflare Tunnel, or `ssh -R`.
+
+Usage:
+
+    python examples/webhooks/webhook_receiver.py --port 8080
+
+    # In another shell, expose it publicly and use that URL in Helius:
+    ngrok http 8080
+
+    # If your webhook was created with authHeader="Bearer shared-secret":
+    python examples/webhooks/webhook_receiver.py \
+        --auth-header "Bearer shared-secret"
+
+The handler accepts POST requests on any path, verifies the optional
+Authorization header, pretty-prints JSON payloads, and replies with 200 OK.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+
+class WebhookHandler(BaseHTTPRequestHandler):
+    expected_auth_header: str | None = None
+
+    def do_POST(self) -> None:  # noqa: N802 - stdlib handler hook name
+        if self.expected_auth_header is not None:
+            actual = self.headers.get("Authorization")
+            if actual != self.expected_auth_header:
+                self.respond(HTTPStatus.UNAUTHORIZED, {"ok": False})
+                print("Rejected request with missing or invalid Authorization header")
+                return
+
+        length = int(self.headers.get("Content-Length", "0"))
+        raw_body = self.rfile.read(length)
+
+        try:
+            payload: Any = json.loads(raw_body)
+        except json.JSONDecodeError:
+            payload = raw_body.decode("utf-8", errors="replace")
+
+        print("\n=== Helius webhook received ===")
+        print(f"Path: {self.path}")
+        print(f"User-Agent: {self.headers.get('User-Agent', '-')}")
+        if isinstance(payload, (dict, list)):
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            print(payload)
+
+        self.respond(HTTPStatus.OK, {"ok": True})
+
+    def do_GET(self) -> None:  # noqa: N802 - stdlib handler hook name
+        self.respond(
+            HTTPStatus.OK, {"ok": True, "message": "POST webhook payloads here"}
+        )
+
+    def log_message(self, format: str, *args: Any) -> None:
+        # Keep the default access log, but send it to stdout next to payload logs.
+        print(f"{self.address_string()} - {format % args}")
+
+    def respond(self, status: HTTPStatus, payload: dict[str, Any]) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--host", default="127.0.0.1", help="Bind host (default 127.0.0.1)"
+    )
+    parser.add_argument("--port", type=int, default=8080, help="Bind port (default 8080)")
+    parser.add_argument(
+        "--auth-header",
+        help="Required Authorization header value, matching the webhook authHeader",
+    )
+    args = parser.parse_args()
+
+    WebhookHandler.expected_auth_header = args.auth_header
+    server = ThreadingHTTPServer((args.host, args.port), WebhookHandler)
+
+    print(f"Listening on http://{args.host}:{args.port}")
+    if args.auth_header:
+        print("Authorization header verification is enabled")
+    print("Press Ctrl+C to stop", flush=True)
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopping receiver", file=sys.stderr)
+    finally:
+        server.server_close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{helius_python-0.3.4 → helius_python-0.4.0}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "helius-python"
-version = "0.3.4"
+version = "0.4.0"
 authors = [
   { name="Markos Narinian", email="manarinian@gmail.com" },
 ]

{helius_python-0.3.4 → helius_python-0.4.0}/src/helius/laserstream/websockets.py

@@ -9,7 +9,7 @@ from pydantic.alias_generators import to_camel
 from typing_extensions import TypedDict
 from websockets.sync.client import connect
 
-from helius.rpc import JsonRpcRequest
+from helius.utils import JsonRpcRequest
 
 
 class Notification(BaseModel):

{helius_python-0.3.4 → helius_python-0.4.0}/src/helius/solana_rpc/client.py

@@ -5,7 +5,6 @@ import httpx
 from dotenv import dotenv_values
 from pydantic import Field, TypeAdapter, validate_call
 
-from helius.rpc import JsonRpcRequest
 from helius.solana_rpc.models import (
     Account,
     Block,
@@ -33,6 +32,7 @@ from helius.solana_rpc.models import (
     TransferFilters,
     VotingAccount,
 )
+from helius.utils import JsonRpcRequest
 
 
 # TODO: Use Pydantic typed dict where useful

{helius_python-0.3.4 → helius_python-0.4.0}/src/helius/solana_rpc/models.py

@@ -4,8 +4,6 @@ from pydantic import AliasGenerator, BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel
 from typing_extensions import TypedDict
 
-# TODO: Improve camelCase <-> snake_case
-
 
 class Account(BaseModel):
     model_config = ConfigDict(alias_generator=AliasGenerator(validation_alias=to_camel))

helius_python-0.4.0/src/helius/utils/__init__.py

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