Perps API

Perps API Overview

The Perps API is the same backend the HyperFlow app trades through. It gives you programmatic access to markets, order placement, account state, and transfers.

The Perps API is in alpha: it serves the invite-gated alpha at alpha.hyperflow.fun/perps, endpoints and schemas may change without notice, and the base URL will change when perps reaches general availability. Trading through the API requires an alpha account like trading through the app.

Base URL: https://alpha-api.hyperflow.fun/api/v1

Integration at a glance

Four steps: 1 Enable trading (POST /auth/register — main wallet authorizes an agent, once), 2 Deposit (spot transfer, poll deposit-history), 3 Trade (POST /orders, cancel, modify, margin), 4 Withdraw (POST /account/withdraw, poll withdrawal-history).

The pages in this section

Authentication & Signing

Trading keys, the EIP-712 domain, and the exact typed-data schemas.

Orders

Submit, cancel, modify — including trigger (TP/SL) orders and batching.

Account Data

Balance, positions, open orders, history, and margin adjustments.

Deposits & Withdrawals

Funding config, deposit tracking, and signed withdrawals.

Response envelope

Every endpoint wraps its payload in the same envelope:

1{ "success": true, "data": { "...": "..." }, "timestamp": 1787067314951 }

Errors return success: false with an error object:

1{ "success": false, "error": { "code": "...", "message": "..." }, "timestamp": 1787067314951 }
  • timestamp is Unix milliseconds.
  • Prices, sizes, and amounts are decimal strings ("0.00159", "2000") — never floats. (Non-monetary ratios like /config’s trader_share are plain JSON numbers.)

The account model

Your API identity is a 32-byte account id derived from your wallet:

account_id = <20-byte wallet address> + <11 zero bytes> + <1-byte subaccount index>

Index 0 is the default account, so for wallet 0xAbC…123 the account id is the lowercase wallet followed by 24 hex zeros:

1const accountId = (wallet.toLowerCase() + "00".repeat(11) + "00") as `0x${string}`;

Some endpoints key by the 32-byte account_id, others by the 20-byte wallet — each endpoint’s docs state which.

Authentication model

There is no transport-level auth — no API keys, no bearer tokens. Instead:

  • Reads are open, keyed by wallet or account id. This matches Hyperliquid’s model: any wallet’s balances, positions, and history are publicly readable on the underlying venue, and HyperFlow keeps parity rather than pretending otherwise.
  • Writes are signed: every state-changing request carries an EIP-712 signature in the body, plus a single-use millisecond nonce. The server recovers the signer from the signature — see Authentication & Signing.

Market data

HyperFlow does not proxy market data — read it from Hyperliquid’s public API, which is the venue of execution:

DataSource
Order bookHL WebSocket l2Book subscription
TradesHL WebSocket trades subscription
CandlesHL REST POST /info {"type": "candleSnapshot", ...}
Mark / oracle price, funding rateHL WebSocket activeAssetCtx
Market config (fees, tick size, leverage, limits)HyperFlow GET /markets

Hyperliquid endpoints: https://api.hyperliquid.xyz (REST) and wss://api.hyperliquid.xyz/ws (WebSocket) — see the Hyperliquid API docs.

GET /markets

Static per-market configuration. Live response (trimmed):

1{
2  "data": [{
3    "symbol": "BTC",
4    "hl_symbol": "BTC",
5    "hl_asset_index": 0,
6    "max_leverage": 20,
7    "initial_margin_ratio": "0.025",
8    "maintenance_margin_ratio": "0.015",
9    "maker_fee_rate": "0.00015",
10    "taker_fee_rate": "0.00045",
11    "min_order_value": "10",
12    "max_notional": "2000",
13    "max_open_orders": 20,
14    "tick_size": "1",
15    "sz_decimals": 5,
16    "px_decimals": 1,
17    "is_active": true
18  }],
19  "success": true,
20  "timestamp": 1787067314951
21}

Practical limits

LimitValue
Orders per batch (POST /orders)20
Cancels per batch (POST /orders/cancel-batch)20
limit on paginated readsmax 200
Open orders per market20 (from GET /markets)
Per-order notional$10 min · $2,000 max (alpha)

Next: Authentication & Signing