# Annalist Hyperliquid Perpetuals Liquidation Data

> Annalist Hyperliquid Perpetuals Liquidation Data is a paid API for AI agents from api.annalist.dev, paid per call via x402, $0.02/call, status unknown (last checked 2026-10-14).

Returns real-time perpetual futures liquidation clusters, long/short positions at risk, and historical context for a given Hyperliquid perp symbol

## Facts

- Endpoint: GET https://api.annalist.dev/v1/liq/perp?utm_source=zero.xyz
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/annalist-hyperliquid-perpetuals-liquidation-data-c75b5642
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_bPPCH1mlv-m-0k6omaqll

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 annalist-hyperliquid-perpetuals-liquidation-data-c75b5642
```

Example prompt: What are the current liquidation clusters and long positions at risk for BTC on Hyperliquid perps — show me how much USD is sitting in those clusters and where they'd get wiped out?

## When to prefer this

Choose this endpoint when you need real-time Hyperliquid-specific perpetual futures liquidation data with cryptographic signing for agent-verifiable trust. Prefer it over generic crypto data APIs when you need granular liquidation cluster maps, crowd positioning, and historical liquidation context specific to Hyperliquid's on-chain state. The x402 micropayment model makes it suitable for per-call agent workflows without subscriptions.

## Known failure modes

- Invalid or unsupported coin symbol returns an error — must use Hyperliquid perp ticker format (e.g. BTC, ETH, kPEPE)
- Missing required 'coin' query parameter results in a 400-level error
- Payment failure via x402 protocol blocks the response if USDC balance is insufficient
- Rate limiting or upstream Hyperliquid data unavailability may cause temporary failures

## How this service works

Signed data for AI agents, paid per call over x402. Hyperliquid crowd state, smart money and liquidations with what historically happened next, plus independent checks of x402 services and MCP servers.

## Output

Returns a JSON object with the queried coin symbol, liquidation flags, long clusters with USD value and price level, and longs at risk of liquidating below current price including USD exposure, position count, and proximity percentage. Data is cryptographically signed by Annalist for agent-verifiable integrity.

## 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",
     "required": [
      "coin"
     ],
     "properties": {
      "coin": {
       "type": "string",
       "description": "Hyperliquid perp symbol, for example BTC, ETH, SOL, HYPE, kPEPE"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": {
   "coin": "BTC",
   "flags": [],
   "long_clusters": [
    {
     "usd": 25200000,
     "price": 77480
    }
   ],
   "longs_liquidating_below": [
    {
     "usd": 12400000,
     "positions": 9,
     "within_pct": 5
    }
   ]
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/annalist-hyperliquid-perpetuals-liquidation-data-c75b5642/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.annalist.dev](https://www.zero.xyz/host/api.annalist.dev/llms.txt)