Perps

Open, manage, and track perpetual futures positions on Hyperliquid through the Perps API.

The Perps API opens, manages, and closes perpetual futures positions and reports portfolio state. It is a dedicated API, separate from the Yield API and the Borrow API.

Perps trading carries jurisdictional restrictions. Read the perpetuals disclaimer before integrating.

Providers

Two provider IDs are live today, both settling on Hyperliquid with USDC collateral:

Provider ID	What it is
hyperliquid	Hyperliquid’s main perpetual dex
hyperliquid-xyz	The HIP-3 builder-deployed “xyz” market set on Hyperliquid, listed under its own provider ID

hyperliquid-xyz markets are perpetual contracts on Hyperliquid, including ones that track an equity’s price. They are not share ownership and are not part of Tokenized Stocks.

Retrieve the live provider list, including each provider’s supportedActions and per-action argument schemas, with GET /v1/providers. Enablement is per project: your project may not have every provider or action turned on.

Markets

GET /v1/markets lists tradeable markets, filterable by providerId. A market ID follows the pattern {providerId}-{coin}-{quote}. Each market carries leverage, margin-mode, price, funding, size, and fee fields; see Core concepts for what each means.

Actions

Every action is requested through POST /v1/actions with a providerId, the user’s address, an action name, and its args. The action groups:

Group	Actions
Positions	open, close
Risk	updateLeverage, updateMargin
Orders	stopLoss, takeProfit, setTpAndSl, editOrder, cancelOrder
Account	fund, withdraw, approveAgent, approveBuilderFee, setUnifiedAccount

An open action takes a marketId, a side (long or short), either an amount (margin) or a size (notional), and a leverage within that market’s leverageRange. Omit limitPrice for a market order, or set it for a limit order. marginMode selects cross or isolated margin and cannot change while the position is open.

fund deposits collateral from args.fromToken on another chain: native USDC on Arbitrum bridges directly through Hyperliquid’s Bridge2, anything else routes through LI.FI.

A provider’s actual supportedActions and argument schemas come from GET /v1/providers: treat that response as authoritative for what your project can call.

Sign and submit

Each action returns one or more transactions, each with a signingFormat. Hyperliquid venue actions use EIP712_TYPED_DATA; Arbitrum funding transactions use EVM_TRANSACTION. Sign and submit the transactions in the order returned, then poll the action:

1. Sign each transaction’s signablePayload.
2. Submit each signed payload with POST /v1/transactions/{transactionId}/submit, in order.
3. Poll GET /v1/actions/{id} until the action reaches a terminal status.

An action can prepend transactions you didn’t ask for: an APPROVE_BUILDER_FEE transaction when your approved max builder fee is below the builder fee applied to the order, and, on an open where your project has unified accounts enabled and the account is still eligible to switch, a SET_USER_ABSTRACTION transaction that switches the account to unified mode. Sign and submit whatever the response returns, in order.

See Perps API reference for the full request and response shapes, and Quickstart for a worked open-position walkthrough. For a step-by-step build, see the Perps guide.

Positions, orders, and balances

Track portfolio state with POST /v1/positions, POST /v1/orders, and POST /v1/balances. Positions and orders carry a pendingActions array you can pass straight back into POST /v1/actions. Read GET /v1/events for fills, liquidations, and stop-loss/take-profit triggers, and GET /v1/activity for a combined activity feed. Core concepts explains the fields each response returns.

Geo-restrictions

POST /v1/actions checks the caller’s IP against banned regions and returns 403 when blocked. It also returns 403 (EXECUTE_FORBIDDEN) when your project is disabled for the provider or for Perps. See Geo-blocking for how bans are configured and Perps API objects for error codes.

Monetization

Perps actions can carry a builder fee of 1 to 10 bps, configured per project. See Monetization.

Next steps

Quickstart

Open a position end to end: find a market, open, sign, submit, check positions.

Core concepts

Markets, orders, and positions: the fields you’ll read back from every response.

Perps widget

Coming soon: an embeddable perps trading UI.

Perps dashboard

Coming soon: a full perps trading dashboard.

Perps API reference

Every endpoint, argument schema, and response field.

Perpetuals disclaimer

Jurisdictional restrictions that apply to perps trading.