systemsdata 0.1.0

Official Python client for the Systems Capital API — US equity price history and quantitative statistics.

systemsdata

Official Python client for the Systems Capital API — US equity close-price history and quantitative return statistics for 2,600+ tickers, updated every trading day.

---

Install

pip install systemsdata

Optional pandas support:

pip install systemsdata[pandas]

---

Quick start

1 — Get an API key

python -m systemsdata setup

This opens the signup/dashboard URL, then asks you to paste your key. The key is stored in ~/.systemsdata/config.json and loaded automatically on every subsequent import.

Alternatively, set the environment variable:

export SYSTEMSDATA_API_KEY="sc_live_..."

Or authenticate inline:

import systemsdata as sd
sd.auth("sc_live_...")

---

2 — Fetch statistics

import systemsdata as sd

# 3-month kurtosis for AAPL (most recent data point)
result = sd.stats("AAPL", range="3m", metrics=["kurtosis"])
print(result.metrics["kurtosis"])   # → 1.2347

# All metrics, 1-year range, 3-month trailing window
result = sd.stats("NVDA", range="1y", window="3m")
print(result)
# StatsResult(
#   symbol='NVDA', window='3m',
#   period=2024-03-14 → 2025-03-14 (252 pts)
#   metrics:
#   avg_return: 0.1823
#   std_dev: 3.2841
#   kurtosis: 2.9103
#   ...
# )

3 — Fetch price history

prices = sd.prices("AAPL", range="1y")
print(prices.end_date, prices.points[-1].close)  # → 2025-03-14  214.37

# pandas DataFrame (requires systemsdata[pandas])
df = prices.to_dataframe()
print(df.tail())

---

API reference

sd.auth(api_key)

Set the API key for the current session. Not needed if SYSTEMSDATA_API_KEY is set or if you ran python -m systemsdata setup.

---

sd.stats(symbol, *, range, from_date, to_date, metrics, window) → StatsResult

Compute quantitative return statistics at the most recent data point.

Parameter	Type	Default	Description
symbol	str	required	Ticker, e.g. "AAPL"
range	str	"3m"	"1w" | "1m" | "3m" | "1y" | "all"
from_date	str | None	None	Custom start YYYY-MM-DD
to_date	str | None	None	Custom end YYYY-MM-DD
metrics	list[str] | None	all	Subset to compute
window	str	"period"	Trailing calc window (see below)

Valid metrics keys: avg_return, std_dev, median, mode, min, max, skewness, kurtosis, annualized_return, price_slope

Valid window values: "period" (entire range), "1d", "1w", "1m", "3m", "6m", "1y", "2y", "5y"

range controls which price data is loaded; window controls the trailing slice used in each calculation. Example: range="1y", window="3m" loads one year of data but computes stats using only the last 3 months.

---

sd.prices(symbol, *, range, from_date, to_date) → PriceHistory

Fetch daily close-price history.

h = sd.prices("MSFT", range="6m")
h.points       # list[PricePoint(date, close)]
h.to_dicts()   # list[{"date": ..., "close": ...}]
h.to_dataframe()  # pandas DataFrame with DatetimeIndex

---

Credit model

Action	Cost
1 data point (date + close)	2 credits
1 metric value	1 credit

Monthly bucket caching: loading the same symbol/month twice costs credits only on the first load. Free tier: 5,000 credits/month (signed-in) or 500 (anonymous).

---

Error handling

from systemsdata import AuthError, QuotaError, NotFoundError

try:
    result = sd.stats("AAPL", range="3m")
except AuthError:
    print("Invalid or missing API key")
except QuotaError as e:
    print(f"Out of credits — upgrade at {e.upgrade_url}")
except NotFoundError:
    print("Symbol not found")

---

CLI

python -m systemsdata setup   # interactive key setup
python -m systemsdata info    # show active key and config
python -m systemsdata test    # smoke-test with a live API call

---

LLM / agent usage

The API ships an OpenAPI 3.1 spec at:

https://www.systemscapital.net/api/v1/openapi

LLM agents can register the two endpoints (/data, /stats) as tools and pass the API key via the Authorization: Bearer sc_live_... header.

---

License

MIT