crypto-bs 0.1.0__tar.gz

crypto_bs-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Seyed Mohammad Hossein Fasihi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

crypto_bs-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include crypto_bs *.py
+recursive-include tests *.py
+recursive-include examples *.py

crypto_bs-0.1.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: crypto_bs
+Version: 0.1.0
+Summary: Python library for pricing coin-settled crypto options
+Author-email: Seyed Mohammad Hossein Fasihi <mhmd.fasihi@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Seyed Mohammad Hossein Fasihi
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        
+Project-URL: Homepage, https://github.com/MhmdFasihi/crypto_black_scholes
+Project-URL: Repository, https://github.com/MhmdFasihi/crypto_black_scholes
+Project-URL: Issues, https://github.com/MhmdFasihi/crypto_black_scholes/issues
+Keywords: black-scholes,black-76,options,greeks,implied-volatility,crypto,bitcoin,deribit,pricing,risk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pandas>=1.3.0
+Dynamic: license-file
+
+# Crypto Black-Scholes
+
+A comprehensive Python library for pricing coin-settled cryptocurrency options using advanced Black-Scholes and Black-76 models.
+
+## 🚀 Features
+
+- **Multiple Pricing Models**: Black-Scholes, Black-76, and coin-based adaptations
+- **Complete Greeks Calculation**: Delta, Gamma, Theta, Vega, Rho + second-order Greeks (Speed, Charm, Vanna, Vomma)
+- **Portfolio Risk Analysis**: Multi-position portfolio Greeks and risk metrics
+- **Real-time Data Integration**: Live data from Deribit exchange
+- **Coin-Settled Options Support**: Premiums and payoffs in cryptocurrency units
+- **Breakeven Analysis**: Accurate breakeven calculations for coin-settled options
+- **Implied Volatility**: Calculate IV from market prices
+- **Advanced Validation**: Compare model prices with exchange data
+
+## 📊 Model Details
+
+This package implements **three pricing approaches** optimized for cryptocurrency options:
+
+### 1. Black-76 Model (Primary for Coin-Settled)
+- Designed for futures options (perfect for coin-settled crypto options)
+- Uses forward/futures price instead of spot price
+- No risk-free rate discounting (r=0)
+- Premium and payoff in cryptocurrency units
+
+### 2. Enhanced Black-Scholes
+- Standard Black-Scholes with coin-based adaptations
+- Supports both USD and cryptocurrency denominated options
+- Advanced Greeks with second-order derivatives
+
+### 3. Portfolio-Level Analysis
+- Aggregate Greeks across multiple positions
+- Risk metrics including gamma exposure and pin risk
+- Greeks breakdown by underlying asset and expiry
+
+## 💰 Coin-Settled Options Focus
+
+**Key Differences from Standard Options:**
+- **Premium**: Paid in cryptocurrency (e.g., 0.1 BTC for a $120K BTC option)
+- **Settlement**: Payoff delivered in cryptocurrency
+- **Pricing**: Uses Black-76 model with forward prices
+- **Greeks**: Adjusted for cryptocurrency denomination
+- **Breakeven**: Calculated in USD terms but based on crypto premium
+
+## 📈 Installation
+
+```bash
+pip install .
+```
+
+## 🎯 Quick Start
+
+```python
+from crypto_bs import price_option, delta, gamma, breakeven_price, breakeven_price_coin_based
+
+# Basic Black-76 pricing for coin-settled options
+price = price_option(F=110000, K=105000, T=1/365, sigma=0.6, option_type='call')
+print(f"Option Price: {price:.6f} BTC")
+
+# Calculate Greeks
+d = delta(110000, 105000, 1/365, 0.6, 'call')
+g = gamma(110000, 105000, 1/365, 0.6)
+
+# Breakeven analysis (USD premium)
+be_usd = breakeven_price(105000, 500, 'call')
+print(f"Breakeven (USD premium): ${be_usd:.2f}")
+
+# Breakeven analysis (coin-settled premium)
+be_coin = breakeven_price_coin_based(105000, price, 'call')
+print(f"Breakeven (coin-based): ${be_coin:.2f}")
+```
+
+## 🔧 Advanced Usage
+
+### Coin-Based Pricing with Full Analysis
+
+```python
+from crypto_bs import BlackScholesModel, OptionParameters, OptionType
+
+# Advanced pricing with coin-based support
+bs_model = BlackScholesModel()
+params = OptionParameters(
+    spot_price=110000,
+    strike_price=105000,
+    time_to_maturity=1/365,
+    volatility=0.6,
+    option_type=OptionType.CALL,
+    is_coin_based=True  # Key for coin-settled options
+)
+
+result = bs_model.calculate_option_price(params)
+print(f"Coin Price: {result.coin_based_price:.6f} BTC")
+print(f"USD Equivalent: ${result.usd_price:.2f}")
+print(f"Delta: {result.delta:.6f}")
+```
+
+### Portfolio Risk Analysis
+
+```python
+from crypto_bs import analyze_portfolio_risk
+
+portfolio = [
+    {
+        'quantity': 10,
+        'spot_price': 110000,
+        'strike_price': 105000,
+        'time_to_maturity': 1/365,
+        'volatility': 0.6,
+        'option_type': 'call',
+        'underlying': 'BTC',
+        'is_coin_based': True
+    }
+]
+
+risk_analysis = analyze_portfolio_risk(portfolio)
+print("Portfolio Delta:", risk_analysis['portfolio_summary']['total_delta'])
+print("Gamma Exposure:", risk_analysis['risk_metrics']['gamma_exposure'])
+```
+
+### Real-Time Deribit Integration
+
+```python
+from crypto_bs import get_btc_forward_price, get_option_data, validate_deribit_pricing
+
+# Get live data
+F = get_btc_forward_price()
+option_data = get_option_data('BTC-3SEP25-105000-C')
+
+# Validate model against exchange
+validation = validate_deribit_pricing(
+    deribit_price_btc=option_data['mark_price'],
+    spot=F,
+    strike=105000,
+    time_to_maturity=1/365,
+    option_type='call'
+)
+print(f"Model vs Exchange difference: {validation['price_difference_btc']:.6f} BTC")
+```
+
+### Breakeven for Coin-Settled Options
+
+For coin-settled options where the premium is paid in coin units (e.g., BTC):
+
+```python
+from crypto_bs import breakeven_price_coin_based
+
+K = 105000
+premium_btc = 0.0123  # premium in BTC
+
+be = breakeven_price_coin_based(K, premium_btc, 'call')
+print(f"Coin-based breakeven: ${be:.2f}")
+```
+
+
+## 📊 API Reference
+
+### Core Functions
+- `price_option(F, K, T, sigma, option_type)` - Basic Black-76 pricing
+- `delta(F, K, T, sigma, option_type)` - Option delta
+- `gamma(F, K, T, sigma)` - Option gamma
+- `vega(F, K, T, sigma)` - Option vega
+- `theta(F, K, T, sigma, option_type)` - Option theta
+- `breakeven_price(K, premium, option_type)` - Breakeven calculation
+
+### Advanced Classes
+- `BlackScholesModel` - Advanced pricing with coin-based support
+- `GreeksCalculator` - Portfolio-level Greeks and risk analysis
+- `OptionParameters` - Structured option parameters
+- `PortfolioGreeks` - Portfolio Greeks aggregation
+
+### Data Integration
+- `get_btc_forward_price()` - BTC perpetual price from Deribit
+- `get_option_data(instrument)` - Option data from Deribit
+- `get_available_instruments()` - List available options
+
+## ✅ Validation Results
+
+**Real Deribit Data Test (Sept 2025):**
+- **Exchange Price**: 0.0535 BTC
+- **Model Price**: 0.0542 BTC
+- **Difference**: 0.0007 BTC (1.3% relative difference)
+- **Implied Volatility Match**: Within market expectations
+
+## 🎯 Use Cases
+
+- **Crypto Options Trading**: Price and risk-manage BTC/ETH options
+- **Portfolio Hedging**: Calculate Greeks for complex option portfolios
+- **Risk Analysis**: Assess gamma exposure and pin risk
+- **Model Validation**: Compare theoretical prices with exchange data
+- **Breakeven Analysis**: Determine profitable exercise points
+
+## 🧪 Testing
+
+Run the test suite using pytest:
+
+```bash
+# Using pytest (recommended)
+pytest tests/ -v
+
+# Or using the test runner script
+python run_tests.py
+
+# Or run tests directly
+python tests/test_pricing.py
+```
+
+All 16 tests should pass, covering:
+- Basic Black-76 pricing
+- Greeks calculations
+- Coin-based pricing
+- Advanced portfolio analysis
+- Breakeven calculations
+
+---
+
+**Built for cryptocurrency options traders who need accurate, coin-settled pricing models.**

crypto_bs-0.1.0/README.md

@@ -0,0 +1,216 @@
+# Crypto Black-Scholes
+
+A comprehensive Python library for pricing coin-settled cryptocurrency options using advanced Black-Scholes and Black-76 models.
+
+## 🚀 Features
+
+- **Multiple Pricing Models**: Black-Scholes, Black-76, and coin-based adaptations
+- **Complete Greeks Calculation**: Delta, Gamma, Theta, Vega, Rho + second-order Greeks (Speed, Charm, Vanna, Vomma)
+- **Portfolio Risk Analysis**: Multi-position portfolio Greeks and risk metrics
+- **Real-time Data Integration**: Live data from Deribit exchange
+- **Coin-Settled Options Support**: Premiums and payoffs in cryptocurrency units
+- **Breakeven Analysis**: Accurate breakeven calculations for coin-settled options
+- **Implied Volatility**: Calculate IV from market prices
+- **Advanced Validation**: Compare model prices with exchange data
+
+## 📊 Model Details
+
+This package implements **three pricing approaches** optimized for cryptocurrency options:
+
+### 1. Black-76 Model (Primary for Coin-Settled)
+- Designed for futures options (perfect for coin-settled crypto options)
+- Uses forward/futures price instead of spot price
+- No risk-free rate discounting (r=0)
+- Premium and payoff in cryptocurrency units
+
+### 2. Enhanced Black-Scholes
+- Standard Black-Scholes with coin-based adaptations
+- Supports both USD and cryptocurrency denominated options
+- Advanced Greeks with second-order derivatives
+
+### 3. Portfolio-Level Analysis
+- Aggregate Greeks across multiple positions
+- Risk metrics including gamma exposure and pin risk
+- Greeks breakdown by underlying asset and expiry
+
+## 💰 Coin-Settled Options Focus
+
+**Key Differences from Standard Options:**
+- **Premium**: Paid in cryptocurrency (e.g., 0.1 BTC for a $120K BTC option)
+- **Settlement**: Payoff delivered in cryptocurrency
+- **Pricing**: Uses Black-76 model with forward prices
+- **Greeks**: Adjusted for cryptocurrency denomination
+- **Breakeven**: Calculated in USD terms but based on crypto premium
+
+## 📈 Installation
+
+```bash
+pip install .
+```
+
+## 🎯 Quick Start
+
+```python
+from crypto_bs import price_option, delta, gamma, breakeven_price, breakeven_price_coin_based
+
+# Basic Black-76 pricing for coin-settled options
+price = price_option(F=110000, K=105000, T=1/365, sigma=0.6, option_type='call')
+print(f"Option Price: {price:.6f} BTC")
+
+# Calculate Greeks
+d = delta(110000, 105000, 1/365, 0.6, 'call')
+g = gamma(110000, 105000, 1/365, 0.6)
+
+# Breakeven analysis (USD premium)
+be_usd = breakeven_price(105000, 500, 'call')
+print(f"Breakeven (USD premium): ${be_usd:.2f}")
+
+# Breakeven analysis (coin-settled premium)
+be_coin = breakeven_price_coin_based(105000, price, 'call')
+print(f"Breakeven (coin-based): ${be_coin:.2f}")
+```
+
+## 🔧 Advanced Usage
+
+### Coin-Based Pricing with Full Analysis
+
+```python
+from crypto_bs import BlackScholesModel, OptionParameters, OptionType
+
+# Advanced pricing with coin-based support
+bs_model = BlackScholesModel()
+params = OptionParameters(
+    spot_price=110000,
+    strike_price=105000,
+    time_to_maturity=1/365,
+    volatility=0.6,
+    option_type=OptionType.CALL,
+    is_coin_based=True  # Key for coin-settled options
+)
+
+result = bs_model.calculate_option_price(params)
+print(f"Coin Price: {result.coin_based_price:.6f} BTC")
+print(f"USD Equivalent: ${result.usd_price:.2f}")
+print(f"Delta: {result.delta:.6f}")
+```
+
+### Portfolio Risk Analysis
+
+```python
+from crypto_bs import analyze_portfolio_risk
+
+portfolio = [
+    {
+        'quantity': 10,
+        'spot_price': 110000,
+        'strike_price': 105000,
+        'time_to_maturity': 1/365,
+        'volatility': 0.6,
+        'option_type': 'call',
+        'underlying': 'BTC',
+        'is_coin_based': True
+    }
+]
+
+risk_analysis = analyze_portfolio_risk(portfolio)
+print("Portfolio Delta:", risk_analysis['portfolio_summary']['total_delta'])
+print("Gamma Exposure:", risk_analysis['risk_metrics']['gamma_exposure'])
+```
+
+### Real-Time Deribit Integration
+
+```python
+from crypto_bs import get_btc_forward_price, get_option_data, validate_deribit_pricing
+
+# Get live data
+F = get_btc_forward_price()
+option_data = get_option_data('BTC-3SEP25-105000-C')
+
+# Validate model against exchange
+validation = validate_deribit_pricing(
+    deribit_price_btc=option_data['mark_price'],
+    spot=F,
+    strike=105000,
+    time_to_maturity=1/365,
+    option_type='call'
+)
+print(f"Model vs Exchange difference: {validation['price_difference_btc']:.6f} BTC")
+```
+
+### Breakeven for Coin-Settled Options
+
+For coin-settled options where the premium is paid in coin units (e.g., BTC):
+
+```python
+from crypto_bs import breakeven_price_coin_based
+
+K = 105000
+premium_btc = 0.0123  # premium in BTC
+
+be = breakeven_price_coin_based(K, premium_btc, 'call')
+print(f"Coin-based breakeven: ${be:.2f}")
+```
+
+
+## 📊 API Reference
+
+### Core Functions
+- `price_option(F, K, T, sigma, option_type)` - Basic Black-76 pricing
+- `delta(F, K, T, sigma, option_type)` - Option delta
+- `gamma(F, K, T, sigma)` - Option gamma
+- `vega(F, K, T, sigma)` - Option vega
+- `theta(F, K, T, sigma, option_type)` - Option theta
+- `breakeven_price(K, premium, option_type)` - Breakeven calculation
+
+### Advanced Classes
+- `BlackScholesModel` - Advanced pricing with coin-based support
+- `GreeksCalculator` - Portfolio-level Greeks and risk analysis
+- `OptionParameters` - Structured option parameters
+- `PortfolioGreeks` - Portfolio Greeks aggregation
+
+### Data Integration
+- `get_btc_forward_price()` - BTC perpetual price from Deribit
+- `get_option_data(instrument)` - Option data from Deribit
+- `get_available_instruments()` - List available options
+
+## ✅ Validation Results
+
+**Real Deribit Data Test (Sept 2025):**
+- **Exchange Price**: 0.0535 BTC
+- **Model Price**: 0.0542 BTC
+- **Difference**: 0.0007 BTC (1.3% relative difference)
+- **Implied Volatility Match**: Within market expectations
+
+## 🎯 Use Cases
+
+- **Crypto Options Trading**: Price and risk-manage BTC/ETH options
+- **Portfolio Hedging**: Calculate Greeks for complex option portfolios
+- **Risk Analysis**: Assess gamma exposure and pin risk
+- **Model Validation**: Compare theoretical prices with exchange data
+- **Breakeven Analysis**: Determine profitable exercise points
+
+## 🧪 Testing
+
+Run the test suite using pytest:
+
+```bash
+# Using pytest (recommended)
+pytest tests/ -v
+
+# Or using the test runner script
+python run_tests.py
+
+# Or run tests directly
+python tests/test_pricing.py
+```
+
+All 16 tests should pass, covering:
+- Basic Black-76 pricing
+- Greeks calculations
+- Coin-based pricing
+- Advanced portfolio analysis
+- Breakeven calculations
+
+---
+
+**Built for cryptocurrency options traders who need accurate, coin-settled pricing models.**

crypto_bs-0.1.0/crypto_bs/__init__.py

@@ -0,0 +1,31 @@
+from .pricing import price_option
+from .greeks import delta, gamma, vega, theta, rho
+from .utils import breakeven_price, breakeven_price_coin_based
+from .data_fetch import get_btc_forward_price, get_option_data, get_available_instruments, get_btc_price, get_btc_volatility
+
+# Advanced implementations
+from .black_scholes import (
+    BlackScholesModel, Black76Model, OptionParameters, OptionPricing,
+    OptionType, PricingModel, price_coin_based_option, validate_deribit_pricing
+)
+from .greeks_calculator import (
+    GreeksCalculator, GreeksProfile, PortfolioGreeks, RiskMetrics,
+    calculate_option_greeks, analyze_portfolio_risk
+)
+
+__all__ = [
+    # Basic functions
+    'price_option', 'delta', 'gamma', 'vega', 'theta', 'rho', 'breakeven_price',
+    'breakeven_price_coin_based',
+    'get_btc_forward_price', 'get_option_data', 'get_available_instruments',
+    'get_btc_price', 'get_btc_volatility',
+
+    # Advanced classes
+    'BlackScholesModel', 'Black76Model', 'OptionParameters', 'OptionPricing',
+    'OptionType', 'PricingModel', 'GreeksCalculator', 'GreeksProfile',
+    'PortfolioGreeks', 'RiskMetrics',
+
+    # Advanced functions
+    'price_coin_based_option', 'validate_deribit_pricing',
+    'calculate_option_greeks', 'analyze_portfolio_risk'
+]