# x402stock Basis Spread API

> x402stock Basis Spread API is a paid API for AI agents from x402stock.xyz, paid per call via x402, $0.05/call, status unknown (last checked 2026-10-11).

Returns the current basis spread (price difference) between US equity spot prices and their corresponding on-chain perpetual futures contracts on Hyperliquid

## Facts

- Endpoint: GET https://x402stock.xyz/api/v1/basis?utm_source=zero.xyz
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/x402stock-basis-spread-api-89ce3916
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_cuXcn-q4YptgCJQB8ex4z

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 x402stock-basis-spread-api-89ce3916
```

Example prompt: Show me all US stocks where the on-chain perpetual futures are trading at a basis of at least 0.5% above or below the equity price — limit to the top 40 results.

## When to prefer this

Use this endpoint when you need to compare US equity spot prices against their Hyperliquid on-chain perpetual futures equivalents — specifically to measure basis spread, funding rates, or gauge overnight/off-hours market sentiment. Prefer this over generic stock price endpoints when the user is interested in derivatives, basis trading, arbitrage between spot and perp, or using perpetual futures as a real-time proxy for equity sentiment when US markets are closed.

## Known failure modes

- No pairs meet the min_basis threshold — returns empty rows array
- Symbol collision: pairs differing by more than 25% are marked comparable=false with an excluded_reason
- Perp or equity data feed temporarily unavailable — sections field will indicate which feed is down
- limit exceeds 200 — request rejected with validation error
- Stale data during market transitions or feed outages

## How this service works

Scans every US stock that also trades as a 24/7 synthetic perp and returns the gap: official (delayed) price, prev close, perp mark and oracle, funding APR, open interest, and computed `basis_percent` + `basis_vs_prev_close_percent` — the implied overnight move while the US market is shut. Widest dislocation first, plus a plain-English `reading`. `?limit=`, `?min_basis=`. From x402stock

## Output

A JSON array of rows, each representing a US equity ticker matched to its on-chain perpetual counterpart, including: spot equity price and previous close, perp mark and oracle prices, basis in percentage and absolute dollar terms, basis vs previous close, direction (premium/discount/flat), perp funding APR, open interest, day volume in USD, whether the pair is comparable, and any exclusion reason. Also includes metadata: timestamp, US market open status, venue map (equity source and perp venue), a reading summary of the widest dislocations, and total available pairs.

## 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",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "required": [
      "min_basis",
      "limit"
     ],
     "properties": {
      "limit": {
       "type": "integer",
       "default": 40,
       "maximum": 200,
       "exclusiveMinimum": 0
      },
      "min_basis": {
       "type": "number",
       "default": 0,
       "maximum": 100,
       "minimum": 0
      }
     },
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "required": [
      "source",
      "as_of",
      "venue_map",
      "us_market_open",
      "reading",
      "method",
      "count",
      "rows",
      "sections",
      "note",
      "total_available"
     ],
     "properties": {
      "note": {
       "anyOf": [
        {
         "type": "string"
        },
        {
         "type": "null"
        }
       ]
      },
      "rows": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "ticker",
         "equity_price",
         "equity_prev_close",
         "equity_change_percent",
         "equity_as_of",
         "perp_symbol",
         "perp_mark",
         "perp_oracle",
         "perp_funding_apr_percent",
         "perp_open_interest",
         "perp_day_volume_usd",
         "basis_percent",
         "basis_absolute",
         "basis_vs_prev_close_percent",
         "direction",
         "comparable",
         "excluded_reason"
        ],
        "properties": {
         "ticker": {
          "type": "string"
         },
         "direction": {
          "enum": [
           "premium",
           "discount",
           "flat",
           "unknown"
          ],
          "type": "string"
         },
         "perp_mark": {
          "anyOf": [
           {
            "type": "number"
           },
  
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "note": null,
  "rows": [
   {
    "ticker": "NVDA",
    "direction": "premium",
    "perp_mark": 182.95,
    "comparable": true,
    "perp_oracle": 182.88,
    "perp_symbol": "xyz:NVDA",
    "equity_as_of": "2026-07-30T20:00:00.000Z",
    "equity_price": 181.42,
    "basis_percent": 0.84,
    "basis_absolute": 1.53,
    "excluded_reason": null,
    "equity_prev_close": 180.11,
    "perp_open_interest": 41230.5,
    "perp_day_volume_usd": 9128441.22,
    "equity_change_percent": 0.73,
    "perp_funding_apr_percent": 11.42,
    "basis_vs_prev_close_percent": 1.58
   },
   {
    "ticker": "TSLA",
    "direction": "discount",
    "perp_mark": 401.02,
    "comparable": true,
    "perp_oracle": 401.11,
    "perp_symbol": "xyz:TSLA",
    "equity_as_of": "2026-07-30T20:00:00.000Z",
    "equity_price": 402.11,
    "basis_percent": -0.27,
    "basis_absolute": -1.09,
    "excluded_reason": null,
    "equity_prev_close": 399.4,
    "perp_open_interest": 18220.1,
    "perp_day_volume_usd": 4410233.9,
    "equity_change_percent": 0.68,
    "perp_funding_apr_percent": -3.19,
    "basis_vs_prev_close_percent": 0.41
   }
  ],
  "as_of": "2026-07-30T23:40:00.000Z",
  "count": 2,
  "method": "Legs are joined by ticker symbol. Macro perps (commodities, FX, indices) are excluded because their symbols collide with unrelated US tickers, and any remaining pair differing by more than 25% is treated as a symbol collision rather than a dislocation — see `comparable` and `excluded_reason` per row.",
  "source": "x402stock",
  "reading": "US market closed — the 24/7 perp is the live opinion of where these reopen. Widest vs last print: NVDA at 0.84%.",
  "sections": {
   "perps": "ok",
   "equities": "ok"
  },
  "venue_map": {
   "perp": "hyperliquid:xyz",
   "equity": "us_listed"
  },
  "us_market_open": false,
  "total_available": 2
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/x402stock-basis-spread-api-89ce3916/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402stock.xyz](https://www.zero.xyz/host/x402stock.xyz/llms.txt)