Orders and positions

Units

Field	Unit	Example
`size`	Base asset of the market, decimal string	`"0.25"` BTC on `BTC/USD`
`price`, `sl`, `tp`	Quote currency of the market, decimal string	`"65000.5"`
`leverage`	Multiplier, decimal string	`"10"`
`slippage`	Percent, decimal string	`"1"` means 1 %
`collateral`	Collateral token symbol	`"USDC"`, `"DAI"`, `"WETH"`, `"GNS"` where the chain supports it. Omitted: USDC where the chain lists it, otherwise the chain’s single active collateral (`GET /v1/{chain}/markets` lists `collaterals[]`).

The API derives the collateral amount from size × price / leverage, converted to the collateral token at its USD price. Fills report the executed size, price and collateral in the same units. Precision is published per market in GET /markets: pricePrecision and sizePrecision are the maximum number of decimals. A value with more decimals is rejected with 422 PRECISION_ERROR; nothing is rounded for you. minPositionUsd is the smallest notional the contracts accept.

Order types

`type`	`price`	Behaviour
`market`	optional expected price, defaults to the mark price	Sent to the oracle at once. Filled at the oracle price, bounded by `slippage` around `price`.
`limit`	required trigger price	Rests on-chain. A long triggers when the price falls to `price`, a short when it rises to it.
`stop`	required trigger price	Rests on-chain. A long triggers when the price rises to `price`, a short when it falls to it.

sl and tp attach a stop loss and take profit to the resulting position. reduceOnly: true with a market order closes (fully or partially) the position on the opposite side of the same market instead of opening; there is no reduce-only resting order on Gains, use sl/tp on the position for that.

Signing and broadcasting

Every write answers with a transaction object and never sends anything itself: the agent key (or the trader’s wallet) signs it, pays the gas and broadcasts it. The object is the shape wallets and the 0x or Uniswap trade APIs use, so walletClient.sendTransaction(transaction) is all it takes; the SDK does it for you when it is built with a sender.

{
  "order": { "id": "5316911983139663", "status": "prepared", "expiresAt": 1788857728819, "...": "..." },
  "transaction": {
    "to": "0xFF162c694eAA571f685030649814282eA457f169",
    "data": "0x737b84cd...",
    "value": "0",
    "chainId": 42161,
    "gas": "1807117",
    "expiresAt": 1788857728819
  }
}

value is always zero: fees come out of the collateral. Do not fill a nonce or fee fields, the wallet does. The agent needs ETH on the chain for gas; the API tells you when it cannot estimate (gas: null), which usually means an empty agent.

Lifecycle

POST /orders ──► prepared ──► pending ──► filled
              (you sign and     │           (fill: price, size, collateral, feeCollateral, positionId, txHash)
               broadcast)       ├──► rejected   (reason: SLIPPAGE, EXPOSURE_LIMITS, PRICE_IMPACT, MAX_LEVERAGE, ...)
                                └──► timed_out  (reclaim with DELETE /orders/{id}; reclaimTxHash on the order)

POST /orders (limit, stop) ──► prepared ──► open ──► filled | canceled

prepared, never broadcast before expiresAt ──► expired

POST /orders validates the order, checks the agent scope, simulates it from the agent and answers 201 with the order in prepared state under its final id, plus the transaction to sign and broadcast: to (the Diamond), data, value: "0", chainId, a gas estimate (null when the agent has no ETH yet) and expiresAt. Broadcast it with the agent key, then POST /orders/{id}/submit with the hash: the order becomes pending (market) or open (limit, stop), and the receipt is checked, so a reverted transaction reads rejected. The API watches the chain too: a transaction that lands without the submit call still moves the order on, and if the Diamond assigned another index than predicted the order is re-keyed to it. A prepared order not broadcast before expiresAt reads as expired; prepare it again. The oracle answers within seconds (~60 seconds is the on-chain timeout). Track the id with:

GET /v1/{chain}/orders/{id}, which returns the same object with the current status;
the orders WebSocket channel, which pushes every transition and the fills channel, which pushes fills only;
order.waitForFill() in the SDK, which polls and throws on any terminal state other than filled.

The id is stable for the whole lifecycle and identical on the native API and on the Hyperliquid facade (oid). Once filled, fill.positionId is the id of the open position.

Idempotency

Pass a clientId (up to 64 characters). Re-sending the same order with the same clientId returns the existing order instead of placing a second one; sending a different order with a used clientId answers 409 IDEMPOTENCY_CONFLICT. clientId is part of the signed body, so it cannot be forged.

Rejections

reason on a rejected order is the on-chain cancel reason:

Reason	Meaning
`SLIPPAGE`	The oracle price left the `slippage` band around the expected price.
`EXPOSURE_LIMITS`	The market’s open-interest cap would be exceeded.
`PRICE_IMPACT`	The price impact of the size exceeds the market’s limit.
`MAX_LEVERAGE`	Leverage above the market’s maximum at execution.
`TP_REACHED`, `SL_REACHED`	The attached take profit or stop loss was already past the execution price.
`NO_TRADE`, `WRONG_TRADE`, `NOT_HIT`	Close or trigger requests that no longer match an open trade or a hit trigger.

Anything rejected before the transaction is sent (precision, scope, simulation) comes back as an HTTP error, see Errors, and never creates an order.

Updating and cancelling orders

PATCH /v1/{chain}/orders/{id} prepares the update of a resting limit or stop order: price, sl, tp, slippage. Changing the size means cancel and re-create. PATCH /v1/{chain}/positions/{id} prepares sl, tp, leverage or collateral changes the same way and returns the position with the transaction. DELETE /v1/{chain}/orders/{id} prepares the cancel of a resting order, or the reclaim of a pending market request once the oracle timeout has elapsed (409 ORDER_NOT_MODIFIABLE before that, with reclaimableAtBlock in the details). The agent broadcasts it; the status follows the chain event (canceled, or timed_out with reclaimTxHash). Nobody reclaims for you: a request that timed out keeps its collateral locked until this transaction is sent. A prepared order that was never broadcast is withdrawn without a transaction (transaction: null, status expired).

Positions

GET /v1/{chain}/account/{address}/positions returns every open position with live markPrice, liquidationPrice, unrealizedPnl, fundingFee and borrowingFee, computed with the same SDK math the trading interface uses.

Endpoint	Effect
`POST /positions/{id}/close`	Market close. `size` (base asset) for a partial close, omit for a full close. Returns the prepared close transaction and a `prepared` close order; after broadcast and submit it is `pending` until the oracle fills it.
`PATCH /positions/{id}` with `sl` and/or `tp`	Moves the stop loss and take profit.
`PATCH /positions/{id}` with `leverage`	Changes the leverage; the contracts pull or return collateral to keep the notional.
`PATCH /positions/{id}` with `collateral: {action: "add" \| "remove", amount}`	Adds or removes collateral while keeping the notional, which is the same operation expressed as an amount.

Position ids are derived from the trader and the on-chain trade index, so they are stable across API restarts and match the positionId of the fill that opened them.

Limits worth knowing

Isolated margin only in v1 (onlyIsolated: true on every market).
Position size increases go through POST /orders on the same market and side; the contracts merge them into the existing position.
Markets outside crypto close according to their session (isOpen on the market); orders on a closed market answer 422 MARKET_CLOSED.

Trading API

API Reference

Integrators

Technical Reference

Units

Order types

Signing and broadcasting

Lifecycle

Idempotency

Rejections

Updating and cancelling orders

Positions

Limits worth knowing

​Units

​Order types

​Signing and broadcasting

​Lifecycle

​Idempotency

​Rejections

​Updating and cancelling orders

​Positions

​Limits worth knowing

Units

Order types

Signing and broadcasting

Lifecycle

Idempotency

Rejections

Updating and cancelling orders

Positions

Limits worth knowing