# Perp Gap API

> Cross-venue price gaps for trade.xyz stock perps on Hyperliquid (HIP-3) vs the underlying stock (pre-market, regular, after-hours or overnight) and Solana xStocks. Also returns basis, funding and open interest, plus a rule-based long/short/watch/avoid verdict using SEC EDGAR insider and filing signals. Pay per call with x402 in USDC on Base or Solana mainnet. No account and no API key. Data, not financial advice.

## HTTP (x402)
- [GET /gaps?tickers=TSLA,NVDA](https://perp-gap-api.perpgap.workers.dev/gaps): $0.01. Up to 20 tickers. Unpaid requests return 402 with a PAYMENT-REQUIRED header.
- [GET /gaps?tickers=TSLA,NVDA&venues=all](https://perp-gap-api.perpgap.workers.dev/gaps): same price. Adds a cross-venue comparison per ticker: trade.xyz vs Aster vs Lighter mark prices, gap % between venues and vs the stock, and each venue's funding (hourly and annualized).
- [GET /verdict?ticker=GME](https://perp-gap-api.perpgap.workers.dev/verdict): $0.03. Verdict, score, confidence, reasons and inputs, plus a per-ticker news block and a heuristic news_context.
- [GET /research?ticker=TSLA](https://perp-gap-api.perpgap.workers.dev/research): $0.03. Ticker research card in one JSON: spot quote and market session (pre-market/regular/after-hours/overnight/closed), perp prices on trade.xyz, Aster and Lighter, gap % per venue vs spot and vs the xStock, funding and basis, recent 72h gap history, and the rule-based verdict.

- [GET /history?ticker=TSLA&from=&to=&interval=1h](https://perp-gap-api.perpgap.workers.dev/history): $0.02. Historical gap time series (live 30-minute snapshots plus about 60 days of backfill), up to 90 days per query.
- [GET /export?date=YYYY-MM-DD&format=csv](https://perp-gap-api.perpgap.workers.dev/export): $0.25. Every snapshot for one UTC day across all tracked tickers, as CSV or JSON.

- [GET /tickers](https://perp-gap-api.perpgap.workers.dev/tickers): free. Auto-discovered list of covered US stock/ETF perps on trade.xyz (refreshed every 6h), highest open interest first.

## MCP
- [https://perp-gap-api.perpgap.workers.dev/mcp](https://perp-gap-api.perpgap.workers.dev/mcp): Streamable HTTP MCP server. get_gap_sample is free; get_gaps ($0.01), get_verdict ($0.03), get_research_card ($0.03), get_history ($0.02) and get_export ($0.25) are paid with x402 over MCP.

## Machine-readable
- [OpenAPI](https://perp-gap-api.perpgap.workers.dev/openapi.json)
- [x402 discovery](https://perp-gap-api.perpgap.workers.dev/.well-known/x402)
- [MCP server card](https://perp-gap-api.perpgap.workers.dev/.well-known/mcp/server-card.json)
- [A2A agent card](https://perp-gap-api.perpgap.workers.dev/.well-known/agent-card.json)
- [agents.json](https://perp-gap-api.perpgap.workers.dev/agents.json)

## Sources
Hyperliquid info API (dex "xyz"), Aster futures API, Lighter API, Yahoo Finance chart, DexScreener / Jupiter (xStocks), SEC EDGAR. Missing values are null. Overnight (20:00-04:00 ET, Sun-Thu nights) the stock reference comes from Alpaca's overnight feed (Blue Ocean ATS; bid/ask mid or 15-min-delayed last trade), falling back to Robinhood 24 Hour Market quotes (ref_session 'overnight'); every row carries ref_source and ref_age_seconds; NYSE holidays and weekends are labelled closed.

## Contact
- Email: webexpert@mail.grokbot.com
- Website: https://perp-gap-api.perpgap.workers.dev/
- Health: https://perp-gap-api.perpgap.workers.dev/health