{"uid":"cap_beDQ6Tmhl7wqwVjkxdXZy","slug":"perpgap-api-stock-perp-price-gap-scanner-72fe9221","name":"PerpGap API – Stock Perp Price Gap Scanner","description":"Gap table for trade.xyz (Hyperliquid HIP-3) stock perps: perp mark/oracle vs live stock price and Solana xStock, basis, hourly and annualized funding, open interest; venues=all adds Aster and Lighter marks, funding and cross-venue spreads. Use when an agent needs current premium/discount or funding arbitrage signals across many tokenized stocks at once (cheapest call). Errors: 402 payment required, 502 upstream error.","url":"https://perp-gap-api.perpgap.workers.dev/gaps?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":[],"properties":{"venues":{"enum":["all"],"type":"string","examples":["all"],"description":"Optional. 'all' adds per-ticker cross-venue comparison: trade.xyz vs Aster vs Lighter marks, gaps and funding (hourly + annualized). Omit for trade.xyz only."},"tickers":{"type":"string","examples":["TSLA,NVDA,GME","all"],"description":"Optional. Comma-separated tickers or \"all\" (auto-discovered US stock perps; see free GET /tickers), max 60 per call (highest OI kept). Default: 20 large names. Unknown tickers are skipped."}},"additionalProperties":false}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["rows"],"properties":{"dex":{"type":"string"},"rows":{"type":"array","items":{"type":"object","required":["ticker","perp_mark"],"properties":{"flags":{"type":"array","items":{"type":"string"}},"ref_ts":{"type":["integer","null"]},"ticker":{"type":"string"},"venues":{"type":"object","description":"Only with venues=all. xyz/aster/lighter objects {mark,index,funding_hourly,funding_annualized_pct,volume_24h_usd,open_interest_usd} or null, plus gap_aster_vs_xyz_pct, gap_lighter_vs_xyz_pct, gap_lighter_vs_aster_pct, gap_aster_vs_ref_pct, gap_lighter_vs_ref_pct, max_mark_spread_pct, richest, cheapest, funding_spread_annualized_pct."},"perp_ts":{"type":"integer"},"perp_mark":{"type":["number","null"]},"ref_price":{"type":["number","null"]},"ref_source":{"type":["string","null"],"description":"yahoo, alpaca-overnight (bid_ask_mid|last_trade) or robinhood-24h fallback (overnight)"},"perp_oracle":{"type":["number","null"]},"ref_session":{"type":["string","null"]},"xstock_price":{"type":["number","null"]},"open_interest":{"type":["number","null"]},"funding_hourly":{"type":["number","null"]},"market_session":{"enum":["pre-market","regular","after-hours","overnight","closed"],"type":"string"},"ref_age_seconds":{"type":["integer","null"]},"open_interest_usd":{"type":["number","null"]},"gap_perp_vs_ref_pct":{"type":["number","null"]},"funding_annualized_pct":{"type":["number","null"]},"gap_perp_vs_xstock_pct":{"type":["number","null"]},"basis_mark_vs_oracle_pct":{"type":["number","null"]}}}},"count":{"type":"integer"},"disclaimer":{"type":"string"},"generated_at":{"type":"integer"}},"description":"Error responses are JSON {error: string}: 402 payment required; 502 upstream data error."}}}}},"responseSchema":{"type":"json","example":{"dex":"xyz","rows":[{"flags":[],"ticker":"TSLA","perp_mark":366.28,"ref_price":366.13,"perp_oracle":366.14,"ref_session":"regular","xstock_price":366.37,"funding_hourly":0.00000625,"open_interest_usd":41383684.29,"gap_perp_vs_ref_pct":0.041,"funding_annualized_pct":5.475,"gap_perp_vs_xstock_pct":-0.0246,"basis_mark_vs_oracle_pct":0.0382}],"count":1,"disclaimer":"Data, not financial advice.","generated_at":1791998269}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Do0oGQ1ld4iJsOX_KIu4K","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns real-time price gaps, funding rates, basis, open interest, and cross-venue comparisons for US stock perpetual futures across trade.xyz, Aster, and Lighter versus real stock prices and Solana xStocks.","exampleAgentPrompt":"Pull the current price gaps and funding rates for TSLA, NVDA, and AAPL perps across all venues — trade.xyz, Aster, and Lighter — and compare them against the real stock prices and xStock prices so I can spot any arbitrage opportunities.","exampleUseCases":[{"title":"Spot perp arbitrage across DeFi venues","prompt":"Check TSLA and NVDA right now — what are the price gaps between their perps on trade.xyz, Aster, and Lighter versus the actual stock price, and which venue is cheapest?"},{"title":"Monitor funding rates for yield strategy","prompt":"Give me the hourly and annualized funding rates for the top 20 US stock perps on DeFi exchanges so I can figure out which ones are worth farming for funding yield."},{"title":"Cross-venue OI and spread dashboard","prompt":"Fetch open interest, basis, and cross-venue mark spreads for all available US stock perps across trade.xyz, Aster, and Lighter — I want to see which tickers have the widest spreads."}],"resultDescription":"A JSON object with an array of rows per ticker, each containing: perp mark price, reference stock price (from Yahoo, Alpaca, or Robinhood), xStock price on Solana, price gap percentages (perp vs ref, perp vs xStock), oracle price, funding rate (hourly and annualized), open interest in USD, market session, flags, and optionally (with venues=all) per-venue breakdowns for trade.xyz, Aster, and Lighter including cross-venue gap percentages, richest/cheapest venue labels, and funding spread. Also includes a generated_at timestamp and disclaimer.","failureModes":["Invalid ticker returns null or missing row in results","More than 60 tickers requested may be truncated to highest OI subset","Reference price unavailable (ref_price null) when Yahoo/Alpaca/Robinhood all fail","Perp mark null if venue has no active market for that ticker","Payment failure via x402 if USDC balance insufficient on Base or Solana","Rate limiting or worker timeout on very large ticker sets"],"whenToPreferThis":"Use this endpoint when you need real-time, cross-venue price gap data specifically for US stock perpetual futures on DeFi platforms (trade.xyz, Aster, Lighter) compared against real stock prices and Solana xStocks. Prefer this over generic crypto data APIs when the user wants basis, funding arbitrage, or cross-venue spread analysis for tokenized stock perps. Ideal for DeFi arbitrage bots, funding rate yield strategies, or perp market monitoring agents.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-19T00:35:42.794Z","isFirstParty":false,"canonicalSlug":"perpgap-api-stock-perp-price-gap-scanner-72fe9221"}