How to Integrate Hyperliquid Into Your Platform

Hyperliquid Architecture Overview

Before integrating, understand Hyperliquid's core architecture to make informed implementation decisions.

• HyperBFT consensus: Hyperliquid operates its own L1 blockchain using HyperBFT consensus with sub-second block times. This means order execution is on-chain but feels nearly instantaneous from the user's perspective.
• On-chain order book: Unlike AMM-based protocols, Hyperliquid runs a full central limit order book (CLOB) on-chain. This provides familiar order types (limit, market, stop, etc.) and transparent price discovery.
• Cross-margin and isolated margin: Traders can choose between cross-margin (all positions share collateral) and isolated margin (each position has dedicated collateral) modes.
• USDC collateral: All positions are collateralized with USDC. Deposits are bridged from Arbitrum to the Hyperliquid L1.
• HIP-3 (Builder Codes): The HIP-3 standard allows third-party front-ends to attach a builder code to orders, routing a configurable fee to the front-end operator. This is the primary revenue mechanism for branded platforms built on Hyperliquid.

Set Up API Connectivity

Hyperliquid provides two primary API interfaces. You will typically use both in a production integration.

1. REST API (Info endpoint): Used for querying account state, open orders, positions, historical trades, and market metadata. The base URL for mainnet is https://api.hyperliquid.xyz. All requests are POST requests to the /info endpoint with a JSON body specifying the request type.
2. REST API (Exchange endpoint): Used for submitting orders, cancellations, and other write operations. Requests go to the /exchange endpoint and require EIP-712 typed data signatures for authentication.
3. WebSocket API: Used for real-time streaming of order book updates, trades, candle data, and user-specific events (fills, order updates, liquidations). Connect to wss://api.hyperliquid.xyz/ws and subscribe to channels by sending JSON subscription messages.

Start with the Info endpoint to fetch market metadata (available pairs, tick sizes, lot sizes) and build your local market configuration from this data rather than hardcoding it.

Implement Authentication and Order Signing

Hyperliquid uses EIP-712 typed data signatures for order authentication. Every order must be signed by the trader's wallet.

1. Construct the typed data object. Each order type has a specific EIP-712 type structure defined in Hyperliquid's documentation. The structure includes fields for asset index, price, size, side (buy/sell), order type, and timestamp.
2. Request wallet signature. Use the eth_signTypedData_v4 method to request the user's wallet to sign the structured data. This produces a signature that proves the order was authorized by the account holder.
3. Submit with signature. Include the signed data and signature in the POST request to the Exchange endpoint. The Hyperliquid validators verify the signature on-chain before processing the order.
4. Implement agent wallets (recommended). To avoid prompting the user for a wallet signature on every order, use Hyperliquid's agent wallet system. The user signs a one-time authorization granting an agent wallet permission to trade on their behalf. The agent wallet's private key is stored locally (encrypted) and used for subsequent order signing without additional wallet prompts.

Agent wallets significantly improve the trading UX. Without them, users must confirm each order in their wallet popup, which is slow and disruptive during active trading.

Integrate HIP-3 Builder Codes

HIP-3 (Builder Codes) is Hyperliquid's mechanism for third-party front-ends to earn trading fees. Implementing HIP-3 is essential if you plan to generate revenue from your integration.

1. Register a builder code. Apply for a builder code through the Hyperliquid builder program. The builder code is a unique identifier tied to your platform.
2. Attach builder code to orders. When constructing orders, include the builder fee fields in the order payload. This specifies the additional fee that traders pay, which is routed to your builder address.
3. Set fee levels. Configure the builder fee amount per order. This is typically expressed in basis points. For example, a 2 bps builder fee on a $10,000 trade generates $2 in revenue for your platform.
4. Monitor builder revenue. Use the Hyperliquid API to query builder fee accruals and withdrawals. Build internal dashboards to track revenue by day, by pair, and by user for business analytics.

The builder fee is separate from Hyperliquid's base trading fee. Traders pay both, so be transparent about the total fee they incur. Competitive builder fees typically range from 1-5 basis points depending on the platform's value proposition.

Handle Market Data and Price Feeds

Accurate, real-time market data is fundamental to a usable trading interface. Implement these data feeds for a complete experience.

• Order book: Subscribe to the l2Book WebSocket channel for real-time order book snapshots. Process updates incrementally to maintain a local order book state without re-fetching the full book on every change.
• Trades: Subscribe to the trades channel for real-time trade prints. Display these in a trade history panel and use them to update the last price indicator.
• Candles: Subscribe to the candle channel for OHLCV data at your desired timeframe. Feed this data into your charting library. For historical candles beyond the WebSocket buffer, use the Info API's candle snapshot endpoint.
• Funding rates: Query current and predicted funding rates via the Info API. Display these prominently as funding rates are a key factor in perpetual futures trading decisions.
• Mark price and index price: Display both the mark price (used for PnL and liquidation calculations) and the index price (reference price from external sources) to help traders understand their positions.

Implement reconnection logic for WebSocket connections with exponential backoff. Network interruptions are inevitable, and stale data in a trading interface can lead to poor trading decisions.

Build Deposit and Withdrawal Flows

Users need to move funds between their wallet and the Hyperliquid L1 to trade. Implement clear deposit and withdrawal interfaces.

1. Deposits: Deposits to Hyperliquid are made by sending USDC on Arbitrum to the Hyperliquid bridge contract. Your interface should guide the user through approving USDC spending, then executing the bridge transaction. Display the estimated confirmation time (typically under 2 minutes).
2. Withdrawals: Withdrawals are initiated via the Exchange API with a signed withdrawal request. Funds are bridged back to the user's Arbitrum address. Processing time varies but is typically under 10 minutes.
3. Balance display: Show the user's available balance, margin in use, and unrealized PnL clearly. Update balances in real time as trades execute and positions change value.
4. Transaction history: Maintain a log of deposits and withdrawals with timestamps, amounts, and transaction hashes for user reference.

Handle edge cases including insufficient gas for Arbitrum transactions, USDC approval already granted (skip the approve step), and pending deposits that have not yet been credited on the Hyperliquid side.

Testing and Deployment

Thorough testing against Hyperliquid's testnet environment is critical before connecting to mainnet with real funds.

1. Testnet integration: Hyperliquid provides a testnet at https://api.hyperliquid-testnet.xyz. All API endpoints and WebSocket channels work identically to mainnet. Use testnet USDC (available from the Hyperliquid testnet faucet) for integration testing.
2. Order lifecycle testing: Test every order type your platform supports: market, limit, stop-market, stop-limit, take-profit, and reduce-only. Verify correct behavior for partial fills, cancellations, and amendments.
3. Margin and liquidation testing: Open leveraged positions on testnet and verify that margin calculations, liquidation prices, and PnL tracking match Hyperliquid's values. Intentionally trigger liquidations to ensure your UI handles them gracefully.
4. Production deployment: When switching to mainnet, update only the API base URL and WebSocket URL. All data structures and signing schemes are identical. Start with small position sizes to verify mainnet behavior before allowing full trading.