Language Examples

All examples expect PERSPICIUM_API_KEY to be set in the environment.

cURL

curl "https://perspicium.com/api/v0/greeks/gex?ticker=SPY&basis=open_interest&range_pct=1.0" \
  -H "Authorization: ApiKey $PERSPICIUM_API_KEY"

Multiple values for the same query parameter are repeated:

curl "https://perspicium.com/api/v0/options/open-interest?ticker=SPY&expiration=2026-05-15&expiration=2026-06-19" \
  -H "Authorization: ApiKey $PERSPICIUM_API_KEY"

Python

import os
import requests

BASE_URL = "https://perspicium.com/api/v0"


class PerspiciumClient:
    def __init__(self, api_key=None, timeout=30):
        self.api_key = api_key or os.environ["PERSPICIUM_API_KEY"]
        self.timeout = timeout

    def get(self, path, params=None):
        response = requests.get(
            f"{BASE_URL}{path}",
            headers={"Authorization": f"ApiKey {self.api_key}"},
            params=params or {},
            timeout=self.timeout,
        )
        payload = response.json()
        if not response.ok or not payload.get("success"):
            error = payload.get("error", {})
            raise RuntimeError(f"{error.get('code')}: {error.get('message')}")
        return payload["data"]


client = PerspiciumClient()
data = client.get("/options/iv", {"ticker": "SPY", "range_pct": 0.15})
print(data["spot"])

JavaScript

const BASE_URL = "https://perspicium.com/api/v0";

export async function perspiciumGet(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  for (const [key, value] of Object.entries(params)) {
    if (Array.isArray(value)) {
      for (const item of value) url.searchParams.append(key, item);
    } else if (value !== undefined && value !== null) {
      url.searchParams.set(key, String(value));
    }
  }

  const response = await fetch(url, {
    headers: { Authorization: `ApiKey ${process.env.PERSPICIUM_API_KEY}` },
  });
  const payload = await response.json();

  if (!response.ok || !payload.success) {
    const error = payload.error || {};
    throw new Error(`${error.code || response.status}: ${error.message || "Request failed"}`);
  }

  return payload.data;
}

const data = await perspiciumGet("/quant/portfolio-optimizer", {
  tickers: ["SPY", "QQQ", "TLT"],
  objective: "sharpe",
  period: "5y",
});
console.log(data.weights);

R

library(httr2)

perspicium_get <- function(path, query = list()) {
  req <- request(paste0("https://perspicium.com/api/v0", path)) |>
    req_headers(Authorization = paste("ApiKey", Sys.getenv("PERSPICIUM_API_KEY"))) |>
    req_url_query(!!!query)

  resp <- req_perform(req)
  payload <- resp_body_json(resp)

  if (!isTRUE(payload$success)) {
    stop(paste(payload$error$code, payload$error$message, sep = ": "))
  }

  payload$data
}

data <- perspicium_get("/quant/risk", list(ticker = "NVDA", benchmark = "SPY", period = "5y"))
print(data$summary)

Copy-Ready Files

Runnable examples are also available in the repository under:

• examples/curl/
• examples/python/
• examples/javascript/
• examples/r/

You can browse or clone these directly from GitHub.