# Whale Context (`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.

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

## What it does

Aggregate whale context for one coin (cohort-level, no individual wallets): per-exchange reserve changes (1d/7d), top-trader long/short positioning on major-exchange perps, and large on-chain transfers to/from exchange wallets above a USD threshold. The transfer feed covers ERC-20 tokens; for native assets (BTC, ETH) it substitutes market-wide USDT exchange flows as a dry-powder signal. Exchange withdrawals suggest accumulation; deposits suggest potential sell pressure. For specific whale wallets and their live positions use flow_whale_positions.

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | string | path | yes | Coin symbol, e.g. "BTC" or "ETH". |
| `min_usd` | number | query | no | Minimum transfer size in USD to count as a whale transfer. Defaults to 1000000. |

## Call it

### cURL

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

### MCP

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

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/flow/whales/ETH", {
  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/whales/ETH",
    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_context",
    "arguments": {
      "symbol": "ETH"
    }
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "flow_whale_context",
    "arguments": {
      "symbol": "ETH"
    },
    "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/whales/ETH"
```

## Sample response

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

```json
{
  "reserves": {
    "net1dCoins": -4766.312464,
    "net7dCoins": 129277.52091,
    "venues": [
      {
        "balanceCoins": 3097618.071101,
        "change1dCoins": 1695.81836,
        "change1dPct": 0.05,
        "change7dCoins": 8063.872717,
        "change7dPct": 0.26,
        "exchange": "Coinbase"
      },
      {
        "balanceCoins": 3054100.711408,
        "change1dCoins": -53.163254,
        "change1dPct": 0,
        "change7dCoins": 5985.042272,
        "change7dPct": 0.2,
        "exchange": "Binance"
      },
      {
        "balanceCoins": 2637493.576821,
        "change1dCoins": 162.508217,
        "change1dPct": 0.01,
        "change7dCoins": 10238.553516,
        "change7dPct": 0.39,
        "exchange": "Bitfinex"
      },
      {
        "balanceCoins": 1128627.733144,
        "change1dCoins": -14006.617922,
        "change1dPct": -1.23,
        "change7dCoins": -24952.799027,
        "change7dPct": -2.16,
        "exchange": "OKX"
      },
      {
        "balanceCoins": 420590.432647,
        "change1dCoins": 10739.343454,
        "change1dPct": 2.62,
        "change7dCoins": 55533.562997,
        "change7dPct": 15.21,
        "exchange": "Bybit"
      },
      {
        "balanceCoins": 408249.635548,
        "change1dCoins": 4741.245639,
        "change1dPct": 1.18,
        "change7dCoins": 53706.515653,
        "change7dPct": 15.15,
        "exchange": "Gate"
      },
      "… 9 more"
    ]
  },
  "source": "CoinGlass",
  "symbol": "ETH",
  "topTraders": [
    {
      "longPct": 65.88,
      "longShortRatio": 1.93,
      "shortPct": 34.12,
      "timeMs": 1794168000000
    },
    {
      "longPct": 66.04,
      "longShortRatio": 1.95,
      "shortPct": 33.96,
      "timeMs": 1794182400000
    },
    {
      "longPct": 65.96,
      "longShortRatio": 1.94,
      "shortPct": 34.04,
      "timeMs": 1794196800000
    },
    {
      "longPct": 65.63,
      "longShortRatio": 1.91,
      "shortPct": 34.37,
      "timeMs": 1794211200000
    },
    {
      "longPct": 65.51,
      "longShortRatio": 1.9,
      "shortPct": 34.49,
      "timeMs": 1794225600000
    },
    {
      "longPct": 64.81,
      "longShortRatio": 1.84,
      "shortPct": 35.19,
      "timeMs": 1794240000000
    },
    "… 6 more"
  ],
  "transfers": {
    "depositCount": 43,
    "depositUsd": 529309178.41807,
    "largest": [
      {
        "amountUsd": 306869098,
        "asset": "USDT",
        "direction": "deposit",
        "exchange": "Binance",
        "timeMs": 1794290447000
      },
      {
        "amountUsd": 55000000,
        "asset": "USDT",
        "direction": "deposit",
        "exchange": "Coinbase",
        "timeMs": 1794294887000
      },
      {
        "amountUsd": 50000000,
        "asset": "USDT",
        "direction": "withdrawal",
        "exchange": "Binance",
        "timeMs": 1794302351000
      },
      {
        "amountUsd": 30000000,
        "asset": "USDT",
        "direction": "withdrawal",
        "exchange": "Binance",
        "timeMs": 1794292967000
      },
      {
        "amountUsd": 20525561.390882,
        "asset": "USDT",
        "direction": "withdrawal",
        "exchange": "Coinbase",
        "timeMs": 1794295223000
      },
      {
        "amountUsd": 20000000,
        "asset": "USDT",
        "direction": "withdrawal",
        "exchange": "Binance",
        "timeMs": 1794282911000
      },
      "… 44 more"
    ],
    "minUsd": 1000000,
    "proxyAsset": "USDT",
    "withdrawalCount": 57,
    "withdrawalUsd": 378523222.128867
  },
  "generatedAt": "2026-11-10T16:32:11.0000000+00:00"
}
```

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

```text
ETH whale activity (CoinGlass)
  exchange reserves (ETH): net change 1d -4766, 7d +129278
    top venues: Coinbase 3097618 (1d +0.05%, 7d +0.26%) | Binance 3054101 (1d +0.00%, 7d +0.20%) | Bitfinex 2637494 (1d +0.01%, 7d +0.39%)
  top traders (Binance perps, 4h): 64.8% long / 35.2% short (ratio 1.84) | 48h ago 65.9% long
  USDT flows >= $1.0M (market-wide dry-powder proxy; no native ETH feed): 43 deposits ($529.3M) vs 57 withdrawals ($378.5M)
    largest: $306.9M USDT deposit to Binance
```

## Related tools

- [Whale Positions](https://www.f1ow.com/docs/tools/flow_whale_positions) — Live whale accounts: equity, side, notional, entry, leverage, unrealized PnL — and the reported liquidation price of each position.
- [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.
- [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.