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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: helius-python
-Version: 0.3.3
+Version: 0.3.4
 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

helius_python-0.3.4/examples/README.md

@@ -0,0 +1,4 @@
+# Examples
+
+Examples can be found under the `examples` directory
+Please note that all examples are AI-generated and not thoroughly reviewed.

helius_python-0.3.4/examples/laserstream/websocket_logs.py

@@ -0,0 +1,76 @@
+"""Listen for Solana log notifications over Helius WebSockets.
+
+Subscribes with `logsSubscribe`, prints a small number of notifications,
+then unsubscribes cleanly. Use `--mentions <ADDRESS>` to filter logs to a
+single account or program; otherwise the example listens to all logs.
+
+Usage:
+
+    export HELIUS_API_KEY=your_helius_api_key
+    python examples/laserstream/websocket_logs.py --mentions <ADDRESS>
+    python examples/laserstream/websocket_logs.py --count 3
+
+Docs:
+    https://www.helius.dev/docs/api-reference/rpc/websocket/logssubscribe
+"""
+
+from __future__ import annotations
+
+import argparse
+from contextlib import suppress
+import sys
+
+from helius.laserstream.websockets import WebSocketClient
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--mentions",
+        help="Only receive logs mentioning this account or program address",
+    )
+    parser.add_argument(
+        "--count",
+        type=int,
+        default=5,
+        help="Number of notifications to print before exiting (default 5)",
+    )
+    args = parser.parse_args()
+
+    log_filter = {"mentions": [args.mentions]} if args.mentions else "all"
+
+    with WebSocketClient() as client:
+        subscription = client.logs_subscribe(
+            filter=log_filter,
+            commitment="confirmed",
+        )
+        print(f"Subscribed to logs with id {subscription}. Waiting...\n")
+
+        try:
+            for index, (context, notification, _subscription) in enumerate(
+                client.listen(), start=1
+            ):
+                slot = context.get("slot") if context else "unknown"
+                status = "ERR" if notification.err else "OK "
+                print(f"[{index}/{args.count}] slot={slot} {status} {notification.signature}")
+                for line in notification.logs[:5]:
+                    print(f"    {line}")
+                if len(notification.logs) > 5:
+                    print(f"    ... {len(notification.logs) - 5} more log lines")
+                print()
+                if index >= args.count:
+                    break
+        finally:
+            # A busy `logsSubscribe` stream can deliver another notification
+            # between our unsubscribe request and the unsubscribe response. The
+            # client helper currently expects the very next frame to be the RPC
+            # response, so ignore that race here and let the context manager
+            # close the socket cleanly.
+            with suppress(KeyError):
+                client.logs_unsubscribe(subscription)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

helius_python-0.3.4/examples/solana_rpc/address_transactions.py

@@ -0,0 +1,125 @@
+"""List Helius enhanced transactions for an address.
+
+Uses Helius's `getTransactionsForAddress` RPC method, which can return
+either compact signature rows or full transaction payloads with pagination.
+
+Usage:
+
+    export HELIUS_API_KEY=your_helius_api_key
+    python examples/solana_rpc/address_transactions.py <ADDRESS> [--limit 10]
+    python examples/solana_rpc/address_transactions.py <ADDRESS> --full --limit 5
+
+Docs:
+    https://www.helius.dev/docs/getting-data/get-transactions-for-address
+
+Note:
+    Helius documents this exclusive RPC method as requiring a Developer plan
+    or higher.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import sys
+
+import httpx
+
+from helius.solana_rpc import SolanaRpcClient
+
+
+def format_time(block_time: int | None) -> str:
+    if block_time is None:
+        return "(no time)"
+    return dt.datetime.fromtimestamp(block_time, tz=dt.timezone.utc).strftime(
+        "%Y-%m-%d %H:%M:%SZ"
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("address", help="Wallet, account, or program address")
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=10,
+        help="Number of rows to fetch (1-1000, default 10)",
+    )
+    parser.add_argument(
+        "--pagination-token",
+        help="Token returned by a previous page of results",
+    )
+    parser.add_argument(
+        "--full",
+        action="store_true",
+        help="Fetch full transaction details instead of signature rows",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate arguments and print the planned request without sending it",
+    )
+    args = parser.parse_args()
+
+    details = "full" if args.full else "signatures"
+    if args.dry_run:
+        print("Would call get_transactions_for_address with:")
+        print(f"  address={args.address}")
+        print(f"  transaction_details={details}")
+        print(f"  limit={args.limit}")
+        print(f"  pagination_token={args.pagination_token}")
+        print(f"  encoding={'jsonParsed' if args.full else None}")
+        return 0
+
+    try:
+        with SolanaRpcClient() as client:
+            transactions, next_token = client.get_transactions_for_address(
+                address=args.address,
+                transaction_details=details,
+                sort_order="desc",
+                commitment="finalized",
+                limit=args.limit,
+                pagination_token=args.pagination_token,
+                encoding="jsonParsed" if args.full else None,
+                max_supported_transaction_version=0 if args.full else None,
+            )
+    except httpx.HTTPStatusError as exc:
+        print(
+            f"HTTP {exc.response.status_code}: getTransactionsForAddress was rejected. "
+            "This Helius-exclusive method may require a Developer plan or higher.",
+            file=sys.stderr,
+        )
+        return 2
+
+    print(f"\n=== Transactions for {args.address} ===\n")
+    if not transactions:
+        print("No transactions returned.")
+        return 0
+
+    for tx in transactions:
+        if details == "signatures":
+            status = "ERR" if tx.err else "OK "
+            print(
+                f"{format_time(tx.block_time)}  slot={tx.slot:<12} "
+                f"idx={tx.transaction_index:<4} {status}  {tx.signature}"
+            )
+        else:
+            signature = "(signature unavailable)"
+            signatures = tx.transaction.get("signatures")
+            if isinstance(signatures, list) and signatures:
+                signature = signatures[0]
+            err = tx.meta.get("err") if isinstance(tx.meta, dict) else None
+            status = "ERR" if err else "OK "
+            print(
+                f"{format_time(tx.block_time)}  slot={tx.slot:<12} "
+                f"idx={tx.transaction_index:<4} {status}  {signature}"
+            )
+
+    if next_token:
+        print(f"\nNext page token: {next_token}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

helius_python-0.3.4/examples/solana_rpc/address_transfers.py

@@ -0,0 +1,118 @@
+"""List token and SOL transfers for an address.
+
+Uses Helius's `getTransfersByAddress` RPC method exposed by this client as
+`get_transfers_by_address`.
+
+Usage:
+
+    export HELIUS_API_KEY=your_helius_api_key
+    python examples/solana_rpc/address_transfers.py <ADDRESS> [--limit 20]
+    python examples/solana_rpc/address_transfers.py <ADDRESS> --direction in --mint <MINT>
+
+Docs:
+    https://www.helius.dev/docs/getting-data/get-transfers-by-address
+
+Note:
+    Helius documents this exclusive RPC method as requiring a Developer plan
+    or higher.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import sys
+
+import httpx
+
+from helius.solana_rpc import SolanaRpcClient
+
+
+def format_time(block_time: int) -> str:
+    return dt.datetime.fromtimestamp(block_time, tz=dt.timezone.utc).strftime(
+        "%Y-%m-%d %H:%M:%SZ"
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("address", help="Wallet, token account, or owner address")
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=20,
+        help="Number of transfers to fetch (1-100, default 20)",
+    )
+    parser.add_argument(
+        "--direction",
+        choices=("in", "out", "any"),
+        default="any",
+        help="Transfer direction relative to address (default any)",
+    )
+    parser.add_argument("--with-address", help="Counterparty address filter")
+    parser.add_argument("--mint", help="Mint address filter")
+    parser.add_argument(
+        "--pagination-token",
+        help="Token returned by a previous page of results",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate arguments and print the planned request without sending it",
+    )
+    args = parser.parse_args()
+
+    if args.dry_run:
+        print("Would call get_transfers_by_address with:")
+        print(f"  address={args.address}")
+        print(f"  with_address={args.with_address}")
+        print(f"  direction={args.direction}")
+        print(f"  mint={args.mint}")
+        print(f"  limit={args.limit}")
+        print(f"  pagination_token={args.pagination_token}")
+        return 0
+
+    try:
+        with SolanaRpcClient() as client:
+            transfers, next_token = client.get_transfers_by_address(
+                address=args.address,
+                with_address=args.with_address,
+                direction=args.direction,
+                mint=args.mint,
+                limit=args.limit,
+                pagination_token=args.pagination_token,
+                commitment="finalized",
+                sort_order="desc",
+            )
+    except httpx.HTTPStatusError as exc:
+        print(
+            f"HTTP {exc.response.status_code}: getTransfersByAddress was rejected. "
+            "This Helius-exclusive method may require a Developer plan or higher.",
+            file=sys.stderr,
+        )
+        return 2
+
+    print(f"\n=== Transfers for {args.address} ===\n")
+    if not transfers:
+        print("No transfers returned.")
+        return 0
+
+    for transfer in transfers:
+        from_acct = transfer.from_user_account or transfer.from_token_account or "-"
+        to_acct = transfer.to_user_account or transfer.to_token_account or "-"
+        print(
+            f"{format_time(transfer.block_time)}  slot={transfer.slot:<12} "
+            f"{transfer.type:<11} {transfer.ui_amount:>18}  mint={transfer.mint}"
+        )
+        print(f"    from={from_acct}")
+        print(f"    to  ={to_acct}")
+        print(f"    sig ={transfer.signature}")
+
+    if next_token:
+        print(f"\nNext page token: {next_token}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/block_explorer.py

@@ -8,8 +8,8 @@ breakdown of successful vs. failed transactions plus total fees paid.
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/block_explorer.py
-    python examples/block_explorer.py --slot 250000000
+    python examples/solana_rpc/block_explorer.py
+    python examples/solana_rpc/block_explorer.py --slot 250000000
 
 Uses (with `with`):
     get_slot, get_block.
@@ -43,9 +43,10 @@ def main() -> int:
             else helius.get_slot(commitment="finalized")
         )
         block = helius.get_block(
-            slot,
+            slot=slot,
             commitment="finalized",
             encoding="jsonParsed",
+            rewards=False,
             max_supported_transcation_version=0,
         )
 

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/devnet_airdrop.py

@@ -7,7 +7,7 @@ polls `getSignatureStatuses` until the airdrop transaction reaches a
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/devnet_airdrop.py <WALLET_ADDRESS> [--sol 1.0]
+    python examples/solana_rpc/devnet_airdrop.py <WALLET_ADDRESS> [--sol 1.0]
 
 Note:
     `requestAirdrop` is only available on Devnet and Testnet — never on
@@ -24,6 +24,8 @@ import argparse
 import sys
 import time
 
+import httpx
+
 from helius.solana_rpc import SolanaRpcClient
 
 LAMPORTS_PER_SOL = 1_000_000_000
@@ -45,20 +47,40 @@ def main() -> int:
         default=30.0,
         help="Seconds to wait for confirmation (default: 30)",
     )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate arguments and print the planned airdrop without sending it",
+    )
     args = parser.parse_args()
     lamports = int(args.sol * LAMPORTS_PER_SOL)
 
+    if args.dry_run:
+        print("Would request devnet airdrop with:")
+        print(f"  address={args.address}")
+        print(f"  sol={args.sol}")
+        print(f"  lamports={lamports}")
+        print(f"  timeout={args.timeout}")
+        return 0
+
     client = SolanaRpcClient(base_url=DEVNET_URL)
     try:
         print(f"Requesting {args.sol} SOL airdrop to {args.address} on devnet...")
-        signature = client.request_airdrop(args.address, lamports)
+        try:
+            signature = client.request_airdrop(public_key=args.address, lamports=lamports)
+        except httpx.HTTPStatusError as exc:
+            print(
+                f"HTTP {exc.response.status_code}: devnet airdrop request was rejected.",
+                file=sys.stderr,
+            )
+            return 2
         print(f"  signature: {signature}")
 
         deadline = time.monotonic() + args.timeout
         status = None
         while time.monotonic() < deadline:
             _ctx, statuses = client.get_signature_statuses(
-                [signature], search_transaction_history=True
+                signatures=[signature], search_transaction_history=True
             )
             status = statuses[0]
             if status is not None and status.confirmation_status in (
@@ -79,7 +101,7 @@ def main() -> int:
             return 1
         print(f"  status: {status.confirmation_status} at slot {status.slot}")
 
-        _ctx, balance = client.get_balance(args.address)
+        _ctx, balance = client.get_balance(public_key=args.address)
         print(f"Post-airdrop balance: {balance / LAMPORTS_PER_SOL:.9f} SOL")
     finally:
         client.close()

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/network_status.py

@@ -7,7 +7,7 @@ recent-performance summary (avg TPS over the last samples).
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/network_status.py
+    python examples/solana_rpc/network_status.py
 
 Uses (with `with`):
     get_health, get_version, get_slot, get_block_height, get_epoch_info,

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/priority_fees.py

@@ -12,8 +12,8 @@ sample only counts transactions that locked those accounts as writable
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/priority_fees.py
-    python examples/priority_fees.py --account <PUBKEY> --account <PUBKEY>
+    python examples/solana_rpc/priority_fees.py
+    python examples/solana_rpc/priority_fees.py --account <PUBKEY> --account <PUBKEY>
 
 Uses (with `with`):
     get_recent_prioritization_fees.

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/stake_overview.py

@@ -7,7 +7,7 @@ validator set (top 10 by stake).
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/stake_overview.py
+    python examples/solana_rpc/stake_overview.py
 
 Uses (with `try/finally`):
     get_inflation_rate, get_inflation_governor, get_supply,
@@ -18,6 +18,8 @@ from __future__ import annotations
 
 import sys
 
+import httpx
+
 from helius.solana_rpc import SolanaRpcClient
 
 LAMPORTS_PER_SOL = 1_000_000_000
@@ -25,10 +27,11 @@ LAMPORTS_PER_SOL = 1_000_000_000
 
 def main() -> int:
     client = SolanaRpcClient()
+    client._client.timeout = httpx.Timeout(30.0)
     try:
         rate = client.get_inflation_rate()
         gov = client.get_inflation_governor()
-        _ctx, supply = client.get_supply(exclude_non_circulating_accounts_list=True)
+        _ctx, supply = client.get_supply(exclude_non_circulating_accounts_list=False)
         _ctx, min_stake = client.get_stake_minimum_delegation()
         current, delinquent = client.get_vote_accounts()
     finally:

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/token_inspector.py

@@ -7,11 +7,15 @@ Given a mint address, prints:
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/token_inspector.py <MINT_ADDRESS>
+    python examples/solana_rpc/token_inspector.py <MINT_ADDRESS>
 
-Example with USDC:
+Example with a small-holder-count mint:
 
-    python examples/token_inspector.py EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+    python examples/solana_rpc/token_inspector.py J5iyNuTa6zqqA62Xe4h1VBvcBW5CTSNNva3QPh8DU5RV
+
+Note:
+    Very large mints may be rejected by `getTokenLargestAccounts` if the
+    upstream RPC would need to scan too many accounts.
 
 Uses (with `try/finally`):
     get_token_supply, get_token_largest_accounts.
@@ -22,6 +26,8 @@ from __future__ import annotations
 import argparse
 import sys
 
+import httpx
+
 from helius.solana_rpc import SolanaRpcClient
 
 
@@ -31,9 +37,10 @@ def main() -> int:
     args = parser.parse_args()
 
     client = SolanaRpcClient()
+    client._client.timeout = httpx.Timeout(30.0)
     try:
-        _ctx, supply = client.get_token_supply(args.mint)
-        _ctx, holders = client.get_token_largest_accounts(args.mint)
+        _ctx, supply = client.get_token_supply(mint_address=args.mint)
+        _ctx, holders = client.get_token_largest_accounts(mint=args.mint)
     finally:
         client.close()
 

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/transaction_inspector.py

@@ -7,7 +7,7 @@ involved, and any log messages emitted by the on-chain programs.
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/transaction_inspector.py <SIGNATURE>
+    python examples/solana_rpc/transaction_inspector.py <SIGNATURE>
 
 Uses (with `with`):
     get_transaction.
@@ -31,7 +31,7 @@ def main() -> int:
 
     with SolanaRpcClient() as helius:
         tx = helius.get_transaction(
-            args.signature,
+            transaction_signature=args.signature,
             encoding="jsonParsed",
             max_supported_transaction_version=0,
         )

{helius_python-0.3.3/examples → helius_python-0.3.4/examples/solana_rpc}/wallet_tracker.py

@@ -3,11 +3,11 @@
 Usage:
 
     export HELIUS_API_KEY=your_helius_api_key
-    python examples/wallet_tracker.py <WALLET_ADDRESS> [--limit 20]
+    python examples/solana_rpc/wallet_tracker.py <WALLET_ADDRESS> [--limit 20]
 
 Example (Helius's own treasury-ish address, replace with any):
 
-    python examples/wallet_tracker.py 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
+    python examples/solana_rpc/wallet_tracker.py 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
 
 It prints:
     - SOL balance (in SOL, not lamports)
@@ -43,7 +43,7 @@ def main() -> int:
 
     with SolanaRpcClient() as client:  # reads HELIUS_API_KEY from env / .env
         # --- SOL balance ---------------------------------------------------
-        _ctx, lamports = client.get_balance(args.address)
+        _ctx, lamports = client.get_balance(public_key=args.address)
         print(f"\n=== {args.address} ===\n")
         print(
             f"SOL balance: {lamports / LAMPORTS_PER_SOL:.9f} SOL "
@@ -75,7 +75,7 @@ def main() -> int:
             print("SPL token accounts: none with non-zero balance.\n")
 
         # --- Recent activity ----------------------------------------------
-        sigs = client.get_signatures_for_address(args.address, limit=args.limit)
+        sigs = client.get_signatures_for_address(address=args.address, limit=args.limit)
         print(f"Last {len(sigs)} signatures:")
         for sig in sigs:
             ts = (

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

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

helius_python-0.3.4/test_examples.py

@@ -0,0 +1,216 @@
+"""Run every example script with known-safe arguments.
+
+This is a live smoke-test runner, not a pytest test module. It intentionally
+executes the examples as subprocesses so imports, argument parsing, and runtime
+behavior match how users run them from the repository root.
+
+Usage:
+
+    .venv/bin/python test_examples.py
+
+The runner expects `HELIUS_API_KEY` to be available in the environment or in
+`.env`, matching the examples themselves. Some Helius endpoints are plan-gated
+or network-gated; those failures are reported as "external" instead of as
+example runtime bugs.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent
+PYTHONPATH = str(ROOT / "src")
+USE_COLOR = "NO_COLOR" not in os.environ
+
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+RED = "\033[31m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+SYSTEM_PROGRAM = "11111111111111111111111111111111"
+SMALL_MINT = "J5iyNuTa6zqqA62Xe4h1VBvcBW5CTSNNva3QPh8DU5RV"
+KNOWN_SIGNATURE = (
+    "eqRntqi1tjXv1zEGBM5btQGWoxWc73XXGDJXjxLE65Atj6T6qzNnJf5LyTbUoGXHS9TzeAnQniAre48SjcJft9f"
+)
+DEVNET_ADDRESS = "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
+
+
+@dataclass(frozen=True)
+class ExampleTest:
+    name: str
+    args: list[str]
+    timeout: int = 60
+    external_failure_markers: tuple[str, ...] = field(default_factory=tuple)
+
+
+TESTS = [
+    ExampleTest(
+        name="solana_rpc/address_transactions",
+        args=[
+            "examples/solana_rpc/address_transactions.py",
+            SYSTEM_PROGRAM,
+            "--limit",
+            "1",
+            "--dry-run",
+        ],
+    ),
+    ExampleTest(
+        name="solana_rpc/address_transfers",
+        args=[
+            "examples/solana_rpc/address_transfers.py",
+            SYSTEM_PROGRAM,
+            "--limit",
+            "1",
+            "--dry-run",
+        ],
+    ),
+    ExampleTest(
+        name="solana_rpc/block_explorer",
+        args=["examples/solana_rpc/block_explorer.py", "--slot", "423563000"],
+        timeout=90,
+    ),
+    ExampleTest(
+        name="solana_rpc/devnet_airdrop",
+        args=[
+            "examples/solana_rpc/devnet_airdrop.py",
+            DEVNET_ADDRESS,
+            "--sol",
+            "0.000000001",
+            "--timeout",
+            "5",
+            "--dry-run",
+        ],
+    ),
+    ExampleTest(
+        name="solana_rpc/network_status",
+        args=["examples/solana_rpc/network_status.py"],
+    ),
+    ExampleTest(
+        name="solana_rpc/priority_fees",
+        args=["examples/solana_rpc/priority_fees.py"],
+    ),
+    ExampleTest(
+        name="solana_rpc/stake_overview",
+        args=["examples/solana_rpc/stake_overview.py"],
+        timeout=120,
+    ),
+    ExampleTest(
+        name="solana_rpc/token_inspector",
+        args=["examples/solana_rpc/token_inspector.py", SMALL_MINT],
+        timeout=90,
+    ),
+    ExampleTest(
+        name="solana_rpc/transaction_inspector",
+        args=["examples/solana_rpc/transaction_inspector.py", KNOWN_SIGNATURE],
+        timeout=90,
+    ),
+    ExampleTest(
+        name="solana_rpc/wallet_tracker",
+        args=["examples/solana_rpc/wallet_tracker.py", SYSTEM_PROGRAM, "--limit", "1"],
+        timeout=120,
+    ),
+    ExampleTest(
+        name="laserstream/websocket_logs",
+        args=["examples/laserstream/websocket_logs.py", "--count", "1"],
+        timeout=45,
+        external_failure_markers=("TimeoutError: timed out", "403 Forbidden", "HTTP 403"),
+    ),
+]
+
+
+def color(text: str, ansi_color: str) -> str:
+    if not USE_COLOR:
+        return text
+    return f"{ansi_color}{text}{RESET}"
+
+
+def run_example(test: ExampleTest) -> tuple[str, str]:
+    env = os.environ.copy()
+    env["PYTHONPATH"] = (
+        f"{PYTHONPATH}{os.pathsep}{env['PYTHONPATH']}"
+        if env.get("PYTHONPATH")
+        else PYTHONPATH
+    )
+
+    command = [sys.executable, *test.args]
+    try:
+        result = subprocess.run(
+            command,
+            cwd=ROOT,
+            env=env,
+            text=True,
+            capture_output=True,
+            timeout=test.timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        output = (exc.stdout or "") + (exc.stderr or "")
+        return "external" if "websocket" in test.name else "failed", output
+
+    output = result.stdout + result.stderr
+    if result.returncode == 0:
+        return "passed", output
+    if any(marker in output for marker in test.external_failure_markers):
+        return "external", output
+    return "failed", output
+
+
+def main() -> int:
+    passed: list[str] = []
+    external: list[str] = []
+    failed: list[tuple[str, str]] = []
+
+    for test in TESTS:
+        print(f"\n=== {test.name} ===", flush=True)
+        status, output = run_example(test)
+        if status == "passed":
+            passed.append(test.name)
+            print(color("PASS", GREEN + BOLD))
+        elif status == "external":
+            external.append(test.name)
+            print(
+                color(
+                    "EXTERNAL",
+                    YELLOW + BOLD,
+                )
+                + ": endpoint, plan, or network prevented a live success"
+            )
+        else:
+            failed.append((test.name, output))
+            print(color("FAIL", RED + BOLD))
+
+        if output.strip():
+            lines = output.strip().splitlines()
+            preview = "\n".join(lines[:30])
+            if len(lines) > 30:
+                preview += f"\n... ({len(lines) - 30} more lines)"
+            print(preview)
+
+    print("\n=== Summary ===")
+    print(f"{color('Passed', GREEN)}   : {len(passed)}")
+    print(f"{color('External', YELLOW)} : {len(external)}")
+    print(f"{color('Failed', RED)}   : {len(failed)}")
+
+    if external:
+        print("\nExternal failures:")
+        for name in external:
+            print(f"  - {name}")
+
+    if failed:
+        print("\nUnexpected failures:")
+        for name, output in failed:
+            print(f"\n--- {name} ---")
+            print(output.strip())
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())