Hyperliquid

Nansen's Hyperliquid API endpoints cover both data and trading. Track positions, analyze trades, screen tokens and follow smart money activity across the fastest-growing perps platform — and open, manage and close your own positions with your own keys.

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.

• Trade perpetuals: Open, manage and close positions, and move USDC on and off the venue — see Perp Trading

Data or trading?

The two halves of this section answer different questions and are documented separately:

	Endpoints	Start here
Data — what is happening on Hyperliquid, for any address or token	/profiler/*, /tgm/*, /smart-money/*, /perp-screener, /perp-leaderboard	The table below
Trading — act on your own wallet	/perp/*, /perp/bridge/*	Perp Trading

Trading endpoints never take a private key: Nansen returns an unsigned action, you sign it locally, and you submit the signature. They are credit-free and region-restricted — the Perp Trading guide covers the flow, the one-time builder-fee approval, funding, and error handling end to end.

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

   • Trading your own wallet → Follow Perp Trading

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

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