# Hyperliquid Whale Positioning API

> Hyperliquid Whale Positioning API is a paid API for AI agents from api.vextorium.com, paid per call via x402, $0.005/call, status unknown (last checked 2026-10-11).

Returns aggregated positioning data for the 150 largest active Hyperliquid accounts, including per-coin long/short notional, whale counts, bias, average entry price, and unrealized PnL; or detailed per-whale breakdown for a single coin.

## Facts

- Endpoint: POST https://api.vextorium.com/v1/hyperliquid-whales?utm_source=zero.xyz
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/hyperliquid-whale-positioning-api-883b01b4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_R0HhdUgHRfNl_yf9tKER3

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-positioning-api-883b01b4 -d '<json body>'
```

Example prompt: Show me how the top 150 Hyperliquid whales are positioned right now — I want to see which coins they're long or short on, the notional sizes, how many whales are on each side, and their unrealized PnL.

## When to prefer this

Choose this endpoint when you need real-time positioning intelligence specifically from Hyperliquid's largest active accounts (top 150 by capital), especially for perpetual futures markets. It is the right choice when you want aggregated whale sentiment (long/short bias, notional, PnL) across all coins at once, or granular per-whale breakdown for a specific coin including entry, liquidation, and leverage. Prefer this over generic on-chain analytics when the focus is on Hyperliquid-native perpetuals trading activity and large-account behavior.

## Known failure modes

- Missing or invalid 'currency' field may return all coins rather than a specific one
- Hyperliquid leaderboard data may be momentarily stale if the source hasn't updated
- If limit exceeds available whale accounts, fewer results may be returned
- Network or upstream Hyperliquid API unavailability may result in an error response
- Malformed request body type (not json/form-data/text) returns a validation error

## How this service works

How the 150 largest actively trading Hyperliquid accounts are positioned: per coin long and short notional, bias, number of whales on each side, average entry and unrealized PnL; or, for one coin, every whale position with entry, liquidation and leverage.

## Output

Returns a JSON object with a list of coins, each containing: long and short notional in USD, number of whales on each side, long bias percentage, average entry price, and aggregate unrealized PnL. If a specific currency is requested, returns individual whale-level positions including entry price, liquidation price, and leverage. Also includes source attribution and total analyzed position count.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method",
    "bodyType",
    "body"
   ],
   "properties": {
    "body": {
     "required": [],
     "properties": {
      "limit": {
       "type": "integer"
      },
      "currency": {
       "type": "string"
      }
     }
    },
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "POST"
     ],
     "type": "string"
    },
    "bodyType": {
     "enum": [
      "json",
      "form-data",
      "text"
     ],
     "type": "string"
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": [
      "object",
      "null"
     ],
     "properties": {
      "note": {
       "type": [
        "string",
        "null"
       ]
      },
      "coins": {
       "type": [
        "array",
        "null"
       ],
       "items": {
        "type": [
         "null",
         "object"
        ],
        "properties": {
         "currency": {
          "type": [
           "null",
           "string"
          ]
         },
         "avg_input": {
          "type": [
           "null",
           "number"
          ]
         },
         "long_whales": {
          "type": [
           "null",
           "number"
          ]
         },
         "short_whales": {
          "type": [
           "null",
           "number"
          ]
         },
         "long_bias_pct": {
          "type": [
           "null",
           "number"
          ]
         },
         "long_notional_usd": {
          "type": [
           "null",
           "number"
          ]
         },
         "short_notional_usd": {
          "type": [
           "null",
           "number"
          ]
         },
         "unrealized_pnl_usd": {
          "type": [
           "null",
           "number"
          ]
         }
        }
       }
      },
      "source": {
       "type": [
        "string",
        "null"
       ]
      },
      "analyzed_positions": {
       "type": [
        "number",
        "null"
       ]
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "note": "Only the 150 active accounts with the most capital. Not a recommendation.",
  "coins": [
   {
    "currency": "ETH",
    "avg_input": 2422.007686,
    "long_whales": 24,
    "short_whales": 22,
    "long_bias_pct": 33.6,
    "long_notional_usd": 473509354,
    "short_notional_usd": 934586458,
    "unrealized_pnl_usd": -32752466
   },
   {
    "currency": "BTC",
    "avg_input": 78488.828893,
    "long_whales": 18,
    "short_whales": 26,
    "long_bias_pct": 19.2,
    "long_notional_usd": 180960071,
    "short_notional_usd": 763297363,
    "unrealized_pnl_usd": -46719599
   }
  ],
  "source": "Hyperliquid (public leaderboard and account state)",
  "analyzed_positions": 1310
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/hyperliquid-whale-positioning-api-883b01b4/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.vextorium.com](https://www.zero.xyz/host/api.vextorium.com/llms.txt)