Yield.xyz Perps

​

Overview

​

How perpetual-futures trading works

• 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 for the signing flow.

​

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

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, open Integrations, find Yield.xyz under Yield, add it, and paste your API key for the selected Portal environment.

​

Endpoints

​

Typical flow

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

# 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..." }'

​

Chain identifiers

• providerId is a venue slug (for example hyperliquid), not a CAIP-2 chain id. 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

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

​

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

​

Guides

• Trade perps with Yield.xyz using the Enclave MPC API

​

API reference