PerpsKit

Unified perpetual futures infrastructure — API, widget, and dashboard for venue-aggregated perps trading.

PerpsKit

PerpsKit is Yield.xyz’s modular infrastructure for on-chain perpetual futures (“perps”). It aggregates perp venues behind a normalized interface so wallets, exchanges, and fintech apps can launch perps trading with minimal engineering lift — while keeping execution self-custodial.

PerpsKit provides:

• A unified model for markets, portfolio state, and trading actions
• Transaction construction that returns ordered, unsigned payloads for client-side signing
• Flexible monetization via builder codes / partner fee logic (venue-dependent)
• Operational controls for production deployments, including configurable geo-restrictions

Perps API Reference

Endpoints, schemas, and examples

Getting Started

Quick integration flow

---

Integration modes

Widget

An embeddable, production-ready trading UI you can drop into your product.

Best for: teams that want to launch fast with minimal frontend engineering.

Typical capabilities:

• Market discovery and trade entry
• Position management (open/close)
• Order placement (venue-dependent)
• Portfolio views (positions, balances, PnL)

API

A unified API for integrating perps into your own UI and workflows.

Best for: teams building a native trading experience or integrating into an existing “Trade” surface.

What you get:

• Normalized market metadata and real-time data primitives
• A consistent action model across venues
• Transaction construction for deterministic signing flows

Dashboard

A configurable desktop trading experience designed to feel familiar to active traders and easy to tailor for partners.

Best for: partners that want a full-featured perps surface with lower frontend maintenance, plus admin configuration (enabled venues, fee settings, reporting).

---

What PerpsKit standardizes

Markets

Market metadata and venue-specific constraints (order types, margin modes, leverage ranges, fees, funding).

Portfolio state

Positions, orders, collateral, margin usage, and unrealized PnL in a consistent shape across venues.

Trading actions

A unified action model (open/close/update leverage/stop-loss/take-profit/cancel/fund/withdraw) mapped to venue execution.

Unsigned transaction construction

One or more ordered, unsigned payloads you route into your signing stack (EOA, smart accounts, MPC, custody).

Perps venues have venue-specific behavior (supported order types, margin modes, leverage caps, funding cadence, and collateral models). PerpsKit normalizes the integration surface while preserving venue constraints in metadata.

---

Supported venues

PerpsKit is designed to aggregate multiple venues over time.

• Available now: Hyperliquid
• Planned / expanding coverage: Drift, dYdX, GMX

Leverage and market counts are venue- and market-dependent.

---

Monetization (builder codes / partner fee logic)

PerpsKit supports monetization models that let partners capture value at the trade level (venue-dependent). A common pattern is builder codes — where a configurable fee is attached to user trades and collected by the builder/partner.

Hyperliquid builder codes

Hyperliquid supports builder codes on perps trades with protocol-enforced limits:

• Users must approve a max builder fee via an ApproveBuilderFee action
• Orders can include a builder parameter, e.g. {"b":"0x…","f":10}
• f is specified in tenths of a basis point (e.g., 10 = 1 bp)
• Builder fees on perps are capped at 0.1%

How fees are calculated

Builder fees are charged on executed notional per fill. Fees are not calculated on margin; they apply to trade execution notional and are collected in the collateral / quote asset.

Approval requirement (important)

Builder fee approval must be signed by the user’s main wallet (venue requirement).

Treat builder fees like product configuration: transparent display, explicit user approval where required, and clean reporting.

---

Compliance and geo-restrictions

Perps trading can be restricted in certain jurisdictions depending on venue policies and partner requirements. PerpsKit supports configurable geo-restrictions so partners can launch with region-appropriate controls.

Geo-restrictions are operational controls. Maintain allow/deny lists, align with legal guidance, and ensure frontend and backend enforcement are consistent.

---

Example flow (high-level)

1. Discover venues and markets

   List available venues and markets, and select the market you want to trade.

2. Request a trading action

   Request an action (open/close/update leverage/stop-loss/take-profit/cancel) with the required arguments.

3. Sign and submit transactions

   Execute the returned ordered, unsigned payload(s) using your wallet/custody stack.

4. Read updated state

   Fetch updated positions, orders, balances, and margin usage to update UX and reporting.

PerpsKit returns unsigned payloads for deterministic signing flows — especially important for institutional custody and policy-controlled execution.

---

What to build with PerpsKit

Wallet perps trading

Add a perps surface without building venue integrations from scratch.

Trading UIs and dashboards

Deliver a familiar trading experience with normalized markets and portfolio views.

Bots and automation

Programmatically route actions across venues using a consistent action model.

Partner monetization

Attach trade-level fees via builder codes / partner fee logic (venue-dependent).

---

Next steps

Getting Started

Start with the PerpsKit integration flow

Authentication

Set up API access

Markets API

Browse available markets

PerpsKit pricing

View pricing and enablement