A non-custodial, deterministic delta-neutral funding/points farming bot for Hyperliquid. It runs a long-spot / short-perp basis pair so your net price exposure stays ~flat while the short perp leg collects funding (and accrues points/volume on your own account).
Status: complete, tested, and run live on Hyperliquid mainnet — a stable reference implementation. The single-venue (long spot / short perp) loop is built, hardened, and tested — 195 tests; the perp leg always carries the builder code, and the short is set 1x isolated then read back after entry (all verifiable here with
pytest). It trades HYPE and the Unit-bridged BTC/ETH spot markets (UBTC/UETH), and signs day-to-day with a dedicated Hyperliquid agent wallet that cannot withdraw. It has been run live on mainnet: the delta-neutral pair filled and the builder fee accrued on-chain to a dedicated builder wallet — that receipt lives on-chain (Hyperliquid referral state), not in this repo. The cross-venue rail (HL leg + Lighter hedge) has also been proven live end-to-end — a pair opened on both venues, verified net-flat from raw on-chain positions, then flattened. Working, tested software — not investment advice and not a yield guarantee. Seedocs/ENGINEERING_NOTES.mdfor the design, the money-safety model, and the bugs caught before they cost real money.
The mainnet builder-fee rail is verifiable on-chain — there's no "trust me." Query
the dedicated builder wallet's Hyperliquid referral state and read builderRewards:
curl -s https://api.hyperliquid.xyz/info -H 'content-type: application/json' \
-d '{"type":"referral","user":"0x670e190af40779C355351E3673E8742e3048c65F"}'That wallet receives the builder fee from the Hyperliquid perp leg's builder code. The figure grows as the bot trades; nothing in this repo can fabricate an on-chain balance. This is the structural point of deltafarm — the economics are on-chain and checkable, not a self-reported number.
The cross-venue strategy holds opposite perp legs on two venues so net price delta ≈ 0 while the pair harvests the funding spread (short the higher-funding venue, long the other) and farms points/volume on both.
- The HL leg always carries the builder code; the hedge leg carries none.
Only Hyperliquid is monetized — Lighter is purely the neutralizer. The hedge
adapter's
place_perp_orderhas no builder parameter at all. - Venue = Lighter, chosen by three explicit criteria (not vibes): SDK maturity (Lighter ships an official, maintained Python SDK with signing solved), points payout, and signing-stack overlap. Pacifica was rejected because Solana introduces a whole second key/signing paradigm.
- Never holds naked delta: if the second leg fails, the first is unwound with a fresh quote and the unwind is confirmed (or it shouts STILL EXPOSED).
- Points-program safety: order size is jittered within a bounded fraction
(
SIZE_JITTER_FRAC) so the legs don't pattern-match wash trading.
# Configure the hedge venue (see .env.example: HEDGE_VENUE=lighter + LIGHTER_*).
deltafarm run --cross --paper # simulate both legs off live books, place NOTHING
deltafarm status --cross # HL + hedge perp positions (net delta ~0)
deltafarm monitor --cross --iters 10
deltafarm flatten --cross # close both legsThe live Lighter client (
build_lighter_client) is wired over the official Lighter Python SDK and validated against the live Lighter book — the same way the HL adapter was validated against the live Hyperliquid book. A live cross-venue pair has been opened, verified delta-neutral from raw positions on both venues, and flattened. Leg-fill detection polls to a terminal status and falls back to authoritative on-chain positions, so endpoint lag can't trigger a false leg-failure unwind.
deltafarm dashboard renders a single terminal page — positions, net delta,
funding, builder-fee accrued, and recent activity — from live (or --paper)
state plus the local events.jsonl. No web server, no framework; it's the same
deterministic data the bot trades on.
deltafarm dashboard # one render of current state
deltafarm dashboard --paper # paper positions + live market reads
deltafarm dashboard --watch # refresh in place every POLL_INTERVAL_SECS
deltafarm dashboard --cross # cross-venue view (HL + hedge legs)+---------------------------------------------------------------+
| deltafarm - live dashboard mainnet | live |
+---------------------------------------------------------------+
| POSITIONS (HYPE) |
| HL perp -0.2511 HYPE @ $2,000.00 -$502.20 |
| HL spot +0.2500 HYPE @ $1,990.00 $497.50 |
| NET DELTA -$4.70 [flat] |
+---------------------------------------------------------------+
| FUNDING (hourly) |
| HL +0.0050% |
+---------------------------------------------------------------+
| ACCOUNTING |
| enters 3 exits 2 refusals 1 |
| builder fee routed (est) $0.02 |
| realized funding (24h) $1.37 |
+---------------------------------------------------------------+
| RECENT |
| 18:00:36 enter $60 |
| 18:01:40 flatten 2 ord |
+---------------------------------------------------------------+
The builder fee routed figure is a local estimate (routed notional × declared fee). The authoritative number is on-chain — the fee rail is live and verifiable via Hyperliquid referral state; we never call this "customer revenue." The net-delta line flags STILL EXPOSED if either leg is naked beyond the flat tolerance, so a half-filled pair can't hide.
- Strategy:
long {COIN} spot+short {COIN} perpon Hyperliquid. Delta ≈ 0.{COIN}is HYPE by default; BTC and ETH are supported viaSPOT_COIN, because Hyperliquid lists their spot as the Unit-bridgedUBTC/USDC/UETH/USDC(the perp coin and the spot token differ). Any market you add must have matching perp/spotszDecimals— see Known Limitations in the engineering notes. - Edge gate: it only enters when the expected funding over your stated hold
period clears the full round-trip cost (both legs, both sides, including the
builder fee). Thin or negative funding ⇒ it refuses to trade. See
strategies/economics.py. - Book-based marketable pricing: every order crosses the live order book
(lifts the best ask to buy, hits the best bid to sell) instead of guessing a
mid ± fixed-%price — so the full pair actually fills. A spread guard (MAX_SPREAD_BPS) refuses to cross a pathologically wide book rather than taking a terrible fill. Seecore/execution/marketable.py. - Risk rails: per-order and total-notional spend caps, plus a one-command kill switch that flattens the perp (reduce-only) and unwinds the spot hedge. Order submission is idempotent under retry (per-order client id + bounded backoff) so a network blip never double-fills.
- Monitor loop:
deltafarm monitorpolls funding + delta and exits the pair gracefully when the funding edge disappears; it survives transient API errors without crashing. - Accounting: every enter / exit / flatten / funding / monitor event is
appended to a local
events.jsonl.deltafarm pnlreports funding − fees − routed builder fee;deltafarm dashboardrenders a live terminal view (positions, delta, funding, builder-fee accrued).
Your keys never leave your machine. deltafarm signs locally with keys you put
in a .env file (which is gitignored and never tracked). There is no server, no
hosted wallet, and no LLM with wallet authority — the strategy is fully
deterministic code you can read.
Two keys, separated by design:
HL_AGENT_KEY— the key that signs orders. This is a dedicated Hyperliquid agent wallet (anapproveAgentkey) created withdeltafarm approve-agent, separated from your main wallet by design. It can place and cancel orders but cannot withdraw or transfer funds — Hyperliquid transfers are signed by the account owner, so a leaked agent key cannot drain the account; the worst case is bounded trading loss, itself capped by the isolated-margin pin, the spend caps, and the kill switch. HL agent keys are time-boxed — re-approve before expiry.HL_MAIN_KEY— your main wallet key, used only once bydeltafarm approve-builder. Leave it unset for all normal runs.
deltafarm attaches a builder code to every Hyperliquid perp order. The
declared builder fee defaults to 0.02% (configurable via BUILDER_FEE_TENTHS_BP),
and our code refuses to set any builder fee above 0.10% (BUILDER_FEE_CAP_TENTHS_BP
in config.py — a self-imposed cap, not a platform limit). The fee applies to the
Hyperliquid perp leg only; the hedge/Lighter leg carries no builder code and no
builder fee. This fee is shown to you in plain config and is part of the round-trip
cost the edge gate must clear before any entry — it is never hidden from the economics.
The builder fee accrues on-chain to the builder address. We describe this only as "the fee rail is live and on-chain verifiable." We make no claim that it is "customer revenue."
Hyperliquid requires a one-time approveBuilderFee signed by your main
wallet before any builder code can apply. Skip it and the builder code is
silently inert. Run this once:
# HL_MAIN_KEY must be set for this command only.
deltafarm approve-builderThen unset HL_MAIN_KEY so normal runs can never touch your main wallet.
You can run deltafarm from any Hyperliquid account mode — Unified Account (the default), Portfolio Margin, or Standard. Your order pays the builder fee regardless; you don't have to change your account settings.
The one account that does need Standard mode is the builder's fee-receiving wallet — that's a one-time setup on the operator's side, not yours. (Hyperliquid requires builder-code addresses to be in Standard mode to accrue fees; trader accounts have no such requirement.)
Setting up the builder wallet for the first time? Two Hyperliquid behaviors will bite you if you don't know them:
- A brand-new wallet must receive a deposit before it can do anything.
HL rejects mode changes, transfers, and approvals from an unfunded address
with
"Must deposit before performing actions". Fund the wallet first (faucet on testnet, or a deposit on mainnet), then configure it. - A Unified Account can't send USDC out (
"Action disabled when unified account is active"), and builder addresses must be in Standard mode anyway (see above). So the builder wallet is a dedicated, Standard-mode wallet, funded independently — not your unified trading account, and not funded by an outbound transfer from it.
To switch a wallet to Standard mode programmatically:
Exchange(wallet, url).user_set_abstraction(addr.lower(), "disabled").
Again: this is operator (builder) setup. Traders/users do none of it.
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
copy .env.example .env # then fill it in (see comments in the file)
deltafarm approve-builder # once, with HL_MAIN_KEY set (main wallet)
deltafarm approve-agent # once: create a dedicated agent key that can't withdraw
deltafarm run # enters the basis pair (if the edge clears cost)
deltafarm status # show perp + spot positions (delta should be ~0)
deltafarm monitor # poll funding/delta; auto-exit when the edge is gone
deltafarm pnl # funding / fees / routed builder fee / net
deltafarm dashboard # terminal view: positions / delta / funding / fee
deltafarm flatten # close both legs, return to flatStart on NETWORK=testnet with faucet funds before risking real capital.
Add --paper to any trading command to run the exact same strategy on live
market data while placing nothing on-chain. Orders are simulated against the
real book; positions are tracked in memory only. This is the safe way to evaluate
deltafarm before funding anything:
deltafarm run --paper # simulate both legs off the live book
deltafarm monitor --paper --iters 10 # 10 polls against live data, no ordersIf deltafarm run reports a wide-spread refusal, the order book for one leg is
wider than MAX_SPREAD_BPS (default 50 bps). That's the bot protecting you from a
bad fill — crossing an 8%-wide book to "get filled" is how you lose the edge. Wait
for a tighter book, or raise the cap deliberately if you understand the cost.
The Hyperliquid builder-code requirement is ≥100 USDC of held perps account value — a threshold that stays in your account, not a burned fee. The same ~$100 both satisfies registration and margins a tiny starter pair. Use the standard account abstraction mode.
If you use deltafarm to farm a points or rewards program, you bear the sybil / eligibility risk on your own account. Points programs set and change their own rules; this tool makes no representation that any given account or activity pattern will qualify, and it cannot protect you from a program clawing back or denying points. Farm responsibly and read each program's terms.
.venv\Scripts\pytest -vThe rails core (deltafarm/core) is unit-tested with a fake adapter; the
Hyperliquid SDK calls are mocked. Live network behavior is validated manually in
the rails-proof milestones, and paper mode (--paper) exercises the full
strategy against live data without placing orders.
MIT — see LICENSE. Non-custodial, self-hosted, no warranty; you run
it on your own keys and bear your own trading and points-eligibility risk.