# On-Demand Liq & Whale Signal API

> Agent-First REST + MCP API for real-time Hyperliquid liquidation and smart-money signals: the
> largest leveraged positions closest to forced liquidation, net smart-money bias per coin, cascade
> risk clusters, executed liquidations, and whale entries/exits. Read-only. Built for AI agents,
> developers and automation teams — a single API call returns actionable data in under 2 minutes.

Base URL: https://goose-liq.duckdns.org (replace with the hosted URL in production).
Auth: send header `goose-LIQ-API-KEY: <key>` on every `/v1/*` call except `/v1/health`.
Get a key with zero friction: `POST /v1/keys/trial` returns a free 24h key (no signup, 1 per IP) — this is how an agent bootstraps access.
All list responses share the envelope `{ "data": [...], "count": N, "as_of": <ms>, "source": "..." }`.
Errors are machine-readable: `{ "error": { "code", "message", "hint" } }` — the `hint` tells an agent how to self-correct.

## Core endpoints
- [POST /v1/keys/trial](https://goose-liq.duckdns.org/v1/keys/trial): Get a free 24h trial API key — no signup, 1 per IP (idempotent). Returns {api_key, expires}. Use it in the goose-LIQ-API-KEY header. Start here.
- [GET /v1/positions/at-risk](https://goose-liq.duckdns.org/v1/positions/at-risk): Largest leveraged positions nearest forced liquidation ("liquidation radar"). Params: coin, min_notional, sort (distanz|groesse), limit.
- [GET /v1/consensus](https://goose-liq.duckdns.org/v1/consensus): Net long/short bias per coin among proven smart-money wallets. Params: min_wallets, limit.
- [GET /v1/cascades](https://goose-liq.duckdns.org/v1/cascades): Clusters of positions near liquidation on the same coin+side (cascade risk). Params: coin, danger_pct, acute_pct, min_wallets.
- [GET /v1/liquidations](https://goose-liq.duckdns.org/v1/liquidations): Most recent actually-executed forced liquidations with fill price. Params: coin, limit.
- [GET /v1/entries](https://goose-liq.duckdns.org/v1/entries): Fresh new positions opened by smart-money/whale wallets, with entry price. Params: coin, min_notional, limit.
- [GET /v1/exits](https://goose-liq.duckdns.org/v1/exits): Voluntary position closes by smart-money/whale wallets, with realized PnL. Params: coin, min_notional, limit.
- [GET /v1/wallets/{address}](https://goose-liq.duckdns.org/v1/wallets/): Wallet profile — tags (smart/whale/active), sources, liquidation history and stats.
- [GET /v1/coins](https://goose-liq.duckdns.org/v1/coins): All valid coin symbols in the current snapshot.
- [GET /v1/health](https://goose-liq.duckdns.org/v1/health): Status and data freshness (no key required).

## Docs
- [Full documentation](https://goose-liq.duckdns.org/docs): Interactive Swagger UI — try every endpoint in the browser.
- [OpenAPI schema](https://goose-liq.duckdns.org/openapi.json): Machine-readable API description.
- [Docs page (Markdown)](docs/index.md): Quickstart, endpoint reference, error format, copy-paste examples.

## MCP (for AI assistants)
- MCP server: `mcp_server/server.py` (stdio). Exposes the same actions as tools so assistants like Claude can call the tool directly.
- Tools: get_positions_at_risk, get_smart_money_consensus, get_cascades, get_recent_liquidations, get_whale_entries, get_whale_exits, lookup_wallet, list_coins.

## Notes
- Data source: public on-chain and leaderboard data from Hyperliquid perps. Read-only — the API can never place orders or modify data.
- Typical use: agents monitoring liquidation cascades, following smart-money entries/exits, or building trading strategies on top of the signals.