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. The live code path can send real orders to HyperLiquid, but live trading is not a supported feature of Forven and mainnet is not supported at all. Paper trading — optionally validated against the HyperLiquid testnet — is the supported way to run the app.

This page is for any user deciding how to run Forven. The short version: paper is the default and the supported mode, paper is where every strategy proves itself, and the live mainnet path is left in the codebase only as an unsupported, at-your-own-risk escape hatch for advanced users who wire it up themselves.

Forven is a research tool. Paper results describe simulated behaviour and do not predict live results. Live trading is unsupported and risks real capital; nothing here is financial advice or an endorsement of trading real money with this software.

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. Paper — optionally against the HyperLiquid testnet — is the supported way to run Forven; the live path is documented only so the unsupported escape hatch is understood, not recommended.

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.

Paper is the default and the supported mode. The live path is only reached if you deliberately set the mode to live and supply your own exchange credentials — which is unsupported and at your own risk.

# 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.

Paper + testnet is the supported mode

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

Live trading is not a supported feature of Forven, and mainnet is not supported at all. The supported way to run the app is paper mode — optionally validating signals and the exchange connection against the HyperLiquid testnet, which uses no real funds. Practical guidance:

• Run paper mode (the default). It fills locally, touches no exchange, and risks nothing.
• If you want to exercise the HyperLiquid integration end to end without risk, point it at testnet (FORVEN_HL_USE_TESTNET=true). Testnet funds are not real.
• The live mainnet path remains in the codebase but is unsupported. Wiring real exchange keys and flipping to live is entirely at your own risk; the project does not support, recommend, or warrant it.

If you stay on paper (and, at most, testnet), there is no real capital at stake. Everything below about switching to live describes the unsupported escape hatch.

Switching to live (unsupported, at your own risk)

Going live is unsupported. The mechanics below are documented for completeness only — they are not a recommendation. Switching the mode is one step; clearing the paper→live promotion gate for an individual strategy is a separate, stricter one. If you choose to do this, you do so entirely at your own risk.

Steps

1. Understand it is unsupported. Live mainnet trading is not a supported feature; proceeding is at your own risk. Prefer testnet for any exchange testing.
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 (unsupported; live/mainnet is at your own risk)
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 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'. Remember this path is unsupported — prefer testnet, and treat any mainnet use as entirely at your own risk.

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

• Paper (and testnet) is the supported mode. Live mainnet trading is unsupported; mainnet is not a supported feature at all. Anyone who wires real keys and flips to live does so entirely at their own risk.
• 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 is 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 — the (unsupported) live monitoring view
• HyperLiquid integration — credentials, the supported testnet, and the FORVEN_ALLOW_MAINNET gate
• Going live safely — the safety machinery and why live mainnet is unsupported