# Annalist (annalist.dev)

> Signed crowd-state and smart-money positioning data for Hyperliquid perpetuals, with historical base rates. Built for agents; pay per call over x402 (USDC on Base). No accounts, no API keys.

Every answer says what is happening (7-day moves, funding extremes, open interest, attention) and what historically followed similar states (sample size, median and spread of later returns). Responses are signed (Ed25519); the archive behind them is append-only with daily hashes published at https://github.com/ryanroskowski/annalist-ledger and timestamped in Bitcoin.

## Paid HTTP routes (x402)
- GET /v1/crowd/perp ($0.01): Use before acting on a Hyperliquid perpetual to see whether it is crowded or in a hype state and what historically followed. Returns 7-day move, funding (hourly, APR, percentile vs its own 90 days and vs all perps), open interest and its 24h/7d change, premium, Wikipedia attention, active crowd states, and each state's base rates (sample size, median and spread of 7/30/90-day returns). Signed. Not investment advice.
- GET /v1/crowd/states ($0.02): Every Hyperliquid perp currently in a crowd state (7-day moves of +50/+100/+200%, funding in its own top or bottom 5%, Wikipedia attention spikes, new listings), ranked by 7-day move, each with base rates for what followed similar states historically. Optional ?state= filter. Signed. Not investment advice.
- GET /v1/crowd/market ($0.01): Market-wide crowding on Hyperliquid: breadth of 7-day moves, how many perps are up 50%+/100%+ in a week, share of perps with funding in their own top/bottom 5%, total open interest and its 24h change, BTC and ETH funding percentiles, and Wikipedia attention to cryptocurrency. Signed. Not investment advice.
- GET /v1/crowd/changes ($0.005): For bots that poll: crowd-state events (a perp entering or leaving a state) since a timestamp, newest first, up to 7 days back. Each event is signed with the mark price at the time. Not investment advice.
- GET /v1/crowd/history ($0.05): Signed historical crowd-state events for backtesting: up to 30 days per call, optionally filtered by coin and state. The archive is append-only and its daily hashes are published and Bitcoin-timestamped.
- GET /v1/smart/perp ($0.01): Use before acting on a Hyperliquid perpetual to see how the most profitable Hyperliquid traders are positioned in it: how many wallets in a 200-wallet smart-money cohort are long vs short, their long, short and net exposure in USD, the 24h change, how concentrated it is (largest wallet's share, trader-count view), leverage settings, their share of open interest, and how that compares with the crowd (funding, 7-day move). Flags smart money broadly positioned against a crowded move. Aggregates only, never wallet addresses. Signed. Not investment advice.
- GET /v1/smart/market ($0.02): Where Hyperliquid's most profitable traders are positioned across all perps: the cohort's overall net long or short, the coins it is most net long and most net short, the biggest 24-hour changes, and coins where smart money is positioned against the crowd. Cohort definition included. Aggregates only. Signed. Not investment advice.

## MCP
- Streamable HTTP endpoint: https://api.annalist.dev/mcp. Paid tools (crowd_perp, crowd_states, crowd_market, crowd_changes, crowd_history, smart_perp, smart_market) use x402 over MCP; free tools: annalist_about, annalist_baserates, annalist_market_sample, annalist_track_record.

## Free routes
- GET /v1/quote: prices and data freshness for every route
- GET /v1/status: collector freshness
- GET /v1/sample: the market view, delayed 24 hours
- GET /v1/baserates: the full base-rate tables and their definitions
- GET /v1/accuracy: the live track record of every state against its backtest
- GET /openapi.json, /.well-known/agent-card.json, /.well-known/annalist-key.json

Notice: Historical statistics and current market data. Not investment advice. Data, not recommendations. Hyperliquid restricts some jurisdictions from trading; we sell information only.