> For the complete documentation index, see [llms.txt](https://docs.viperexecution.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viperexecution.com/api-reference/overview.md).

# Overview

## What this is

The Viper Execution v1 API is a programmatic interface for running institutional-grade execution algorithms on Hyperliquid. It provides the same execution algorithms available in the Viper dashboard (Glidemaker, Pacemaker, GhostSweep, FlowScale, FlowBand, Smart Exit) through a REST surface suitable for trading bots.

The reference is organized by resource family — account, connections, positions & leverage, orders & fills, execute & executions, monitors, webhooks, baskets, and market data — each in its own section of the navigation. Real-time data (account, execution, and monitor streams) lives under **Streams**.

## Status

v1 is live and stable. The core surface — `/v1/execute`, `/v1/executions/*`, authentication, and the error envelope — is in production and won't break under you.

* Scope enforcement is **active** at the gateway. A key calling an endpoint outside its scope returns 403 `insufficient_scope` with `required_scope` in the error details. Provision each key with only the scopes your bot actually uses.
* The full v1 family set is shipped — account, connections, positions & leverage, orders & fills, execute & executions, monitors, webhooks, baskets, market data, and streams.
* Example payloads in this reference are authoritative for response shape.

## Base URL

```
https://api.viperexecution.com
```

All v1 endpoints live under the `/v1/` path prefix. The legacy `/api/` prefix is the dashboard's internal API — bots should never use it.

## Authentication model

v1 uses **HMAC-SHA256 request signing** with per-request timestamps. Every request carries three headers:

* `X-Viper-Api-Key-Id` — your public key identifier (`vk_…`)
* `X-Viper-Timestamp` — UNIX epoch seconds, recent
* `X-Viper-Signature` — HMAC-SHA256(secret, `{timestamp}{method}{path}{body}`)

Full signing details are in **Authentication**. The dashboard's JWT auth does NOT work here; these are separate systems.

Key properties:

* Agent-wallet architecture — your API key signs with a server-side agent key. Agents can place/cancel orders but cannot withdraw funds. The agent never holds withdrawal permission — funds stay under your control.
* Scope-limited — each key is provisioned with specific scopes (`read`, `trade`, `algo`). `algo` covers execution launch and management.
* Rate-limited per key — you get a per-minute weight budget based on your tier. Launch endpoints are weight-20 (heavy); reads are weight-1 to weight-5.

## The v1 surface

| Family                   | What it covers                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account**              | Account state, balances, P\&L, fills, fee tier, referrals                                                                                   |
| **Connections**          | API-key → venue connection bindings (`GET /v1/connections`)                                                                                 |
| **Positions & Leverage** | Open positions, entry-fee analytics, leverage config, position close                                                                        |
| **Orders & Fills**       | Manual order placement, cancel/modify, order history, fills                                                                                 |
| **Execute & Executions** | Algorithmic execution launch, lifecycle, introspection — the six algos (Glidemaker, Pacemaker, GhostSweep, FlowScale, FlowBand, Smart Exit) |
| **Monitors**             | Trade monitors — conditional automation                                                                                                     |
| **Webhooks**             | Inbound TradingView-style webhook receivers                                                                                                 |
| **Baskets**              | Execution Baskets — grouped multi-leg executions                                                                                            |
| **Market Data**          | Instruments, markets, orderbook, price                                                                                                      |
| **Streams & Utility**    | WebSocket + SSE streams, health, status, rate limits                                                                                        |

## Quick start

A minimal Python client that signs a request and launches a Glidemaker:

```python
import os, hashlib, hmac as hmac_mod, httpx, time, json, uuid

API_KEY = os.environ['VIPER_API_KEY']       # opaque vk_… id
API_SECRET = os.environ['VIPER_API_SECRET'] # opaque vs_… secret
BASE = 'https://api.viperexecution.com'


def call(method, path, body=None, idem_key=None):
    ts = str(int(time.time()))
    body_bytes = json.dumps(body).encode() if body is not None else b''
    payload = f'{ts}{method}{path}{body_bytes.decode()}'.encode()
    sig = hmac_mod.new(API_SECRET.encode(), payload, hashlib.sha256).hexdigest()
    headers = {
        'X-Viper-Api-Key-Id': API_KEY,
        'X-Viper-Signature': sig,
        'X-Viper-Timestamp': ts,
    }
    if idem_key: headers['Idempotency-Key'] = idem_key
    if body is not None: headers['Content-Type'] = 'application/json'
    r = httpx.request(method, f'{BASE}{path}', headers=headers, content=body_bytes, timeout=30)
    return r


# Launch a Glidemaker
r = call('POST', '/v1/execute',
    body={
        'algo': 'glidemaker',
        'symbol': 'BTC',
        'side': 'buy',
        'total_size': 0.001,
        'params': {'strategy': 'neutral', 'limit_price': 65000}
    },
    idem_key=str(uuid.uuid4())
)
print(r.status_code, r.json())
```

That's \~30 lines of real code. The raw REST + HMAC surface is fully supported and always will be — build your client in whatever language and framework fits your infrastructure, with full control over timeouts, retries, connection pooling, and error handling.

If you'd rather not hand-roll the signing and WebSocket plumbing, an **official Python SDK** is available — a typed convenience wrapper over these same endpoints, never a gate, never required:

```bash
pip install viper-execution
```

It signs every request, auto-generates idempotency keys, maps the error envelope to typed exceptions, and ships a resilient WebSocket client — while every response stays a plain dict. See the [Python SDK](/api-reference/python-sdk.md) page for the quickstart, the client surface, and the runnable example catalog.

## Design principles worth knowing

A few design principles shape the v1 surface. The ones bot devs most need to know:

1. **Respect user input** — what you send is what we record. We don't silently rewrite fields. If a request produces incoherent behavior, we reject with 422; we don't "correct" it for you.
2. **Preflight validates shape, not state** — we check size/price decimals and field consistency, but position/balance/leverage validation happens at order placement time with live data.
3. **Algos enforce semantic correctness** — when you send `reduce_only: true`, that's an intent. The algo makes it real by checking live state and using Hyperliquid's native reduce\_only flag on every order.
4. **Idempotency is mandatory on `/v1/execute`** — double-launch from a retry loop is the most damaging bot bug class. Always include an `Idempotency-Key` header. See **Authentication → Idempotency**.

## Key provisioning

API keys are created **self-serve in the dashboard** — Settings → API Keys → Create — and the secret is shown only once at creation. You must have a wallet linked to your account before a key can be created (creation is refused with a 409 otherwise). See **Authentication → Creating your API key** for the full procedure, the available options, and the link-wallet-first precondition.

Keys carry a handle (your account identifier) and a scope set (`read`, `trade`, `algo`). Request the minimum scope your bot needs — narrowed scopes limit blast radius if a key leaks.

## Support

For API bugs and questions, reach out at <support@viperexecution.com>.

When reporting an issue with a specific request, include the `request_id` from the response headers — it's the lookup key for our logs.