gexbot api

research

REST endpoint for on-demand gbR options chart assets, 3D volatility surfaces, and tabular CSV/JSON datasets across US optionable equities.

GET/v2/research/{TICKER}/{METRIC}Research Tier
Official Endpoint Specification

Research API Specification & Interactive Builder

The complete REST endpoint specification, accepted parameter schemas, response models, and interactive URL testing tools are maintained directly on the platform.

View Full API Specification & Builder on gexbot.com ↗

Endpoint Overview

The Research API computes on-demand Greek exposures, volatility surfaces, open interest profiles, and price-spread parity. It serves index options, ETFs, and all US optionable equities.

GET https://api.gex.bot/v2/research/{TICKER}/{METRIC}

Architecture & Service Base URLs

  • API Gateway: https://api.gex.bot/v2/research/{TICKER}/{METRIC}
  • Asset Storage & CDN: https://assets.gexbot.com/gbR/ (or https://r.gex.bot/)

Operating Hours & Data Cadence

  • Regular Market Hours (09:30–16:00 ET):
    • Evaluates live option market quotes using the gbR pricing model.
    • Caches requests on 15-minute floor intervals on-demand.
  • Premarket Hours (Before 09:30 ET):
    • Open Interest (OI) refreshes daily at 08:00 ET.
    • Calculations default to theoretical fair-value models (theo).
    • Option volume metrics remain disabled until market open at 09:30 ET.
  • After Hours & Weekends:
    • Queries return the cached snapshot from the previous trading session close.

Authentication & Headers

All requests require an active API key with a Research or Quant subscription tier. Pass the key in the Authorization header as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>
User-Agent: <YOUR_APP_NAME>/1.0
Accept: image/webp
HeaderTypeRequiredDescription
AuthorizationstringYesBearer token format: Bearer <YOUR_API_KEY>.
User-AgentstringYesUnique identifier for your client application.
AcceptstringNoPreferred MIME type (image/webp, image/png, image/svg+xml, application/json, text/csv).

Path Parameters

ParameterTypeRequiredExampleDescription
TICKERstringYesSPX, NVDA, AAPLTicker symbol of the underlying asset (1 to 6 characters).
METRICstringYesgex_oi, iv_mid, oiThe analytical metric or Greek exposure to calculate.

Metric Aliases

The API translates legacy and shorthand metric names to internal engines:

Request AliasCanonical Engine MetricCategory
open_interestoiMarket Data
put_call_parityparityMarket Data
gamma_wall_absgamma_flipMarket Data
iv_askivol_askImplied Volatility
iv_midivol_midImplied Volatility
iv_bidivol_bidImplied Volatility

Query Parameters

ParameterTypeDefaultAccepted ValuesDescription
formatstringwebpwebp, png, jpeg, svg, pdf, json, csv, htmlResponse payload format. Image formats return an asset descriptor.
viewstringskewskew, term, surface, lineChart visualization mode.
typestringbar / linebar, line, histogram, scatterSeries render style.
themestringdarkdark, lightColor palette for rendered chart images.
strikesinteger15 / 50Positive integer (e.g. 15, 50)Number of strike intervals calculated around spot price.
start_dteinteger / date0Integer or MM-DD-YYYYStart days-to-expiration boundary (inclusive).
end_dteinteger / date98Integer or MM-DD-YYYYEnd days-to-expiration boundary (inclusive).
expiration_filterstringNonem (monthly), w (weekly), q (quarterly)Restricts calculations to specific expiration types.
contract_filterstringallall, calls, putsFilters calculation contracts by option side.
moneyness_filterstringNoneotm, ntm, itm, atm, d10, d15, d20, d25Filters contracts by moneyness or delta bucket.
contract_aggbooleanfalsetrue, falseWhen true, nets calls minus puts per strike.
expiry_aggbooleanfalsetrue, falseWhen true, aggregates all expiries across each strike.
skew_adjbooleanfalsetrue, falseAdjusts Greek calculations for volatility skew.
limit_ybooleanfalsetrue, falseClamps Y-axis scale to remove extreme statistical outliers.
seriesstringNonedeltas, moneyness, strikesFor IV term view, plots term structure across delta tiers.

Response Schemas

1. Image Asset Descriptor Response

When format is webp, png, svg, jpeg, or pdf, the server returns a JSON object containing the relative asset URL:

{
  "url": "gbR/QUFQTF9za2V3X2NvbnRyYWN0X2FnZ18yMDI2MDcwOFQxNTQ4MDU.svg",
  "name": "QUFQTF9za2V3X2NvbnRyYWN0X2FnZ18yMDI2MDcwOFQxNTQ4MDU.svg",
  "content_type": "image/svg+xml",
  "description": "$AAPL skew 20260708T154805",
  "time_stamp": "20260708T154805",
  "model": "gbR"
}
FieldTypeDescription
urlstringRelative asset path. Resolve against https://assets.gexbot.com/gbR/ to fetch the file.
namestringAsset filename. Matches the last path segment of url.
content_typestringMIME type of the rendered file.
descriptionstringSummary containing ticker, metric, and generation timestamp.
time_stampstringGeneration timestamp in YYYYMMDDTHHMMSS format.
modelstringPricing model used for computation (gbR during market hours, theo during premarket).

2. Tabular Data Response (format=csv)

When format=csv, the endpoint returns raw tabular text directly:

Strike,Call_GEX,Put_GEX,Net_GEX,Spot,ATM_IV
5800,12450.50,-3400.20,9050.30,5850.25,14.20
5810,18900.10,-2100.00,16800.10,5850.25,14.15
5820,24500.80,-1800.50,22700.30,5850.25,14.10

Error Handling & Rate Limits

HTTP StatusError ReasonResponse Body / Behavior
400 Bad RequestInvalid query parameter or unsupported format for metric.{"error": true, "description": "csv is not enabled for this command yet"}
401 UnauthorizedMissing or invalid API key.{"error": "Unauthorized"}
429 Too Many RequestsQuery quota exceeded for the current window.{"error": "Rate limit exceeded."}

Code Examples

# Request SVG chart asset descriptor
curl -X GET "https://api.gex.bot/v2/research/SPX/gex_oi?format=svg&strikes=25&contract_agg=true" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "User-Agent: MyResearchApp/1.0" \
  -H "Accept: application/json"

# Request raw CSV dataset
curl -X GET "https://api.gex.bot/v2/research/AAPL/gex_oi?format=csv&start_dte=0&end_dte=30" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "User-Agent: MyResearchApp/1.0"
import requests

API_KEY = "YOUR_API_KEY"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "User-Agent": "PythonClient/1.0"
}

# Fetch chart asset descriptor
url = "https://api.gex.bot/v2/research/NVDA/iv_mid"
params = {
    "format": "webp",
    "view": "term",
    "start_dte": 0,
    "end_dte": 180
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
image_url = f"https://assets.gexbot.com/{data['url']}"
print(f"Chart available at: {image_url}")
const API_KEY = 'YOUR_API_KEY';

async function fetchResearchCSV(ticker: string, metric: string) {
  const url = new URL(`https://api.gex.bot/v2/research/${ticker}/${metric}`);
  url.searchParams.set('format', 'csv');
  url.searchParams.set('start_dte', '0');
  url.searchParams.set('end_dte', '98');

  const res = await fetch(url.toString(), {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'User-Agent': 'NodeApp/1.0',
    },
  });

  if (!res.ok) {
    throw new Error(`Request failed with status ${res.status}`);
  }

  const csvData = await res.text();
  return csvData;
}

On this page