viper-execution 0.2.2__tar.gz → 0.3.0__tar.gz

{viper_execution-0.2.2 → viper_execution-0.3.0}/.gitignore

@@ -7,3 +7,5 @@ build/
 .venv/
 venv/
 .env
+
+*.zip

viper_execution-0.3.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: viper-execution
+Version: 0.3.0
+Summary: Institutional-grade Python SDK for the Viper Execution trading API on Hyperliquid.
+Project-URL: Homepage, https://viperexecution.com
+Project-URL: Documentation, https://docs.viperexecution.com
+Project-URL: Repository, https://github.com/viperexecution/viper-sdk-python
+Project-URL: Issues, https://github.com/viperexecution/viper-sdk-python/issues
+Author: Viper Execution
+License: MIT License
+        
+        Copyright (c) 2026 Viper Execution
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: algotrading,hyperliquid,trading,viper,websocket
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Viper Execution Python SDK
+
+Institutional-grade Python client for the [Viper Execution](https://viperexecution.com) trading API on Hyperliquid.
+
+> **Status:** SDK `0.2.x`. Ships a typed async REST client (`ViperRestClient`) and a resilient WebSocket client (`ViperWSClient`). The SDK version is independent of the API version — this is SDK 0.x against API v1.
+
+The SDK is a convenience layer over the raw HMAC + REST/WebSocket surface — never required. Every response is returned as a plain `dict`, so you are never boxed out of the raw payload; the typed signatures and `TypedDict` hints are there for editor and type-checker support only.
+
+## Install
+
+```bash
+pip install viper-execution
+```
+
+Requires Python ≥ 3.10.
+
+## Quickstart (REST)
+
+```python
+import asyncio
+from viper import ViperRestClient
+
+async def main():
+    # from_env() reads VIPER_API_KEY / VIPER_API_SECRET / VIPER_HANDLE /
+    # VIPER_WALLET. Pass anything explicitly to override the environment.
+    async with ViperRestClient.from_env() as viper:
+        # market data
+        btc = (await viper.instrument("BTC"))["instrument"]
+        print("BTC mark:", btc["mark_price"])
+
+        # launch a Glidemaker (idempotency key is auto-generated)
+        res = await viper.execute(
+            algo="glidemaker", symbol="BTC", side="buy", total_size=0.001,
+            params={"strategy": "neutral", "limit_price": 65000},
+        )
+        print(res["execution_id"], res["status"])
+
+asyncio.run(main())
+```
+
+## Quickstart (WebSocket)
+
+```python
+import os
+import asyncio
+from viper import ViperWSClient
+
+async def main():
+    wallet = os.environ["VIPER_WALLET"].lower()
+    client = ViperWSClient.from_env(
+        on_event=lambda f: print(f["channel"], f.get("event")),
+    )
+    await client.start()
+    await client.subscribe("account.state", wallet)
+    await asyncio.sleep(30)
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Using credentials
+
+Both clients take credentials two ways, both first-class — pick whichever fits how your process gets its secrets.
+
+**From the environment (quickest, and production-correct).** `from_env()` reads `VIPER_API_KEY`, `VIPER_API_SECRET`, `VIPER_HANDLE`, and `VIPER_WALLET`. This is also the right pattern for deployment: containers, CI, and secret managers all inject secrets as env vars, so the same code runs unchanged from laptop to production. Anything passed explicitly overrides the environment:
+
+```python
+viper = ViperRestClient.from_env(handle="override-handle")
+```
+
+**Explicitly (your own secret store).** If your keys live in Vault, AWS Secrets Manager, an HSM, or a config file, fetch them in your code and pass them to the constructor directly — `from_env()` is never required:
+
+```python
+api_key_id, api_secret = my_secret_store.get("viper")  # however you fetch them
+viper = ViperRestClient(
+    api_key_id=api_key_id,
+    api_secret=api_secret,
+    handle="your-handle",
+    wallet="0x...",
+)
+```
+
+`ViperWSClient` constructs identically.
+
+## Using the REST client
+
+`ViperRestClient` is async and instance-based (no global singleton). It covers the core trading surface: execute and executions, orders, account, positions, market data (instruments, price, orderbook), leverage, and limits.
+
+```python
+async with ViperRestClient.from_env() as viper:
+    # reads — return the raw dict as-is
+    state   = await viper.account_state()
+    pos     = await viper.positions()
+    price   = await viper.price("BTC")
+
+    # mutating calls auto-generate an Idempotency-Key and are throttled
+    order   = await viper.place_order(symbol="BTC", side="buy", size=0.001,
+                                      order_type="limit", price=60000, post_only=True)
+    await viper.cancel_order(symbol="BTC", order_id=order["order_ids"][0])
+```
+
+What the client handles for you:
+
+- **Signing** — HMAC-SHA256 over the canonical `{timestamp}{method}{path}{body}`, signed over the exact bytes sent. You never construct a signature.
+- **Idempotency** — every mutating call (`execute`, `place_order`, `cancel_*`, `modify_order`, `close_*`, execution lifecycle, `set_leverage`, `update_settings`, `nuke`) auto-generates an `Idempotency-Key` unless you pass one. Reads don't.
+- **Replay spacing** — a per-instance throttle keeps mutating calls ≥ 1.1s apart; reads are never blocked.
+- **Configurable transport** — inject your own `httpx.AsyncClient` via `http_client=...` to set timeouts, proxies, or pools.
+
+`nuke()` (cancel all orders + close all positions) requires `confirm=True` with no default — the conscious step the raw API gets from its mandatory `Idempotency-Key`, which the client otherwise fills for you.
+
+### Errors
+
+The API error envelope is mapped to typed exceptions, all subclasses of `ViperError`:
+
+| Exception | Maps from |
+|---|---|
+| `ViperValidationError` | `validation_error`, `bad_request`, `missing_field`, … (400/422) |
+| `ViperAuthError` | `unauthorized`, `insufficient_scope`, `forbidden`, `tenancy_denied` (401/403) |
+| `ViperConflictError` | `conflict`, `idempotency_mismatch`, `state_transition_forbidden` (409) |
+| `ViperNotFoundError` | `not_found`, `unknown_route`, `scope_not_found` (404) |
+| `ViperRateLimitError` | `rate_limited`, `venue_rate_limit` (429) — carries `retry_after` |
+| `ViperAPIError` | anything else |
+
+Every exception carries `.code` (the machine-readable error code), `.status`, and `.payload`, so you can branch precisely — e.g. tell a state `conflict` from an `idempotency_mismatch`:
+
+```python
+from viper import ViperConflictError
+
+try:
+    await viper.execute(algo="glidemaker", symbol="BTC", side="buy",
+                        total_size=0.001, params={"strategy": "neutral"})
+except ViperConflictError as e:
+    if e.code == "idempotency_mismatch":
+        ...  # reused key with a different body — a client bug
+```
+
+## Runnable examples
+
+Examples ship inside the package — no extra downloads. List the catalog and
+run one by name or number:
+
+```bash
+viper-examples                          # list the catalog
+viper-examples stream-account-state     # run by name
+viper-examples 01                       # ...or by number
+```
+
+Set the env vars the examples read — bash/zsh:
+
+```bash
+export VIPER_API_KEY=vk_...
+export VIPER_API_SECRET=vs_...
+export VIPER_HANDLE=your-handle     # optional
+export VIPER_WALLET=0x...           # the wallet to trade/stream
+```
+
+…or PowerShell:
+
+```powershell
+$env:VIPER_API_KEY = "vk_..."
+$env:VIPER_API_SECRET = "vs_..."
+$env:VIPER_HANDLE = "your-handle"   # optional
+$env:VIPER_WALLET = "0x..."         # the wallet to trade/stream
+```
+
+### Live algo examples
+
+Several examples fire a real algo. They place **real orders on mainnet** (there
+is no testnet). Each reads the live BTC mark, sizes to a USD notional (default
+~$250), discloses exactly what it will do with a short Ctrl-C abort window, fires
+**once**, observes, then cancels.
+
+Over the WebSocket command surface:
+
+```bash
+viper-examples start-glidemaker     # passive limit
+viper-examples start-pacemaker      # TWAP
+```
+
+Over the REST client:
+
+```bash
+viper-examples detect-and-fire-glidemaker   # poll a signal, then fire on it
+viper-examples start-ghostsweep             # hidden stop
+viper-examples start-flowscale              # scaled ladder
+viper-examples start-flowband               # floating stealth scale
+viper-examples smart-exit                   # reduce-only stop on an existing long
+```
+
+Optional knobs:
+
+```bash
+export VIPER_EXAMPLE_USD=250         # target notional (default 250)
+export VIPER_EXAMPLE_OBSERVE_S=10    # seconds to observe before cancel (default 10)
+export VIPER_EXAMPLE_NO_CANCEL=1     # leave the execution running instead of cancelling
+```
+
+The source for each example lives in
+[`src/viper/examples/`](src/viper/examples/).
+
+## What the WebSocket client handles for you
+
+The `/v1/ws` stream has a number of behaviors a naive client gets wrong. `ViperWSClient` handles them as a built-in contract:
+
+- **Liveness** — transport ping/pong plus a data-staleness watchdog; silent half-open connections are detected and reconnected.
+- **Reconnect with resume** — on drop, it reconnects with exponential backoff and resubscribes every scope carrying its `last_seq` cursor, so you resume exactly where you left off (replay from the per-scope ring buffer).
+- **Resync recovery** — when the server can't satisfy a cursor (`buffer_overflow` / `last_seq_ahead_of_server` / `scope_not_found`), it REST-fetches authoritative current state and resubscribes fresh.
+- **Multi-wallet attribution** — every data frame is routed by `data.wallet`, so one socket can carry many wallets without cross-attribution. (Control markers such as `hydrated` carry no `data.wallet`; route those by `scope_id`.)
+- **Slow hydration** — `account.state` hydration is server-slow (~5s; it gathers balance + HIP-3 collateral across all dexes, then bursts frames). The client does not mistake that for a dead stream, and neither should your application logic.
+- **Terminal conditions** — credential revocation (close `4013`), a handshake auth rejection (HTTP `401`/`403` — revoked/invalid key or insufficient scope), or an exhausted reconnect budget all stop the loop permanently via `on_terminal` rather than reconnect-hammering.
+
+## Callbacks
+
+| Callback | Fires on |
+|---|---|
+| `on_event(frame)` | Every classified data frame (the main path) |
+| `on_meta(frame)` | `_meta` frames: welcome + upstream connectivity events |
+| `on_terminal(code)` | Terminal stop. `code` is the WS close code (`4013` = credentials revoked), the handshake HTTP status (`401`/`403`), or `-1` (reconnect budget exhausted) |
+| `on_command_result(frame)` | Subscribe acks / command errors (no correlation id) |
+| `on_raw(frame)` | Optional advanced tap: every frame pre-classification (audit/metrics) |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

viper_execution-0.3.0/README.md

@@ -0,0 +1,224 @@
+# Viper Execution Python SDK
+
+Institutional-grade Python client for the [Viper Execution](https://viperexecution.com) trading API on Hyperliquid.
+
+> **Status:** SDK `0.2.x`. Ships a typed async REST client (`ViperRestClient`) and a resilient WebSocket client (`ViperWSClient`). The SDK version is independent of the API version — this is SDK 0.x against API v1.
+
+The SDK is a convenience layer over the raw HMAC + REST/WebSocket surface — never required. Every response is returned as a plain `dict`, so you are never boxed out of the raw payload; the typed signatures and `TypedDict` hints are there for editor and type-checker support only.
+
+## Install
+
+```bash
+pip install viper-execution
+```
+
+Requires Python ≥ 3.10.
+
+## Quickstart (REST)
+
+```python
+import asyncio
+from viper import ViperRestClient
+
+async def main():
+    # from_env() reads VIPER_API_KEY / VIPER_API_SECRET / VIPER_HANDLE /
+    # VIPER_WALLET. Pass anything explicitly to override the environment.
+    async with ViperRestClient.from_env() as viper:
+        # market data
+        btc = (await viper.instrument("BTC"))["instrument"]
+        print("BTC mark:", btc["mark_price"])
+
+        # launch a Glidemaker (idempotency key is auto-generated)
+        res = await viper.execute(
+            algo="glidemaker", symbol="BTC", side="buy", total_size=0.001,
+            params={"strategy": "neutral", "limit_price": 65000},
+        )
+        print(res["execution_id"], res["status"])
+
+asyncio.run(main())
+```
+
+## Quickstart (WebSocket)
+
+```python
+import os
+import asyncio
+from viper import ViperWSClient
+
+async def main():
+    wallet = os.environ["VIPER_WALLET"].lower()
+    client = ViperWSClient.from_env(
+        on_event=lambda f: print(f["channel"], f.get("event")),
+    )
+    await client.start()
+    await client.subscribe("account.state", wallet)
+    await asyncio.sleep(30)
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Using credentials
+
+Both clients take credentials two ways, both first-class — pick whichever fits how your process gets its secrets.
+
+**From the environment (quickest, and production-correct).** `from_env()` reads `VIPER_API_KEY`, `VIPER_API_SECRET`, `VIPER_HANDLE`, and `VIPER_WALLET`. This is also the right pattern for deployment: containers, CI, and secret managers all inject secrets as env vars, so the same code runs unchanged from laptop to production. Anything passed explicitly overrides the environment:
+
+```python
+viper = ViperRestClient.from_env(handle="override-handle")
+```
+
+**Explicitly (your own secret store).** If your keys live in Vault, AWS Secrets Manager, an HSM, or a config file, fetch them in your code and pass them to the constructor directly — `from_env()` is never required:
+
+```python
+api_key_id, api_secret = my_secret_store.get("viper")  # however you fetch them
+viper = ViperRestClient(
+    api_key_id=api_key_id,
+    api_secret=api_secret,
+    handle="your-handle",
+    wallet="0x...",
+)
+```
+
+`ViperWSClient` constructs identically.
+
+## Using the REST client
+
+`ViperRestClient` is async and instance-based (no global singleton). It covers the core trading surface: execute and executions, orders, account, positions, market data (instruments, price, orderbook), leverage, and limits.
+
+```python
+async with ViperRestClient.from_env() as viper:
+    # reads — return the raw dict as-is
+    state   = await viper.account_state()
+    pos     = await viper.positions()
+    price   = await viper.price("BTC")
+
+    # mutating calls auto-generate an Idempotency-Key and are throttled
+    order   = await viper.place_order(symbol="BTC", side="buy", size=0.001,
+                                      order_type="limit", price=60000, post_only=True)
+    await viper.cancel_order(symbol="BTC", order_id=order["order_ids"][0])
+```
+
+What the client handles for you:
+
+- **Signing** — HMAC-SHA256 over the canonical `{timestamp}{method}{path}{body}`, signed over the exact bytes sent. You never construct a signature.
+- **Idempotency** — every mutating call (`execute`, `place_order`, `cancel_*`, `modify_order`, `close_*`, execution lifecycle, `set_leverage`, `update_settings`, `nuke`) auto-generates an `Idempotency-Key` unless you pass one. Reads don't.
+- **Replay spacing** — a per-instance throttle keeps mutating calls ≥ 1.1s apart; reads are never blocked.
+- **Configurable transport** — inject your own `httpx.AsyncClient` via `http_client=...` to set timeouts, proxies, or pools.
+
+`nuke()` (cancel all orders + close all positions) requires `confirm=True` with no default — the conscious step the raw API gets from its mandatory `Idempotency-Key`, which the client otherwise fills for you.
+
+### Errors
+
+The API error envelope is mapped to typed exceptions, all subclasses of `ViperError`:
+
+| Exception | Maps from |
+|---|---|
+| `ViperValidationError` | `validation_error`, `bad_request`, `missing_field`, … (400/422) |
+| `ViperAuthError` | `unauthorized`, `insufficient_scope`, `forbidden`, `tenancy_denied` (401/403) |
+| `ViperConflictError` | `conflict`, `idempotency_mismatch`, `state_transition_forbidden` (409) |
+| `ViperNotFoundError` | `not_found`, `unknown_route`, `scope_not_found` (404) |
+| `ViperRateLimitError` | `rate_limited`, `venue_rate_limit` (429) — carries `retry_after` |
+| `ViperAPIError` | anything else |
+
+Every exception carries `.code` (the machine-readable error code), `.status`, and `.payload`, so you can branch precisely — e.g. tell a state `conflict` from an `idempotency_mismatch`:
+
+```python
+from viper import ViperConflictError
+
+try:
+    await viper.execute(algo="glidemaker", symbol="BTC", side="buy",
+                        total_size=0.001, params={"strategy": "neutral"})
+except ViperConflictError as e:
+    if e.code == "idempotency_mismatch":
+        ...  # reused key with a different body — a client bug
+```
+
+## Runnable examples
+
+Examples ship inside the package — no extra downloads. List the catalog and
+run one by name or number:
+
+```bash
+viper-examples                          # list the catalog
+viper-examples stream-account-state     # run by name
+viper-examples 01                       # ...or by number
+```
+
+Set the env vars the examples read — bash/zsh:
+
+```bash
+export VIPER_API_KEY=vk_...
+export VIPER_API_SECRET=vs_...
+export VIPER_HANDLE=your-handle     # optional
+export VIPER_WALLET=0x...           # the wallet to trade/stream
+```
+
+…or PowerShell:
+
+```powershell
+$env:VIPER_API_KEY = "vk_..."
+$env:VIPER_API_SECRET = "vs_..."
+$env:VIPER_HANDLE = "your-handle"   # optional
+$env:VIPER_WALLET = "0x..."         # the wallet to trade/stream
+```
+
+### Live algo examples
+
+Several examples fire a real algo. They place **real orders on mainnet** (there
+is no testnet). Each reads the live BTC mark, sizes to a USD notional (default
+~$250), discloses exactly what it will do with a short Ctrl-C abort window, fires
+**once**, observes, then cancels.
+
+Over the WebSocket command surface:
+
+```bash
+viper-examples start-glidemaker     # passive limit
+viper-examples start-pacemaker      # TWAP
+```
+
+Over the REST client:
+
+```bash
+viper-examples detect-and-fire-glidemaker   # poll a signal, then fire on it
+viper-examples start-ghostsweep             # hidden stop
+viper-examples start-flowscale              # scaled ladder
+viper-examples start-flowband               # floating stealth scale
+viper-examples smart-exit                   # reduce-only stop on an existing long
+```
+
+Optional knobs:
+
+```bash
+export VIPER_EXAMPLE_USD=250         # target notional (default 250)
+export VIPER_EXAMPLE_OBSERVE_S=10    # seconds to observe before cancel (default 10)
+export VIPER_EXAMPLE_NO_CANCEL=1     # leave the execution running instead of cancelling
+```
+
+The source for each example lives in
+[`src/viper/examples/`](src/viper/examples/).
+
+## What the WebSocket client handles for you
+
+The `/v1/ws` stream has a number of behaviors a naive client gets wrong. `ViperWSClient` handles them as a built-in contract:
+
+- **Liveness** — transport ping/pong plus a data-staleness watchdog; silent half-open connections are detected and reconnected.
+- **Reconnect with resume** — on drop, it reconnects with exponential backoff and resubscribes every scope carrying its `last_seq` cursor, so you resume exactly where you left off (replay from the per-scope ring buffer).
+- **Resync recovery** — when the server can't satisfy a cursor (`buffer_overflow` / `last_seq_ahead_of_server` / `scope_not_found`), it REST-fetches authoritative current state and resubscribes fresh.
+- **Multi-wallet attribution** — every data frame is routed by `data.wallet`, so one socket can carry many wallets without cross-attribution. (Control markers such as `hydrated` carry no `data.wallet`; route those by `scope_id`.)
+- **Slow hydration** — `account.state` hydration is server-slow (~5s; it gathers balance + HIP-3 collateral across all dexes, then bursts frames). The client does not mistake that for a dead stream, and neither should your application logic.
+- **Terminal conditions** — credential revocation (close `4013`), a handshake auth rejection (HTTP `401`/`403` — revoked/invalid key or insufficient scope), or an exhausted reconnect budget all stop the loop permanently via `on_terminal` rather than reconnect-hammering.
+
+## Callbacks
+
+| Callback | Fires on |
+|---|---|
+| `on_event(frame)` | Every classified data frame (the main path) |
+| `on_meta(frame)` | `_meta` frames: welcome + upstream connectivity events |
+| `on_terminal(code)` | Terminal stop. `code` is the WS close code (`4013` = credentials revoked), the handshake HTTP status (`401`/`403`), or `-1` (reconnect budget exhausted) |
+| `on_command_result(frame)` | Subscribe acks / command errors (no correlation id) |
+| `on_raw(frame)` | Optional advanced tap: every frame pre-classification (audit/metrics) |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{viper_execution-0.2.2 → viper_execution-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viper-execution"
-version = "0.2.2"
+version = "0.3.0"
 description = "Institutional-grade Python SDK for the Viper Execution trading API on Hyperliquid."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ license = { file = "LICENSE" }
 authors = [{ name = "Viper Execution" }]
 keywords = ["viper", "hyperliquid", "trading", "algotrading", "websocket"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "License :: OSI Approved :: MIT License",
     "Intended Audience :: Financial and Insurance Industry",
     "Programming Language :: Python :: 3",

{viper_execution-0.2.2 → viper_execution-0.3.0}/src/viper/examples/__init__.py

@@ -38,7 +38,7 @@ _ENV_VARS = [
 ]
 
 
-def _discover() -> List[Tuple[str, str, int, str]]:
+def _discover() -> List[Tuple[str, str, int, str, str]]:
     """Return [(slug, module_name, order, description), ...] sorted by order."""
     found = []
     for info in pkgutil.iter_modules(__path__):
@@ -49,13 +49,15 @@ def _discover() -> List[Tuple[str, str, int, str]]:
         if not hasattr(mod, "main") or not hasattr(mod, "DESCRIPTION"):
             continue
         order = int(getattr(mod, "ORDER", 999))
+        kind = str(getattr(mod, "KIND", "rest")).lower()
+        section = str(getattr(mod, "SECTION", "Other"))
         slug = name.replace("_", "-")
-        found.append((slug, name, order, str(mod.DESCRIPTION)))
+        found.append((slug, name, order, str(mod.DESCRIPTION), kind, section))
     found.sort(key=lambda r: (r[2], r[0]))
     return found
 
 
-def list_examples() -> List[Tuple[str, str, int, str]]:
+def list_examples() -> List[Tuple[str, str, int, str, str]]:
     """Public helper: the discovered example catalog."""
     return _discover()
 
@@ -63,7 +65,7 @@ def list_examples() -> List[Tuple[str, str, int, str]]:
 def _resolve(token: str, catalog) -> str | None:
     """Map a user token (slug, module name, or order number) to a module name."""
     t = token.strip().lower().replace("_", "-")
-    for slug, mod_name, order, _desc in catalog:
+    for slug, mod_name, order, _desc, _kind, _section in catalog:
         if t == slug or t == mod_name.replace("_", "-"):
             return mod_name
         if t.lstrip("0") == str(order) or t == f"{order:02d}":
@@ -88,6 +90,18 @@ def _print_env_setup() -> None:
             print(f'    export {name}="{val}"')
 
 
+# Section display order for the catalog listing. Sections not listed here are
+# appended afterward (alphabetically) under their own header.
+_SECTION_ORDER = [
+    "Getting Started",
+    "Algorithms",
+    "Account & Market Data",
+    "Monitors",
+    "Streaming (WebSocket reads)",
+    "Trading over WebSocket (Tier-3 writes)",
+]
+
+
 def _print_catalog(catalog) -> None:
     print("Viper SDK — Examples")
     print("====================")
@@ -96,10 +110,19 @@ def _print_catalog(catalog) -> None:
     if not catalog:
         print("  (no examples found)")
     else:
-        print("Available examples:")
         width = max(len(s) for s, *_ in catalog)
-        for slug, _mod, order, desc in catalog:
-            print(f"  {order:02d}  {slug.ljust(width)}   {desc}")
+        # Group by section, ordered by _SECTION_ORDER (others appended A-Z).
+        by_section = {}
+        for row in catalog:
+            by_section.setdefault(row[5], []).append(row)
+        ordered = [s for s in _SECTION_ORDER if s in by_section]
+        ordered += sorted(s for s in by_section if s not in _SECTION_ORDER)
+        for sec in ordered:
+            print(f"\n{sec}")
+            print("  " + "-" * len(sec))
+            for slug, _mod, order, desc, kind, _section in by_section[sec]:
+                tag = "[WS]  " if kind == "ws" else "[REST]"
+                print(f"  {order:02d}  {tag}  {slug.ljust(width)}   {desc}")
     print()
     _print_env_setup()
     print()