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

viper_execution-0.2.3/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: viper-execution
+Version: 0.2.3
+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.2.3/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.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viper-execution"
-version = "0.2.2"
+version = "0.2.3"
 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/PKG-INFO

@@ -1,183 +0,0 @@
-Metadata-Version: 2.4
-Name: viper-execution
-Version: 0.2.2
-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 :: 4 - Beta
-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.0` (beta). Ships the resilient WebSocket client and the resync REST-fetch mapping. The full typed REST client lands in a subsequent release. The SDK version is independent of the API version — this is SDK 0.x against API v1.
-
-## Install
-
-```bash
-pip install viper-execution
-```
-
-Requires Python ≥ 3.10.
-
-## Quickstart
-
-```python
-import os
-import asyncio
-from viper import ViperWSClient
-
-async def main():
-    # from_env() reads VIPER_API_KEY / VIPER_API_SECRET / VIPER_HANDLE /
-    # VIPER_WALLET. Pass anything explicitly to override the environment.
-    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
-
-`ViperWSClient` takes 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
-client = ViperWSClient.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
-client = ViperWSClient(
-    api_key_id=api_key_id,
-    api_secret=api_secret,
-    handle="your-handle",
-    wallet="0x...",
-    on_event=lambda f: print(f["channel"], f.get("event")),
-)
-```
-
-## 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 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 stream
-```
-
-### Live algo examples
-
-Two examples fire a real algo over the WebSocket command surface:
-
-```bash
-viper-examples start-glidemaker     # passive limit
-viper-examples start-pacemaker      # TWAP
-```
-
-These place **real orders on mainnet** (there is no testnet). Each one reads
-the live BTC mark from `/v1/instruments`, sizes the order to a USD notional,
-prints exactly what it is about to do with a short Ctrl-C abort window, fires
-once, streams the execution's frames (fills, slices, status), then cancels. 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/README.md

@@ -1,135 +0,0 @@
-# Viper Execution Python SDK
-
-Institutional-grade Python client for the [Viper Execution](https://viperexecution.com) trading API on Hyperliquid.
-
-> **Status:** SDK `0.2.0` (beta). Ships the resilient WebSocket client and the resync REST-fetch mapping. The full typed REST client lands in a subsequent release. The SDK version is independent of the API version — this is SDK 0.x against API v1.
-
-## Install
-
-```bash
-pip install viper-execution
-```
-
-Requires Python ≥ 3.10.
-
-## Quickstart
-
-```python
-import os
-import asyncio
-from viper import ViperWSClient
-
-async def main():
-    # from_env() reads VIPER_API_KEY / VIPER_API_SECRET / VIPER_HANDLE /
-    # VIPER_WALLET. Pass anything explicitly to override the environment.
-    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
-
-`ViperWSClient` takes 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
-client = ViperWSClient.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
-client = ViperWSClient(
-    api_key_id=api_key_id,
-    api_secret=api_secret,
-    handle="your-handle",
-    wallet="0x...",
-    on_event=lambda f: print(f["channel"], f.get("event")),
-)
-```
-
-## 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 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 stream
-```
-
-### Live algo examples
-
-Two examples fire a real algo over the WebSocket command surface:
-
-```bash
-viper-examples start-glidemaker     # passive limit
-viper-examples start-pacemaker      # TWAP
-```
-
-These place **real orders on mainnet** (there is no testnet). Each one reads
-the live BTC mark from `/v1/instruments`, sizes the order to a USD notional,
-prints exactly what it is about to do with a short Ctrl-C abort window, fires
-once, streams the execution's frames (fills, slices, status), then cancels. 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).