API Reference

One credential, every surface

The VYX API opens the same live order-flow data and account that power the desk 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). Everything the in-app VYX chat can see or do on your trade desks, this surface can too: the live scored board, dry-run previews, signal and regime composition, and full desk control including your AI trader's strategy — so your own AI subscription (Claude, ChatGPT, or any agent that speaks REST or MCP) can work your desk exactly the way the built-in chat does. This page documents the REST API; the MCP server is a thin client of it. A command-line tool is on the way.

Access

Every account can mint an API key for the REST API, the MCP server, webhooks, and the event stream — reading your board is free at 60 requests/minute, and paid plans raise the budget (Trader 300, Autopilot 600, Quant 1,200). 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.

• Every account: REST API, CLI, MCP, webhooks, and the event stream — free to read at 60 req/min, higher budgets on paid plans.
• 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 on the desk 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 scopes, and each endpoint declares the scope it needs. New keys default to every scope — the read scopes, write:account, and stream — so a client can work a desk out of the box; uncheck what a key does not need. No scope can trade live: placing real orders always goes through the app.

• read:market — symbols, candles, microstructure (OFI/CVD/funding/OI), pulse, board.
• read:account — your signals, regimes, traders, price alerts, trade desks (workspaces in the API), and settings.
• read:ai — AI-analyst notes, trader decisions, and alert history.
• write:account — create, update, and delete signals/regimes/traders/workspaces.
• 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. Params: interval, limit, projection, symbols (all = the whole venue, the default · tradable = only markets that clear the tradable-size floor · ids:1,2,3 = an explicit set).
• 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: live scoring, signals, alerts, and more

Read your board scored live — the same scoring the desk runs, computed fresh on every call for every plan — and manage every object on it. A signal is a composite of indicators, and the API accepts the same rich item shape the in-app chat composes (role, direction, normalization, gates, weights). Objects are addressed by your own clientId, so a create with an existing clientId updates it in place.

• GET /v1/scan — your board scored live by your active desk signals (or ?signal= one by id/name). Params: side, sort (abs|buy|sell|firing), limit, min_score, interval.
• GET /v1/symbols/{id}/insight — one market's full read: your signals' scores, per-indicator why, current-bar flow, and recent structure.
• GET /v1/search?metric=&op=&value= — screen the whole universe by one metric (spreadBps, imb, ofi, fundingBps, oiDeltaPct, and more).
• GET /v1/regimes/read — your regime tiles evaluated on the live universe.
• GET|POST /v1/signals and DELETE /v1/signals/{clientId} — manage composites. combine is consensus, linear, or strict.
• POST /v1/signals/{clientId}/server-side — toggle 24/7 server-side execution (Trader and up).
• CRUD /v1/regimes, /v1/traders, /v1/workspaces (your trade desks) — the rest of your board.
• GET|POST /v1/watchlist and /v1/watchlists — pinned symbols and named watchlists (create, add/remove tickers).

curl "https://api.vyx.app/v1/scan?sort=abs&limit=12" \
  -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 }
    ]
  }'

Check your work before saving

The same dry-run loop the in-app chat uses before it proposes anything: preview a candidate against the live field, then validate a saved signal against history. Nothing is saved by a preview; a validation is an honest verdict, never a forecast.

• POST /v1/preview/signal — score a candidate composite across the live board: fire count, buy/sell split, dead-gate detection.
• POST /v1/preview/indicator — one formula across the universe: range, median, how much of the field reads zero.
• POST /v1/preview/regime — a candidate regime's current reading, distribution, and whether it actually moves.
• POST /v1/signals/{clientId}/validate — proof over history: volatility and direction verdicts with sample sizes.

curl -X POST https://api.vyx.app/v1/preview/indicator \
  -H "Authorization: Bearer $VYX_KEY" -H "Content-Type: application/json" \
  -d '{ "formula": "spreadBps" }'

Trade desks and your AI trader

Read and work a trade desk the way the in-app chat does. A desk's lit signals are exactly what its AI trader trades, so changing them changes what an armed trader acts on at its next tick — the API tells you this, and so should your agent. Traders are composed with the same strategy model the chat uses and follow the same plan gating as in the app (AI traders are part of Autopilot and up). They are always created disabled: enabling, arming, and anything that touches live execution stays with you, inside the app.

• GET /v1/desk — a desk whole: lit signals, interval, liquidity floor, its trader (strategy, mode, run status and why), open trades, recent closed trades with R, and the account's armed posture. ?desk= by id or name; default is the active desk.
• POST /v1/desk — create a new empty desk. POST /v1/desk/active — switch the active desk (syncs to your devices). POST /v1/desk/share — get its public no-login link.
• POST /v1/desk/signals — set, add, or remove the desk's lit signals by id or name.
• POST /v1/traders with a strategy body — compose a trader: summary, setups, planning, management, sizing, avoid. Modes: analyst or testnet. Created disabled.
• POST /v1/traders/{id}/strategy — revise the strategy in place; the version bumps and learnings are preserved. It can never flip mode or enabled.

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

curl -X POST https://api.vyx.app/v1/desk/signals \
  -H "Authorization: Bearer $VYX_KEY" -H "Content-Type: application/json" \
  -d '{ "signals": ["My Fracture", "OI Surge"], "mode": "set" }'

AI analyst

Read what the server-side AI analyst is seeing. The analyst is recommendation-only — it reads and configures your board, and 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.

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 — REST and MCP calls share one budget — and every response tells you what that budget is. Go over it and you get a 429 with Retry-After; wait it out and you are back in.

• Per-minute budget by plan: Free 60 · Trader 300 · Autopilot 600 · Quant 1,200.
• 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-Reset · Retry-After (on 429)

Next steps

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