research
REST endpoint for on-demand gbR options chart assets, 3D volatility surfaces, and tabular CSV/JSON datasets across US optionable equities.
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/(orhttps://r.gex.bot/)
Operating Hours & Data Cadence
- Regular Market Hours (09:30–16:00 ET):
- Evaluates live option market quotes using the
gbRpricing model. - Caches requests on 15-minute floor intervals on-demand.
- Evaluates live option market quotes using the
- 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| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer token format: Bearer <YOUR_API_KEY>. |
User-Agent | string | Yes | Unique identifier for your client application. |
Accept | string | No | Preferred MIME type (image/webp, image/png, image/svg+xml, application/json, text/csv). |
Path Parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
TICKER | string | Yes | SPX, NVDA, AAPL | Ticker symbol of the underlying asset (1 to 6 characters). |
METRIC | string | Yes | gex_oi, iv_mid, oi | The analytical metric or Greek exposure to calculate. |
Metric Aliases
The API translates legacy and shorthand metric names to internal engines:
| Request Alias | Canonical Engine Metric | Category |
|---|---|---|
open_interest | oi | Market Data |
put_call_parity | parity | Market Data |
gamma_wall_abs | gamma_flip | Market Data |
iv_ask | ivol_ask | Implied Volatility |
iv_mid | ivol_mid | Implied Volatility |
iv_bid | ivol_bid | Implied Volatility |
Query Parameters
| Parameter | Type | Default | Accepted Values | Description |
|---|---|---|---|---|
format | string | webp | webp, png, jpeg, svg, pdf, json, csv, html | Response payload format. Image formats return an asset descriptor. |
view | string | skew | skew, term, surface, line | Chart visualization mode. |
type | string | bar / line | bar, line, histogram, scatter | Series render style. |
theme | string | dark | dark, light | Color palette for rendered chart images. |
strikes | integer | 15 / 50 | Positive integer (e.g. 15, 50) | Number of strike intervals calculated around spot price. |
start_dte | integer / date | 0 | Integer or MM-DD-YYYY | Start days-to-expiration boundary (inclusive). |
end_dte | integer / date | 98 | Integer or MM-DD-YYYY | End days-to-expiration boundary (inclusive). |
expiration_filter | string | None | m (monthly), w (weekly), q (quarterly) | Restricts calculations to specific expiration types. |
contract_filter | string | all | all, calls, puts | Filters calculation contracts by option side. |
moneyness_filter | string | None | otm, ntm, itm, atm, d10, d15, d20, d25 | Filters contracts by moneyness or delta bucket. |
contract_agg | boolean | false | true, false | When true, nets calls minus puts per strike. |
expiry_agg | boolean | false | true, false | When true, aggregates all expiries across each strike. |
skew_adj | boolean | false | true, false | Adjusts Greek calculations for volatility skew. |
limit_y | boolean | false | true, false | Clamps Y-axis scale to remove extreme statistical outliers. |
series | string | None | deltas, moneyness, strikes | For 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"
}| Field | Type | Description |
|---|---|---|
url | string | Relative asset path. Resolve against https://assets.gexbot.com/gbR/ to fetch the file. |
name | string | Asset filename. Matches the last path segment of url. |
content_type | string | MIME type of the rendered file. |
description | string | Summary containing ticker, metric, and generation timestamp. |
time_stamp | string | Generation timestamp in YYYYMMDDTHHMMSS format. |
model | string | Pricing 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.10Error Handling & Rate Limits
| HTTP Status | Error Reason | Response Body / Behavior |
|---|---|---|
400 Bad Request | Invalid query parameter or unsupported format for metric. | {"error": true, "description": "csv is not enabled for this command yet"} |
401 Unauthorized | Missing or invalid API key. | {"error": "Unauthorized"} |
429 Too Many Requests | Query 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;
}