---
title: "Whale Positions"
method: GET
path: "/flow/whale-positions"
tags: ["flow"]
---

# Whale Positions

`GET /flow/whale-positions`

## Request

- Base URL: `https://mcp.f1ow.com/v1`
- URL: `https://mcp.f1ow.com/v1/flow/whale-positions`
- Auth: one of:
  - HTTP bearer
  - none

Live whale positions on Hyperliquid perps. 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.

## Query parameters

- `addresses` string: Optional comma-separated 0x wallet addresses to inspect (max 10). Omit to auto-discover the biggest live whales.

## Response `200`

The result.

- object
  - `data` object
    - `accounts` object[]
      - `address` string
      - `accountValueUsd` number: Wallet equity, USD
      - `positions` object[]
        - `coin` string
        - `side` string: long or short
        - `isLong` boolean
        - `notionalUsd` number: Position notional, USD
        - `entryPriceUsd` number: Entry price, USD
        - `liquidationPriceUsd` number: Liquidation price, USD; omitted when not liquidatable at current margin
        - `leverage` number: Position leverage as a multiple
        - `unrealizedPnlUsd` number: Unrealized PnL, USD
  - `text` string, required: Human-readable rendering of the result.
  - `meta` ResponseMeta
    - `generatedAt` string, date-time: When the data was produced (source timestamp where the provider has one), ISO 8601 UTC

## Other responses

- `400`: An argument is missing or invalid.
- `401`: No credential was sent.
- `402`: x402 route: a priced call without a valid payment (challenge in the base64 PAYMENT-REQUIRED header). Metered routes: the account balance or access period is spent.
- `403`: The credential was rejected.
- `500`: Unexpected server error.
- `502`: The data source could not answer.

---

[API](https://skmtc.dev/f1ow/apis/f1ow-api.md) · [All operations](https://skmtc.dev/f1ow/apis/f1ow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/f1ow/apis/f1ow-api/revisions/6974f25b6067?raw)