Hyperliquid compatibility

The facade at https://api.gains.trade/hl/{chain} (https://api-testnet.gains.trade/hl/arbitrum-sepolia on testnet, wss://api.gains.trade/hl/{chain}/ws for the stream) speaks Hyperliquid’s POST /info, POST /exchange and WebSocket protocol, verifies Hyperliquid’s own signing scheme, and forwards to the native Gains API. It never renames a Hyperliquid field. Gains-only information appears as extra fields that a Hyperliquid client ignores.

Only the subset that integrators actually use is implemented. Anything else returns a Hyperliquid-shaped empty result or error, never a different schema.

Before the first order

approveAgent (user-signed, HyperliquidTransaction:ApproveAgent) registers the agent with full trading scope. The response is Hyperliquid’s {"status":"ok","response":{"type":"default"}} plus one extra field, delegationTx.
The master wallet sends delegationTx (setTradingDelegate(relayer) on the Gains Diamond, once per chain). Until it is mined, L1 actions answer {"status":"err","response":"L1 error: API Wallet 0x... is not yet the on-chain delegate of its user. ..."} with delegationTx repeated.
The master wallet approves the Diamond for USDC once.

This on-chain step does not exist on Hyperliquid and cannot be hidden: Gains is non-custodial and the delegation is the trader’s own transaction. The facade is the one place Gains relays and pays gas, because Hyperliquid SDKs only sign typed data; native integrations broadcast their own transactions. hyperliquidChain may be Mainnet or Testnet: an SDK pointed at a custom base URL signs as Testnet, and the facade accepts it.

Conventions

Hyperliquid	On the facade
Asset id `a`	The Gains `pairIndex`, identical to `meta.universe` index.
`coin`	`BTC`, `ETH`, … for USD-quoted markets; `EUR-JPY` style for other quotes.
`szDecimals`	`min(sizePrecision, 6)` of the market. Prices are accepted up to the market’s `pricePrecision`; more decimals answer the Hyperliquid error `Price must be divisible by tick size.`.
Nonce	Millisecond timestamp, unique per agent, inside the Hyperliquid window (2 days back, 1 day ahead).
`oid`	The native order `id` as a number. The same id works on `GET /v1/{chain}/orders/{id}`.
Leverage	Set with `updateLeverage` per asset before ordering. Unset means the market’s minimum leverage. Cross (`isCross: true`) answers an error.
Collateral	USDC.

`POST /info`

`type`	Backed by	Notes
`meta`, `metaAndAssetCtxs`	`GET /markets`, prices, 24 h trades	`marginTables` has one table per distinct max leverage; `onlyIsolated: true`, `marginMode: "noCross"` on every asset. `dayNtlVlm` and `dayBaseVlm` from the last 24 h of executed trades; `openInterest` in base units; `funding` is the hourly long rate as a fraction.
`allMids`	`GET /prices`	Mark prices.
`l2Book`	`GET /markets/{symbol}/book`	The virtual book, 20 levels per side, `n: 1` on every level. `nSigFigs` and `mantissa` are accepted and ignored.
`candleSnapshot`	`GET /markets/{symbol}/candles`	Intervals `1m 5m 15m 30m 1h 4h 1d`; others return `[]`. `v: "0.0"`, `n: 0`.
`clearinghouseState`	account + positions	Isolated positions in `assetPositions[]`; `crossMarginSummary` zeroed; `withdrawable` is the wallet balance in collateral.
`openOrders`, `frontendOpenOrders`	`GET /account/{address}/orders`	Pending market requests are listed with `orderType: "Market"`.
`userFills`, `userFillsByTime`	`GET /account/{address}/fills`	500 most recent; `fee: "0.0"` (fees are in `closedPnl`), `startPosition: "0.0"`.
`orderStatus`	`GET /orders/{id}`	`oid` as number or cloid. Statuses: `pending`, `open`, `filled`, `rejected`, `timedOut`, `canceled`. `pending` and `timedOut` do not exist on Hyperliquid.
`historicalOrders`	order history	Orders placed through the API.
`userFunding`		Always `[]` in v1.
`fundingHistory`	`GET /markets/{symbol}/funding`	One entry with the current rate.
`userRateLimit`, `userFees`, `referral`	gateway, fee tier, referrer	Shapes preserved, values from Gains.
`spotMeta`, `spotClearinghouseState`		`{"tokens":[],"universe":[]}` and `{"balances":[]}`.
`subAccounts`, `vaultDetails`		`null`, as Hyperliquid returns when there are none.

Unknown type answers 422 with the text Failed to deserialize the JSON body into the target type, like Hyperliquid. An unknown coin answers 200 with null.

`POST /exchange`

Envelope {action, nonce, signature, vaultAddress?, expiresAfter?}. L1 actions are hashed exactly as the Hyperliquid Python SDK does (msgpack of the action in key order, nonce, vault marker, optional expiresAfter) and verified as the phantom agent Agent{source, connectionId} on chain id 1337, source a on mainnet chains and b on testnet. User-signed actions use the HyperliquidSignTransaction domain with the client’s signatureChainId. The verification is tested against the official SDK’s signing vectors.

`action.type`	Native call	Notes
`order`	`POST /orders`	`Ioc`/`FrontendMarket`, or `Gtc` at a marketable price, become market orders with `slippage` derived from `p`. Non-marketable `Gtc` becomes a limit order; `Alo` at a marketable price answers the post-only error. `t.trigger` with `r: true` or `grouping: positionTpsl` sets the position’s SL or TP; a non-reduce-only trigger becomes a stop order. `c` is the `clientId`.
`cancel`, `cancelByCloid`	`DELETE /orders/{id}`	`f` accepted.
`modify`, `batchModify`	`PATCH /orders/{id}`	Price only; size changes answer an error.
`updateLeverage`	preference + `PATCH /positions/{id}`	Stored per asset for later orders; applied to an open position on that asset. `isCross: true` answers an error.
`updateIsolatedMargin`	`PATCH /positions/{id}`	`ntli` in USDC millionths, positive adds, negative removes.
`approveAgent`	`POST /agents`	Full scope, name and `valid_until` expiry honoured.
`approveBuilderFee`, `setReferrer`, `scheduleCancel`		Accepted, answer `default`. Dead man’s switch is not enforced in v1.
`twapOrder`, `twapCancel`		`{"status":"err","response":"TWAP orders are not supported yet on Gains."}`
`usdSend`, `withdraw3`, `spotSend`, `usdClassTransfer`, `sendAsset`, vaults, sub-accounts		`{"status":"err","response":"Gains is non-custodial: ..."}`. Funds never leave the wallet.

Responses

Order statuses use Hyperliquid’s shapes with one addition for the oracle step:

{"status":"ok","response":{"type":"order","data":{"statuses":[
  {"pending":{"oid":5316911983139663,"txHash":"0x...","cloid":"0x..."}},
  {"resting":{"oid":5316911983139664}},
  {"error":"Order must have minimum value of $10."}
]}}}

filled appears on orderStatus and orderUpdates once the oracle answers, never synchronously: a market order on Gains is pending for a few seconds.

WebSocket

{"method":"subscribe","subscription":{...}}, unsubscribe, ping/pong ({"channel":"pong"}) and post (info and action) as on Hyperliquid. Subscriptions: allMids, l2Book, bbo, trades, candle, activeAssetCtx, orderUpdates, userEvents (delivered on channel user), userFills (with isSnapshot), userFundings (empty snapshot), notification, clearinghouseState, openOrders. webData2/webData3, twapStates, userNonFundingLedgerUpdates, activeAssetData, spot and vault channels are not available. orderUpdates carries status: "pending" then filled or timedOut.

Differences at a glance

	Hyperliquid	Facade
Execution	Matching engine, synchronous fill	Oracle fill within seconds; `pending` first
Agent approval	`approveAgent` only	`approveAgent` plus one on-chain `setTradingDelegate` by the master wallet
Cross margin, vaults, sub-accounts, spot, transfers, TWAP	Yes	No (isolated only; custody stays in the wallet)
Book	Real	Virtual, from depth bands
`userFunding` history	Yes	Empty in v1
Rate limits	Address-based on volume	Per IP and per agent, see Errors and limits

Trading API

API Reference

Integrators

Technical Reference

Hyperliquid compatibility

Before the first order

Conventions

`POST /info`

`POST /exchange`

Responses

WebSocket

Differences at a glance

​Before the first order

​Conventions

​POST /info

​POST /exchange

​Responses

​WebSocket

​Differences at a glance

Before the first order

Conventions

`POST /info`

`POST /exchange`

Responses

WebSocket

Differences at a glance