> ## 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.

# 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.

<Warning>
  Perps trading carries jurisdictional restrictions. Read the [perpetuals disclaimer](/legal/perpetuals-disclaimer) before integrating.
</Warning>

## 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](/documentation/trade/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](/documentation/trade/core-concepts/index#markets) 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.

<Note>
  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.
</Note>

See [Perps API reference](/api-reference/perps-api/actions/execute-action) for the full request and response shapes, and [Quickstart](/documentation/get-started/quickstart#perps-api) for a worked open-position walkthrough. For a step-by-step build, see the [Perps guide](/guides/perps/index).

## 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](/documentation/trade/core-concepts/index) 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](/documentation/advanced-setup/geo-blocking/index) for how bans are configured and [Perps API objects](/api-reference/perps-api/objects) for error codes.

## Monetization

Perps actions can carry a builder fee of 1 to 10 bps, configured per project. See [Monetization](/documentation/trade/monetization).

## Next steps

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/documentation/get-started/quickstart#perps-api">
    Open a position end to end: find a market, open, sign, submit, check positions.
  </Card>

  <Card title="Core concepts" icon="shapes" href="/documentation/trade/core-concepts/index">
    Markets, orders, and positions: the fields you'll read back from every response.
  </Card>

  <Card title="Perps widget" icon="window" href="/guides/widgets-dashboard/perps-widget">
    Coming soon: an embeddable perps trading UI.
  </Card>

  <Card title="Perps dashboard" icon="chart-line" href="/guides/widgets-dashboard/perps-dashboard">
    Coming soon: a full perps trading dashboard.
  </Card>

  <Card title="Perps API reference" icon="code" href="/api-reference/perps-api/discovery/list-markets">
    Every endpoint, argument schema, and response field.
  </Card>

  <Card title="Perpetuals disclaimer" icon="triangle-exclamation" href="/legal/perpetuals-disclaimer">
    Jurisdictional restrictions that apply to perps trading.
  </Card>
</Columns>


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