HyperLiquid integration

HyperLiquid is the only exchange Forven can route real orders to. This page is for operators wiring up the connection: where credentials live, how the network (testnet vs mainnet) is chosen, the wallets and sub-accounts Forven can manage, what gates mainnet, and how Forven keeps its own records in sync with exchange truth.

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

Paper does not touch HyperLiquid

Most of what you do in Forven never reaches the exchange. Paper trading runs on the Binance market-data feed and simulates fills inside Forven; funding and open-interest enrichment also come from Binance. The connection on this page matters for strategies you promote to the Live stage (unsupported; see execution modes) and for Bot Factory bots you explicitly arm live. Until then, a HyperLiquid connection is something you test, not something you trade on.

Testnet vs mainnet

• Testnet — HyperLiquid's sandbox, with non-real funds. Where you should verify everything.
• Mainnet — real capital.

The network comes from the Hyperliquid testnet toggle in Settings → HyperLiquid → Credentials & network, which is on by default. (FORVEN_HL_USE_TESTNET sets it only when no in-app HyperLiquid settings exist.) Saving the toggle off asks you to type LIVE under "Save changes that affect real money?". The network is resolved once per order path, and every safety gate checks the network the order will actually hit, so a log line can never say "testnet" while an order goes to mainnet.

The top strip shows a TESTNET or MAINNET badge once the network is known, and /api/dashboard reports it as account.network. Confirm it reads what you expect before trusting any position view.

The mainnet gate

Mainnet order execution is default-deny. Before any real-funds order is accepted, all of these must hold:

• Hyperliquid testnet is off in Settings;
• FORVEN_ALLOW_MAINNET=1 is set in the backend's environment — the hard gate in the exchange layer, with no UI control;
• a verified HyperLiquid API (agent) wallet. On mainnet, a master-account private key is refused. An agent wallet can trade but cannot withdraw, so even a full compromise of Forven cannot move funds off the exchange.

Without the flag, any order that resolves to mainnet is refused. Reduce-only exits and protective stops are always allowed, so you can always get out of a position. The GO LIVE dialog shows the gate as Mainnet switch: "Armed: orders will be placed" or "Not armed: mainnet orders are refused". On mainnet, leverage is also capped at 3× and several risk limits become fixed ceilings — see mainnet locks.

An armed gate stays visible: /api/health reports when the arming was first observed and how old it is. An optional expiry (mainnet_arming_expiry_hours, off by default) can stop new entries after a set time; an expired arming never blocks an exit — being unable to get out of a real position is worse than the staleness the expiry guards against.

# Open the mainnet gate (unsupported, at your own risk); set it before starting the backend
$env:FORVEN_ALLOW_MAINNET = "1"

See going live safely for the full pre-capital checklist.

Credentials

Forven needs your HyperLiquid wallet address (the account that holds funds) and your API wallet — its address and its private key (the API secret). It reads them from these sources, first match wins:

1. Settings → HyperLiquid → Credentials & network — the in-app form: Hyperliquid wallet address, Hyperliquid API address, and Hyperliquid API secret. The secret is stored encrypted in your local keystore. Highest precedence.
2. Environment variables — used when no in-app HyperLiquid settings exist.
3. A legacy encrypted credentials file — a settings.json plus .key under FORVEN_HL_CREDS_PATH, for older setups. FORVEN_HL_DISABLE_ENCRYPTION=1 reads a plaintext file instead.

Environment variables

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

Prefer the in-app form: it encrypts the secret at rest. A fuller treatment of every variable is in the environment variables reference.

Wallets, sub-accounts, and direction books

Settings → HyperLiquid is the one place for all HyperLiquid setup:

• Credentials & network — the account address, API wallet address and secret, Hyperliquid testnet (on by default), and Use cross margin (live) (off by default).
• Wallets & sub-accounts — a named-wallet registry with a Mainnet / Testnet pill. It shows the master wallet's perp balance and spot USDC. Create sub-account (its name becomes the wallet label) or Register existing; a sub-account found on the exchange but not yet registered shows Register. Per wallet: Fund from the master or withdraw, move between spot and perp, and Remove. Every money move asks for confirmation, and on mainnet the dialog warns "This moves real funds on Hyperliquid mainnet." Transfers need a signer that is allowed to move funds; agent wallets are barred by the protocol.
• Direction books (long/short sub-accounts) — off by default. When on, live longs and shorts route to separate sub-accounts, and Slice live capital across BOTH books (on by default) sizes each live strategy off the combined pool. Each wallet has its own capacity check at order time, capped at 80% margin (Live max per-wallet margin).

Named wallets are also how you isolate capital for Bot Factory bots: a bot armed live trades only from the wallet you assign it.

Connecting: step by step

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

Steps

1. Create a HyperLiquid testnet account and an API wallet for it.
2. Open Settings → HyperLiquid → Credentials & network and fill in Hyperliquid wallet address (the account), Hyperliquid API address and Hyperliquid API secret (the API wallet and its private key). Leave Hyperliquid testnet on.
3. Save and check the connection. The top strip should read TESTNET, and the account balances should populate under Wallets & sub-accounts.
4. Watch the circuit breakers. On the risk page, the Circuit Breakers row (Price Feed, Trade, Account) should read CLOSED. See circuit breakers.
5. Check the testnet harness. A daily scheduled job places a real ~$15 testnet order and walks the whole live lifecycle — open, protective stop, trailing tighten, close — asserting exchange truth at every step, then cleans up after itself. GET /api/ops/testnet-harness/last shows the last result; POST /api/ops/testnet-harness/run runs it now. It refuses mainnet.
6. Mainnet is unsupported. Going beyond testnet is at your own risk.

What you'll see

On a healthy testnet connection: a TESTNET badge, populated balances, all three HyperLiquid breakers CLOSED, and a passing harness report. If the breakers are tripped or the account is empty, the connection or credentials are wrong — fix that before going further.

How orders reach the exchange

You never need to place entries by hand. Live orders come from the execution kernel, driven by the scanner for each strategy at the Live stage (live_graduated), and from bots you armed live. No AI agent places orders. (Manual orders from the Live Trades desk use the same order path and gates.)

1. The kernel produces an entry (asset, direction, stop-loss, take-profit, leverage).
2. Sizing and admission: the strategy's capital slice, the risk gates, the portfolio budget, the per-wallet margin cap, the go-live notional ceiling, and the liquidity guard. See risk controls.
3. Leverage is set in whole numbers, as HyperLiquid requires: a validated 1.3× is set at 2× on the exchange, while the position size still follows the validated leverage. On mainnet it never exceeds 3×.
4. The order is submitted through the HyperLiquid SDK with a mandatory protective stop, mirrored on the exchange as a resting reduce-only trigger. With direction books on, it routes to the long or short sub-account.
5. HyperLiquid returns an order ID; a trade record is created with execution_type='live' and the fill is reconciled.

Only spot free USDC counts toward equity, so a balance cannot be double-counted between spot and perp.

Nonce monotonicity and order serialization

Every signed submission passes through one process-wide lock with a strictly increasing millisecond nonce, so two orders in the same millisecond cannot collide at the exchange. It covers opens, cancels, and updates, which is why live order routing is single-file rather than parallel. Every HyperLiquid HTTP call also has a hard timeout, so a stalled exchange request cannot freeze the daemon.

Account reconciliation and phantom recovery

Forven keeps its own trade records and treats the exchange as the source of truth, reconciling the two continuously during live execution.

• Phantom positions. If HyperLiquid shows a filled position with no matching local trade, recovery creates a record so the position is tracked, and an orphan with no protective stop gets an emergency stop. A recovered trade is not linked to a strategy and may need review.
• Pending-open reconcile. A local trade with no exchange order ID has its risk slot freed after 180s, and an exchange-verify pass closes it if it genuinely never filled.
• Confirmed empties. One empty position read never closes live positions; the reconciler requires consecutive confirmation.
• Close rejections are surfaced. If a close is rejected or does not fill, the trade is not booked as closed at an invented price — the error is recorded and the position stays open for the next attempt.

Recovery state surfaces on the risk page. If an unfamiliar position appears right after a restart, check recovery before assuming a rogue order.

Exchange health: circuit breakers and rate limits

Three circuit breakers watch HyperLiquid — hl_price, hl_trade, and hl_account — following a CLOSED → OPEN → HALF_OPEN → CLOSED state machine. They trip on true outages (5xx, connection errors), not on rate limits. A 429 is treated as transient: signed submissions retry with bounded backoff and do not trip hl_trade, which keeps the emergency-close path alive during a rate-limit burst. Prices used to size live orders are also age-bounded, so a stale cached mid is never used to price an order. Full detail is on the circuit breakers page.

Caveats

• Paper is the supported mode. Live is unsupported and at your own risk.
• "Live" is testnet by default. A strategy at the Live stage sends real orders, but to testnet until you change the network.
• Mainnet is multiply gated. It takes a strategy promoted with a typed GO LIVE, the testnet setting off (typed LIVE), FORVEN_ALLOW_MAINNET=1, and an agent wallet. No single switch enables real-funds orders.
• Capital is pooled, then divided. Live strategies share the account, sized in equal slices; the kill-switch is account-wide.
• 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 — what decides whether an order is real, and why live is unsupported.
• 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.