Programmatic trading
What it means to run a bot on a HyperVaults vault, and how it fits together
If you manage a vault, programmatic access lets you trade it with code — market-making, systematic entries, rebalancing, automated stops — the way you'd run a bot against any Hyperliquid account. The difference: the capital lives in a non-custodial on-chain vault, and your bot can only trade it, never move it. That constraint is the whole point, and it shapes how the API works.
The mental model
Four ideas carry everything else.
The vault is the account. Your vault has one Hyperliquid account. Orders act on its positions and balances; you read its state at the vault address. There is no separate "bot account" — the bot operates the vault's account through the gate.
You hold a key to the gate, not a signing key. A bot key is a credential that lets you ask the gate to act. The gate holds the vault's protocol-provisioned agent wallet and signs on your behalf. So a leaked key can place bad trades (a bounded, disclosed risk) but can never withdraw or transfer — it has no signing key to do so. Revoke a key and it's dead on its next request.
The surface is order-only. Every endpoint is an order action — place, modify, cancel, trigger, TWAP, leverage, margin. There is deliberately no transfer or withdraw endpoint. Your bot cannot drain the vault even if its key leaks or its code goes rogue. This is the guarantee your investors rely on, expressed as an API boundary.
Markets are curated. You can trade the perp dexes the protocol curates and, for spot, the tokens the vault has put on its watchlist. A spot buy of an un-declared token is refused until you register it once (a manager wallet transaction); a sell is never gated. This keeps the vault's on-chain accounting honest — nothing un-curated can enter its NAV.
Anatomy of a trading bot
A bot on the gate has the same shape as any trading bot, with two setup steps that are specific to vaults.
Set up once:
- Get a bot key (mint it from the manage page).
- Resolve the numeric asset ids for the markets you trade, from Hyperliquid meta — network-specific.
- Configure perps: set leverage + margin mode per market.
- For spot: register any tokens you'll buy on the vault watchlist.
Then loop:
read state → decide → act → reconcile
(info API) (your edge) (gate) (info API / WS)- Read positions, open orders, fills, and marks from Hyperliquid's info API — the gate is write-only, so all reads go to Hyperliquid directly, addressed to the vault.
- Act by POSTing typed params to the gate; it builds, signs, and submits the Hyperliquid action.
- Reconcile: a modify re-lists an order under a new id; a market order can be rejected inside a success envelope. Read back rather than assume.
Poll modestly (Hyperliquid rate-limits per IP) or subscribe to the WebSocket for live fills and marks.
How this differs from trading Hyperliquid directly
If you've built on Hyperliquid before, this is the delta:
| Trading Hyperliquid directly | Trading a vault through the gate |
|---|---|
| You sign every action with your key | The gate signs with the vault's agent; you send typed params |
| Your key can withdraw and transfer | Order-only — no value-moving endpoint exists |
| One credential, all-or-nothing | Per-vault bot keys you mint and revoke individually |
| Any listed market | Curated dexes; spot buys need watchlist registration |
| Your account | The vault account — read state at the vault address |
| Native dex by default | Builder-dex (HIP-3) reads need the dex param (trap) |
| — | Standing checked on-chain per request: rotate the manager and every key dies |
Everything else — order types, tick/lot rules, funding, liquidations — is Hyperliquid, unchanged. These docs cover the vault layer; the Hyperliquid API docs are the source of truth for the exchange itself.
Start here
- Quickstart — a bot key to your first order, end to end.
- Authentication & errors — keys, sessions, the error model.
- Assets & formatting — get asset ids and price/size formatting right first.
- Actions — all nine endpoints with fields.
- Reading state — positions, orders, fills.