HyperLiquid integration

HyperLiquid is the exchange Forven routes real orders to. This page is for operators wiring up the connection: where credentials live, how the network (testnet vs mainnet) is chosen, what gates mainnet behind an explicit opt-in, and how Forven keeps its own records in sync with exchange truth.

Credentials never leave your machine. Forven reads them from your environment, a local file, or your encrypted settings, and signs orders locally. There is no Forven-hosted relay.

Paper does not touch HyperLiquid

Before anything else: most of what you do in Forven never reaches the exchange. Paper trading fills against local OHLCV mid-prices and records to SQLite only. The connection on this page matters once a strategy reaches the live stage and execution mode is live. Until then, a HyperLiquid connection is something you test, not something you trade on.

The public site calls the paper stage a "candidate"; the engine and this page use the real name, paper.

Testnet vs mainnet

Forven talks to two HyperLiquid networks:

• Testnet — HyperLiquid's sandbox, with non-real funds. The default for paper and paper-test modes, and where you should verify your connection.
• Mainnet — real capital. Selected only when execution mode is live and the mainnet gate is explicitly opened.

The network is derived from execution mode by default — paper/test selects testnet, live selects mainnet — and you can override it per deployment with the hyperliquid_testnet setting or the FORVEN_HL_USE_TESTNET environment variable.

The active network surfaces on the dashboard as account.network (testnet or mainnet), and the risk page mirrors it as recovery_network. Confirm it reads what you expect before trusting any position view.

The mainnet gate

Selecting mainnet is not enough on its own. Mainnet order execution is default-deny: the FORVEN_ALLOW_MAINNET environment variable must be set to 1. If it is unset or 0, Forven refuses to place real-capital orders even when execution mode is live and the network resolves to mainnet.

This is deliberate. It takes two independent, explicit decisions — switch execution mode to live, and set FORVEN_ALLOW_MAINNET=1 — before any order can reach real funds. On top of that, beta builds (FORVEN_ENV=beta) hard-lock execution to paper regardless of config, so a beta install cannot reach mainnet at all.

# Open the mainnet gate (only meaningful on a non-beta build with execution mode 'live')
$env:FORVEN_ALLOW_MAINNET = "1"

See going live safely for the full pre-capital checklist — the mainnet gate is one switch among several.

Credentials

Forven needs your HyperLiquid wallet address, API key, and API secret. It reads them from three sources, checked in order — the first source that supplies credentials wins:

1. Encrypted settings — stored in your local keystore (the in-app Settings → HyperLiquid form), decrypted at use. Highest precedence.
2. Environment variables — consulted when encrypted settings are empty.
3. A local file — a plaintext credentials file on disk, used only when neither of the above is present.

Environment variables

# Provide HyperLiquid credentials via the environment (current shell only)
$env:FORVEN_HL_WALLET_ADDRESS = "0xyour_wallet_address"
$env:FORVEN_HL_API_KEY        = "your_api_key"
$env:FORVEN_HL_API_SECRET     = "your_api_secret"
$env:FORVEN_HL_USE_TESTNET    = "true"   # stay on testnet while you verify

The credential file

If you prefer a file over environment variables, create hyperliquid.json in your FORVEN_HOME (default ~/.forven). The file holds the wallet address and API key; provide the secret through the environment or encrypted settings.

{
  "wallet_address": "0xyour_wallet_address",
  "api_key": "your_api_key"
}

Keep this file private. It lives entirely on your machine, but it is plaintext — prefer encrypted settings or environment variables for the secret, and never commit it anywhere.

A fuller treatment of every variable, including defaults, is in the environment variables reference.

Connecting: step by step

Wire up testnet first, prove it works, and only then consider mainnet.

Steps

1. Create HyperLiquid testnet API credentials in your HyperLiquid account (wallet address, API key, API secret).
2. Provide them to Forven via environment variables, ~/.forven/hyperliquid.json, or encrypted settings — see above.
3. Keep the network on testnet. Leave execution mode at the default paper, or set FORVEN_HL_USE_TESTNET=true.
4. Open the Settings page and confirm the hyperliquid_testnet toggle reflects testnet.
5. Check the connection on the dashboard. Confirm account.network reads testnet and the account fields populate (equity, margin, withdrawable).
6. Watch the circuit breakers. On the risk page, the three HyperLiquid breakers (hl_price, hl_trade, hl_account) should read CLOSED (healthy). See circuit breakers.
7. Only then, for mainnet: switch execution mode to live, set FORVEN_ALLOW_MAINNET=1, supply mainnet credentials, and re-verify on a non-beta build.

What you'll see

On a healthy testnet connection, the dashboard shows account.network: testnet with live account values, and the risk page shows all three HyperLiquid circuit breakers CLOSED. If the breakers are tripped or the account is empty, the connection or your credentials are wrong — fix that before going further.

How orders reach the exchange

You never place an order at HyperLiquid by hand from Forven. Live orders originate from the scanner (which evaluates each live strategy's signals) and are submitted by the execution-trader agent — the only component with exchange access. Every other agent must queue a task for the execution-trader; direct placement from anywhere else is not supported.

A live entry flows like this:

1. The scanner emits a buy/sell signal for a live strategy (asset, direction, size, stop-loss, take-profit, leverage).
2. It calls can_open() to check portfolio-level risk against the shared wallet — drawdown, daily-loss, per-trade risk, and the global position cap. See risk controls.
3. If allowed, it queues an execution-trader task.
4. The execution-trader submits the order via the HyperLiquid SDK (market or limit).
5. HyperLiquid returns an order ID; a trade record is created with status='OPEN' and execution_type='live'.
6. The agent reconciles the fill price and updates the trade.

Nonce monotonicity and order serialization

Every signed submission to HyperLiquid passes through one process-wide lock (_HL_SUBMIT_LOCK) with a strictly increasing millisecond nonce. This prevents nonce collisions when two orders would otherwise submit in the same millisecond, which the exchange would reject as duplicate or nonce-mismatch. The lock covers all open, cancel, and update calls. It is an internal mechanism with no UI surface — but it is why live order routing is single-file rather than parallel.

One narrow edge: the nonce counter resets to the current millisecond when the process restarts. Two restarts in the same millisecond that both submit an order could, in theory, collide — rare, but worth knowing.

One shared wallet

Live execution pools all active strategies into one HyperLiquid wallet. Risk limits apply globally to that pool, not per strategy — the concurrent-position cap covers the whole wallet, and drawdown is measured across the combined account. Paper sessions, by contrast, stay isolated per session. Read risk controls before deploying more than one strategy live.

Account reconciliation and phantom recovery

Forven keeps its own SQLite trade records and treats the exchange as the source of truth, reconciling the two at startup and periodically (roughly every ten minutes) during live execution.

• Phantom positions. If HyperLiquid shows a filled position with no matching local trade, recovery creates a new trade record so the position is tracked rather than orphaned. Such a recovered trade is not linked to a strategy and may need manual review.
• Pending-open reconcile. If a local trade has no exchange order ID, it is marked pending_open_reconcile. Its risk slot is freed after _PENDING_OPEN_SLOT_FREE_SECONDS (180s); within that window an exchange-verify pass closes it if it was genuinely unfilled.

Recovery state surfaces on the risk page (recovery_* fields: active flag, status, position and discrepancy counts, batch ID, and the active recovery_network). If an unfamiliar position appears right after a restart, check recovery before assuming a rogue order — it is usually the system catching up to exchange truth.

Exchange health: circuit breakers and rate limits

Three CCXT-backed circuit breakers watch HyperLiquid: hl_price, hl_trade, and hl_account. They follow a CLOSED → OPEN → HALF_OPEN → CLOSED state machine and trip on true outages (5xx, connection errors), not on rate limits.

A HyperLiquid 429 (rate limit) is treated as transient, not an outage. Signed order submissions retry with bounded exponential backoff (illustratively 0.5s → 4s max) and do not trip hl_trade — which is what keeps the emergency-close path working during a rate-limit burst. Only genuine failures open a breaker. Full detail is on the circuit breakers page.

Funding and perpetuals

HyperLiquid supports spot and perpetual-futures trading, and Forven monitors funding rates as part of its market-data enrichment alongside open interest and liquidations. Funding is an input to research and live monitoring, not a separate trading surface you operate from this page.

Caveats

• Beta is paper-locked. FORVEN_ENV=beta forces execution to paper; mainnet is unreachable on a beta build no matter how the connection is configured.
• Mainnet is double-gated. It takes both execution mode live and FORVEN_ALLOW_MAINNET=1. Neither alone enables real orders.
• The secret is env/encrypted only. FORVEN_HL_API_SECRET is not read from hyperliquid.json; supply it through the environment or encrypted settings.
• The wallet is shared and global. Live position and risk limits apply to the whole pool. One badly-behaved strategy can spend the entire account's risk budget.
• A recovered trade may be unlinked. Phantom recovery can create trade records with no parent strategy; review them.
• Keys are yours to protect. Forven stores them locally and signs locally, but plaintext files and shell history are still your responsibility.

Related

• Execution modes: paper vs live — how the two modes differ and how mode selects the network.
• Going live safely — the checklist and strict gate before any real capital.
• Circuit breakers — the three HyperLiquid breakers and how 429s are handled.
• Environment variables — every credential and safety variable with defaults.