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

viper_execution-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # full history + main, so the guard can compare the tag to main's tip
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Release guard. The publish job (needs: build) runs only if this passes,
+      # so a tag failing either check never reaches PyPI, where versions are
+      # immutable. Two checks:
+      #   1. Tag name matches the pyproject version.
+      #   2. Tag commit is the tip of main. A version comparison alone is
+      #      insufficient: a tag can reference a commit behind main while the
+      #      version string is unchanged, so commit identity is compared directly.
+      - name: Validate release tag
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"
+          VER="v$(grep -E '^version *= *"' pyproject.toml | head -1 | sed -E 's/.*"([^"]+)".*/\1/')"
+          echo "tag=$TAG  pyproject=$VER"
+          if [ "$TAG" != "$VER" ]; then
+            echo "::error::Tag $TAG does not match pyproject version $VER."
+            exit 1
+          fi
+          git fetch --quiet origin main
+          TAG_SHA="$(git rev-parse HEAD)"
+          MAIN_SHA="$(git rev-parse origin/main)"
+          echo "tag_sha=$TAG_SHA  main_sha=$MAIN_SHA"
+          if [ "$TAG_SHA" != "$MAIN_SHA" ]; then
+            echo "::error::Tag commit is not the tip of main. Re-point the tag to main before releasing."
+            exit 1
+          fi
+          echo "Release tag validated: $TAG at $TAG_SHA"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Verify metadata
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

{viper_execution-0.2.0 → viper_execution-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: viper-execution
-Version: 0.2.0
+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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viper-execution"
-version = "0.2.0"
+version = "0.2.2"
 description = "Institutional-grade Python SDK for the Viper Execution trading API on Hyperliquid."
 readme = "README.md"
 requires-python = ">=3.10"

viper_execution-0.2.2/src/viper/examples/_algo_rest_common.py

@@ -0,0 +1,123 @@
+"""
+Shared REST launch flow for the price-level algo examples (GhostSweep,
+FlowScale, FlowBand). NOT discovered as an example itself (leading underscore).
+
+run_buy_algo does, in order:
+  1. Read live BTC mark + sizing fields via rest.instrument("BTC").
+  2. Size to a USD notional (default $250), floored to the instrument's lot.
+  3. Build the algo's params from the live mark (per-algo callback).
+  4. Disclose exactly what will be sent, with a Ctrl-C abort window (nothing
+     sent yet).
+  5. Fire EXACTLY ONCE via rest.execute(...) — one idempotency key up front.
+  6. Poll rest.execution(id) for status, then cancel unless told otherwise.
+
+These place REAL orders on mainnet. There is no testnet. The default params
+arm each algo away from the market (a few % out), so within the short observe
+window they rest rather than fill — then get cancelled.
+
+Env: VIPER_API_KEY, VIPER_API_SECRET, VIPER_HANDLE, VIPER_WALLET (required);
+     VIPER_EXAMPLE_USD (250), VIPER_EXAMPLE_ABORT_S (3),
+     VIPER_EXAMPLE_OBSERVE_S (10), VIPER_EXAMPLE_POLL_S (2.0),
+     VIPER_EXAMPLE_NO_CANCEL (set to leave it running).
+"""
+from __future__ import annotations
+
+import os
+import math
+import uuid
+import asyncio
+from typing import Callable, Optional
+
+from viper import ViperRestClient, ViperError
+
+SYMBOL = "BTC"
+USD = float(os.environ.get("VIPER_EXAMPLE_USD", "250"))
+ABORT_S = float(os.environ.get("VIPER_EXAMPLE_ABORT_S", "3"))
+OBSERVE_S = float(os.environ.get("VIPER_EXAMPLE_OBSERVE_S", "10"))
+POLL_S = float(os.environ.get("VIPER_EXAMPLE_POLL_S", "2.0"))
+NO_CANCEL = bool(os.environ.get("VIPER_EXAMPLE_NO_CANCEL"))
+
+
+def require_env() -> None:
+    missing = [k for k in ("VIPER_API_KEY", "VIPER_API_SECRET") if not os.environ.get(k)]
+    if missing:
+        raise SystemExit(f"# missing required env: {', '.join(missing)}")
+    if not os.environ.get("VIPER_WALLET"):
+        print("# note: VIPER_WALLET not set — the resolved wallet comes from your handle.")
+
+
+def compute_size(usd: float, mark: float, sz_decimals: int, min_size: float) -> float:
+    """USD notional -> base size, floored to the instrument's lot, min-clamped."""
+    q = 10 ** int(sz_decimals)
+    sized = math.floor((usd / mark) * q) / q
+    if min_size and sized < min_size:
+        sized = min_size
+    return sized
+
+
+async def instrument_mark(rest: ViperRestClient) -> tuple:
+    """Return (mark, sz_decimals, min_order_value_size) for BTC."""
+    rec = (await rest.instrument(SYMBOL))["instrument"]
+    return (float(rec["mark_price"]), int(rec.get("sz_decimals", 5)),
+            float(rec.get("min_order_value_size") or 0.0))
+
+
+async def poll_and_cancel(rest: ViperRestClient, exec_id: str, label: str) -> None:
+    """Poll execution status for the observe window, then cancel (unless
+    VIPER_EXAMPLE_NO_CANCEL). Status/fill live under the `state` object."""
+    deadline = asyncio.get_event_loop().time() + OBSERVE_S
+    while asyncio.get_event_loop().time() < deadline:
+        await asyncio.sleep(max(2.0, POLL_S))
+        try:
+            st = await rest.execution(exec_id)
+        except ViperError as e:
+            print(f"#   status poll failed: {type(e).__name__} code={e.code}")
+            break
+        state = st.get("state") or {}
+        print(f"#   status={state.get('status')} "
+              f"filled={state.get('filled_size')}/{state.get('total_size')} "
+              f"({state.get('filled_pct')}%)")
+    if NO_CANCEL:
+        print(f"# VIPER_EXAMPLE_NO_CANCEL set — leaving {exec_id} running.")
+    else:
+        try:
+            c = await rest.cancel_execution(exec_id)
+            print(f"# {label}: cancel -> {c.get('status') or c.get('result') or 'ok'}")
+        except ViperError as e:
+            print(f"# cancel failed: {type(e).__name__} code={e.code}")
+
+
+async def run_buy_algo(*, algo: str, build_params: Callable[[float], dict],
+                       label: str) -> None:
+    """Size off live mark, disclose + abort window, fire one buy via REST, poll,
+    cancel. `build_params(mark)` returns the per-algo params dict."""
+    require_env()
+    rest = ViperRestClient.from_env()
+    async with rest:
+        mark, sz_decimals, min_size = await instrument_mark(rest)
+        size = compute_size(USD, mark, sz_decimals, min_size)
+        params = build_params(mark)
+
+        print(f"# {label}: LIVE buy {size} {SYMBOL} (~${USD:.0f} at mark {mark}) "
+              f"on MAINNET — this places a real order.")
+        print(f"#   params={params}")
+        print(f"# Ctrl-C within {ABORT_S:.0f}s to abort (nothing sent yet)...")
+        try:
+            await asyncio.sleep(ABORT_S)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            print("\n# aborted — nothing was sent.")
+            return
+
+        idem = uuid.uuid4().hex
+        try:
+            res = await rest.execute(algo=algo, symbol=SYMBOL, side="buy",
+                                     total_size=size, params=params,
+                                     idempotency_key=idem)
+        except ViperError as e:
+            print(f"# execute failed: {type(e).__name__} code={e.code} status={e.status}")
+            return
+
+        exec_id = res.get("execution_id") or res.get("id")
+        print(f"# {label}: launched execution_id={exec_id} status={res.get('status')}")
+        if exec_id:
+            await poll_and_cancel(rest, exec_id, label)

{viper_execution-0.2.0 → viper_execution-0.2.2}/src/viper/examples/detect_and_fire_glidemaker.py

@@ -101,11 +101,12 @@ async def main():
     _require_env()
     rest = ViperRestClient.from_env()
     async with rest:
-        # 1) size off the live instrument
-        inst = await rest.instrument(SYMBOL)
-        mark = float(inst["mark_price"])
-        size = _compute_size(USD, mark, inst.get("sz_decimals", 5),
-                             float(inst.get("min_order_value_size") or 0))
+        # 1) size off the live instrument. GET /v1/instruments/{symbol} wraps the
+        #    record under "instrument" (alongside a validation_example).
+        rec = (await rest.instrument(SYMBOL))["instrument"]
+        mark = float(rec["mark_price"])
+        size = _compute_size(USD, mark, rec.get("sz_decimals", 5),
+                             float(rec.get("min_order_value_size") or 0))
 
         # 2) watch for the signal
         if not await _detect_signal(rest):
@@ -149,8 +150,10 @@ async def main():
                 except ViperError as e:
                     print(f"#   status poll failed: {type(e).__name__} code={e.code}")
                     break
-                print(f"#   execution status={st.get('status')} "
-                      f"filled={st.get('filled_size')}/{st.get('total_size')}")
+                state = st.get("state") or {}
+                print(f"#   execution status={state.get('status')} "
+                      f"filled={state.get('filled_size')}/{state.get('total_size')} "
+                      f"({state.get('filled_pct')}%) maker={state.get('maker_fill_size')}")
             if NO_CANCEL:
                 print(f"# VIPER_EXAMPLE_NO_CANCEL set — leaving {exec_id} running.")
             else:

viper_execution-0.2.2/src/viper/examples/smart_exit.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Fire Smart Exit (conditional reduce-only exit) on an existing BTC long — REST,
+live mainnet.
+
+Smart Exit is a reduce-only stop: for a SELL exit it fires when ask < limit_price.
+This example finds your existing BTC long, arms a sell-stop 5% BELOW mark (so it
+rests as protection and does NOT fire within the observe window), then cancels.
+reduce_only is forced by the algo — the request does not declare it.
+
+Smart Exit exits a position; it does not open one. If you have no BTC long, the
+example tells you and exits without firing. Open a small long (~$250) first, then
+re-run. There is no testnet.
+
+Env: VIPER_API_KEY, VIPER_API_SECRET, VIPER_HANDLE, VIPER_WALLET (+ optional
+VIPER_EXAMPLE_OBSERVE_S / _NO_CANCEL). Run:
+    viper-examples smart-exit
+"""
+import uuid
+import asyncio
+
+from viper import ViperRestClient, ViperError
+from viper.examples._algo_rest_common import (
+    require_env, instrument_mark, poll_and_cancel, ABORT_S, SYMBOL,
+)
+
+ORDER = 8
+DESCRIPTION = "Arm Smart Exit (reduce-only stop) on an existing BTC long over REST — live, auto-cancels."
+
+
+def _find_long(positions: dict):
+    """Return the signed size of the BTC long, or None. size>0 is long."""
+    for p in (positions or {}).get("items", []):
+        if str(p.get("symbol", "")).upper() == SYMBOL:
+            size = float(p.get("size") or 0)
+            if size > 0:
+                return size
+    return None
+
+
+async def main():
+    require_env()
+    rest = ViperRestClient.from_env()
+    async with rest:
+        long_size = _find_long(await rest.positions())
+        if not long_size:
+            print(f"# Smart Exit exits an existing {SYMBOL} long; none found.")
+            print(f"# Open a small {SYMBOL} long (~$250) first, then re-run.")
+            return
+
+        mark, _, _ = await instrument_mark(rest)
+        # SELL exit fires when ask < limit_price; 5% below mark -> arms as a
+        # stop, won't fire now.
+        limit_price = round(mark * 0.95)
+        params = {"strategy": "neutral", "limit_price": limit_price}
+
+        print(f"# Smart Exit: LIVE reduce-only sell-stop on {long_size} {SYMBOL} "
+              f"long — limit {limit_price} (~5% below mark {mark}).")
+        print(f"#   params={params}")
+        print(f"# Ctrl-C within {ABORT_S:.0f}s to abort (nothing sent yet)...")
+        try:
+            await asyncio.sleep(ABORT_S)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            print("\n# aborted — nothing was sent.")
+            return
+
+        idem = uuid.uuid4().hex
+        try:
+            # No reduce_only kwarg: Smart Exit forces it at the algo layer, and
+            # the request schema rejects a declared reduce_only.
+            res = await rest.execute(algo="smart_exit", symbol=SYMBOL, side="sell",
+                                     total_size=long_size, params=params,
+                                     idempotency_key=idem)
+        except ViperError as e:
+            print(f"# execute failed: {type(e).__name__} code={e.code} status={e.status}")
+            return
+
+        exec_id = res.get("execution_id") or res.get("id")
+        print(f"# Smart Exit: launched execution_id={exec_id} status={res.get('status')}")
+        if exec_id:
+            await poll_and_cancel(rest, exec_id, "Smart Exit")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

viper_execution-0.2.2/src/viper/examples/start_flowband.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+Fire FlowBand (floating stealth scale) on BTC over REST — live mainnet.
+
+FlowBand floats a stealth scale of levels across a percentage band. This example
+uses a 0.5%-2% band (the required range params); for a BUY the levels rest below
+market and won't fully fill in the short observe window, then get cancelled.
+Places real orders (~$250 total). There is no testnet.
+
+Env: VIPER_API_KEY, VIPER_API_SECRET, VIPER_HANDLE, VIPER_WALLET (+ optional
+VIPER_EXAMPLE_USD / _OBSERVE_S / _NO_CANCEL). Run:
+    viper-examples start-flowband
+"""
+import asyncio
+
+from viper.examples._algo_rest_common import run_buy_algo
+
+ORDER = 7
+DESCRIPTION = "Fire FlowBand (floating stealth scale) on BTC over REST — live ~$250, auto-cancels."
+
+
+def _params(mark: float) -> dict:
+    # required percentage band; num_levels/flow_band/bias take server defaults.
+    return {"range_from_pct": 0.5, "range_to_pct": 2.0}
+
+
+async def main():
+    await run_buy_algo(algo="flowband", build_params=_params, label="FlowBand")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

viper_execution-0.2.2/src/viper/examples/start_flowscale.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+Fire FlowScale (scaled ladder) on BTC over REST — live mainnet.
+
+FlowScale lays a scaled ladder of clips across a percentage band relative to the
+market. This example uses a 0.5%-2% band with the minimum 5 clips; for a BUY the
+ladder rests below market and won't fully fill in the short observe window, then
+gets cancelled. Places real orders (~$250 total). There is no testnet.
+
+Env: VIPER_API_KEY, VIPER_API_SECRET, VIPER_HANDLE, VIPER_WALLET (+ optional
+VIPER_EXAMPLE_USD / _OBSERVE_S / _NO_CANCEL). Run:
+    viper-examples start-flowscale
+"""
+import asyncio
+
+from viper.examples._algo_rest_common import run_buy_algo
+
+ORDER = 6
+DESCRIPTION = "Fire FlowScale (scaled ladder) on BTC over REST — live ~$250, auto-cancels."
+
+
+def _params(mark: float) -> dict:
+    # scaled ladder 0.5%-2% out, 5 clips (the minimum). pct band -> no absolute price.
+    return {"range_from_pct": 0.5, "range_to_pct": 2.0, "num_clips": 5}
+
+
+async def main():
+    await run_buy_algo(algo="flowscale", build_params=_params, label="FlowScale")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

viper_execution-0.2.2/src/viper/examples/start_ghostsweep.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+Fire GhostSweep (hidden stop/take) on BTC over REST — live mainnet.
+
+GhostSweep arms a hidden sweep at a trigger price. For a BUY it activates when
+ask <= trigger_price, so this example sets trigger 5% BELOW mark: the sweep arms
+as a hidden buy-stop on a dip and does NOT fire within the observe window, then
+gets cancelled. Places a real order (~$250). There is no testnet.
+
+Env: VIPER_API_KEY, VIPER_API_SECRET, VIPER_HANDLE, VIPER_WALLET (+ optional
+VIPER_EXAMPLE_USD / _OBSERVE_S / _NO_CANCEL). Run:
+    viper-examples start-ghostsweep
+"""
+import asyncio
+
+from viper.examples._algo_rest_common import run_buy_algo
+
+ORDER = 5
+DESCRIPTION = "Fire GhostSweep (hidden stop) on BTC over REST — live ~$250, auto-cancels."
+
+
+def _params(mark: float) -> dict:
+    # BUY sweep arms when ask <= trigger_price; 5% below mark -> arms, won't fire now.
+    return {"strategy": "neutral", "trigger_price": round(mark * 0.95)}
+
+
+async def main():
+    await run_buy_algo(algo="ghostsweep", build_params=_params, label="GhostSweep")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

viper_execution-0.2.0/.github/workflows/release.yml

@@ -1,43 +0,0 @@
-name: release
-
-on:
-  push:
-    tags:
-      - "v*"
-
-jobs:
-  build:
-    name: Build distribution
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - name: Build sdist and wheel
-        run: |
-          python -m pip install --upgrade build
-          python -m build
-      - name: Verify metadata
-        run: |
-          python -m pip install --upgrade twine
-          twine check dist/*
-      - uses: actions/upload-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-  publish:
-    name: Publish to PyPI
-    needs: build
-    runs-on: ubuntu-latest
-    environment: pypi
-    permissions:
-      id-token: write
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist/
-      - name: Publish
-        uses: pypa/gh-action-pypi-publish@release/v1