# Annalist Historical Crowd-State Events

> Annalist Historical Crowd-State Events is a paid API for AI agents from api.annalist.dev, paid per call via x402, $0.05/call, status unknown (last checked 2026-10-13).

Returns signed, Bitcoin-timestamped historical crowd-state events for Hyperliquid perpetuals over a specified date range, optionally filtered by coin and state type.

## Facts

- Endpoint: GET https://api.annalist.dev/v1/crowd/history?utm_source=zero.xyz
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/annalist-historical-crowd-state-events-c36bc195
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_tTtjaJDpG781VjKAahj6U

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-historical-crowd-state-events-c36bc195
```

Example prompt: Pull the Annalist crowd-state history for BTC on Hyperliquid from 2025-05-01 to 2025-05-30, filtering for up_100pct_7d events, so I can backtest my momentum strategy.

## When to prefer this

Choose this endpoint when you need tamper-evident, cryptographically signed historical crowd-state data for Hyperliquid perpetuals — specifically for backtesting trading strategies, auditing past hype cycles, or verifying crowd-state transitions with Bitcoin-timestamped provenance. Prefer it over real-time endpoints when your use case is retrospective analysis rather than live monitoring. The append-only archive with published daily hashes makes it uniquely suited for compliance, research, or strategy validation where data integrity must be provable.

## Known failure modes

- Date range exceeds 30 days — API rejects with an error
- Invalid coin symbol not found on Hyperliquid — returns empty result or error
- Invalid state enum value — request rejected with validation error
- No events exist for the given filter combination — returns empty list
- Payment failure via x402 — request blocked before execution
- Malformed date format (non ISO-8601) — returns 400 bad request

## 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

A list of signed historical crowd-state events for the requested date range, each timestamped and linked to a Bitcoin-anchored daily hash. Each event records a Hyperliquid perpetual entering or leaving a defined crowd state (e.g. up_50pct_7d, funding_top5, attention_spike_3x), with cryptographic signatures enabling independent verification of the archive's 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": [
      "from",
      "to"
     ],
     "properties": {
      "to": {
       "type": "string",
       "format": "date"
      },
      "coin": {
       "type": "string",
       "description": "Hyperliquid perp symbol, for example BTC, ETH, SOL, HYPE, kPEPE"
      },
      "from": {
       "type": "string",
       "format": "date"
      },
      "state": {
       "enum": [
        "up_50pct_7d",
        "up_100pct_7d",
        "up_200pct_7d",
        "funding_top5",
        "funding_bottom5",
        "attention_spike_3x",
        "new_listing"
       ],
       "type": "string"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": {
   "events": []
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/annalist-historical-crowd-state-events-c36bc195/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)