# ByKaranteli Hyperliquid Whale Position Events History

> ByKaranteli Hyperliquid Whale Position Events History is a paid API for AI agents from bykaranteli.com, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-13).

Returns historical position change events (opens, closes, size changes, flips) for the 300 largest Hyperliquid accounts by equity, recorded every 5 minutes since 2026-09-02, with full trade details.

## Facts

- Endpoint: GET https://bykaranteli.com/api/x402/hl-whale-events
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/bykaranteli-hyperliquid-whale-position-events-history-09711672
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_nbDvpoPL9tCFxw74-sLgr

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 bykaranteli-hyperliquid-whale-position-events-history-09711672
```

Example prompt: Pull all BTC position-change events from the top 300 Hyperliquid whale accounts between January 10 and January 15, 2027, limited to 500 results, and only show me events where they opened new positions.

## When to prefer this

Choose this endpoint when you need historical depth (back to 2026-09-02) on Hyperliquid whale position changes beyond the last 200 events available on the free board, or when you need to filter by specific coin, event type, or time window with up to 20,000 records per call. Prefer this over the free /api/public/hyperliquid-whales endpoint when doing backtesting, research, or alerting that requires more than the most recent 200 events.

## Known failure modes

- Invalid ISO date strings in from/to params return an error or empty result
- Limit exceeding 20000 may be rejected or clamped
- Unknown symbol values return empty rows rather than an error
- Payment failure (402) if the x402 payment header is missing or insufficient
- Rate limiting if called too frequently without valid payment

## How this service works

Every recorded position change of the 300 largest Hyperliquid accounts by equity (opened, closed, increased, reduced, flipped) with size before and after, notional changed, entry and liquidation price and leverage, scanned every 5 minutes on our side from 2026-09-02; the free /api/public/hyperliquid-whales returns the live board and only the last 200 events.

## Output

A JSON object with an 'ok' flag, a 'count' of returned rows, a 'dataset' label ('hl-whale-events'), and a 'rows' array. Each row contains details of a single position change event: the account, coin/symbol, event type (opened/closed/increased/reduced/flipped), position size before and after the event, notional USD amount changed, entry price, liquidation price, leverage used, and a timestamp.

## 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": {
      "to": {
       "type": "string",
       "description": "iso, optional"
      },
      "from": {
       "type": "string",
       "description": "iso, optional"
      },
      "limit": {
       "type": "number",
       "description": "number, optional, max 20000"
      },
      "symbol": {
       "type": "string",
       "description": "string, optional coin, e.g. BTC"
      },
      "exchange": {
       "type": "string",
       "description": "string, optional kind filter: opened | closed | increased | reduced | flipped"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "ok": true,
  "rows": [],
  "count": 500,
  "dataset": "hl-whale-events"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/bykaranteli-hyperliquid-whale-position-events-history-09711672/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from bykaranteli.com](https://www.zero.xyz/host/bykaranteli.com/llms.txt)