> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/perps-api/discovery/list-markets).

## 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](/documentation/trade/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

<Columns cols={2}>
  <Card title="Perps" icon="chart-candlestick" href="/documentation/trade/perps">
    Providers, the action model, signing, and monetization.
  </Card>

  <Card title="Perps API reference" icon="code" href="/api-reference/perps-api/portfolio/get-positions">
    Full field-by-field schemas for markets, orders, positions, and balances.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.