Perspicium Public API v0

Unlock institutional-grade options intelligence and quantitative analytics. Integrate real-time expected moves, IV surfaces, and dealer positioning flows directly into your research notebooks, proprietary trading tools, and execution workflows.

Core Capabilities

● Real-time Greeks: Instant GEX, DEX, and Vanna/Charm exposure profiles.
● Quant Engine: Market memory matching, portfolio optimization, and risk modeling.
● Market Intel: Unusual options activity (UOA) and expected move bands.

Quickstart

# Test connectivity with your API key
curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/ping"

# Get expected move for SPY
curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/options/expected-move?ticker=SPY"

Authentication

Perspicium uses API keys for authentication. You can generate and rotate your keys in your Account Dashboard.

Supported Headers

Authorization: ApiKey
Authorization: Bearer
X-API-Key:

Error Responses

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "API key invalid"
  }
}

Rate Limits

Scope	Daily Limit	Monthly Limit
Default Tier	10 requests	100 requests
Ping / Health	Burst limit: 60 per minute
Analytics Tier	Burst limit: 30 per minute

Standard

GET /api/v0/ping

Health Check

Sample Request

curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/ping"

import requests

url = "https://perspicium.com/api/v0/ping"
headers = {"Authorization": "ApiKey YOUR_KEY"}
params = {
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = new URL("https://perspicium.com/api/v0/ping");


const response = await fetch(url, {
  headers: { "Authorization": "ApiKey YOUR_KEY" }
});
console.log(await response.json());

Expected JSON Data

200 OK

{ "success": true, "data": { "status": "ok" } }

Options Intelligence

GET /api/v0/options/expected-move

Expected Move Bands

Query Parameters

ticker

Underlying asset symbol.

Example: SPY

range_pct

Percentage window for strike search (default 1.0).

Example: 1.0

Sample Request

curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/options/expected-move?ticker=SPY&range_pct=1.0"

import requests

url = "https://perspicium.com/api/v0/options/expected-move"
headers = {"Authorization": "ApiKey YOUR_KEY"}
params = {
    "ticker": "SPY",
    "range_pct": "1.0",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = new URL("https://perspicium.com/api/v0/options/expected-move");

const params = {
  "ticker": "SPY",
  "range_pct": "1.0",

};
Object.keys(params).forEach(k => url.searchParams.append(k, params[k]));


const response = await fetch(url, {
  headers: { "Authorization": "ApiKey YOUR_KEY" }
});
console.log(await response.json());

Expected JSON Data

200 OK

{
  "success": true,
  "data": {
    "ticker": "SPY",
    "spot": 522.41,
    "term": [
      { "expiry": "2024-04-19", "move": 5.42, "upper": 527.83, "lower": 516.99 }
    ]
  }
}

GET /api/v0/options/iv

Implied Volatility Surface

Query Parameters

ticker

Symbol for which to fetch IV term and smile.

Example: SPX

range_pct

Filter strikes within X% of spot (default 0.15).

Example: 0.15

Sample Request

curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/options/iv?ticker=SPX&range_pct=0.15"

import requests

url = "https://perspicium.com/api/v0/options/iv"
headers = {"Authorization": "ApiKey YOUR_KEY"}
params = {
    "ticker": "SPX",
    "range_pct": "0.15",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = new URL("https://perspicium.com/api/v0/options/iv");

const params = {
  "ticker": "SPX",
  "range_pct": "0.15",

};
Object.keys(params).forEach(k => url.searchParams.append(k, params[k]));


const response = await fetch(url, {
  headers: { "Authorization": "ApiKey YOUR_KEY" }
});
console.log(await response.json());

Expected JSON Data

200 OK

{
  "success": true,
  "data": {
    "ticker": "SPX",
    "smile": [
      { "strike": 5200, "iv": 0.142, "expiry": "2024-05-17" }
    ],
    "term": [
      { "expiry": "2024-04-19", "atm_iv": 0.125 }
    ]
  }
}

GET /api/v0/options/uoa

Unusual Options Activity

Query Parameters

ticker

Filter for a specific symbol.

Example: TSLA

include_0dte

Include zero-days to expiration (default false).

Example: true

limit

Maximum number of trades to return (max 100).

Example: 50

Sample Request

curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/options/uoa?ticker=TSLA&include_0dte=true&limit=50"

import requests

url = "https://perspicium.com/api/v0/options/uoa"
headers = {"Authorization": "ApiKey YOUR_KEY"}
params = {
    "ticker": "TSLA",
    "include_0dte": "true",
    "limit": "50",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = new URL("https://perspicium.com/api/v0/options/uoa");

const params = {
  "ticker": "TSLA",
  "include_0dte": "true",
  "limit": "50",

};
Object.keys(params).forEach(k => url.searchParams.append(k, params[k]));


const response = await fetch(url, {
  headers: { "Authorization": "ApiKey YOUR_KEY" }
});
console.log(await response.json());

Expected JSON Data

200 OK

{
  "success": true,
  "data": {
    "ticker": "TSLA",
    "trades": [
      { "strike": 180, "type": "CALL", "volume": 5200, "details": "Sweep" }
    ]
  }
}

Dealer Flows (Greeks)

GET /api/v0/greeks/gex

Gamma Exposure Profile

Query Parameters

ticker

Underlying symbol.

Example: SPY

basis

Aggregate by open_interest or volume.

Example: open_interest

expiration

Filter to specific expiry (multiples allowed).

Example: 2024-06-21

Sample Request

curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/greeks/gex?ticker=SPY&basis=open_interest&expiration=2024-06-21"

import requests

url = "https://perspicium.com/api/v0/greeks/gex"
headers = {"Authorization": "ApiKey YOUR_KEY"}
params = {
    "ticker": "SPY",
    "basis": "open_interest",
    "expiration": "2024-06-21",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = new URL("https://perspicium.com/api/v0/greeks/gex");

const params = {
  "ticker": "SPY",
  "basis": "open_interest",
  "expiration": "2024-06-21",

};
Object.keys(params).forEach(k => url.searchParams.append(k, params[k]));


const response = await fetch(url, {
  headers: { "Authorization": "ApiKey YOUR_KEY" }
});
console.log(await response.json());

Expected JSON Data

200 OK

{
  "success": true,
  "data": {
    "ticker": "SPY",
    "zero_level": 521.8,
    "series": {
      "net": [ { "strike": 520, "value": 4.2e9 } ]
    }
  }
}

Quantitative Engine

GET /api/v0/quant/risk

Risk & Performance

Query Parameters

ticker

Asset symbol.

Example: NVDA

benchmark

Benchmark for beta/alpha (default SPY).

Example: SPY

period

Timeframe for analysis.

Example: 5y

Sample Request

curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/quant/risk?ticker=NVDA&benchmark=SPY&period=5y"

import requests

url = "https://perspicium.com/api/v0/quant/risk"
headers = {"Authorization": "ApiKey YOUR_KEY"}
params = {
    "ticker": "NVDA",
    "benchmark": "SPY",
    "period": "5y",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = new URL("https://perspicium.com/api/v0/quant/risk");

const params = {
  "ticker": "NVDA",
  "benchmark": "SPY",
  "period": "5y",

};
Object.keys(params).forEach(k => url.searchParams.append(k, params[k]));


const response = await fetch(url, {
  headers: { "Authorization": "ApiKey YOUR_KEY" }
});
console.log(await response.json());

Expected JSON Data

200 OK

{
  "success": true,
  "data": {
    "ticker": "NVDA",
    "summary": { "beta": 1.42, "sharpe": 2.1 }
  }
}

GET /api/v0/quant/market-memory

Memory Pattern Matching

Query Parameters

ticker

Core asset for pattern detection.

Example: SPY

kernel_size

Window length for lookup.

Example: 30

similarity

Metric: cosine or euclidean.

Example: cosine

Sample Request

curl -H "Authorization: ApiKey YOUR_KEY" \
  "https://perspicium.com/api/v0/quant/market-memory?ticker=SPY&kernel_size=30&similarity=cosine"

import requests

url = "https://perspicium.com/api/v0/quant/market-memory"
headers = {"Authorization": "ApiKey YOUR_KEY"}
params = {
    "ticker": "SPY",
    "kernel_size": "30",
    "similarity": "cosine",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = new URL("https://perspicium.com/api/v0/quant/market-memory");

const params = {
  "ticker": "SPY",
  "kernel_size": "30",
  "similarity": "cosine",

};
Object.keys(params).forEach(k => url.searchParams.append(k, params[k]));


const response = await fetch(url, {
  headers: { "Authorization": "ApiKey YOUR_KEY" }
});
console.log(await response.json());

Expected JSON Data

200 OK

{
  "success": true,
  "data": {
    "matches": [
      { "score": 0.98, "trailing_prices": { ... } }
    ]
  }
}