Endpoint Reference
Base URL:
https://perspicium.com/api/v0
All endpoints require an API key.
Global Parameter Rules
| Parameter Family | Behavior |
|---|---|
ticker, benchmark |
Uppercased, trimmed, max 10 characters, allowed characters A-Z, 0-9, ., _, -. Invalid values fall back to the endpoint default. |
tickers |
Repeated query parameter. De-duplicated and capped at 20 values. |
range_pct |
Clamped to 0.01 through 2.0. |
window |
Clamped to 5 through 365 where supported. |
| Boolean query values | 1, true, yes, and on are treated as true for include_0dte. |
Health
GET /ping
Checks whether authentication and routing are working.
Parameters: none.
Response data:
| Field | Type | Description |
|---|---|---|
status |
string | Always ok on success. |
Options
GET /options/expected-move
Computes expected move data from the option chain.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Underlying symbol. |
range_pct |
number | 1.0 |
Strike range window. See Global Rules. |
Response data:
| Field | Type | Description |
|---|---|---|
ticker |
string | Sanitized symbol. |
spot |
number | Current underlying price used by the calculation. |
range_pct |
number | Applied strike range. |
term |
array | Expiration-level expected move records. |
table |
array | Display-ready expected move table rows. |
GET /options/iv
Returns implied volatility smile and term structure data.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Underlying symbol. |
range_pct |
number | 0.15 |
Strike range window. See Global Rules. |
Response data:
| Field | Type | Description |
|---|---|---|
ticker |
string | Sanitized symbol. |
spot |
number | Current underlying price. |
range_pct |
number | Applied strike range. |
expirations |
string[] | Available expiration dates. |
smile |
array | Strike/expiration IV smile records. |
term |
array | Expiration-level term structure records. |
GET /options/open-interest
Summarizes option chain activity by strike and expiration.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Underlying symbol. |
range_pct |
number | 0.25 |
Strike range window. |
basis |
string | open_interest |
One of open_interest, volume, total_premium. |
expiration |
string[] | all | Repeatable filter. Values must match available expirations. |
Response data:
| Field | Type | Description |
|---|---|---|
ticker |
string | Sanitized symbol. |
spot |
number | Current underlying price. |
basis |
string | Applied aggregation basis. |
strike_summary |
array | Aggregated records by strike. |
expiry_summary |
array | Aggregated records by expiration. |
GET /options/uoa
Finds unusual options activity.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Underlying symbol. |
include_0dte |
boolean | false |
Include zero-days-to-expiration contracts. |
limit |
integer | 50 |
Number of records, clamped to 10 through 100. |
Response data:
| Field | Type | Description |
|---|---|---|
ticker |
string | Sanitized symbol. |
spot |
number or null | Current underlying price when available. |
include_0dte |
boolean | Applied 0DTE setting. |
trades |
array | Ranked unusual activity records. |
GET /options/chain
Returns option chain rows and available expirations.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Underlying symbol. |
range_pct |
number | 0.15 |
Strike range window. |
expiry |
string | none | Optional single expiration filter. |
Response data:
| Field | Type | Description |
|---|---|---|
ticker |
string | Sanitized symbol. |
spot |
number | Current underlying price. |
expirations |
string[] | Available expiration dates. |
selected_expiry |
string or null | Applied expiry filter. |
chain |
array | Option contract rows with JSON-safe null values. |
Greeks
GET /greeks/gex
Computes gamma exposure by strike, cumulative gamma, smoothed series, and highlighted levels.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Underlying symbol. |
basis |
string | open_interest |
One of open_interest, volume, total_premium. |
expiration |
string[] | all | Repeatable filter. Values must match available expirations. |
range_pct |
number | 1.0 |
Strike range window. See Global Rules. |
Response data:
| Field | Type | Description |
|---|---|---|
ticker |
string | Sanitized symbol. |
spot |
number | Current underlying price. |
basis |
string | Applied aggregation basis. |
range_pct |
number | Applied strike range. |
expirations |
string[] | Expirations included in the result. |
selected_expirations |
string[] | Requested expirations, or ["all"]. |
zero_level |
number or null | Estimated gamma flip / zero level. |
series.net |
array | {strike, value} records. |
series.cumulative_scaled |
array | {strike, value} records. |
series.smoothed |
array | {strike, value} records. |
highlight_strikes |
object | Named strikes returned by the analytics engine. |
basis_column |
string | Source column used for basis. |
dw_column |
string | Dollar-weighted column used by the engine. |
Quant
GET /quant/risk
Calculates rolling risk and performance metrics for one asset against a benchmark.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | NVDA |
Asset symbol. |
benchmark |
string | SPY |
Benchmark symbol. |
period |
string | 5y |
Historical data period. |
window |
integer | 60 |
Rolling window. See Global Rules. |
Response data includes summary plus timeseries.rolling_sharpe, timeseries.drawdown_pct, timeseries.rolling_corr, and timeseries.rolling_vol_pct.
GET /quant/asset-correlation
Returns cross-asset performance and correlation analytics for Perspicium's configured ETF universe.
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 3y |
Historical data period. |
window |
integer | 90 |
Rolling window. See Global Rules. |
Response data includes summary, perf_table, correlation_matrix, timeseries.cum_returns_pct, and timeseries.rolling_sharpe.
GET /quant/market-memory
Finds historical price windows similar to the most recent price pattern.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Asset symbol. |
similarity |
string | cosine |
One of cosine, dot, spearman. |
kernel_size |
integer | 30 |
Lookback size. See Global Rules. |
top_n |
integer | 5 |
Number of matches. See Global Rules. |
min_separation |
integer | 0 |
Minimum window separation. See Global Rules. |
Response data includes kernel_prices and matches with score, match_prices, and trailing_prices.
GET /quant/portfolio-optimizer
Optimizes a long-only portfolio over supplied tickers.
| Parameter | Type | Default | Description |
|---|---|---|---|
tickers |
string[] | required | Repeatable ticker list, capped at 20. |
objective |
string | sharpe |
sharpe, min_var, or equal_weight. Unknown values fall back to equal weighting behavior in the optimizer. |
period |
string | 5y |
Historical data period. |
Response data includes tickers, objective, period, weights, port_return, port_vol, sharpe, risk_contributions, opt_portfolio, and eq_portfolio.
GET /quant/seasonality
Computes seasonality pivots, stats, and annual cumulative returns.
| Parameter | Type | Default | Description |
|---|---|---|---|
ticker |
string | SPY |
Asset symbol. |
grouping |
string | monthly |
One of monthly, quarterly, weekday, calendar, presidential. Invalid values fall back to monthly. |
period |
string | 10y |
Historical data period. |
Response data includes seasonality_pivot, stats, and annual_cum_returns when enough data is available.
GET /quant/sector-insights
Computes sector breadth and return analytics for Perspicium's configured sector ETF universe.
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 1M |
Historical data period. |
Response data includes summary, timeseries.ad_line, timeseries.ad_ratio_monthly_mean, and timeseries.cum_returns_pct.