Guides
Log inRegister interest

Perps Widget v1

Using the Yield.xyz Perps Widget

The Yield.xyz Perps Widget is a drop-in perpetual futures trading module that can be embedded in any app to offer users a self-custodial perpetual contracts trading experience. Built with React, it's designed to feel like a native part of your product.

Under the hood, the widget uses the Yield.xyz Perps API to power the full trading lifecycle: it discovers available providers, retrieves market data and portfolio state, and constructs intent-based actions (open/close/manage positions, update orders, customize leverage, etc.) that return unsigned transactions ready for the user to sign.

Currently, the widget supports perps trading on Hyperliquid, and is optimized for a compact 400×600px embed—ideal for wallets, exchanges, and fintech apps that want to ship perps trading without building the entire perps stack from scratch.

Features

Out of the box, the Perps Widget includes:

  • Open long/short positions with customizable leverage
  • Multiple order types: Market and limit orders
  • Risk management: Take profit and stop loss (TP/SL) orders
  • Position management: Increase, decrease, or close positions
  • Account funding: Fund the perps account and withdraw from Hyperliquid
  • Wallet integration: Connect via WalletConnect (Reown AppKit)
  • Real-time updates: Live market prices and portfolio data
  • Embeddable design: Compact 400×600px layout perfect for embedding

What You Can Build

The Perps Widget enables you to integrate a complete perpetual futures trading experience into your application without building the entire trading infrastructure. Your users can:

  • Trade perpetual contracts with leverage directly from your app
  • Manage their positions and orders through an intuitive interface
  • Execute trades while maintaining full custody of their assets
  • Access Hyperliquid's liquidity without leaving your platform

Installation & Setup

The Perps Widget is currently distributed as a self-hosted solution. You'll clone the repository, configure it with your API keys, and deploy it to your own infrastructure.

Prerequisites

  • Node.js 20+
  • pnpm 9+

Installation

Clone the Perps Widget repository:

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

Environment Configuration

Copy the example environment file and configure your API keys:

cp .env.example .env

Edit .env and set the following required variables:

# Perps API Configuration
VITE_PERPS_BASE_URL=https://perps.yield.xyz
VITE_PERPS_API_KEY=your-perps-api-key

# Wallet Connection
VITE_REOWN_PROJECT_ID=your-reown-project-id

# Token Balance Service
VITE_MORALIS_API_KEY=your-moralis-api-key

Environment Variable Details:

  • VITE_PERPS_BASE_URL — The Yield.xyz Perps API endpoint
  • VITE_PERPS_API_KEY — Your Perps API key (obtain from Yield.xyz)
  • VITE_REOWN_PROJECT_ID — Reown (WalletConnect) project ID for wallet connections
  • VITE_MORALIS_API_KEY — Moralis API key for fetching token balances

Security Note: Any variable prefixed with VITE_ is exposed in the client bundle. Do not put sensitive secrets in these variables. Treat browser-exposed keys as public and restrict them appropriately (e.g., using allowlists and rate limits) on the server side.

Development

Start the development server:

pnpm dev

The widget will be available at http://localhost:3000.

Build for Production

Build the widget for production deployment:

pnpm build

The production build will be output to the dist/ directory, ready for deployment to your hosting provider.

Embedding the Widget

Once you've built and deployed the Perps Widget to your own domain, you can embed it in your application using an iframe. The widget is optimized for a 400×600px layout.

Basic Embed

<iframe
  src="https://your-perps-widget.example"
  width="400"
  height="600"
  style="border:0; border-radius:12px; overflow:hidden"
  allow="clipboard-read; clipboard-write"
></iframe>

Responsive Embed

For responsive layouts, you can use CSS to make the iframe adapt to different screen sizes:

<div style="max-width: 400px; margin: 0 auto;">
  <iframe
    src="https://your-perps-widget.example"
    width="100%"
    height="600"
    style="border:0; border-radius:12px; overflow:hidden"
    allow="clipboard-read; clipboard-write"
  ></iframe>
</div>

How It Works (API Flow)

The Perps Widget is powered by the Yield.xyz Perps API, which handles the complete trading lifecycle through a series of endpoints:

1. Discovery

Fetch available perps providers and their supported actions (schemas included).

GET https://perps.yield.xyz/v1/providers

Get available markets:

POST https://perps.yield.xyz/v1/markets

2. Portfolio State

Fetch the user's current perps state, including margin/balances, open positions, and open orders, so you can render the trading UI with real account data.

Get account balance (margin):

POST https://perps.yield.xyz/v1/balances

Get open positions:

POST https://perps.yield.xyz/v1/positions

Get open orders:

POST https://perps.yield.xyz/v1/orders

3. Execute Actions

Request an intent-based trading action (open/close/manage/fund/withdraw). The API returns unsigned transaction data ready for user signing.

POST https://perps.yield.xyz/v1/actions

4. Submit Transaction

After the user signs the transaction, submit the signed transaction for broadcast/execution.

POST https://perps.yield.xyz/v1/transactions/{transactionId}/submit

This architecture ensures that users maintain full custody of their assets—the API never holds private keys and only returns unsigned transactions for the user to approve.

Tech Stack

The Perps Widget is built with modern web technologies:

  • React 19 with React Compiler for optimal performance
  • TanStack Router for file-based routing
  • Effect for functional error handling and service architecture
  • Tailwind CSS v4 for styling
  • Viem + Wagmi for Ethereum interactions
  • Reown AppKit (formerly WalletConnect) for wallet connections

Customization

Styling

The widget uses Tailwind CSS v4. To customize the appearance:

  1. Modify the Tailwind configuration in tailwind.config.js
  2. Edit component styles in the src/components/ directory
  3. Add custom CSS in src/index.css

Adding Features

To extend the widget with custom features:

  1. Add new components in src/components/modules/
  2. Create new routes in src/routes/
  3. Implement new services in src/services/
  4. Update state management in src/atoms/

Wallet Integration

The widget uses Reown AppKit (WalletConnect) for wallet connections. To customize the wallet experience:

  1. Configure supported wallets in your Reown project
  2. Modify wallet connection logic in the context providers
  3. Update the wallet UI components as needed

API Reference

For complete API documentation and integration guides, visit:

Support & Resources

Getting Help

If you encounter issues or have questions:

  1. Check the GitHub repository for documentation
  2. Review the Yield.xyz documentation
  3. Contact Yield.xyz support for API-related questions

Best Practices

Performance

  1. Host on a CDN: Deploy the built widget to a CDN for optimal load times
  2. Enable caching: Configure appropriate cache headers for static assets
  3. Lazy load: Load the iframe only when the trading section is visible

Security

  1. Use HTTPS: Always serve the widget over HTTPS
  2. Restrict API keys: Configure allowlists and rate limits for your API keys
  3. Content Security Policy: Set appropriate CSP headers on your hosting

User Experience

  1. Loading states: Show a loading indicator while the iframe loads
  2. Error handling: Provide fallback content if the widget fails to load
  3. Responsive design: Ensure the widget container adapts to different screen sizes
  4. Clear call-to-action: Guide users to the trading widget with clear navigation

Troubleshooting

Common Issues

Widget not loading:

  • Check that all environment variables are correctly set
  • Verify your API keys are valid
  • Ensure your hosting domain is allowed in your Reown project

Wallet connection fails:

  • Verify your VITE_REOWN_PROJECT_ID is correct
  • Check that WalletConnect is not blocked by browser extensions
  • Ensure the iframe has the required permissions

API errors:

  • Check your VITE_PERPS_API_KEY is valid
  • Verify the API endpoint is reachable
  • Review API rate limits and usage quotas

Build errors:

  • Ensure you're using Node.js 20+ and pnpm 9+
  • Clear node_modules and reinstall: rm -rf node_modules && pnpm install
  • Check for TypeScript errors: pnpm tsc --noEmit

What's Next

The Yield.xyz Perps Widget is actively being developed. Planned features include:

  • Support for additional perps providers beyond Hyperliquid
  • Advanced charting and technical analysis tools
  • Custom themes and white-labeling options
  • Mobile-optimized responsive layouts
  • SDK for programmatic control and integration

Stay updated by watching the GitHub repository and following Yield.xyz announcements.

Updated 3 months ago