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

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

<Columns cols={2}>
  <Card title="Perps API Reference" icon="code" href="/api-reference/perps-api">
    Endpoints, schemas, and examples
  </Card>

  <Card title="Getting Started" icon="rocket" href="/api-reference/perps-api/introduction/getting-started">
    Quick integration flow
  </Card>
</Columns>

***

## Integration modes

<Tabs>
  <Tab title="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)
  </Tab>

  <Tab title="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
  </Tab>

  <Tab title="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).
  </Tab>
</Tabs>

***

## What PerpsKit standardizes

<Columns cols={2}>
  <Card title="Markets" icon="list">
    Market metadata and venue-specific constraints (order types, margin modes, leverage ranges, fees, funding).
  </Card>

  <Card title="Portfolio state" icon="wallet">
    Positions, orders, collateral, margin usage, and unrealized PnL in a consistent shape across venues.
  </Card>

  <Card title="Trading actions" icon="bolt">
    A unified action model (open/close/update leverage/stop-loss/take-profit/cancel/fund/withdraw) mapped to venue execution.
  </Card>

  <Card title="Unsigned transaction construction" icon="shield-check">
    One or more ordered, unsigned payloads you route into your signing stack (EOA, smart accounts, MPC, custody).
  </Card>
</Columns>

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

***

## Supported venues

PerpsKit is designed to aggregate multiple venues over time.

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

<Info>
  Leverage and market counts are venue- and market-dependent.
</Info>

***

## 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%**

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Approval requirement (important)">
    Builder fee approval must be signed by the user’s main wallet (venue requirement).
  </Accordion>
</AccordionGroup>

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

***

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

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

***

## Example flow (high-level)

<Steps>
  <Step title="Discover venues and markets">
    List available venues and markets, and select the market you want to trade.
  </Step>

  <Step title="Request a trading action">
    Request an action (open/close/update leverage/stop-loss/take-profit/cancel) with the required arguments.
  </Step>

  <Step title="Sign and submit transactions">
    Execute the returned ordered, unsigned payload(s) using your wallet/custody stack.
  </Step>

  <Step title="Read updated state">
    Fetch updated positions, orders, balances, and margin usage to update UX and reporting.
  </Step>
</Steps>

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

***

## What to build with PerpsKit

<Columns cols={2}>
  <Card title="Wallet perps trading" icon="smartphone">
    Add a perps surface without building venue integrations from scratch.
  </Card>

  <Card title="Trading UIs and dashboards" icon="chart-line">
    Deliver a familiar trading experience with normalized markets and portfolio views.
  </Card>

  <Card title="Bots and automation" icon="robot">
    Programmatically route actions across venues using a consistent action model.
  </Card>

  <Card title="Partner monetization" icon="coins">
    Attach trade-level fees via builder codes / partner fee logic (venue-dependent).
  </Card>
</Columns>

***

## Next steps

<Columns cols={2}>
  <Card title="Getting Started" icon="rocket" href="/api-reference/perps-api/introduction/getting-started">
    Start with the PerpsKit integration flow
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/perps-api/introduction/authentication">
    Set up API access
  </Card>

  <Card title="Markets API" icon="list" href="/api-reference/perps-api/discovery/list-markets">
    Browse available markets
  </Card>

  <Card title="PerpsKit pricing" icon="dollar-sign" href="/documentation/plans-limits/kit-pricing/perpskit-pricing">
    View pricing and enablement
  </Card>
</Columns>