# PerpGap Historical Price Gap API

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

Returns historical time-series data on price gaps between stock perpetual futures (trade.xyz, Aster, Lighter) and reference stock prices or Solana xStocks, including funding rates, OI, and basis metrics

## Facts

- Endpoint: GET https://perp-gap-api.perpgap.workers.dev/history?utm_source=zero.xyz
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-19
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/perpgap-historical-price-gap-api-df0e1846
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_uiG5-M1zXbbj0YETRWG51

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-historical-price-gap-api-df0e1846
```

Example prompt: Pull the hourly price gap history for TSLA between October 7 and October 14, 2026, including funding rates, open interest, and how the perp mark on trade.xyz compared to the real stock price and xStock price.

## When to prefer this

Use this endpoint when you need time-series historical data on stock perpetual price gaps across decentralized exchanges (trade.xyz, Aster, Lighter) versus real stock prices or Solana xStocks. Prefer this over real-time snapshot endpoints when trend analysis, backtesting, or funding rate history over a date range is the goal. Ideal for arbitrage research, basis trading analysis, and on-chain synthetic stock monitoring across multiple DeFi venues.

## Known failure modes

- Invalid or unsupported ticker symbol returns an error or empty rows
- Date range too wide may result in truncated or paginated data
- Payment failure (x402) if USDC balance is insufficient on Base or Solana
- Missing required fields (ticker, from, to) returns a validation error
- Interval value not supported returns an error
- Data unavailable for non-market hours may return sparse rows

## How this service works

Pay-per-call API for AI agents: stock-perp price gaps across trade.xyz, Aster and Lighter vs the real stock and Solana xStocks, plus funding, basis, OI, research cards, history and rule-based verdicts. x402, USDC on Base or Solana.

## Output

Returns a JSON array of time-series rows for the requested ticker and date range. Each row includes timestamps, perp mark prices from trade.xyz/Aster/Lighter, reference stock price, xStock price, hourly and annualized funding rates, open interest in USD, and percentage gap metrics between each exchange pair and versus the reference stock. Also returns count, ticker, interval, and a disclaimer.

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "to": "2026-10-14T20:00:00.000Z",
  "from": "2026-10-07T00:00:00.000Z",
  "rows": [
   {
    "ts": 1792008000,
    "time": "2026-10-14T20:00:00.000Z",
    "source": "snapshot",
    "ticker": "TSLA",
    "perp_mark": 365.69,
    "ref_price": 365.57,
    "aster_mark": 366.01,
    "perp_oracle": 365.58,
    "ref_session": "regular",
    "lighter_mark": 365.77,
    "xstock_price": 365.69,
    "funding_hourly": 0.00000625,
    "open_interest_usd": 42087597,
    "gap_perp_vs_ref_pct": 0.0328,
    "max_mark_spread_pct": 0.0875,
    "aster_funding_hourly": 0,
    "gap_aster_vs_xyz_pct": 0.0875,
    "funding_annualized_pct": 5.475,
    "gap_lighter_vs_xyz_pct": 0.0219,
    "gap_perp_vs_xstock_pct": 0,
    "lighter_funding_hourly": 0.000004,
    "basis_mark_vs_oracle_pct": 0.0301
   }
  ],
  "count": 1,
  "ticker": "TSLA",
  "interval": "1h",
  "disclaimer": "Data, not financial advice."
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/perpgap-historical-price-gap-api-df0e1846/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)