# Hyperliquid Whale Net Positioning by Coin

> Hyperliquid Whale Net Positioning by Coin is a paid API for AI agents from chiefofstaff-solana.iodized-lemon.workers.dev, paid per call via x402, $0.005/call, status unknown (last checked 2026-10-11).

Returns whale net positioning data (long vs short notional, leverage, tilt, gross % of OI) across Hyperliquid perpetual markets, optionally filtered to a specific coin.

## Facts

- Endpoint: GET https://chiefofstaff-solana.iodized-lemon.workers.dev/hl/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-net-positioning-by-coin-b13668d9
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_I6gn0TJ8QUqWUc_3ssaQy

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-net-positioning-by-coin-b13668d9
```

Example prompt: What are whales doing on Hyperliquid right now for SOL — are they net long or short, how much notional is on each side, and what's their average leverage?

## When to prefer this

Use this endpoint when you need to understand large-player (whale) directional bias and leverage on Hyperliquid perpetual markets, especially to inform trading decisions or risk management. Prefer this over funding rate or liquidation endpoints when the key question is 'are big players net long or short and by how much?' The optional coin filter allows targeted single-market queries at the same price. At $0.005 USDC per call it is cost-effective for frequent polling by trading agents.

## Known failure modes

- Data older than expected refresh window (age_s high) — endpoint reports age but still returns last known data
- Invalid coin ticker returns empty by_coin array or 404
- Payment not completed (x402 flow not satisfied) — returns 402 Payment Required with payment instructions
- Network timeout to Hyperliquid data source — may return stale or error response

## How this service works

Paid token safety / rug-pull checks for AI agents: Solana SPL (/check) and Robinhood Chain ERC-20 (/rh/check). One-sentence verdict + blocking/warnings/unknowns, casino|speculative|legit tier, holder count & concentration, liquidity, 1h volume & buy/sell flow, honeypot/tax or mint/freeze authority, RugCheck/GoPlus cross-checks. $0.01 USDC on Base or Solana via x402. Also: Hyperliquid perp market data for trading agents: funding extremes across all HL perps ($0.002), whale liquidation levels ($0.003), whale net positioning ($0.005), and a one-call LLM-ready market brief ($0.008). Refreshed ~every 3 min from HL public data; every response has generated_at/age_s; stale data is never charged.

## Output

A JSON object containing per-coin whale positioning data: net USD position (positive = net long, negative = net short), long and short notional in USD, number of long/short whale accounts, average leverage, tilt label (net long/net short), gross % of open interest controlled by whales, plus metadata fields generated_at and age_s indicating data freshness. Data is refreshed approximately every 3 minutes; stale data is not charged.

## 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"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "coin": {
       "type": "string",
       "description": "Optional HL perp ticker, e.g. SOL"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "age_s": 41,
  "by_coin": [
   {
    "coin": "BTC",
    "tilt": "net short",
    "n_long": 24,
    "holders": 51,
    "n_short": 27,
    "net_usd": -375300000,
    "long_usd": 385664755,
    "short_usd": 760964000,
    "avg_leverage": 12.3,
    "gross_pct_of_oi": 34.6
   }
  ],
  "endpoint": "/hl/whales",
  "generated_at": "2026-10-07T20:00:59Z"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/hyperliquid-whale-net-positioning-by-coin-b13668d9/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from chiefofstaff-solana.iodized-lemon.workers.dev](https://www.zero.xyz/host/chiefofstaff-solana.iodized-lemon.workers.dev/llms.txt)