API Trading on Hyperliquid
Build Bots and Tools on a Fully On-Chain Perp & Spot Exchange
Hyperliquid exposes a low-latency API so you can trade programmatically, build dashboards, bots, and copy-trading systems on top of the L1. The core idea is simple: your main wallet holds funds, while one or more API wallets (agents) are authorized to place orders on your behalf without being able to withdraw. This gives you CEX-like automation with DEX-level security.
1. API Architecture Overview
Hyperliquid separates read-only and trading functionality into two logical layers.
| Layer | Purpose | Authentication | Typical Use |
|---|---|---|---|
| Info API | Market + account data | Public (optionally signed) | Charts, dashboards, risk monitors |
| Exchange API | Trading actions (orders, leverage, transfers) | Signed requests | Bots, execution engines |
Info API
- • Returns metadata (asset list, max leverage, fee tiers)
- • Streams or polls order books (L2 data), trades, funding history
- • Fetches your user state (positions, balances, open orders) for monitoring
Exchange API
- • Places, modifies, and cancels orders
- • Changes leverage and margin mode
- • Moves funds between subaccounts and vaults; interacts with vault transfers
2. Main Wallet vs API Wallet (Agent)
Hyperliquid uses an agent model in which API wallets are separate keys delegated by your main wallet.
Main Wallet
- ✓ Owns all funds and positions
- ✓ Signs authorization that whitelists agents
- ✓ Required for deposits, withdrawals, and critical account changes
API Wallet (Agent)
- ✓ Has its own private key
- ✓ Can only perform Exchange API actions
- ✗ Cannot withdraw funds or send assets out
Key Advantages:
- • If the agent key leaks, an attacker can only grief-trade but cannot drain the wallet
- • You can rotate agents or give different bots isolated keys with different permissions
- • Multiple agents can be assigned to different subaccounts
3. Creating an API Wallet
Deposit Funds
Make sure your main wallet has collateral on Hyperliquid (USDC.e bridged from Arbitrum)
Open API Page
In the app, go to More → API section or open the dedicated API URL while connected with your main wallet
Generate Agent
Click Generate API Wallet. The app creates a new agent address and asks you to sign an authorization message from your main wallet
Save Credentials
You will be shown your agent public address and private key (secret). Save the secret in a secure place (environment variables, encrypted password manager, or secrets manager)
Name & Limits (Optional)
Assign a human-readable name (e.g., scalper-bot-main) and configure validity or scope if the UI supports it
4. Using the Python SDK
Hyperliquid maintains an official Python SDK that wraps both Info and Exchange APIs, including signing logic.
Basic Configuration
- • account_address — your main wallet address (owner of funds)
- • secret_key — private key of the agent wallet created in the UI
Typical Python Flow
- Initialize Clients - Create an Info client for data and an Exchange client for orders
- Query Metadata - Fetch the asset list to know trading pairs and leverage limits
- Pull User State - Check balances, open positions, and risk before trading
- Place Order - Build an order payload and send via Exchange endpoint
- Handle Responses - Validate status, log results, and handle errors or retries
5. Key Info API Concepts
When building bots, you will repeatedly hit several Info endpoints.
Core Data Calls
Universe / Meta
Returns asset list (symbols, indices, max leverage). Used to map human-readable tickers like BTC-USD to asset indices.
userState
Per-account snapshot: Collateral balance, Open positions and their sizes, Active orders and margin usage.
l2Book
Returns aggregated bids and asks for a given asset. Used to estimate slippage, spread, and to place smart limit orders.
fundingHistory
Returns historical funding rates per market. Useful for carry/funding arbitrage strategies.
Polling vs Streaming
- • Polling: For simple bots, periodic HTTP polling (e.g., every 1–5 seconds) is enough
- • Streaming: For serious HFT-style systems, use gRPC or WebSocket-style streams via third-party infra providers
6. Exchange API: Placing and Managing Orders
All trading actions go through the Exchange endpoint.
| Action | Purpose |
|---|---|
| order | Place one or multiple orders (market or limit) |
| cancel | Cancel a single order by ID / cloid |
| batchCancel | Cancel multiple orders at once |
| modify | Change price/size of an existing order |
| updateLeverage | Adjust leverage settings for a given market |
| updateIsolatedMargin | Top up or drain isolated margin on a position |
| subaccountTransfer | Move funds between main account and subaccounts |
| vaultTransfer | Deposit to / withdraw from vaults programmatically |
Building a Limit Order Payload
Core parameters your bot must set:
- • asset — asset index or symbol (e.g., BTC-USD mapped to its index)
- • isBuy — boolean: true for buy (long), false for sell (short)
- • size — position size in contract terms
- • price — limit price; can be derived from mid-price ± offset
- • tif — time-in-force (e.g., Gtc for good-till-cancel, or immediate-or-cancel)
- • reduceOnly — ensures the order only reduces, never reverses, a position
Robust Bots Should:
- ✓ Validate requested leverage against max leverage from metadata
- ✓ Use reduceOnly on exit orders (TP/SL)
- ✓ Rate-limit themselves and handle rejected orders gracefully
7. Designing a Safe Bot
API trading adds powerful leverage but also new failure modes. Treat it as production software, not a toy.
🔐 Key Management
- • Store secret_key only in environment variables or secret managers
- • Never hardcode private keys directly into repo files
- • Rotate agent keys periodically and revoke unused ones
📊 Position Limits
- • Implement per-coin and global notional limits
- • Cap leverage (e.g., never exceed 10–20x via your bot logic)
🛑 Kill Switch
- • Add a global flag (TRADING_ENABLED=false) that your infrastructure can flip
- • Implement a circuit breaker: if daily loss > X%, halt trading automatically
✅ Sanity Checks
- • Verify l2Book depth before placing large orders
- • Skip trading during extreme volatility or when spreads exceed a threshold
Simple Strategy Skeleton
- Fetch metadata and user state
- Pull l2Book for BTC-USD
- If spread is tight and funding positive: place a small mean-reversion long
- Set stop-loss and take-profit using limit or reduce-only orders
- Loop with proper delays and logging
You can expand this into funding arbitrage bots, copy trading systems, or market-making strategies around fair value.
8. Best Practices for Production Use
🧪 Separate Environments
Start on testnet endpoints if available, or run in "paper trading" mode by simulating fills from Info data
📝 Structured Logging
Log every request/response with timestamps and correlation IDs. Persist trade history and PnL per bot and per subaccount
🚨 Monitoring & Alerts
Set up alerts for:
- API errors or timeouts
- Unusual position sizes
- Sharp PnL drawdowns or liquidation proximity
🔄 Version Control
Pin SDK versions to avoid unexpected behavior. Test after Hyperliquid releases major updates to API or matching engine
Conclusion: From Manual Clicks to Full Automation
If you already understand how to trade manually on Hyperliquid, moving to API trading is the natural next step:
- • The Info API gives you everything needed for signals and risk
- • The Exchange API plus an agent wallet lets you execute those signals without ever surrendering custody
Once your first bot is stable and risk-controlled, you can scale horizontally: multiple agents, multiple strategies, and multiple subaccounts—all on a single Hyperliquid account.
Ready to generate an API wallet and start building?
Start Trading on Hyperliquid