How to Embed a Perps Trading Widget

Widget Types and Use Cases

Different widget formats serve different integration needs. Choose the format that matches your product's requirements.

• Full trading widget: A complete trading interface with order entry, position management, charts, and market data. Typically occupies a full page section or dedicated tab. Best for applications where trading is a primary activity.
• Compact order widget: A minimal order entry form showing current price, direction buttons, size input, and leverage selector. Best for applications where trading is a secondary feature, such as portfolio trackers or news apps that want to let users act on information.
• Chart-only widget: An embeddable price chart with optional order entry overlay. Users can view market data and optionally place trades directly from the chart. Best for content sites, analytics dashboards, and media applications.
• Portfolio widget: Displays the user's open positions, PnL, and account summary. Read-only by default with optional close-position buttons. Best for wallets, portfolio trackers, and account management interfaces.
• Price ticker widget: A minimal widget showing real-time prices for selected trading pairs. Can be embedded in headers, sidebars, or footers as a persistent market data display.

Step 1: Choose Your Widget Source

Select where the trading widget comes from based on your technical requirements and customization needs.

1. Provider-hosted widgets: Infrastructure providers like perps.studio offer embeddable trading widgets that connect to Hyperliquid, Aster DEX, and other venues. These are maintained by the provider, receiving automatic updates and security patches. Integration is typically a few lines of code.
2. Self-built widgets: Build your own widget using the execution venue's API. This gives maximum control over appearance and behavior but requires more development and ongoing maintenance. Best for teams with strong front-end engineering resources.
3. Open-source components: Some community projects provide open-source trading components. These give you a starting point that can be customized, but require your team to maintain and update them.

For most teams, provider-hosted widgets offer the best balance of implementation speed, maintenance burden, and customization options.

Step 2: Implement the Widget

Widget implementation varies by format but generally follows one of these patterns.

1. Iframe embedding: The simplest integration method. Add an iframe tag pointing to the widget URL with configuration parameters in the query string. This isolates the widget completely from your application's styles and scripts. Example: <iframe src="https://widget.provider.com/trade?pair=BTC-PERP&theme=dark" width="100%" height="600"></iframe>
2. JavaScript SDK: Import a JavaScript library that renders the widget within a target DOM element. This allows tighter integration with your application including shared authentication state, event callbacks, and dynamic configuration. Typical implementation involves importing the SDK, initializing with your API key, and calling a render method on a container element.
3. React/Vue component: For applications built with modern frameworks, some providers offer native React or Vue components. These integrate seamlessly with your component tree, support props-based configuration, and emit events that your application can react to.
4. Web Component: Framework-agnostic custom elements that work in any HTML context. Configured via HTML attributes and emit standard DOM events. This approach works regardless of whether your application uses React, Vue, Angular, or plain HTML.

Choose the integration method that matches your application's technology stack and the depth of integration you need.

Step 3: Customize Appearance

The widget should look like a natural part of your application, not a foreign embed.

• Theme configuration: Most widgets support theme customization via parameters or configuration objects. Pass your brand colors, font preferences, and border radius settings to match the widget to your application's design system.
• Size and layout: Configure the widget dimensions to fit your layout. Full trading widgets typically need at least 800x600 pixels for desktop and should be responsive for mobile viewports. Compact widgets can fit in sidebars or overlays.
• Feature toggling: Show or hide specific widget features based on your needs. For example, hide the chart if your application already has its own charting solution, or hide the order book to save space in a compact layout.
• Localization: If your application serves multiple languages, check whether the widget supports localization. Pass the user's language preference to the widget for consistent language across your application.
• Loading states: Configure or customize the widget's loading state to match your application's loading patterns. A branded loading spinner is better than a generic one or a blank space while the widget initializes.

Step 4: Handle Widget Communication

For deeper integration, establish communication between your application and the embedded widget.

1. Event listeners: Listen for events emitted by the widget: trade placed, position closed, wallet connected, error occurred. Use these events to update your application's state, trigger notifications, or log analytics.
2. Command interface: Some widgets accept commands from the parent application: change trading pair, set order parameters, switch to a different tab. This allows your application to drive the widget programmatically based on user interactions outside the widget.
3. Shared authentication: If your application already handles wallet connectivity, pass the connected wallet information to the widget to avoid requiring users to connect their wallet twice. This typically involves sharing the wallet provider reference or a session token.
4. PostMessage API (for iframes): If using iframe embedding, communicate via the browser's postMessage API. Define a message protocol for both directions: parent-to-widget commands and widget-to-parent events. Validate message origins for security.
5. Deep linking: Support URL parameters that configure the widget's initial state. When a user navigates to a specific pair from your application, the widget should open with that pair pre-selected.

Step 5: Optimize Performance

Trading widgets are data-intensive and must remain responsive even when processing real-time updates.

• Lazy loading: If the trading widget is not visible on initial page load (e.g., behind a tab or modal), defer loading until the user navigates to it. This improves your application's initial load time without affecting trading UX.
• Connection management: Ensure the widget's WebSocket connections are properly managed. When the widget is hidden or the user navigates away, connections should be paused to save bandwidth. When the widget becomes visible, reconnect and resynchronize data.
• Resource isolation: If using iframe embedding, the widget runs in its own execution context, preventing its JavaScript from affecting your application's performance. This is a significant advantage for resource-intensive trading widgets.
• Mobile optimization: Test the widget on mobile devices with limited CPU and memory. Trading widgets can be CPU-intensive due to real-time chart rendering and order book updates. Ensure the widget provider offers mobile-optimized rendering or reduce update frequency on mobile.
• Caching: Verify that the widget properly caches static assets (JavaScript, CSS, fonts) to minimize load times on repeat visits. Check the widget provider's CDN configuration and cache headers.

Revenue Generation from Widget Trading

Embedded trading widgets can generate revenue for your platform through the same mechanisms as full exchanges.

1. Builder code integration: When using a provider-hosted widget, configure your builder code (HIP-3 on Hyperliquid, or equivalent on other venues) in the widget settings. Every trade placed through the widget generates builder fee revenue for your platform.
2. Referral attribution: Track trading activity from the widget separately from other channels. This helps you understand the revenue contribution of the embedded widget versus direct platform access.
3. Revenue potential: Widget trading volume depends on your application's traffic and user engagement. A popular portfolio tracker adding a trading widget can generate significant volume from users who would otherwise leave to trade on another platform. Even modest conversion rates (5-10% of visitors placing a trade) can produce meaningful revenue at scale.