Perps widget

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 and sized for a 400 by 600 pixel slot in a wallet, exchange or fintech app. For a full desktop trading terminal instead, see the Perps dashboard. Both come from the same source repository.

Perps trading carries jurisdictional restrictions, and the Perps API blocks requests from banned regions. Read the perpetuals disclaimer and Geo-blocking before you deploy.

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 API key, used to read wallet token balances.
Optional: a Reown 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

Clone and install

git clone https://github.com/stakekit/perps-widget
cd perps-widget
pnpm install

Set environment variables

Each app reads its own .env. For the widget:

cp packages/widget/.env.example packages/widget/.env

packages/widget/.env

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.

Start the dev server

pnpm dev:widget

Open http://localhost:3000.

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.

Build and deploy

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:

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

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

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

The widget does not load data

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.

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.

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.

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.

Get started

AI & Agents

Earn

Trade

Borrow

Widgets & UI

Dashboards

Integrations & signing

Enterprise

Legacy & migration

What users can do

Prerequisites

Run it locally

Build and deploy

Embed it

How it works

Customize it

Troubleshooting

License

Next steps

Perps dashboard

Perps API guide

​What users can do

​Prerequisites

​Run it locally

​Build and deploy

​Embed it

​How it works

​Customize it

​Troubleshooting

​License

​Next steps

Perps dashboard

Perps API guide

What users can do

Prerequisites

Run it locally

Build and deploy

Embed it

How it works

Customize it

Troubleshooting

License

Next steps