x402-smartperps / tree / README.md · raw (this view has old GitHub links rewritten for the mirror; raw is byte-exact)

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 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/

agentgate-source: code mirror on Cloudflare Pages. All repos