Skip to content

Commit f3fe4c4

Browse files
tdobrowolski1tdobrowolski1
committed
Add flashalpha Python SDK v0.1.0
Thin requests wrapper for the FlashAlpha options analytics API. Covers all live endpoints: exposure (GEX/DEX/VEX/CHEX), levels, narrative, pricing (greeks/IV/Kelly), volatility, market data, historical quotes, and reference data. Includes 32 unit tests (mocked) and 21 integration tests (live API). PyPI-ready with hatchling packaging.
1 parent d345914 commit f3fe4c4

10 files changed

Lines changed: 1155 additions & 1 deletion

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 FlashAlpha
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 175 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,175 @@
1-
# flashalpha-python
1+
# FlashAlpha Python SDK
2+
3+
[![PyPI](https://img.shields.io/pypi/v/flashalpha)](https://pypi.org/project/flashalpha/)
4+
[![Python](https://img.shields.io/pypi/pyversions/flashalpha)](https://pypi.org/project/flashalpha/)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
7+
**Real-time options exposure analytics for Python.** Gamma exposure (GEX), delta (DEX), vanna (VEX), charm (CHEX), key levels, Black-Scholes greeks, implied volatility, Kelly sizing, and more — from the [FlashAlpha API](https://flashalpha.com).
8+
9+
```bash
10+
pip install flashalpha
11+
```
12+
13+
## Quick Start
14+
15+
```python
16+
from flashalpha import FlashAlpha
17+
18+
fa = FlashAlpha("YOUR_API_KEY")
19+
20+
# Get gamma exposure for SPY
21+
gex = fa.gex("SPY")
22+
print(f"Net GEX: ${gex['net_gex']:,.0f}")
23+
print(f"Gamma flip: {gex['gamma_flip']}")
24+
25+
for strike in gex["strikes"][:5]:
26+
print(f" {strike['strike']}: net ${strike['net_gex']:,.0f}")
27+
```
28+
29+
## What You Can Do
30+
31+
### Exposure Analytics — see where dealers are positioned
32+
33+
```python
34+
# Gamma exposure by strike
35+
gex = fa.gex("SPY")
36+
gex = fa.gex("TSLA", expiration="2026-03-21", min_oi=100)
37+
38+
# Delta, vanna, charm exposure
39+
dex = fa.dex("AAPL")
40+
vex = fa.vex("QQQ")
41+
chex = fa.chex("NVDA")
42+
43+
# Key levels (gamma flip, walls, max pain)
44+
levels = fa.exposure_levels("SPY")
45+
print(f"Call wall: {levels['levels']['call_wall']}")
46+
print(f"Put wall: {levels['levels']['put_wall']}")
47+
print(f"Gamma flip: {levels['levels']['gamma_flip']}")
48+
49+
# Full exposure summary with hedging estimates
50+
summary = fa.exposure_summary("SPY") # Growth+
51+
52+
# AI narrative analysis
53+
narrative = fa.narrative("SPY") # Growth+
54+
print(narrative["narrative"]["regime"])
55+
print(narrative["narrative"]["outlook"])
56+
```
57+
58+
### Market Data — live quotes and option chains
59+
60+
```python
61+
# Stock quote
62+
quote = fa.stock_quote("AAPL")
63+
print(f"AAPL: ${quote['mid']}")
64+
65+
# Option quote with greeks
66+
opt = fa.option_quote("SPY", expiry="2026-03-21", strike=660, type="C") # Growth+
67+
print(f"Delta: {opt['delta']}, IV: {opt['implied_vol']}")
68+
69+
# Comprehensive stock summary (price, vol, exposure, macro)
70+
summary = fa.stock_summary("SPY")
71+
72+
# Vol surface (public — no API key needed)
73+
surface = fa.surface("SPY")
74+
```
75+
76+
### Pricing — Black-Scholes greeks and implied vol
77+
78+
```python
79+
# Full BSM greeks (first, second, third order)
80+
g = fa.greeks(spot=580, strike=580, dte=30, sigma=0.18, type="call")
81+
print(f"Delta: {g['first_order']['delta']}")
82+
print(f"Gamma: {g['first_order']['gamma']}")
83+
print(f"Vanna: {g['second_order']['vanna']}")
84+
85+
# Implied volatility from market price
86+
result = fa.iv(spot=580, strike=580, dte=30, price=12.69)
87+
print(f"IV: {result['implied_volatility_pct']}%")
88+
89+
# Kelly criterion position sizing
90+
kelly = fa.kelly( # Growth+
91+
spot=580, strike=580, dte=30,
92+
sigma=0.18, premium=12.69, mu=0.12,
93+
)
94+
print(kelly["recommendation"])
95+
```
96+
97+
### Volatility Analytics — skew, term structure, realized vol
98+
99+
```python
100+
vol = fa.volatility("TSLA") # Growth+
101+
print(f"ATM IV: {vol['atm_iv']}%")
102+
print(f"RV 20d: {vol['realized_vol']['rv_20d']}%")
103+
print(f"VRP assessment: {vol['iv_rv_spreads']['assessment']}")
104+
```
105+
106+
### Historical Data — minute-by-minute from ClickHouse
107+
108+
```python
109+
# Historical stock quotes
110+
hist = fa.historical_stock_quote("SPY", date="2026-03-05", time="10:30")
111+
112+
# Historical option quotes
113+
hist_opt = fa.historical_option_quote(
114+
"SPY", date="2026-03-05", expiry="2026-03-20", strike=580, type="C"
115+
)
116+
```
117+
118+
### Reference & Account
119+
120+
```python
121+
# All available tickers
122+
tickers = fa.tickers()
123+
124+
# Option chain metadata (expirations + strikes)
125+
chain = fa.options("SPY")
126+
127+
# Symbols with live cached data
128+
symbols = fa.symbols()
129+
130+
# Account info and quota
131+
account = fa.account()
132+
print(f"Plan: {account['plan']}, Remaining: {account['remaining']}")
133+
```
134+
135+
## Error Handling
136+
137+
```python
138+
from flashalpha import (
139+
FlashAlpha,
140+
AuthenticationError,
141+
TierRestrictedError,
142+
NotFoundError,
143+
RateLimitError,
144+
)
145+
146+
fa = FlashAlpha("YOUR_API_KEY")
147+
148+
try:
149+
data = fa.exposure_summary("SPY")
150+
except AuthenticationError:
151+
print("Invalid API key")
152+
except TierRestrictedError as e:
153+
print(f"Need {e.required_plan} plan (you have {e.current_plan})")
154+
except NotFoundError:
155+
print("Symbol not found")
156+
except RateLimitError as e:
157+
print(f"Rate limited — retry after {e.retry_after}s")
158+
```
159+
160+
## Plans
161+
162+
| Plan | Daily Requests | Highlights |
163+
|------|---------------|------------|
164+
| **Free** | 50 | Stock quotes, GEX/DEX/VEX/CHEX by strike, levels, greeks, IV, tickers |
165+
| **Basic** | 250 | Everything in Free |
166+
| **Growth** | 2,500 | + Option quotes, exposure summary, narrative, volatility, Kelly sizing |
167+
| **Pro** | Unlimited | Full access |
168+
169+
**Get your API key at [flashalpha.com](https://flashalpha.com)**
170+
171+
## Links
172+
173+
- [API Documentation](https://flashalpha.com/docs)
174+
- [Interactive Playground](https://lab.flashalpha.com/swagger)
175+
- [GitHub](https://github.com/FlashAlpha/flashalpha-python)

‎examples/quickstart.py‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
"""FlashAlpha SDK quick start — get running in 3 minutes."""
2+
3+
from flashalpha import FlashAlpha
4+
5+
# 1. Initialize with your API key
6+
fa = FlashAlpha("YOUR_API_KEY")
7+
8+
# 2. Get gamma exposure for SPY
9+
gex = fa.gex("SPY")
10+
print(f"SPY Net GEX: ${gex['net_gex']:,.0f}")
11+
print(f"Gamma flip: {gex['gamma_flip']:.2f}")
12+
print(f"Regime: {gex['net_gex_label']}")
13+
print()
14+
15+
# 3. Key support/resistance levels
16+
levels = fa.exposure_levels("SPY")["levels"]
17+
print(f"Call wall (resistance): {levels['call_wall']}")
18+
print(f"Put wall (support): {levels['put_wall']}")
19+
print(f"Gamma flip: {levels['gamma_flip']:.2f}")
20+
print(f"0DTE magnet: {levels['zero_dte_magnet']}")
21+
print()
22+
23+
# 4. Stock quote
24+
quote = fa.stock_quote("SPY")
25+
print(f"SPY: ${quote['mid']:.2f} (bid {quote['bid']:.2f} / ask {quote['ask']:.2f})")
26+
print()
27+
28+
# 5. BSM greeks calculator
29+
greeks = fa.greeks(spot=580, strike=580, dte=30, sigma=0.18)
30+
print("BSM Greeks (580C, 30 DTE, 18% vol):")
31+
print(f" Price: ${greeks['theoretical_price']:.2f}")
32+
print(f" Delta: {greeks['first_order']['delta']:.4f}")
33+
print(f" Gamma: {greeks['first_order']['gamma']:.6f}")
34+
print(f" Theta: {greeks['first_order']['theta']:.4f}")
35+
print(f" Vega: {greeks['first_order']['vega']:.4f}")
36+
print(f" Vanna: {greeks['second_order']['vanna']:.6f}")
37+
print()
38+
39+
# 6. Implied volatility solver
40+
iv_result = fa.iv(spot=580, strike=580, dte=30, price=12.69)
41+
print(f"IV from $12.69 premium: {iv_result['implied_volatility_pct']:.1f}%")
42+
print()
43+
44+
# 7. Account info
45+
account = fa.account()
46+
print(f"Plan: {account['plan']} | Remaining: {account['remaining']}")

‎pyproject.toml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
[build-system]
2+
requires = ["hatchling"]
3+
build-backend = "hatchling.build"
4+
5+
[project]
6+
name = "flashalpha"
7+
version = "0.1.0"
8+
description = "Python SDK for the FlashAlpha options analytics API — gamma exposure (GEX), delta, vanna, charm, greeks, and more."
9+
readme = "README.md"
10+
license = "MIT"
11+
requires-python = ">=3.10"
12+
authors = [{ name = "FlashAlpha", email = "tom@flashalpha.com" }]
13+
keywords = [
14+
"options",
15+
"gamma exposure",
16+
"gex",
17+
"greeks",
18+
"options analytics",
19+
"options API",
20+
"delta exposure",
21+
"vanna",
22+
"charm",
23+
"implied volatility",
24+
"black-scholes",
25+
"trading",
26+
"finance",
27+
"quantitative finance",
28+
]
29+
classifiers = [
30+
"Development Status :: 3 - Alpha",
31+
"Intended Audience :: Developers",
32+
"Intended Audience :: Financial and Insurance Industry",
33+
"License :: OSI Approved :: MIT License",
34+
"Programming Language :: Python :: 3",
35+
"Programming Language :: Python :: 3.10",
36+
"Programming Language :: Python :: 3.11",
37+
"Programming Language :: Python :: 3.12",
38+
"Programming Language :: Python :: 3.13",
39+
"Topic :: Office/Business :: Financial",
40+
"Topic :: Office/Business :: Financial :: Investment",
41+
"Topic :: Software Development :: Libraries :: Python Modules",
42+
]
43+
dependencies = ["requests>=2.28"]
44+
45+
[project.urls]
46+
Homepage = "https://flashalpha.com"
47+
Documentation = "https://flashalpha.com/docs"
48+
Repository = "https://github.com/FlashAlpha/flashalpha-python"
49+
Issues = "https://github.com/FlashAlpha/flashalpha-python/issues"
50+
Playground = "https://lab.flashalpha.com/swagger"
51+
52+
[project.optional-dependencies]
53+
dev = ["pytest>=7.0", "pytest-cov", "responses>=0.23"]
54+
55+
[tool.hatch.build.targets.wheel]
56+
packages = ["src/flashalpha"]
57+
58+
[tool.pytest.ini_options]
59+
testpaths = ["tests"]
60+
markers = ["integration: hits the live FlashAlpha API (deselect with -m 'not integration')"]

‎src/flashalpha/__init__.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
"""FlashAlpha Python SDK — options exposure analytics API."""
2+
3+
from .client import FlashAlpha
4+
from .exceptions import (
5+
AuthenticationError,
6+
FlashAlphaError,
7+
NotFoundError,
8+
RateLimitError,
9+
ServerError,
10+
TierRestrictedError,
11+
)
12+
13+
__version__ = "0.1.0"
14+
__all__ = [
15+
"FlashAlpha",
16+
"FlashAlphaError",
17+
"AuthenticationError",
18+
"TierRestrictedError",
19+
"NotFoundError",
20+
"RateLimitError",
21+
"ServerError",
22+
]

0 commit comments

Comments
 (0)