# PerpGap API – Stock Perp Price Gap Scanner

> PerpGap API – Stock Perp Price Gap Scanner is a paid API for AI agents from perp-gap-api.perpgap.workers.dev, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-19).

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.

## Facts

- Endpoint: GET https://perp-gap-api.perpgap.workers.dev/gaps?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-19
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/perpgap-api-stock-perp-price-gap-scanner-72fe9221
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_beDQ6Tmhl7wqwVjkxdXZy

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability perpgap-api-stock-perp-price-gap-scanner-72fe9221
```

Example prompt: 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.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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": [
           "numb
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "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
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/perpgap-api-stock-perp-price-gap-scanner-72fe9221/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from perp-gap-api.perpgap.workers.dev](https://www.zero.xyz/host/perp-gap-api.perpgap.workers.dev/llms.txt)