Hyperliquid

Nansen's Hyperliquid API endpoints provide comprehensive access to perp trading data on Hyperliquid. Track positions, analyze trades, screen tokens, and follow smart money activity across the fastest-growing perps platform.

What can you do?

With Hyperliquid endpoints, you can:

• Track wallet positions: Monitor real-time perpetual positions, PnL, and account health

• Analyze trading activity: View detailed trade history and execution data of any address

• Screen perp trading activity: Find high-volume tokens and smart money flows on Hyperliquid

• Find top performers: Discover the most profitable traders on specific tokens.

Which endpoints can I use?

I want to...	Use this endpoint	Best for
See all open positions for a wallet including leverage, PnL, and liquidation prices	Address Perp Positions	Snapshot of current positions
View a wallet's trading history with entry/exit prices, fees, and PnL	Address Perp Trades	Trade by trade breakdown of address activity
See top profitable wallets on Hyperliquid over a given period	Hyperliquid Leaderboard	Find profitable wallets and copy trading
Find high-volume perp tokens or see where smart money is trading	Perp Screener	Market discovery & trends
Find the most profitable traders on a specific perp token	Perp PnL Leaderboard	Performance rankings
Track what smart money wallets are trading on Hyperliquid	Smart Money Perp Trades	Real-time smart money
See all open positions for a specific perp token including leverage, PnL, and liquidation prices	Token Perp Positions	Snapshot of current positions for a token
View trading history for a specific perp token over a time period	Token Perp Trades	All trading activity for a specific token

Key Differences: Hyperliquid vs. Other Chains

Token Identification

Important: Hyperliquid perp endpoints use token symbols instead of token addresses in Token God Mode Inputs

Other Chains	Hyperliquid
token_address: "0x1234..."	token_symbol: "BTC"
Use contract addresses	Use ticker symbols (BTC, ETH, SOL, etc.)

Example:

// Other chains
{"token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"}

// Hyperliquid
{"token_symbol": "BTC"}  // For leaderboard endpoint

Positive and Negative Positions

Some endpoints (Eg. Token Perp Positions) have negative Position value. This usually represents a short and a positive value represents a long.

Quick Start Checklist

1. Get your API key from Nansen

2. Choose your use case:

   • Wallet monitoring → Use /perp-positions + /perp-trades

   • Market discovery → Use /perp-screener

   • Copy trading → Use /perp-leaderboard + /tgm/perp-pnl-leaderboard

3. Remember: Use token symbols (BTC, ETH) not addresses

4. Add filters: Refine results with volume, PnL, or time filters