PerpsKit is a unified layer for interacting with on-chain perpetual futures. It provides normalized market data, trading actions, account state, and transaction construction across multiple perpetual DEX protocols and networks.

What PerpsKit Does

• Unified trading actions

  A single action model works across all supported perpetual exchanges: open, close, update-leverage, stop-loss, take-profit, cancel-order, fund, withdraw.

• Cross-protocol, cross-chain coverage

  • Initial integration:
    • Hyperliquid
    • GMX
  • Upcoming integrations:
    • Lighter
    • Drift
    • dYdX v4

• Consistent data structures
  PerpsKit exposes normalized DTOs:

  • MarketDto – metadata and configuration for a market
  • ActionDto – high-level trading intent
  • TransactionDto – unsigned EIP-712 or protocol-specific payloads

• Portfolio & balances
  Unified endpoints for:

  • Open positions
  • Orders
  • Collateral state
  • Margin usage
  • Unrealized PnL

Core Endpoints

Discovery & Metadata

List providers

GET /v1/providers

Returns a list of perpetual providers including:

• providerId
• name and network
• supported actions
• argument schemas
• status flags

List all markets

GET /v1/markets

Returns a complete list of perpetual markets, including:

• marketId
• providerId
• base/quote assets
• leverage range
• fees
• funding rate
• order types
• metadata

List markets for one provider

GET /v1/markets?providerId=hyperliquid

Actions

Execute an action

POST /v1/actions

Example:

{
  "providerId": "hyperliquid",
  "action": "open",
  "address": "0x1234...",
  "arguments": {
    "marketId": "hyperliquid-eth-usdc",
    "side": "short",
    "amount": "43",
    "leverage": 20,
    "orderType": "market"
  }

Returns an ActionDto containing one or more unsigned transactions to sign and submit.

Get an action

GET /v1/actions/{actionId}

Use this to:

• Poll for action progress (created → submitted → confirmed/failed)
• Read the latest transaction states attached to the action

Transactions

Submit a signed transaction

POST /v1/transactions/{transactionId}/submit

This is a per-transaction submit endpoint. The transactionId is returned inside the ActionDto.transactions[] array.

Typical usage:

1. Call POST /v1/actions
2. For each returned transactions[i], sign the payload (EIP-712 or protocol-specific)
3. Submit it via POST /v1/transactions/{transactionId}/submit
4. Poll GET /v1/actions/{actionId} until final state

State & Portfolio

Positions

POST /v1/positions
{
  "address": "0x1234...",
  "perpId": "hyperliquid"
}

Balances

POST /v1/balances
{
  "address": "0x1234...",
  "perpId": "hyperliquid"
}

Orders

POST /v1/orders
{
  "address": "0x1234...",
  "perpId": "hyperliquid"
}

Response Examples

Market Example

{
  "id": "hyperliquid-eth-usdc",
  "perpId": "hyperliquid",
  "baseAsset": "ETH",
  "quoteAsset": "USDC",
  "supportedOrderTypes": ["market", "limit"],
  "supportedMarginModes": ["isolated", "cross"],
  "leverageRange": [1, 50],
  "markPrice": 3950.42,
  "dailyLow24h": 3821.55,
  "dailyHigh24h": 4027.88,
  "dailyVolume24h": 3110000000,
  "makerFee": "0.0002",
  "takerFee": "0.0004",
  "fundingRate": "0.00012",
  "fundingRateIntervalHours": 8,
  "metadata": {
    "name": "ETH-USDC Perpetual",
    "logoURI": "<https://assets.perps.yield.xyz/hyperliquid.svg>",
    "url": "<https://hyperliquid.xyz>"
  }
}

Position Example

{
  "perpId": "hyperliquid",
  "side": "short",
  "size": "0.215",
  "entryPrice": 4000,
  "markPrice": 3975,
  "leverage": 20,
  "marginMode": "isolated",
  "margin": 43,
  "unrealizedPnl": 5.38,
  "liquidationPrice": 4200,
  "takeProfit": 3800,
  "stopLoss": 4100,
  "pendingActions": [
    {
      "type": "close",
      "label": "Close Position",
      "args": { "marketId": "hyperliquid-eth-usdc" }
    }
  ]
}

Order Example

{
  "perpId": "hyperliquid",
  "side": "long",
  "type": "limit",
  "size": "0.5",
  "limitPrice": 3900,
  "triggerPrice": null,
  "reduceOnly": false,
  "createdAt": 1733332000,
  "pendingActions": [
    {
      "type": "cancel-order",
      "label": "Cancel Order",
      "args": { "orderId": "abc123" }
    }
  ]
}

Balance Example

{
  "providerId": "hyperliquid",
  "collateralAsset": "USDC",
  "accountValue": 1280.44,
  "usedMargin": 320.13,
  "availableBalance": 960.31,
  "unrealizedPnl": 12.8,
  "positionsCount": 2
}

Action Example

{
  "id": "action_123abc",
  "perpId": "hyperliquid",
  "action": "open",
  "status": "CREATED",
  "transactions": [
    {
      "id": "tx_001",
      "network": "hyperevm",
      "type": "OPEN_POSITION",
      "signingFormat": "EIP712_TYPED_DATA",
      "signablePayload": { "...": "..." },
      "status": "CREATED"
    }
  ]
}

Transaction Status Example

{
  "txHash": "0x123...",
  "status": "CONFIRMED",
  "blockNumber": 9741123,
  "providerState": "open"
}

Example Flow

1. Discover markets GET /v1/markets
2. Open a position POST /v1/actions
3. Submit transaction POST /v1/transactions/{transactionId}/submit
4. Read updated positions POST /v1/positions

Cross-Chain Orchestration

Where supported:

• Accepts arbitrary input assets
• Computes required swap, bridge, or deposit operations
• Returns all unsigned transactions in sequence

Some providers may have restricted funding support.

Integration Options

Direct API Integration

• GET /v1/perps
• GET /v1/perps/markets
• POST /v1/actions
• POST /v1/transactions/submit
• POST /v1/perps/positions
• POST /v1/perps/balances
• POST /v1/perps/orders
• GET /v1/transactions/status?txHash=...

PerpsKit Widget Integration

The Yield.xyz Perps Widget is a drop-in perpetual futures trading frontend module you can embed in any application to provide users a self-custodial perps trading experience. It’s built with React and designed to feel native inside wallets, exchanges, and fintech apps.

Under the hood, the widget uses the Yield.xyz Perps API to power the full lifecycle:

• Discovers available providers and supported actions
• Retrieves markets, live pricing data, and the user’s portfolio state
• Constructs intent-based actions (open/close/manage positions, update orders, leverage adjustments, TP/SL)
• Returns unsigned transaction payloads for the user to sign
• Submits signed transactions for broadcast and execution

Example Deployments:

Embedded Trading Widget A lightweight widget that can be embedded directly inside an existing product interface (wallets, exchanges, fintech apps). This provides users with a seamless trading experience without requiring them to leave the host application.

Example deployment:

Full Trading Terminal Dashboard A full-featured trading dashboard built to mirror the Hyperliquid terminal experience. It includes richer position management, portfolio analytics, and a professional-grade layout optimized for desktop traders.

This version is ideal for platforms targeting active traders who expect a more advanced interface with deeper market visibility and trading controls.

Example deployment:

Monetization via Builder Codes

Yield supports builder code integration across supported perps protocols (e.g., Hyperliquid, Drift, dYdX), allowing clients to earn a configurable facilitation fee per trade. This markup is transparently included in displayed fees and paid out via each protocol’s builder-code mechanism.

Under this model, Yield embeds a “builder code” into each trade flow, enabling partners to collect a small facilitation fee per trade action. This fee is configurable by clients and is shown transparently to users.

Hyperliquid

• Fees can be set to up to 0.1% on perps.
• Builder Fees are approved via the ApproveBuilderFee action by the user upon the initial interaction.
• Once the authorization is complete, future order actions sent on behalf of the user may include an optional builder parameter: {"b": address, "f": number}.
  • b is the address of the fee recipient
  • f is the builder fee to charge in tenths of basis points

How builder fees are calculated

Key information:

• Fees are charged per fill, and apply to position opens, closes, and partial executions.
• Leverage does not affect the fee. Builder fees are not calculated on margin used by the user, but on the notional value that is traded.
• Builder fees are collected in the collateral asset (USDC). If a position is opened or closed across multiple fills, the builder fee is calculated and charged independently for each fill.

Example

A user deposits $1,000 in collateral and opens a perpetual position using 10x leverage, resulting in $10,000 executed notional. If the configured builder fee is 1 bp and the trade executes in a single fill, the builder fee charged on the opening trade is:

$10,000 * 0.01% = $1.00

If the user later closes the position with $12,000 executed notional, an additional $1.20 builder fee may be charged on the close. If the position is partially closed — for example, $4,000 notional — only $0.40 in builder fees is charged for that fill.