{"uid":"cap_TrXMOPK1ehp6odrLh5kfw","slug":"perp-gap-api-research-card-759a57ce","name":"Perp Gap API – Research Card","description":"One-call research card for a single stock perp: spot quote and US session (pre/regular/after-hours/overnight/closed), perp prices on trade.xyz, Aster and Lighter, gap % vs spot and vs Solana xStock, funding, basis, last 72h gap history and the rule-based long/short/watch/avoid verdict. Use when an agent needs everything about one ticker before trading or answering a user. Data, not advice. Errors: 400 missing ticker, 402, 404 not listed, 502 upstream.","url":"https://perp-gap-api.perpgap.workers.dev/research?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":["ticker"],"properties":{"ticker":{"type":"string","pattern":"^[A-Za-z0-9.]{1,10}$","examples":["TSLA","NVDA","GME"],"description":"One US stock ticker listed as a trade.xyz perp (see free GET /tickers), case-insensitive."}},"additionalProperties":false}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["ticker","market","spot","perps","verdict","disclaimer"],"properties":{"spot":{"type":"object","properties":{"price":{"type":["number","null"]},"source":{"type":["string","null"]},"change_pct":{"type":["number","null"]},"prev_close":{"type":["number","null"]},"age_seconds":{"type":["number","null"]},"price_session":{"type":["string","null"],"description":"pre, regular, post, overnight, closed or last_close"}}},"label":{"type":"string"},"perps":{"type":"object","properties":{"aster":{"type":"object","properties":{"mark":{"type":["number","null"]},"index":{"type":["number","null"]},"venue":{"type":"string"},"funding_hourly":{"type":["number","null"]},"gap_vs_spot_pct":{"type":["number","null"]},"gap_vs_xstock_pct":{"type":["number","null"]},"open_interest_usd":{"type":["number","null"]},"gap_vs_trade_xyz_pct":{"type":["number","null"]},"funding_annualized_pct":{"type":["number","null"]},"basis_mark_vs_index_pct":{"type":["number","null"]}}},"lighter":{"type":"object","properties":{"mark":{"type":["number","null"]},"index":{"type":["number","null"]},"venue":{"type":"string"},"funding_hourly":{"type":["number","null"]},"gap_vs_spot_pct":{"type":["number","null"]},"gap_vs_xstock_pct":{"type":["number","null"]},"open_interest_usd":{"type":["number","null"]},"gap_vs_trade_xyz_pct":{"type":["number","null"]},"funding_annualized_pct":{"type":["number","null"]},"basis_mark_vs_index_pct":{"type":["number","null"]}}},"trade_xyz":{"type":"object","properties":{"mark":{"type":["number","null"]},"index":{"type":["number","null"]},"venue":{"type":"string"},"funding_hourly":{"type":["number","null"]},"gap_vs_spot_pct":{"type":["number","null"]},"gap_vs_xstock_pct":{"type":["number","null"]},"open_interest_usd":{"type":["number","null"]},"gap_vs_trade_xyz_pct":{"type":["number","null"]},"funding_annualized_pct":{"type":["number","null"]},"basis_mark_vs_index_pct":{"type":["number","null"]}}}}},"market":{"type":"object","properties":{"holiday":{"type":["string","null"]},"session":{"enum":["pre-market","regular","after-hours","overnight","closed"],"type":"string"}}},"ticker":{"type":"string"},"xstock":{"type":["object","null"],"properties":{"price":{"type":["number","null"]},"gap_xstock_vs_spot_pct":{"type":["number","null"]},"gap_trade_xyz_vs_xstock_pct":{"type":["number","null"]}}},"history":{"type":"object"},"verdict":{"type":"object","properties":{"score":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"verdict":{"enum":["long","short","watch","avoid"],"type":"string"},"confidence":{"type":"number"}}},"disclaimer":{"type":"string"},"cross_venue":{"type":"object"},"generated_at":{"type":"integer"}},"description":"Error responses are JSON {error: string}: 400 ticker required; 402 payment required; 404 ticker not listed on trade.xyz; 502 upstream error."}}}}},"responseSchema":{"type":"json","example":{"card":"research","spot":{"price":365.57,"symbol":"TSLA","change_pct":1.2099,"prev_close":361.2,"price_session":"regular"},"label":"Data, not financial advice.","perps":{"aster":{"mark":366.01,"venue":"Aster","gap_vs_spot_pct":0.1204,"gap_vs_trade_xyz_pct":0.0875,"funding_annualized_pct":0},"lighter":{"mark":365.77,"venue":"Lighter","gap_vs_spot_pct":0.0547,"gap_vs_trade_xyz_pct":0.0219,"funding_annualized_pct":3.504},"trade_xyz":{"mark":365.69,"index":365.58,"venue":"trade.xyz (Hyperliquid xyz)","gap_vs_spot_pct":0.0328,"funding_annualized_pct":5.475,"basis_mark_vs_oracle_pct":0.0301}},"market":{"session":"regular","new_york_time":"Wed 16:00"},"ticker":"TSLA","xstock":{"chain":"solana","price":365.69,"symbol":"TSLAx","gap_xstock_vs_spot_pct":0.0328,"gap_trade_xyz_vs_xstock_pct":0},"history":{"points":72,"window":"last 72h, 1h buckets","available":true,"gap_perp_vs_ref_pct":{"avg":0.04,"max":0.31,"min":-0.12}},"verdict":{"score":0,"reasons":["perp vs reference gap +0.03%: in line, no edge"],"verdict":"watch","confidence":0.3},"disclaimer":"Data, not financial advice.","cross_venue":{"richest":"Aster","cheapest":"trade.xyz","max_mark_spread_pct":0.0875},"generated_at":1792010000}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.03","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.03/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.03","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.03","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_oUVcMnwiNb7KCTvGOSAqT","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.03","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns a full research card for a stock ticker including perp mark prices, price gaps vs spot and xStocks, funding rates, open interest, cross-venue spread, 72-hour gap history, and a rule-based trading verdict across trade.xyz, Aster, and Lighter.","exampleAgentPrompt":"Pull the full perp gap research card for TSLA — I want to see how the mark price on trade.xyz, Aster, and Lighter compares to the real stock price and the Solana xStock, plus the funding rates, any cross-venue spread, the 72-hour gap history, and the rule-based verdict on whether there's an edge.","exampleUseCases":[{"title":"Spot-perp arbitrage opportunity scan","prompt":"Check the perp gap research card for NVDA — I want to know if any of trade.xyz, Aster, or Lighter has a meaningful basis vs the real stock price right now, and what the rule-based verdict says about it."},{"title":"Funding rate comparison across venues","prompt":"What are the annualized funding rates for AAPL perps on trade.xyz, Aster, and Lighter right now? I'm trying to decide where it's cheapest to hold a long position."},{"title":"Cross-venue spread monitoring for a trade","prompt":"Is there a noticeable mark price spread between Aster and Lighter for TSLA perps at the moment? I want to know the richest and cheapest venue and how big the gap is."}],"resultDescription":"A JSON research card containing: spot price with session label and daily change, perp mark and index prices per venue (trade.xyz, Aster, Lighter) with gap vs spot %, gap vs xStock %, cross-venue gap %, annualized and hourly funding rates, basis (mark vs oracle/index), open interest in USD, Solana xStock price and gap vs spot, 72-hour rolling gap history (avg/min/max), cross-venue summary (richest/cheapest/max spread), and a rule-based verdict object with score, confidence, reasons, and a watch/act/ignore classification.","failureModes":["Unknown or unsupported ticker returns null fields or empty perp objects","Market closed outside regular hours causes spot price_session to be 'closed' or 'last_close' with stale price","Venue API outage causes null mark/index for that venue while others populate normally","Missing x402 payment header or insufficient USDC balance returns HTTP 402","Rate limit or Cloudflare Worker timeout returns HTTP 429 or 503"],"whenToPreferThis":"Use this endpoint when you need a unified, structured view of stock-perp price gaps across multiple on-chain venues (trade.xyz, Aster, Lighter) simultaneously, including funding rates, xStock comparison, historical gap data, and an opinionated verdict — rather than querying each venue's API separately or building your own aggregation logic. Ideal for agents performing arbitrage scanning, basis trading research, or cross-venue execution routing decisions on tokenized equity perps.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-19T00:40:34.356Z","isFirstParty":false,"canonicalSlug":"perp-gap-api-research-card-759a57ce"}