# Perp Gap API – Research Card

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

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.

## Facts

- Endpoint: GET https://perp-gap-api.perpgap.workers.dev/research?utm_source=zero.xyz
- Price: $0.03/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-19
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/perp-gap-api-research-card-759a57ce
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_TrXMOPK1ehp6odrLh5kfw

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 perp-gap-api-research-card-759a57ce
```

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

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

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

## Response schema (JSON Schema)

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

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/perp-gap-api-research-card-759a57ce/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)