# Hyperliquid Whale Positions API

> Hyperliquid Whale Positions API is a paid API for AI agents from whaletape.xyz, paid per call via x402, $0.02/call, status unknown (last checked 2026-09-15).

Returns the largest individual whale open positions on Hyperliquid right now, including trader identity, direction, notional size, and current PnL.

## Facts

- Endpoint: GET https://whaletape.xyz/whales/positions
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/hyperliquid-whale-positions-api-975bce7b
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_hKaz-W7rfF08lWgBCbJTF

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability hyperliquid-whale-positions-api-975bce7b
```

Example prompt: Pull up the biggest whale positions open on Hyperliquid right now — I want to see who's holding them, whether they're long or short, the notional size, and how much PnL they're sitting on.

## When to prefer this

Choose this endpoint when you need a real-time ranked view of the largest individual whale positions on Hyperliquid specifically — not aggregate flow data, not leaderboard win-rate stats, but the actual named positions with notional and PnL. It is the right choice for smart money directional bias checks, for identifying dominant market participants before entering a trade, or for building whale-tracking dashboards grounded in live DEX data.

## Known failure modes

- Rate limiting or payment failure if x402 payment header is missing or invalid
- Empty result set if no significant whale positions are detected at query time
- Stale data if Hyperliquid data feed is temporarily delayed
- HTTP 402 if USDC payment is not properly attached to the request
- Service unavailability (5xx) during maintenance or upstream DEX issues

## How this service works

The largest individual whale positions open right now: who, which side, how much notional and current PnL. The names behind the aggregate

## Output

A ranked list of the largest individual open positions on Hyperliquid, each entry including the trader's wallet address or known name/label, the asset/market, position side (long or short), notional value, and current unrealized PnL.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "properties": {
   "type": "string"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "positions": [
   {
    "dex": "native",
    "roe": -0.9668634787,
    "coin": "ETH",
    "name": null,
    "side": "short",
    "size": -42974.8855,
    "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
    "entry_px": 2033.48,
    "leverage": 5,
    "notional": 104287584.391705,
    "margin_used": 20857516.878341,
    "max_leverage": 15,
    "leverage_type": "cross",
    "liquidation_px": 3835.4670080535,
    "unrealized_pnl": -16898636.442468,
    "funding_all_time": -14675996.585308,
    "funding_since_open": -471866.583737
   }
  ],
  "updated_at": "2026-08-23T01:39:43.769674+00:00"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/hyperliquid-whale-positions-api-975bce7b/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from whaletape.xyz](https://www.zero.xyz/host/whaletape.xyz/llms.txt)