> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Yield.xyz Perps
> Let your users trade perpetual futures on Hyperliquid and other venues with leverage, stop-loss and take-profit, using their Portal wallets and the Yield.xyz integration.
## Overview
Portal integrates with [Yield.xyz Perps](https://docs.yield.xyz) so your users can open and close leveraged long and short positions, manage risk with stop-loss and take-profit orders, and fund and withdraw a trading account on leading perpetual-futures venues (starting with Hyperliquid) with their Portal wallets. Portal proxies the Perps API server-side using the API key you store in the Portal Dashboard, so the key never ships in your app.
Perps uses the same Yield.xyz API key and the same Portal integration as [Yield.xyz](/integrations/Yield/yield-xyz) and [Yield.xyz Borrow](/integrations/Yield/yield-xyz-borrow). If you have already enabled Yield.xyz in the Portal Dashboard, the Perps endpoints below work right away; there is no separate card or key to add.
This page covers how perpetual-futures trading works, the one-time setup in Yield.xyz and the Portal Dashboard, and what the proxied endpoints return.
## How perpetual-futures trading works
A **perpetual future** ("perp") is a leveraged derivative that tracks the price of an asset without ever expiring. A trader posts collateral (**margin**) and takes a position that is larger than that margin by a chosen **leverage**: at 10× leverage, \$100 of margin controls a \$1,000 position. A position is either a **long** (profits when the price rises) or a **short** (profits when the price falls). The definitions below are the terms that appear as API fields, so your UI can render them directly.
* **Venue (`provider`) vs. market.** A **provider** is a trading venue (for example `hyperliquid`); a **market** is one tradable instrument on it (for example ETH-USDC), carrying a `leverageRange` (`[min, max]`), `markPrice`, `oraclePrice`, `fundingRate`, `makerFee`/`takerFee` and `minSize`. Discover venues with `GET /providers` and instruments with `GET /markets`.
* **Collateral and margin.** A user first **funds** a trading account with collateral (typically USDC). `POST /balances` returns the account's `accountValue`, `usedMargin` and `availableBalance`. Each position reserves `margin`; `marginMode` is either `isolated` (margin is fixed per position) or `cross` (positions share the account's collateral).
* **Mark price and liquidation.** `markPrice` is the price the venue uses to value an open position and compute PnL (`unrealizedPnl`). If the price moves against the position far enough that its margin can no longer cover the loss, the venue **liquidates** it at its `liquidationPrice`, closing the position and taking the margin. Higher leverage moves `liquidationPrice` closer to the entry price.
* **Funding rate.** Perps have no expiry, so venues use a periodic **funding** payment between longs and shorts to keep the perp price near the spot price. `fundingRate` and `fundingRateIntervalHours` describe it; it is a recurring cost or credit of holding a position, not a one-time fee.
* **Orders.** A position can be opened at the current price (a `market` order) or at a chosen price (a `limit` order). `stop_loss` and `take_profit` orders close a position automatically when the price hits a `triggerPrice`, which is how a user caps a loss or locks in a gain. Orders can be `reduceOnly` (they only shrink an existing position).
* **Venue approvals.** Some venues execute trades through an **agent wallet** that the user authorizes once (`approveAgent`), and may require a one-time builder-fee approval (`approveBuilderFee`). On Hyperliquid, orders are then signed as EIP-712 typed data rather than as on-chain transactions — see the [guide](/apis/enclave-mpc/guide/yield-xyz-perps) for the signing flow.
Perpetual futures are high-risk leveraged products. Leverage amplifies losses as much as gains, and an adverse price move can liquidate a position — losing its entire margin — within minutes. Portal proxies the venue's decisions and adds **no** trading guardrails (no leverage caps, no confirmations, no liquidation warnings): those belong in your UI. A trade action (`open`, `close`, `updateLeverage` and the like) returns a `summary`; where present, show its fields such as `estimatedLiquidationPrice`, `leverage` and `collateral` before the user signs (non-trade actions such as `fund` or `approveAgent` carry a simpler summary or none).
### Why offer it
* **Leveraged trading without leaving your product.** Users who want to trade perps otherwise withdraw to an external venue. With this, positions and collateral live in the wallet you already manage, and the trading activity stays in your product.
* **A new revenue and engagement surface.** Perps trading is active and recurring, unlike a one-time swap or a passive yield position.
* **Same integration as earning and borrowing.** Yield.xyz's perps venues are enabled with the same account, the same API key and the same Portal Dashboard toggle you already use for yield and lending.
## Steps to enable perps
Perps runs through the same Yield.xyz account, API key and Portal integration as yield and lending. If you have already enabled Yield.xyz, you are done — skip to [Endpoints](#endpoints). Otherwise, follow the one-time setup on the [Yield.xyz integration page](/integrations/Yield/yield-xyz#steps-to-enable-the-portal-yield-xyz-integration):
1. Create or access your Yield.xyz account and generate an API key per Portal environment (`Development` and `Production`). The same key covers Yield, Borrow and Perps.
2. In the [Portal Dashboard](https://app.portalhq.io), open `Integrations`, find `Yield.xyz` under `Yield`, add it, and paste your API key for the selected Portal environment.
Portal validates the key against Yield.xyz when you save it, then proxies your SDK/API calls to the Perps API using this key from Portal's servers.
Integrations are environment-scoped. Repeat the setup for each Portal environment (for example Development and Production).
**There is no testnet for perps.** The Yield.xyz Perps API is production-only: there is no sandbox host and no testnet venue, and `POST /api/v3/clients/me/fund` (Portal's testnet faucet) does not apply. Every action is real money on mainnet. Validate with the venue's minimum notional (roughly \$10 on Hyperliquid), funded with real USDC.
**Perps require a Portal client *without* [account abstraction](/resources/account-abstraction) (`isAccountAbstracted: false`).** An AA client's wallet is a smart-contract address, but Hyperliquid — the launch venue — verifies every action by recovering the signer from an EIP-712 signature and acts on the recovered EOA. A deposit from an AA wallet is therefore credited to an address that can never sign, so the funds can be neither traded nor withdrawn. Do not send perps write requests (`fund`, `open`, `close`, `withdraw` and the like) from an account-abstracted client.
## Endpoints
All endpoints live under `https://api.portalhq.io/api/v3/clients/me/integrations/yield-xyz-perps` and accept a Client API Key or Client Session Token as a bearer token. Every success response is wrapped as `{ "data": ... }`.
**Discovery**
| Method | Path | What it does |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------ |
| `GET` | `/providers` | List trading venues, their supported actions and the argument schema for each action |
| `GET` | `/providers/{providerId}` | Details for one venue |
| `GET` | `/markets` | Paginated markets with mark/oracle price, funding rate, leverage range and fees |
| `GET` | `/markets/{marketId}` | One market |
| `GET` | `/markets/{marketId}/candles` | OHLCV price history for charting |
**Portfolio**
| Method | Path | What it does |
| ------ | ------------ | ---------------------------------------------------------------------------------------------------------------- |
| `POST` | `/positions` | Open positions (size, entry/mark price, leverage, margin, PnL, liquidation) for an address on one or more venues |
| `POST` | `/orders` | Resting limit and trigger orders for an address |
| `POST` | `/balances` | Account collateral and margin (`accountValue`, `usedMargin`, `availableBalance`) on a venue |
**Actions**
| Method | Path | What it does |
| ------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/actions` | Build unsigned transaction(s) for `open`, `close`, `updateLeverage`, `stopLoss`, `takeProfit`, `setTpAndSl`, `cancelOrder`, `editOrder`, `updateMargin`, `fund`, `withdraw`, `approveAgent`, `approveBuilderFee` or `setUnifiedAccount` |
| `GET` | `/actions` | Paginated actions for an address |
| `GET` | `/actions/{id}` | One action with its transactions and status |
**History**
| Method | Path | What it does |
| ------ | -------------- | ---------------------------------------------------------------------------------------------------------- |
| `GET` | `/activity` | Unified feed of an address's actions and lifecycle events, newest first |
| `GET` | `/events` | Paginated lifecycle events (`order_filled`, `liquidation`, `stop_loss_triggered`, `take_profit_triggered`) |
| `GET` | `/events/{id}` | One event |
**Transactions & health**
| Method | Path | What it does |
| ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `POST` | `/transactions/{transactionId}/submit` | Submit a signed payload for the venue to broadcast, or report a transaction hash you broadcast yourself |
| `GET` | `/health` | Yield.xyz Perps API health |
| `GET` | `/health/providers` | Per-venue health |
### Typical flow
`hyperliquid` is used as the example venue throughout this page. The venues available to you are whatever `GET /providers` returns — start there and use those `providerId` values rather than hard-coding one, so a venue Yield.xyz adds later works with no change on your side.
1. `GET /providers`, then `GET /markets?providerId={providerId}` (for example `hyperliquid`) to discover what your user can trade.
2. Fund the trading account and complete any one-time venue approvals the venue requires (on Hyperliquid, approve the agent wallet). Both are `POST /actions` actions (`fund`, `approveAgent`). A `fund` action reaches `SUCCESS` on source-chain confirmation, not when the collateral credits on the venue — see [the guide's note](/apis/enclave-mpc/guide/yield-xyz-perps#funding-a-trading-account-and-approving-the-venue) on polling `POST /balances` before showing a funded state.
3. `POST /actions` with the venue, the action (for example `open`) and its `args` (`marketId`, `side`, `size`, `leverage`, `marginMode`). The response contains one or more `transactions`, each with a `signablePayload` and a `signingFormat`.
4. Sign each transaction with the Portal SDK or Enclave MPC API, then `POST /transactions/{transactionId}/submit` with the `signedPayload` (or the `transactionHash` if you broadcast it yourself).
5. `POST /positions`, `POST /orders` and `POST /balances` to show the resulting position, resting orders and account balance.
```bash theme={null}
# 1. Open a 10x long on ETH-USDC
curl --request POST \
--url 'https://api.portalhq.io/api/v3/clients/me/integrations/yield-xyz-perps/actions' \
--header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
--header 'Content-Type: application/json' \
--data '{
"providerId": "hyperliquid",
"address": "0x1234...",
"action": "open",
"args": {
"marketId": "hyperliquid-eth-usdc",
"side": "long",
"size": "1000",
"leverage": 10,
"marginMode": "isolated"
}
}'
# 2. Read the resulting position back
curl --request POST \
--url 'https://api.portalhq.io/api/v3/clients/me/integrations/yield-xyz-perps/positions' \
--header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
--header 'Content-Type: application/json' \
--data '{ "providerId": "hyperliquid", "address": "0x1234..." }'
```
[Alert Webhooks](/resources/alert-webhooks) fire only for the **on-chain legs** of perps: the source-chain approval and fund transactions, and the Arbitrum withdrawal arrival — all delivered as `EVM Wallet Transactions` events. Hyperliquid L1 actions (`open`, `close`, agent and builder-fee approvals) are off-chain EIP-712 messages, not on-chain transactions, so they produce **no** webhook. Track those with `GET /activity` and `GET /events` instead.
## Chain identifiers
Perps is **venue-centric**, not chain-centric, so identifiers work differently than in the rest of Portal:
* **`providerId` is a venue slug** (for example `hyperliquid`), not a [CAIP-2 chain id](/resources/chain-id-formatting). It is passed through unchanged in both directions. A venue is not a blockchain, so do not treat it like one.
* **A real chain appears only where funds settle** — for example a funding source (`args.fromToken.network`) or an on-chain approval/funding transaction's `network`. There, Portal uses CAIP-2: pass `network` as CAIP-2 (`eip155:42161` for Arbitrum) and Portal translates it to the Yield.xyz network name; `network` values in responses are translated back to CAIP-2. A request naming a chain Portal does not support is rejected with a `400` before it reaches Yield.xyz.
* Each transaction also carries a `chainId` string, kept as the venue returns it because it is load-bearing for EIP-712 signature verification. Do not confuse it with the CAIP-2 `network`.
### Funding sources and limits
Funding, withdrawals and orders route through the venue, so their supported chains and minimums are the venue's, not Portal's. On Hyperliquid:
* **Fund sources are EVM chains only.** USDC on Arbitrum funds via `bridge2`; other EVM chains and native tokens route via `lifi`. Solana and Tron are **not** supported fund sources — Hyperliquid has no USDC deposit route from them, so the Yield.xyz Perps API rejects them with `400 EXECUTE_INVALID_ARGUMENT`.
* **Withdrawals return USDC on Arbitrum only**, to the signing address, with a flat \$1 fee and a 2 USDC minimum. See [Hyperliquid's docs](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/bridge2).
* **`bridge2` deposits below 5 USDC are not credited and are lost.** Enforce the 5 USDC floor in your UI before funding.
* **Orders have a \$10 minimum notional.** An order below it is rejected by the venue.
These are Hyperliquid's current limits; confirm them against [Hyperliquid's docs](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/bridge2), and read a venue's own constraints from `GET /providers`.
## Errors
Yield.xyz Perps errors are returned as Portal errors:
* `400`: invalid request (the message names the field), an unsupported chain id, a precondition the venue rejected (for example insufficient margin), a request Yield.xyz rejected, or a Yield.xyz API key that is missing or was rejected. When the venue returns a machine-readable code, Portal surfaces it as `details.code` so your SDK can branch on it programmatically. The venue's free-text reason is logged server-side only and is not returned to the caller.
* `404`: unknown market, venue, action, event or transaction id
* `429`: Yield.xyz rate limit hit; back off and retry
* `503`: Yield.xyz is unreachable or failed upstream
* `500` with `id: INTEGRATION_RESPONSE_SCHEMA_DRIFT`: Yield.xyz changed a response shape and Portal did not forward it. Treat it as a temporary outage of that feature; see [Error codes](/resources/error-codes)
Response enumerations (action, order, transaction and event types and statuses) may gain values over time; treat values you do not recognize as opaque rather than failing.
## Guides
* [Trade perps with Yield.xyz](/apis/enclave-mpc/guide/yield-xyz-perps) using the Enclave MPC API
## API reference
Open the interactive Yield.xyz Perps endpoints reference.
Need some advice on legal disclaimers when offering leveraged trading? Check out [Yield.xyz's disclaimer guidelines here](https://stakekit.notion.site/Yield-Disclaimer-Index-2a35318e934e806f863fecea64be38a8).