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 — tail live events over server-sent events (GET /v1/stream/sse) 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). Numbers carry 8 significant digits — a price keeps its cents, a sub-cent asset keeps its relative precision, and a batch response is about a third smaller than it would be at full float width.

• 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 — (add ?session=asia, london, newYork or overnight to read the boards over the latest window of that session instead of the latest hour) the live order-flow pulse over the liquid crypto perps: funding extremes (measured from Hyperliquid's baseline rate, so a market at the default rate never reads as crowded), most lopsided books, aggressive flow — with universeNote (which markets it covers) and a legend of each number's unit and window. It leads with the clock (the session now, the next Asia, London and New York opens, the high-impact economic releases due in the next 24 hours) and the unusual board: the markets out of character for the hour that just closed — volume, net flow, number of takers, the biggest taker's share, range, spread, book depth or open-interest move — each placed against that market's own same hour over the last 90 days, weekdays and weekends apart. Plus what the options market prices for BTC, ETH, SOL, HYPE, XRP, AVAX and TRX: 30-day implied volatility, the move it implies over the next hour and day, whether downside protection costs more than upside (skew), put/call open interest and the next expiry's biggest strikes, from Deribit every 15 minutes. Add ?view=read for the market read of the latest session (or ?session= one of them), and &since= the asOf your last read returned, or how long ago such as 3h, to get what changed since you last looked beside it.
• GET /v1/news — the live news wire, each item mapped to the markets it names with freshness and an expected direction. Params: symbol (one market's catalysts), theme, limit (max 40), hours (max 168, default 12).

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 — a price alert going off (price_alert.fired), a desk screen catching new markets (desk_match.fired), or your AI trader opening, closing or reviewing a position (trader.decision). Subscribe to any of them by name, or to * for every event. 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.