> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yield.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Perps widget

> A compact, self-custodial perpetual futures trading app on the Perps API: run it, deploy it and embed it in your product.

export const CompactDemo = ({src, title, width = 480, height = 720, caption}) => {
  return <figure style={{
    margin: "24px 0",
    textAlign: "center"
  }}>
      <iframe src={src} title={title} width={width} height={height} allow="clipboard-read; clipboard-write" loading="lazy" style={{
    border: "1px solid rgba(127, 127, 127, 0.25)",
    borderRadius: "16px",
    width: "100%",
    maxWidth: `${width}px`,
    height: `${height}px`,
    display: "block",
    margin: "0 auto"
  }} />
      <figcaption style={{
    marginTop: "8px",
    fontSize: "14px",
    opacity: 0.75
  }}>
        {caption ? `${caption} ` : ""}
        <a href={src} target="_blank" rel="noopener noreferrer">
          Open the demo in a new tab
        </a>
      </figcaption>
    </figure>;
};

The Perps widget is a compact perpetual futures trading app you host and embed in your product. Users open long and short positions on Hyperliquid with leverage, manage them, and fund their account, all signed in their own wallet. It is built on the [Perps API](/guides/perps/index) and sized for a 400 by 600 pixel slot in a wallet, exchange or fintech app.

<CompactDemo src="https://perps-widget.vercel.app/" title="Yield.xyz Perps widget demo" width={400} height={640} caption="The Perps widget." />

For a full desktop trading terminal instead, see the [Perps dashboard](/guides/widgets-dashboard/perps-dashboard). Both come from the same source repository.

<Warning>
  Perps trading carries jurisdictional restrictions, and the Perps API blocks requests from banned regions. Read the [perpetuals disclaimer](/legal/perpetuals-disclaimer) and [Geo-blocking](/documentation/advanced-setup/geo-blocking/index) before you deploy.
</Warning>

## What users can do

* Open long and short positions with adjustable leverage.
* Place market and limit orders, and set take profit and stop loss.
* Increase, partially close or close a position, adjust its margin and change its leverage.
* Cancel open orders.
* Deposit to and withdraw from their Hyperliquid account.
* See live prices, positions and account balance.
* Connect a wallet through WalletConnect.

Every action returns unsigned transactions or payloads from the Perps API, and the user signs them in their own wallet. Yield.xyz never holds keys.

## Prerequisites

* A Yield.xyz API key with the Perps API enabled. The same project key works for the Earn, Perps and Borrow APIs.
* A [Moralis](https://moralis.io) API key, used to read wallet token balances.
* Optional: a [Reown](https://cloud.reown.com) project ID for WalletConnect.
* Node.js 24 and pnpm 10, as pinned in the repository's `mise.toml`. pnpm 11 stops the install on unapproved build scripts, so use pnpm 10.

## Run it locally

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/stakekit/perps-widget
    cd perps-widget
    pnpm install
    ```
  </Step>

  <Step title="Set environment variables">
    Each app reads its own `.env`. For the widget:

    ```bash theme={null}
    cp packages/widget/.env.example packages/widget/.env
    ```

    ```bash packages/widget/.env theme={null}
    VITE_PERPS_BASE_URL=https://perps.yield.xyz
    VITE_PERPS_API_KEY=your-yield-api-key
    VITE_MORALIS_API_KEY=your-moralis-api-key
    VITE_REOWN_PROJECT_ID=your-reown-project-id
    ```

    `VITE_PERPS_BASE_URL`, `VITE_PERPS_API_KEY` and `VITE_MORALIS_API_KEY` are required. `VITE_REOWN_PROJECT_ID` is optional.
  </Step>

  <Step title="Start the dev server">
    ```bash theme={null}
    pnpm dev:widget
    ```

    Open [http://localhost:3000](http://localhost:3000).
  </Step>
</Steps>

<Warning>
  Every `VITE_` variable is bundled into the browser build, so treat these keys as public. Restrict them where the provider allows it, for example with allowed origins, and see the [security notice](/legal/security-notice).
</Warning>

## Build and deploy

```bash theme={null}
pnpm build:widget
```

The build output is written to `packages/widget/dist`. Deploy it to any static host that serves single-page apps, with every path routed to `index.html`. The repository's `vercel.json` configures this for Vercel. Set the environment variables in your host's build settings, since they are read at build time.

## Embed it

After you deploy the widget, embed it on your own domain with an iframe:

<CodeGroup>
  ```html Fixed size theme={null}
  <iframe
    src="https://perps.your-app.example"
    width="400"
    height="600"
    style="border: 0; border-radius: 12px; overflow: hidden"
    allow="clipboard-read; clipboard-write"
    loading="lazy"
  ></iframe>
  ```

  ```html Responsive theme={null}
  <div style="max-width: 400px; margin: 0 auto">
    <iframe
      src="https://perps.your-app.example"
      width="100%"
      height="600"
      style="border: 0; border-radius: 12px; overflow: hidden"
      allow="clipboard-read; clipboard-write"
      loading="lazy"
    ></iframe>
  </div>
  ```
</CodeGroup>

Serve the widget over HTTPS. If you set a Reown project ID, add your domain to the allowed domains of that Reown project.

## How it works

The widget calls the Perps API at `https://perps.yield.xyz` with your API key:

| Step | Endpoints |
| - | - |
| Discover venues and markets | `GET /v1/providers`, `GET /v1/markets`, `GET /v1/markets/{marketId}`, `GET /v1/markets/{marketId}/candles` |
| Read the account | `POST /v1/balances`, `POST /v1/positions`, `POST /v1/orders` |
| Build an action | `POST /v1/actions` (open, close, update leverage or margin, take profit and stop loss, cancel order, fund, withdraw) |
| Submit the signature | `POST /v1/transactions/{transactionId}/submit` |
| Track the result | `GET /v1/actions/{id}` |

The [Perps API guide](/guides/perps/index) walks through the same flow for teams that build their own interface.

## Customize it

You can modify the source under the terms of its license:

* **Styling.** The apps use Tailwind CSS v4. Change colors, fonts and spacing in the app styles and components.
* **Features.** Screens are file-based routes in `packages/widget/src/routes`. Shared API clients, state and components are in `packages/common`.
* **Wallets.** Wallet connection uses Reown AppKit and wagmi, and is configured in the app's context providers.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The widget does not load data">
    Check that `VITE_PERPS_BASE_URL`, `VITE_PERPS_API_KEY` and `VITE_MORALIS_API_KEY` are set for the app you build, and that the key has the Perps API enabled. Variables are read at build time, so rebuild after changing them.
  </Accordion>

  <Accordion title="Wallet connection fails">
    Check your `VITE_REOWN_PROJECT_ID`, that your domain is allowed in the Reown project, and that browser extensions are not blocking WalletConnect. Some wallet extensions do not inject into an iframe. Open the app in its own tab to compare.
  </Accordion>

  <Accordion title="The install fails">
    Use Node.js 24 and pnpm 10. With pnpm 11 the install stops on unapproved build scripts. To start over, delete `node_modules` and run `pnpm install` again.
  </Accordion>

  <Accordion title="Deep links return 404 after deploying">
    Your host is not routing every path to `index.html`. Add a single-page app rewrite, as in the repository's `vercel.json`.
  </Accordion>
</AccordionGroup>

## License

The Perps widget is published under the Business Source License 1.1 (BSL-1.1), which converts to MIT on 2030-01-20. Read the `LICENSE` file in the repository before you deploy it.

## Next steps

<Columns cols={2}>
  <Card title="Perps dashboard" icon="chart-line" href="/guides/widgets-dashboard/perps-dashboard">
    The full desktop trading terminal from the same repository.
  </Card>

  <Card title="Perps API guide" icon="code" href="/guides/perps/index">
    Build your own Perps interface on the same API.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.