Execution modes: paper vs live

Forven runs in one of two execution modes. Paper fills trades against local candle prices and records them to your local SQLite store — no order ever leaves your machine. Live sends real orders to HyperLiquid, the exchange Forven routes through. The mode is one setting, but it changes everything downstream: where fills come from, whether capital is at risk, and how positions reconcile.

This page is for any beta user deciding which mode to run, and for operators who need to switch safely. The short version: paper is the default, paper is where every strategy proves itself first, and during beta paper is the only mode the app will run.

Forven is a research tool. Paper results describe simulated behaviour and do not predict live results; live trading risks real capital. Nothing here is financial advice.

The two modes at a glance

Paper mode is covered in depth on the paper trading page; live monitoring lives on the live trading page. This page is about the mode setting itself and the safe path between the two.

Paper mode

In paper mode, a strategy in the paper stage of the pipeline — the stage the public site calls a "candidate" — runs forward against the live price feed but fills locally. This is governed by paper_stage_local_execution_only, which defaults to true. The fill price is the signal price, so paper trades carry no slippage and no exchange order ID.

Why local fills matter: they enforce zero look-ahead. The strategy only ever sees prices it could have seen in real time, and it cannot peek at exchange depth it would never have had during research. That discipline is the whole point of the paper stage.

Each paper run lives in its own isolated session with independent starting capital (initial_capital, default 10000) and its own position set. Sessions are per-session, not per-strategy — run a strategy twice and you get two separate sandboxes. Per-session limits come from paper_max_concurrent_positions (unlimited by default), separate from the live cap.

The same local-fill discipline applies to backtests and paper-test (QA) runs via paper_test_local_execution_only (default true).

Live mode

In live mode, a strategy in the live stage routes real orders to HyperLiquid. The flow is different in three important ways:

• Only the execution-trader agent touches the exchange. Other components queue a placement task; the execution-trader is the sole order-placement authority. It submits via the HyperLiquid SDK, monitors fill quality, and reconciles fills back into the trade record.
• All active strategies share ONE wallet. Live execution pools every live strategy's positions into a single HyperLiquid wallet. Risk limits apply globally to the pool — max_concurrent_positions caps the shared wallet, not each strategy. Paper sessions never join this pool.
• Positions reconcile against exchange truth. Live trades carry exchange order IDs and are reconciled by phantom recovery: at startup and roughly every 30 minutes, Forven reads HyperLiquid orders and positions, compares them with your local trades, and repairs mismatches (creating a record for a filled-but-untracked position, or closing a stale unfilled claim). Paper trades have nothing to reconcile against.

Order submissions are serialized through a process-wide lock with a strictly-increasing millisecond nonce, so two orders in the same millisecond cannot collide at the exchange.

How the mode is decided

The effective mode is resolved from, in order of precedence:

1. FORVEN_EXECUTION_MODE environment variable (paper or live) — overrides config.
2. execution_mode in config.json — the persistent setting.
3. Default: paper.

On top of that sits a hard safety override: if the deployment environment is beta, the read site forces paper regardless of what config or env says.

# Read the current effective mode (and a lot more)
curl.exe http://127.0.0.1:8003/api/risk

# The /api/dashboard summary also reports execution_mode
curl.exe http://127.0.0.1:8003/api/dashboard

The base URL for the local API is http://127.0.0.1:8003. Operator-only endpoints may require FORVEN_OPERATOR_KEY if you have set one.

The beta paper-lock

This is the most important safety property on the page, so it is worth stating plainly.

Packaged beta builds set FORVEN_ENV=beta, and that hard-locks execution to paper. The lock is applied at the read site, not the write site — get_execution_mode() returns paper even if config.json literally says live. Practical consequences:

• You cannot accidentally place a live order in a beta build. The POST /api/ops/execution-mode endpoint refuses the switch in beta.
• A stale live value left in config.json can never take effect. It is read, then overridden.
• Because the lock is on read, you don't need to "clean up" config to be safe — the override is unconditional.

If you are running a beta install, paper is the floor and the ceiling. Everything below about switching to live applies only to non-beta builds.

Switching from paper to live (non-beta)

Going live is deliberately gated. Switching the mode is one step; clearing the paper→live promotion gate for an individual strategy is a separate, stricter one. Both must happen before real capital moves.

Steps

1. Confirm the build allows it. In a beta build the switch is refused — there is no override. The rest of these steps assume a non-beta build.
2. Configure HyperLiquid credentials. Forven reads the wallet address, API key, and secret from environment variables (FORVEN_HL_WALLET_ADDRESS, FORVEN_HL_API_KEY, FORVEN_HL_API_SECRET), from ~/.forven/hyperliquid.json, or from encrypted settings. Keys stay on your machine. See HyperLiquid integration for the full setup.
3. Decide testnet or mainnet. Live mode defaults to testnet unless you opt into mainnet. Test on testnet first.
4. Open the mode toggle on the operations page. The real UI route is /ops, under System Controls. The current mode is shown (default: paper).
5. Select Live and confirm. This calls set_execution_mode('live'), which writes config.json and updates the running process. The next scanner run reads live.
6. For real funds, set the mainnet gate. Mainnet is default-deny: FORVEN_ALLOW_MAINNET must be set to 1 before any mainnet order is accepted. Without it, the exchange layer refuses real-funds orders even in live mode.
7. Promote the strategy, not just the mode. A strategy only trades live once it has cleared the strict paper→live gate (walk-forward results, sufficient paper trades and PnL, signal-quality review, Sharpe threshold). Switching the mode does not promote anything by itself.

# Switch execution mode (non-beta only; refused in beta builds)
curl.exe -X POST http://127.0.0.1:8003/api/ops/execution-mode `
  -H "Content-Type: application/json" `
  -d '{\"mode\": \"live\"}'

To stay on testnet, leave FORVEN_HL_USE_TESTNET at its default of true; to trade mainnet, set it to false and set FORVEN_ALLOW_MAINNET=1. The hyperliquid_testnet config setting can override the env-derived network per deployment.

What you'll see

On /ops after a successful switch: the Execution Mode control reflects live, and /api/risk and /api/dashboard report execution_mode: "live". The dashboard's account.network field shows testnet or mainnet, and /api/risk exposes recovery_network mirroring the active network. New orders placed by the execution-trader appear in the trades table tagged execution_type='live'. In a beta build, instead of switching you will see a loud rejection — the lock holds.

Switching back to live → paper

Switching the mode back to paper stops new orders from reaching the exchange, but it does not flatten anything already open. System pause and a mode change do not auto-close positions. To exit real positions you must close them manually or let the kill-switch emergency-close them. Reconcile open live positions before you assume you are flat.

Relevant configuration

Setting paper_stage_local_execution_only to false routes paper-stage trades to HyperLiquid and breaks the zero-look-ahead guarantee. Leave it true unless you have a specific reason and understand the cost.

Caveats (beta)

• Beta is paper-only. Packaged builds hard-lock paper at the read site. Live switching, credentials, and the mainnet gate apply only to non-beta builds.
• Paper PnL is not a proxy for live PnL. Local mid-price fills carry no slippage, partial fills, funding, or rejections. A strategy can look clean in paper and still bleed on real spreads. Read paper results as evidence of process, not a forecast.
• Live pools capital. Every live strategy shares one wallet and one global set of risk limits. Size and concurrency caps are portfolio-wide, not per-strategy.
• A mode change does not close positions. Flipping back to paper, or pausing the system, leaves open live positions open until you exit them.

Forven is a research tool. Surviving paper and passing the live gate are evidence of disciplined process, not a prediction of returns, and nothing here is financial advice.

Related

• Paper trading — running and reading paper sessions in depth
• Live trading — monitoring real positions once you go live
• HyperLiquid integration — credentials, testnet vs mainnet, and the FORVEN_ALLOW_MAINNET gate
• Going live safely — the strict paper→live checklist before real capital