REST & WebSocket API

Forven runs a local FastAPI server. The web UI talks to it over HTTP on 127.0.0.1, and the same API is available to you for scripting, integrations, and diagnostics. This page is the developer reference: the base URL, how authentication works, the endpoint catalog grouped by area, the /ws/live WebSocket feed, and the deprecated paths.

This is a local-first API. By default it binds to loopback only, the keys live on your machine, and nothing is exposed to the internet. If you only use the UI you never touch this directly — but everything the app does, you can do over HTTP. AI clients can drive the research loop through the MCP server instead, which wraps the same endpoints as tools.

Base URL

The server listens on http://127.0.0.1:8003 by default. Two environment variables change that:

• FORVEN_PORT — the listen port (default 8003). A startup guard detects port collisions.
• FORVEN_BIND_HOST — the bind address (default 127.0.0.1, loopback only). A non-loopback address refuses to start unless both keys below are set.

A DNS-rebinding guard rejects unexpected Host headers (extend it with FORVEN_ALLOWED_HOSTS). Browser calls are constrained by CORS (FORVEN_CORS_ORIGINS, default: the local UI origins) and by a cross-site request check on state-changing calls.

Almost every route is under the /api prefix. The WebSocket alias /ws/live and the /verdict/* routes are the exceptions.

Authentication

Forven has two keys with different privilege levels, both set through environment variables.

How the two layers stack

1. The API-key middleware runs before routing and checks FORVEN_API_KEY on every request except /api/health, /api/webhooks/*, /api/shutdown, and OPTIONS. A mismatch returns 401.
2. The operator check is applied to whole routers (and a few individual routes, such as force-close). It validates FORVEN_OPERATOR_KEY and returns 401 if the key is missing or wrong.

With no keys set, both layers pass everything through and the backend logs a warning at startup. That is fine for a single user on loopback. Set FORVEN_AUTH_REQUIRED=true to make the server refuse to start unless both keys are set; do that for anything exposed beyond localhost.

# Operator-gated endpoint: send both keys
$h = @{
  "x-api-key"      = $env:FORVEN_API_KEY
  "x-operator-key" = $env:FORVEN_OPERATOR_KEY
}
Invoke-RestMethod -Uri "http://127.0.0.1:8003/api/strategies" -Headers $h

Routes without the operator gate

These need at most the baseline key:

• GET /api/health and GET /health — liveness, no key at all.
• POST /api/shutdown — graceful shutdown, loopback only, no key; used by the launcher.
• /api/webhooks/* — no key, but HMAC-checked; off unless FORVEN_GITHUB_WEBHOOK_SECRET is set.
• Read-only status and dashboard routes (/api/system/status, /api/system/heartbeat, /api/regime, /api/risk, /api/dashboard/*, trade reads), plus diagnostics and health reads.

Endpoint catalog

The API surface is large — about 500 routes across roughly forty routers. The tables group them by area with representative endpoints. Within an area the pattern is consistent: GET to read, POST/PUT/PATCH to change, DELETE to remove.

System, status & control

See the risk page for what the halts do and Operations for the controls in the UI.

Strategies, lifecycle & pipeline

The stages are quick_screen → gauntlet → paper → live_graduated; the graveyard is archived, rejected, and backtest_failed. A strategy that cannot be fairly tested is archived with an untestable: reason. (The old research_only "Parked" stage is retired; its strategies were moved to the graveyard.) The marketing site calls the paper stage a "candidate"; the API always says paper. Strategies can move back as well as forward, but every forward move goes through the promotion gates, and by default live is never entered without a typed GO LIVE confirmation and a notional ceiling.

Strategy Creator & backtesting

Interrupted gauntlet workflows are recovered at startup. See backtesting for a worked example.

AI Drop Zone

The MCP tools reference maps each tool onto these endpoints. See AI Drop Zone.

Trades & paper trading

By default a paper strategy never promotes to live on its own. See paper trading.

Ideas, data & skills

The old /api/hypotheses/* endpoints are gone. See managing market data and data sources.

Agents, the assistant & approvals

Agents never place trades or task each other directly. See agents and models & providers.

Brain, routines & tasks

MCP servers for agents

See external MCP servers for your agents.

Bot Factory

Bots run on paper by default, as isolated subprocesses (on Windows, inside a low-integrity sandbox). Arming one for live is per-bot, needs a typed confirmation and a notional ceiling, and is unsupported. See the Bot Factory.

Universe books (experimental)

These return 404 unless the portfolio layer is on (Settings → System → Experimental features). See universe books.

Settings, notifications & diagnostics

See notifications, diagnostics, and health monitoring.

WebSocket live feed

The live feed streams price ticks, fills, indicator updates, and regime changes. Two routes share one handler:

• ws://127.0.0.1:8003/api/ws/live — the primary endpoint.
• ws://127.0.0.1:8003/ws/live — an alias.

Use the feed to drive live charts instead of polling the trade endpoints.

# Quick check that the WebSocket route is reachable (requires the wscat npm package)
wscat --connect "ws://127.0.0.1:8003/ws/live"

Response and error conventions

• 202 Accepted means queued work. POST /api/brain/chat returns a task_id; poll GET /api/brain/chat/{task_id}, which keeps returning 202 while the task runs.
• 502 from force-close signals a possibly still-open position — re-verify, never assume.
• Promotion refusals are data, not errors. A blocked promotion returns structured failed_gates, each with an actionable hint. Some refusals are capacity or pending evidence, not a verdict — paper_queue_full (waiting for a paper slot), breadth_pending, multi_coin_live_review — and leave the strategy where it is.
• 429 means you hit the rate limit (default 600 requests a minute per client; health and WebSocket paths are exempt).
• 404 on /api/lab/regime/* means the optional Regime Lab is off (FORVEN_ENABLE_REGIME_LAB).

Legacy paths

Older integrations used /api/forven/*. A compatibility shim still rewrites those requests to /api/*, and responses carry Deprecation and Sunset headers. The announced sunset date (June 30, 2026) has passed: the shim may be removed in any release. The legacy WebSocket paths (/api/forven/ws/live, /forven/ws/live) follow the same rule.

Migrate by dropping the forven segment: /api/forven/strategies becomes /api/strategies. Nothing else changes.

Caveats

• The operator key is the real gate. Most useful routes need it; the baseline key alone gets 401 on them.
• Unauthenticated by default on loopback. Set both keys (and FORVEN_AUTH_REQUIRED=true) before binding to anything else — a non-loopback bind without them refuses to start.
• Some reads are intentionally lighter (status, dashboard, diagnostics, health). Don't take their availability as a sign that all routes are open.
• The execution-mode endpoint only accepts paper. Real orders come from strategies at the Live stage and live-armed bots, and reaching the Live stage takes a typed GO LIVE with a notional ceiling.

Forven is a research tool. The endpoints here surface a disciplined validation process; results are not predictive and nothing here is financial advice.

Related

• Environment variables — every key, port, and safety flag this API reads
• MCP server — let an AI client drive the research loop through these endpoints
• CLI reference — the command-line path to the same lab
• Going live safely — read before any endpoint touches real capital