# Whale Positions (`flow_whale_positions`)

> Live whale accounts: equity, side, notional, entry, leverage, unrealized PnL — and the reported liquidation price of each position.

- Category: Order flow & whales
- MCP tool: `flow_whale_positions`
- REST: `GET /flow/whale-positions`
- x402 price: $0.02 per call (USDC on Base)
- HTML: https://www.f1ow.com/docs/tools/flow_whale_positions

## What it does

Live whale positions on on-chain perpetual exchanges. By default discovers the largest currently-active whale accounts from the venue leaderboard and returns each one's equity and open positions with side, notional (USD), entry price, liquidation price, leverage and unrealized PnL. Optionally pass 'addresses' (comma-separated 0x wallets, max 10) to follow specific wallets instead. For aggregate cohort signals use flow_whale_context.

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `addresses` | string | query | no | Optional comma-separated 0x wallet addresses to inspect (max 10). Omit to auto-discover the biggest live whales. |

## Call it

### cURL

```bash
curl "https://mcp.f1ow.com/v1/flow/whale-positions" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

### MCP

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flow_whale_positions",
    "arguments": {}
  }
}
```

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/flow/whale-positions", {
  headers: { Authorization: `Bearer ${process.env.F1OW_API_KEY}` },
});
const data = await res.json(); // the tool's result as JSON, typed in the OpenAPI spec
console.log(data);
```

### Python

```python
import os, requests

res = requests.get(
    "https://mcp.f1ow.com/v1/flow/whale-positions",
    headers={"Authorization": f"Bearer {os.environ['F1OW_API_KEY']}"},
)
data = res.json()  # the tool's result as JSON, typed in the OpenAPI spec
print(data)
```

### WebSocket

```jsonc
// wss://mcp.f1ow.com/v1/ws — subprotocol "jsonrpc-2.0", Authorization: Bearer <key>
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flow_whale_positions",
    "arguments": {}
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "flow_whale_positions",
    "arguments": {},
    "intervalSeconds": 60
  }
}
```

### x402

```bash
# No account: the first call answers 402 with a PAYMENT-REQUIRED challenge;
# an x402 client pays it in USDC on Base and retries.
curl "https://mcp.f1ow.com/x402/v1/flow/whale-positions"
```

## Sample response

Captured 2026-11-13. The JSON is what REST and WebSocket return and the `structuredContent` of an MCP call (trimmed):

```json
{
  "accounts": [
    {
      "accountValueUsd": 71370898.058053,
      "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
      "positions": [
        {
          "coin": "BTC",
          "entryPriceUsd": 76361.6,
          "isLong": false,
          "leverage": 5,
          "liquidationPriceUsd": 103853.558635233,
          "notionalUsd": 140674378.85424,
          "side": "short",
          "unrealizedPnlUsd": 15788693.203913
        },
        {
          "coin": "ETH",
          "entryPriceUsd": 2322.72,
          "isLong": false,
          "leverage": 5,
          "liquidationPriceUsd": 4368.8861981688,
          "notionalUsd": 57254591.97264,
          "side": "short",
          "unrealizedPnlUsd": 11450924.703282
        },
        {
          "coin": "HYPE",
          "entryPriceUsd": 75.4377,
          "isLong": false,
          "leverage": 5,
          "liquidationPriceUsd": 185.4509511594,
          "notionalUsd": 42152234.798576,
          "side": "short",
          "unrealizedPnlUsd": 2287649.922532
        },
        {
          "coin": "ZEC",
          "entryPriceUsd": 1478.3647,
          "isLong": false,
          "leverage": 3,
          "liquidationPriceUsd": 2781.6698261302,
          "notionalUsd": 34366185.0924,
          "side": "short",
          "unrealizedPnlUsd": 19557436.357339
        },
        {
          "coin": "SOL",
          "entryPriceUsd": 94.3346,
          "isLong": false,
          "leverage": 7,
          "liquidationPriceUsd": 248.8499967264,
          "notionalUsd": 33698517.68997,
          "side": "short",
          "unrealizedPnlUsd": 6049643.822353
        },
        {
          "coin": "XMR",
          "entryPriceUsd": 607.395,
          "isLong": false,
          "leverage": 3,
          "liquidationPriceUsd": 9141.4904185547,
          "notionalUsd": 4125556.202768,
          "side": "short",
          "unrealizedPnlUsd": 606659.028942
        },
        "… 17 more"
      ]
    },
    {
      "accountValueUsd": 63951550.274719,
      "address": "0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36",
      "positions": [
        {
          "coin": "BTC",
          "entryPriceUsd": 77924.2,
          "isLong": false,
          "leverage": 5,
          "liquidationPriceUsd": 110423.711403038,
          "notionalUsd": 108146511.02528,
          "side": "short",
          "unrealizedPnlUsd": 14599339.905798
        },
        {
          "coin": "HYPE",
          "entryPriceUsd": 75.2795,
          "isLong": false,
          "leverage": 5,
          "liquidationPriceUsd": 137.5255171756,
          "notionalUsd": 65979047.158208,
          "side": "short",
          "unrealizedPnlUsd": 3434897.273196
        },
        {
          "coin": "ZEC",
          "entryPriceUsd": 1336.3891,
          "isLong": false,
          "leverage": 3,
          "liquidationPriceUsd": 2170.0992579181,
          "notionalUsd": 46675352.2332,
          "side": "short",
          "unrealizedPnlUsd": 19529016.427216
        },
        {
          "coin": "SOL",
          "entryPriceUsd": 91.3463,
          "isLong": false,
          "leverage": 5,
          "liquidationPriceUsd": 807.5759335542,
          "notionalUsd": 7169303.83239,
          "side": "short",
          "unrealizedPnlUsd": 1019175.127467
        },
        {
          "coin": "DOGE",
          "entryPriceUsd": 0.094571,
          "isLong": false,
          "leverage": 3,
          "liquidationPriceUsd": 0.8570812631,
          "notionalUsd": 5001172.624472,
          "side": "short",
          "unrealizedPnlUsd": 2338014.458641
        },
        {
          "coin": "ENA",
          "entryPriceUsd": 0.243779,
          "isLong": false,
          "leverage": 2,
          "liquidationPriceUsd": 1.8582718456,
          "notionalUsd": 4928230.45946,
          "side": "short",
          "unrealizedPnlUsd": 3788330.92812
        },
        "… 24 more"
      ]
    },
    {
      "accountValueUsd": 32920860.096124,
      "address": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
      "positions": [
        {
          "coin": "ETH",
          "entryPriceUsd": 1967.39,
          "isLong": false,
          "leverage": 15,
          "liquidationPriceUsd": 4849.315017623,
          "notionalUsd": 18921158.7498,
          "side": "short",
          "unrealizedPnlUsd": 310782.818022
        },
        {
          "coin": "SOL",
          "entryPriceUsd": 85.5308,
          "isLong": false,
          "leverage": 20,
          "liquidationPriceUsd": 264.0029910558,
          "notionalUsd": 12318035.14644,
          "side": "short",
          "unrealizedPnlUsd": 855404.608763
        },
        {
          "coin": "BTC",
          "entryPriceUsd": 68934.7,
          "isLong": false,
          "leverage": 20,
          "liquidationPriceUsd": 300620.473110976,
          "notionalUsd": 8492613.3208,
          "side": "short",
          "unrealizedPnlUsd": 34479.532262
        },
        {
          "coin": "HYPE",
          "entryPriceUsd": 73.2154,
          "isLong": false,
          "leverage": 3,
          "liquidationPriceUsd": 318.2999341375,
          "notionalUsd": 7819585.043392,
          "side": "short",
          "unrealizedPnlUsd": 181526.48169
        },
        {
          "coin": "LINK",
          "entryPriceUsd": 10.68094,
          "isLong": false,
          "leverage": 10,
          "liquidationPriceUsd": 108.1269687531,
          "notionalUsd": 2740099.21641,
          "side": "short",
          "unrealizedPnlUsd": 217000.164398
        },
        {
          "coin": "XRP",
          "entryPriceUsd": 1.031289,
          "isLong": false,
          "leverage": 10,
          "liquidationPriceUsd": 12.9894399756,
          "notionalUsd": 2436703.8969,
          "side": "short",
          "unrealizedPnlUsd": 7084.831668
        },
        "… 80 more"
      ]
    },
    {
      "accountValueUsd": 15980850.244409,
      "address": "0xfc667adba8d4837586078f4fdcdc29804337ca06",
      "positions": [
        {
          "coin": "BTC",
          "entryPriceUsd": 71343,
          "isLong": false,
          "leverage": 20,
          "liquidationPriceUsd": 306967.210522249,
          "notionalUsd": 4394434.38336,
          "side": "short",
          "unrealizedPnlUsd": 171985.862449
        },
        {
          "coin": "SOL",
          "entryPriceUsd": 85.9684,
          "isLong": true,
          "leverage": 20,
          "notionalUsd": 4034279.01123,
          "side": "long",
          "unrealizedPnlUsd": -302225.826785
        },
        {
          "coin": "HYPE",
          "entryPriceUsd": 73.3347,
          "isLong": false,
          "leverage": 5,
          "liquidationPriceUsd": 359.1363171546,
          "notionalUsd": 3659733.506648,
          "side": "short",
          "unrealizedPnlUsd": 91056.966892
        },
        {
          "coin": "XRP",
          "entryPriceUsd": 1.125748,
          "isLong": true,
          "leverage": 20,
          "notionalUsd": 3286568.1394,
          "side": "long",
          "unrealizedPnlUsd": -311457.488645
        },
        {
          "coin": "ETH",
          "entryPriceUsd": 1974.36,
          "isLong": true,
          "leverage": 20,
          "notionalUsd": 1306963.38084,
          "side": "long",
          "unrealizedPnlUsd": -26177.570668
        },
        {
          "coin": "NEAR",
          "entryPriceUsd": 3.62058,
          "isLong": false,
          "leverage": 10,
          "liquidationPriceUsd": 69.3856855306,
          "notionalUsd": 785005.87675,
          "side": "short",
          "unrealizedPnlUsd": 23465.349135
        },
        "… 2 more"
      ]
    },
    {
      "accountValueUsd": 1878591.25797,
      "address": "0xf5d81a135f756ca16544e53c20fc20643ec3ad53",
      "positions": [
        {
          "coin": "BTC",
          "entryPriceUsd": 68831.3,
          "isLong": true,
          "leverage": 3,
          "liquidationPriceUsd": 37122.3937771081,
          "notionalUsd": 3997256.67712,
          "side": "long",
          "unrealizedPnlUsd": -10208.825107
        },
        {
          "coin": "ETH",
          "entryPriceUsd": 1936.15,
          "isLong": true,
          "leverage": 3,
          "notionalUsd": 316132.64424,
          "side": "long",
          "unrealizedPnlUsd": -91.356084
        },
        {
          "coin": "SOL",
          "entryPriceUsd": 79.7816,
          "isLong": true,
          "leverage": 3,
          "notionalUsd": 67075.91013,
          "side": "long",
          "unrealizedPnlUsd": 163.81962
        },
        {
          "coin": "HYPE",
          "entryPriceUsd": 71.3803,
          "isLong": true,
          "leverage": 3,
          "notionalUsd": 65346.340256,
          "side": "long",
          "unrealizedPnlUsd": 158.965107
        },
        {
          "coin": "ZEC",
          "entryPriceUsd": 940.2202,
          "isLong": false,
          "leverage": 3,
          "liquidationPriceUsd": 83715.558272885,
          "notionalUsd": 19653.8748,
          "side": "short",
          "unrealizedPnlUsd": -40.879463
        },
        {
          "coin": "INIT",
          "entryPriceUsd": 0.119296,
          "isLong": true,
          "leverage": 3,
          "notionalUsd": 9002.22097,
          "side": "long",
          "unrealizedPnlUsd": -9.553578
        },
        "… 24 more"
      ]
    }
  ],
  "generatedAt": "2026-11-13T08:05:43.5387675+00:00"
}
```

Over MCP the text report a model reads comes with it:

```text
Whale positions (Hyperliquid) — 5 largest verified-live accounts from the venue leaderboard
  0x5b5d…c060 — equity $71.4M, open notional $328.1M across 23 positions:
    BTC SHORT $140.7M @ 76361.6 | liq 103854 | 5x | uPnL +$15.8M
    ETH SHORT $57.3M @ 2322.72 | liq 4368.89 | 5x | uPnL +$11.5M
    HYPE SHORT $42.2M @ 75.4377 | liq 185.451 | 5x | uPnL +$2.3M
    ZEC SHORT $34.4M @ 1478.36 | liq 2781.67 | 3x | uPnL +$19.6M
    SOL SHORT $33.7M @ 94.3346 | liq 248.85 | 7x | uPnL +$6.0M
    XMR SHORT $4.1M @ 607.395 | liq 9141.49 | 3x | uPnL +$607k
    (+17 smaller positions)
  0xb83d…6e36 — equity $64.0M, open notional $261.8M across 30 positions:
    BTC SHORT $108.1M @ 77924.2 | liq 110424 | 5x | uPnL +$14.6M
    HYPE SHORT $66.0M @ 75.2795 | liq 137.526 | 5x | uPnL +$3.4M
    ZEC SHORT $46.7M @ 1336.39 | liq 2170.1 | 3x | uPnL +$19.5M
    SOL SHORT $7.2M @ 91.3463 | liq 807.576 | 5x | uPnL +$1.0M
    DOGE SHORT $5.0M @ 0.094571 | liq 0.857081 | 3x | uPnL +$2.3M
    ENA SHORT $4.9M @ 0.243779 | liq 1.85827 | 2x | uPnL +$3.8M
    (+24 smaller positions)
  0xecb6…2b00 — equity $32.9M, open notional $79.0M across 86 positions:
    ETH SHORT $18.9M @ 1967.39 | liq 4849.32 | 15x | uPnL +$311k
    SOL SHORT $12.3M @ 85.5308 | liq 264.003 | 20x | uPnL +$855k
    BTC SHORT $8.5M @ 68934.7 | liq 300620 | 20x | uPnL +$34k
    HYPE SHORT $7.8M @ 73.2154 | liq 318.3 | 3x | uPnL +$182k
    LINK SHORT $2.7M @ 10.6809 | liq 108.127 | 10x | uPnL +$217k
    XRP SHORT $2.4M @ 1.03129 | liq 12.9894 | 10x | uPnL +$7k
    (+80 smaller positions)
  0xfc66…ca06 — equity $16.0M, open notional $18.5M across 8 positions:
    BTC SHORT $4.4M @ 71343 | liq 306967 | 20x | uPnL +$172k
    SOL LONG $4.0M @ 85.9684 | liq - | 20x | uPnL -$302k
    HYPE SHORT $3.7M @ 73.3347 | liq 359.136 | 5x | uPnL +$91k
    XRP LONG $3.3M @ 1.12575 | liq - | 20x | uPnL -$311k
    ETH LONG $1.3M @ 1974.36 | liq - | 20x | uPnL -$26k
    NEAR SHORT $785k @ 3.62058 | liq 69.3857 | 10x | uPnL +$23k
    (+2 smaller positions)
  0xf5d8…ad53 — equity $1.9M, open notional $4.5M across 30 positions:
    BTC LONG $4.0M @ 68831.3 | liq 37122.4 | 3x | uPnL -$10k
    ETH LONG $316k @ 1936.15 | liq - | 3x | uPnL -$91
    SOL LONG $67k @ 79.7816 | liq - | 3x | uPnL +$164
    HYPE LONG $65k @ 71.3803 | liq - | 3x | uPnL +$159
    ZEC SHORT $20k @ 940.22 | liq 83715.6 | 3x | uPnL -$41
    INIT LONG $9k @ 0.119296 | liq - | 3x | uPnL -$10
    (+24 smaller positions)
```

## Related tools

- [Order Book](https://www.f1ow.com/docs/tools/flow_orderbook) — Best bid and ask, spread, depth and imbalance, with venue-labelled books and resting walls. Orders can be pulled: visible liquidity is evidence, not a promise of execution.
- [Perp Price Levels](https://www.f1ow.com/docs/tools/flow_levels) — Executed volume profiles, value areas, thin zones, inferred long/short entries, realized liquidation prices and persistent resting walls across venues. Levels graded by traded, inferred or resting evidence, with confluence disclosed — not a price forecast.
- [Whale Context](https://www.f1ow.com/docs/tools/flow_whale_context) — The cohort view: exchange reserve changes, top-trader long/short lean, and the large exchange-linked transfers that tend to arrive before a move does.
- [Market Regime](https://www.f1ow.com/docs/tools/research_regime) — What kind of market you are trading in. Seven forces — trend, volatility, cycle, sentiment, leverage stress, ETF liquidity, rotation — each voting with its own reasoning and its own threshold for changing the call.