# Whale Radar (Hyperliquid perps)

> Where are Hyperliquid's whales and best traders positioned right now? Give it a perp (BTC, ETH, SOL, HYPE, ...) or ALL. Get back: whale and smart-money net long/short, the biggest tracked positions with entry, liquidation price, leverage and uPnL, a liquidation-cluster map around the mark (where forced selling/buying would hit), funding/OI/premium crowding and squeeze risk, and a one-line verdict. Not investment advice.

## Pricing
- $0.05 USDC per call on Base mainnet.
Status: LIVE: real USDC payments.
- x402: $0.05 USDC on Base mainnet (asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, amount 50000 base units, payTo 0xeE6239F3E17bEBe5e89F21F29D74D68CAa0d78CE); send PAYMENT-SIGNATURE

## How to call
- POST https://seenly-whale-radar.vercel.app/api/whale-radar  {"coin":"BTC","top":8}
- or GET https://seenly-whale-radar.vercel.app/api/whale-radar?coin=BTC   (coin=ALL → market-wide whale book + funding extremes)
- Unpaid call → HTTP 402 with PAYMENT-REQUIRED (x402 v2, exact, USDC on Base). Sign with an x402 client (e.g. @x402/fetch) and retry with PAYMENT-SIGNATURE. The payer needs USDC only; the Coinbase facilitator pays gas.
- Unknown coin → 422 before payment. Upstream failure → 503, not charged.
- The 402 carries Coinbase x402 Bazaar discovery metadata (extensions.bazaar: input/output JSON Schemas and examples).

## Free daily allowance (opt-in)
- 3 free calls per caller per UTC day (caller = client network: IPv4 /24, IPv6 /64), and at most 50 free calls per day across all callers.
- Opt in per request with header "X-Free-Allowance: use" (or ?free=1). Without it you always get the normal x402 402, so registries and x402 clients are unaffected.
- A granted free call returns 200 with header X-Free-Allowance (used, remaining, limit, resets) and a free_allowance block in the JSON. No payment is taken.
- When your allowance (or the global cap) is used up, the same request returns the normal x402 402 with free_allowance.status (caller_limit / global_limit). Pay as usual.
- Free calls are never sales: they create no settlement and never count toward Agentropolis trust, stats or badges. Calls through the Agentropolis relay always use x402.
- Example: curl -s https://seenly-whale-radar.vercel.app/api/whale-radar -H 'content-type: application/json' -H 'X-Free-Allowance: use' -d '{"coin":"BTC"}'

## Output
coin, market (mark/oracle, premium %, funding hourly/APR/percentile, OI USD, 24h volume/change), whales (cohort coverage, holders, long/short notional + avg entry + uPnL, net bias, share of OI, smart_money bias, top_positions[] with liquidation_px and distance), liquidation_map (1% bands below/above mark, notional within 5%), crowding (score, LONG_CROWDED/SHORT_CROWDED/BALANCED, squeeze_risk, liquidation_magnet, reasons), verdict, one_liner, as_of, sources, disclaimer.

## Method and sources
- Cohort: ~50 largest accounts by account value + ~50 best 30-day PnL accounts (>= $250k, profitable all-time), from Hyperliquid's public leaderboard file; refreshed every 6 h.
- Positions: Hyperliquid info API clearinghouseState for each tracked account, cached ~90 s. Market: metaAndAssetCtxs (funding, OI, premium, mark/oracle).
- Crowding: funding APR and mark-oracle premium say which side is paying; whale skew and stacked liquidations within 5% flag squeeze risk. Deterministic, no LLM.
- Coverage is partial (tracked cohort only, not all traders). Addresses are public on-chain accounts.

## Discovery
- OpenAPI: https://seenly-whale-radar.vercel.app/openapi.json · Kit manifest: https://seenly-whale-radar.vercel.app/.well-known/kits.json · x402: https://seenly-whale-radar.vercel.app/.well-known/x402 · A2A: https://seenly-whale-radar.vercel.app/.well-known/agent-card.json
- Contact: hello@agentropolis.io
- Also listed on Agentropolis: https://agentropolis.io

## Agentropolis listing & badge
- Listing: https://agentropolis.io/listing/seenly.seenly-whale-radar (first-party, affiliated with Agentropolis)
- Badge SVG: https://agentropolis.io/badge/seenly.seenly-whale-radar.svg (trust: no independent sales yet)
- Tiers explained: https://agentropolis.io/badges