# ByKaranteli Hyperliquid Positions Hourly History

> ByKaranteli Hyperliquid Positions Hourly History is a paid API for AI agents from bykaranteli.com, paid per call via x402, $0.1/call, status unknown (last checked 2026-11-16).

Returns per-position hourly snapshots of every open trade held by the 1000 largest Hyperliquid accounts by equity, filterable by coin, address, and time range.

## Facts

- Endpoint: GET https://bykaranteli.com/api/x402/hl-positions-history?utm_source=zero.xyz
- Price: $0.1/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-16
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/bykaranteli-hyperliquid-positions-hourly-history-afa7037b
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_AzpyKeXiGtkohG1fkkQ-c

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-positions-hourly-history-afa7037b
```

Example prompt: Pull hourly position history for the top 1000 Hyperliquid accounts on BTC from 2025-06-01 to 2025-06-07, up to 500 rows, so I can see their entry prices, leverage, and liquidation levels over that week.

## When to prefer this

Use this endpoint when you need granular per-position row data for the largest Hyperliquid accounts historically — specifically when you need entry price, liquidation price, leverage, and size at an individual position level over time. The free /api/public/hyperliquid-positions endpoint only provides live liquidation bands and hourly aggregated totals, not per-position rows. Prefer this when doing whale tracking, liquidation risk analysis, or backtesting based on actual large-account positioning.

## Known failure modes

- Invalid address format (not 0x + 40 hex chars) returns an error
- Requesting data before 2026-09-30 (the history start date) returns empty results
- Exceeding the 1000-row default or 20000-row max limit truncates results silently
- Invalid ISO timestamp format in from/to parameters causes a parse error
- Payment failure or insufficient USDC credit returns a 402 Payment Required response

## How this service works

Every open position of the 1000 largest Hyperliquid accounts by equity once an hour: address, coin, signed size, notional, entry and liquidation price, leverage and account equity, recorded from 2026-09-30, newest hour first; filter by coin, address and time. The free /api/public/hyperliquid-positions serves the live liquidation bands and hourly totals, never per position rows.

## Output

A list of per-position hourly records for the top 1000 Hyperliquid accounts by equity, each row containing account address, coin, signed size, notional value, entry price, liquidation price, leverage, account equity, and the snapshot timestamp. Results are ordered newest hour first and can be filtered by coin symbol, account address, and time range.

## 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, default now"
      },
      "from": {
       "type": "string",
       "description": "iso, optional, default 7 days ago"
      },
      "limit": {
       "type": "number",
       "description": "number, optional, max 20000"
      },
      "symbol": {
       "type": "string",
       "description": "string, optional coin, e.g. BTC"
      },
      "address": {
       "type": "string",
       "description": "string, optional account, 0x and 40 hex characters"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/bykaranteli-hyperliquid-positions-hourly-history-afa7037b/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)
