API Reference

One credential, every surface

The VYX API opens the same live order-flow data and account that power the cockpit to your own code, scripts, and AI. One API key authenticates a versioned REST API, an MCP server for Claude and other AI clients, and an event layer (webhooks and a server-sent stream). This page documents the REST API; the MCP server is a thin client of it. A command-line tool is on the way.

Plans and access

Programmatic access is included on every paid plan — Starter, Pro, and Elite. The Free plan does not include API access. The API is a read, account-configuration, and paper/analysis surface: it never holds custody and never places a live exchange order. The live-trading path is closed to the API entirely and returns 403 by design.

• Starter ($49) and up: REST API, CLI, MCP, webhooks, and the event stream.
• Non-custodial: VYX never holds your funds or your exchange keys.
• Analysis-only: the API reads, configures your board, and simulates — it does not execute live trades.

Authentication

Mint an API key in the cockpit under Settings → API & integrations. The secret is shown once at creation; store it safely. Send it as a Bearer token on every request. Keys look like vyx_sk_live_ followed by 48 hex characters; the visible prefix is a non-secret label for identifying a key.

curl https://api.vyx.app/v1/scan \
  -H "Authorization: Bearer vyx_sk_live_…"

{ "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key." } }

Base URL and versioning

Every REST endpoint lives under the versioned base https://api.vyx.app/v1. The health check is open without a key, and the full machine-readable contract is published as OpenAPI so you can generate a typed client.

curl https://api.vyx.app/v1/health
# { "status": "ok", "version": "v1", "ts": 1782605881220 }

curl https://api.vyx.app/v1/openapi.json

Scopes

Every key carries a set of least-privilege scopes, and each endpoint declares the scope it needs. New keys default to the read scopes plus stream; grant write scopes only when a key needs them.

• read:market — symbols, candles, microstructure (OFI/CVD/funding/OI), pulse, board.
• read:account — your signals, regimes, traders, alerts, workspaces, and settings.
• read:ai — AI-analyst notes, trader decisions, paper positions, and alert history.
• write:account — create, update, and delete signals/alerts/regimes/traders/workspaces.
• write:paper — open and close simulated positions (never real money).
• stream — open the event stream / WebSocket for your granted read scopes.

Market data

The market endpoints read the live Hyperliquid universe. Pass a ticker like BTC, or list symbols to get a numeric id and request candles by either. Each candle carries far more than OHLCV: ten levels of book imbalance and depth, spread aggregates, trade-flow (CVD, taker runs, largest prints), and derivatives (funding, mark/index, open interest, OFI, microprice, and Kyle's lambda).

• GET /v1/symbols — the universe: id, name, venue, asset class, rank, 24h volume.
• GET /v1/symbols/{id}/candles — OHLCV + L10 imbalance/depth + CVD/OFI + funding/OI. {id} accepts a ticker (BTC) or numeric id. Params: interval, limit, before.
• POST /v1/candles/batch — multi-symbol candles in one round-trip (symbol_ids, interval, limit).
• GET /v1/board — the heatmap bootstrap snapshot across the universe.
• GET /v1/pulse — the live order-flow pulse: funding extremes, most lopsided books, aggressive flow.

curl https://api.vyx.app/v1/symbols \
  -H "Authorization: Bearer $VYX_KEY"

{ "id": 366247711256480, "name": "BTC", "venue": "hyperliquid",
  "asset_class": "crypto", "rank": 1, "volume_24h": 1018681025.7 }

curl "https://api.vyx.app/v1/symbols/BTC/candles?interval=1h&limit=50" \
  -H "Authorization: Bearer $VYX_KEY"

Your board: signals, alerts, and more

Read your scored board and manage every object on it. A signal is a composite of indicators — the same model the cockpit and the 24/7 engine use. Objects are addressed by your own clientId, so a create with an existing clientId updates it in place.

• GET /v1/scan — your active signals and their latest engine scores (top movers).
• GET|POST /v1/signals and GET|PUT|DELETE /v1/signals/{clientId} — manage composites. combine is consensus, linear, or strict.
• POST /v1/signals/{clientId}/server-side — toggle 24/7 server-side execution (Pro and up).
• CRUD /v1/alerts, /v1/regimes, /v1/traders, /v1/workspaces — the rest of your board.
• GET|POST /v1/watchlist — your pinned symbols, watchlists, and active signals.

curl https://api.vyx.app/v1/scan \
  -H "Authorization: Bearer $VYX_KEY"

curl -X POST https://api.vyx.app/v1/signals \
  -H "Authorization: Bearer $VYX_KEY" -H "Content-Type: application/json" \
  -d '{
    "clientId": "my-fracture",
    "name": "My Fracture",
    "combine": "linear",
    "indicators": [
      { "id": "i1", "name": "Spread Blowout", "formula": "spreadRange",
        "kind": "range", "normalize": "percentile", "direction": "up",
        "role": "conviction", "weight": 1 }
    ]
  }'

AI analyst and the paper rail

Read what the server-side AI analyst is seeing, and drive the simulated paper rail. The analyst is recommendation-only; the paper rail is a simulation that never sends a real order.

• GET /v1/analyst/notes — latest analyst notes (headline, leans, salience, confidence).
• POST /v1/analyst/ask — a one-shot analyst read of a signal/symbol (metered, rate-limited).
• GET /v1/traders/{id}/decisions — a trader's auditable decision log.
• GET /v1/paper/positions and POST /v1/paper/orders — read and move simulated positions only.

Events: webhooks and streaming

For durable server-to-server delivery, register a webhook: VYX POSTs signed JSON when an event fires (alerts today, more event types as they wire in). Each delivery carries an HMAC-SHA256 signature so you can verify it. For interactive tails, a firewall-friendly server-sent stream is available.

• GET|POST|DELETE /v1/webhooks — register an HTTPS URL + event filter; the secret is returned once.
• GET /v1/stream/sse — a read-only server-sent event tail for your granted scopes.

X-Vyx-Signature: t=1782600000,v1=<hmac-sha256 of "t.body">

Errors and rate limits

Errors are typed JSON with a stable code and a human message. Requests are rate-limited per key by plan; every response carries the limit headers, and a 429 includes Retry-After.

• 400 — invalid input. 401 — missing or invalid key. 403 — scope denied, or the live-trading guardrail.
• 404 — unknown resource. 429 — rate-limited (see Retry-After).

X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset · Retry-After

Next steps

Connect the API to Claude with the MCP server so your own AI can read live order flow and manage your board.