# SmartPerps: Hyperliquid smart-money positioning for trading agents (x402 API + MCP)

Is the smart money long or short? SmartPerps tracks a rules-based cohort of the **120 Hyperliquid accounts with the
highest 30-day PnL** (public leaderboard, all-time PnL > 0, account value >= $100k, market-maker-like volume
excluded) and reads their open perp positions every 5 minutes. Read-only analytics from public data.

> **Not financial advice. Past performance does not guarantee future results.** Bias labels are descriptive statistics
> of current public positions, not predictions or trade signals. SmartPerps never trades, never holds funds and never
> asks for keys.

- API: https://api.youraitools.co/smartperps (fallback https://smartperps.agentgate.workers.dev)
- Remote MCP: `https://api.youraitools.co/smartperps/mcp` (tool `smart_money_bias`, free preview)
- stdio MCP: `node src/mcp-stdio.js` (tools `smart_money_positioning`, `smart_money_scan`, `hyperliquid_wallet_profile`); npm package pending
- Docker: `docker build -t smartperps-mcp . && docker run -i --rm smartperps-mcp`

## Routes

| Route | Price | Returns |
|---|---|---|
| `GET/POST /v1/lite?symbol=BTC` | $0.003 | cohort traders long/short, long/short/net notional, bias, 1h/24h net flow, snapshot age, coverage |
| `GET/POST /v1/coin?symbol=ETH` | $0.02 | lite + 1h/4h/24h flows, avg entry vs mark, leverage, uPnL, concentration, liquidation price bands (count + notional per band), top 10 positions (addresses truncated, no liquidation prices) |
| `GET/POST /v1/scan?limit=10` | $0.03 | cohort book + coins most net long / net short / one-sided, biggest 24h buying and selling |
| `GET/POST /v1/wallet?address=0x...` | $0.01 | live profile of the Hyperliquid account you supply: equity, leverage, positions with distance to liquidation (whole %), 30-day fills, cohort rank |
| `GET /v1/preview?symbol=BTC` | free | bias + trader counts (10/min per IP) |

Pay with x402 v2 (USDC on Base, Polygon, Arbitrum One or Solana) or v1 (Base), or a prepaid
[YourAITools credits](https://api.youraitools.co/credits/) key (`Authorization: Bearer yatc_...`). Only HTTP 200 is
settled: bad input (400), unknown coins (404) and stale or incomplete data (503) are never charged.

## Privacy
- Cohort answers (`/v1/lite`, `/v1/coin`, `/v1/scan`, `/v1/preview`, MCP) never return full account addresses: top
  positions show a truncated address (`0x1234…abcd`) and no liquidation price.
- Liquidation data on these routes is grouped into price bands by distance from mark (0-2%, 2-5%, 5-10%, 10-25%,
  >25%) with a price range, position count and notional per band. Notional is withheld for bands with fewer than 3
  positions, so no band maps to one account.
- `/v1/wallet` profiles only the address the caller supplies, and shows each position's distance to liquidation in
  whole percent instead of the liquidation price.
- SmartPerps covers public on-chain data only. It must not be used to target or harass account holders.

## Fail-closed
- A snapshot older than 30 minutes or covering under 60% of the cohort is refused (503, not charged).
- 60-75% coverage: answered with bias `unknown`, confidence `low` and `sources_failed`.
- Leaderboard outage: the last-good cohort (up to 48 h) is used and `hyperliquid_leaderboard` is listed.
- Info API: `api.hyperliquid.xyz` with fallback `api-ui.hyperliquid.xyz`.

## How it works
Cron (every 5 min) → stream-parse the public leaderboard (hourly) → cohort → `clearinghouseState` per account →
per-coin aggregates + 26 h history in a SQLite Durable Object. Paid requests read the snapshot: no upstream call
between the 402 and the answer. Usage counters live in a separate SQLite DO (no KV).

## Develop
`npm test` (node --test), `npm run gen:examples` (re-record example outputs), `wrangler deploy`.

MIT. Built by agentgate-builder. Source: https://agentgate-source.pages.dev/x402-smartperps/