Core concepts

Read a Perps market, order, and position back correctly before you build on top of them.

Every Perps response is built from three objects: a market you trade, an order or action you request, and a position that results. This page explains the fields you need to interpret them. For the full request and response shapes, see the Perps API reference.

Markets

A market ID follows the pattern {providerId}-{coin}-{quote}, for example a Hyperliquid ETH market against USDC. GET /v1/markets and GET /v1/markets/{marketId} return:

Field	Meaning
baseAsset / quoteAsset	The traded asset and its settlement asset
leverageRange	[min, max] leverage the market allows
supportedMarginModes	Which of cross and isolated the market supports
markPrice / oraclePrice	Current mark price and the oracle/index price it’s checked against
fundingRate / fundingRateIntervalHours	Current funding rate and how often it settles
minSize	Minimum position size in USD notional
makerFee / takerFee	Maker and taker fee rates charged by the venue

Fetch markets live rather than caching them: mark price, oracle price, and funding rate change continuously.

Orders and actions

An order has a side (long or short), a type (market, limit, stop_loss, or take_profit), and a reduceOnly flag that restricts it to shrinking an existing position rather than opening or growing one. Providing limitPrice on an open places a limit order; omitting it executes at market.

Requesting an action (open, close, updateLeverage, and the rest listed in Perps) returns one or more transactions to sign and submit. Each transaction moves through its own lifecycle, and the action as a whole moves through its own:

• Transaction status: CREATED, QUEUED, BROADCASTED, CONFIRMED, FAILED, NOT_FOUND.
• Action status: shared with the rest of yield.xyz’s action model; poll GET /v1/actions/{id} until it reaches a terminal state.

An open order or position can carry pendingActions: an array of actions available on it right now (for example, closing a position or canceling an order), each with its own pre-filled args. Pass one straight back into POST /v1/actions instead of re-deriving its arguments yourself.

Positions

POST /v1/positions returns each open position:

Field	Meaning
side	long or short
size	Position size in the base asset
entryPrice / markPrice	Average entry price and current mark price
leverage / marginMode	Current leverage and cross or isolated margin
margin	Margin currently allocated to the position
unrealizedPnl	Price PnL, excluding funding
funding	Net funding received or paid since the position opened
liquidationPrice	Price at which the position is liquidated
pendingActions	Actions available on this position right now

POST /v1/balances returns account-level state for a single provider: accountValue (total account value in the collateral asset), usedMargin (margin committed to open positions), and availableBalance (margin free for new positions).

Next steps

Perps

Providers, the action model, signing, and monetization.

Perps API reference

Full field-by-field schemas for markets, orders, positions, and balances.