# Annalist Crowd-State Change Events (Polling)

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

Returns a time-ordered stream of crowd-state entry/exit events for Hyperliquid perpetuals since a given timestamp, each signed with the mark price at event time.

## Facts

- Endpoint: GET https://api.annalist.dev/v1/crowd/changes?utm_source=zero.xyz
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/annalist-crowd-state-change-events-polling-76a22673
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_NB_z9zgRmiSM_n0DL9G2m

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-crowd-state-change-events-polling-76a22673
```

Example prompt: Pull all Hyperliquid crowd-state change events since 2024-06-01T12:00:00Z — I want to see which perps entered or exited crowded or hype states and what the mark price was at the time of each event.

## When to prefer this

Choose this endpoint when building a polling bot or event-driven workflow that needs to detect crowd-state transitions on Hyperliquid perps incrementally — i.e., you track a cursor timestamp and want only changes since your last poll. Prefer the historical backtesting sibling endpoint if you need up to 30 days of data in one call, or the current-state endpoint if you want a snapshot of all currently crowded perps without caring about transitions.

## Known failure modes

- Missing or invalid `since` query parameter returns a 400 error
- Timestamp older than 7 days may return an empty result set or an error indicating the lookback limit
- Malformed date-time format (not ISO 8601) causes a 400 validation error
- No events in the window returns an empty array (not an error)
- x402 payment not provided or insufficient returns a 402 Payment Required response
- Service downtime or rate limits may return 503 or 429 errors

## 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 crowd-state change events (newest first) covering up to 7 days back from the request time. Each event includes the perpetual symbol, the type of state transition (entry/exit, crowded/hype), a timestamp, and a mark price signed at the time of the event. Events are filtered to those occurring after the provided `since` 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",
     "required": [
      "since"
     ],
     "properties": {
      "since": {
       "type": "string",
       "format": "date-time"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": {
   "events": [
    {
     "ts": "2026-10-12T14:07:00Z",
     "coin": "XYZ",
     "type": "enter",
     "state": "up_100pct_7d"
    }
   ]
  }
 }
}
```

## More

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