| Name | crypto-bs JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Python library for pricing coin-settled crypto options |
| upload_time | 2025-09-03 08:49:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| 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.
|
| keywords |
black-scholes
black-76
options
greeks
implied-volatility
crypto
bitcoin
deribit
pricing
risk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.**
Raw data
{
"_id": null,
"home_page": null,
"name": "crypto-bs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "black-scholes, black-76, options, greeks, implied-volatility, crypto, bitcoin, deribit, pricing, risk",
"author": null,
"author_email": "Seyed Mohammad Hossein Fasihi <mhmd.fasihi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/32/53/acb5a51927f9e48863707e101f2f5a8587a8447f91ddc52f21ea1459c31c/crypto_bs-0.1.0.tar.gz",
"platform": null,
"description": "# Crypto Black-Scholes\n\nA comprehensive Python library for pricing coin-settled cryptocurrency options using advanced Black-Scholes and Black-76 models.\n\n## \ud83d\ude80 Features\n\n- **Multiple Pricing Models**: Black-Scholes, Black-76, and coin-based adaptations\n- **Complete Greeks Calculation**: Delta, Gamma, Theta, Vega, Rho + second-order Greeks (Speed, Charm, Vanna, Vomma)\n- **Portfolio Risk Analysis**: Multi-position portfolio Greeks and risk metrics\n- **Real-time Data Integration**: Live data from Deribit exchange\n- **Coin-Settled Options Support**: Premiums and payoffs in cryptocurrency units\n- **Breakeven Analysis**: Accurate breakeven calculations for coin-settled options\n- **Implied Volatility**: Calculate IV from market prices\n- **Advanced Validation**: Compare model prices with exchange data\n\n## \ud83d\udcca Model Details\n\nThis package implements **three pricing approaches** optimized for cryptocurrency options:\n\n### 1. Black-76 Model (Primary for Coin-Settled)\n- Designed for futures options (perfect for coin-settled crypto options)\n- Uses forward/futures price instead of spot price\n- No risk-free rate discounting (r=0)\n- Premium and payoff in cryptocurrency units\n\n### 2. Enhanced Black-Scholes\n- Standard Black-Scholes with coin-based adaptations\n- Supports both USD and cryptocurrency denominated options\n- Advanced Greeks with second-order derivatives\n\n### 3. Portfolio-Level Analysis\n- Aggregate Greeks across multiple positions\n- Risk metrics including gamma exposure and pin risk\n- Greeks breakdown by underlying asset and expiry\n\n## \ud83d\udcb0 Coin-Settled Options Focus\n\n**Key Differences from Standard Options:**\n- **Premium**: Paid in cryptocurrency (e.g., 0.1 BTC for a $120K BTC option)\n- **Settlement**: Payoff delivered in cryptocurrency\n- **Pricing**: Uses Black-76 model with forward prices\n- **Greeks**: Adjusted for cryptocurrency denomination\n- **Breakeven**: Calculated in USD terms but based on crypto premium\n\n## \ud83d\udcc8 Installation\n\n```bash\npip install .\n```\n\n## \ud83c\udfaf Quick Start\n\n```python\nfrom crypto_bs import price_option, delta, gamma, breakeven_price, breakeven_price_coin_based\n\n# Basic Black-76 pricing for coin-settled options\nprice = price_option(F=110000, K=105000, T=1/365, sigma=0.6, option_type='call')\nprint(f\"Option Price: {price:.6f} BTC\")\n\n# Calculate Greeks\nd = delta(110000, 105000, 1/365, 0.6, 'call')\ng = gamma(110000, 105000, 1/365, 0.6)\n\n# Breakeven analysis (USD premium)\nbe_usd = breakeven_price(105000, 500, 'call')\nprint(f\"Breakeven (USD premium): ${be_usd:.2f}\")\n\n# Breakeven analysis (coin-settled premium)\nbe_coin = breakeven_price_coin_based(105000, price, 'call')\nprint(f\"Breakeven (coin-based): ${be_coin:.2f}\")\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### Coin-Based Pricing with Full Analysis\n\n```python\nfrom crypto_bs import BlackScholesModel, OptionParameters, OptionType\n\n# Advanced pricing with coin-based support\nbs_model = BlackScholesModel()\nparams = OptionParameters(\n spot_price=110000,\n strike_price=105000,\n time_to_maturity=1/365,\n volatility=0.6,\n option_type=OptionType.CALL,\n is_coin_based=True # Key for coin-settled options\n)\n\nresult = bs_model.calculate_option_price(params)\nprint(f\"Coin Price: {result.coin_based_price:.6f} BTC\")\nprint(f\"USD Equivalent: ${result.usd_price:.2f}\")\nprint(f\"Delta: {result.delta:.6f}\")\n```\n\n### Portfolio Risk Analysis\n\n```python\nfrom crypto_bs import analyze_portfolio_risk\n\nportfolio = [\n {\n 'quantity': 10,\n 'spot_price': 110000,\n 'strike_price': 105000,\n 'time_to_maturity': 1/365,\n 'volatility': 0.6,\n 'option_type': 'call',\n 'underlying': 'BTC',\n 'is_coin_based': True\n }\n]\n\nrisk_analysis = analyze_portfolio_risk(portfolio)\nprint(\"Portfolio Delta:\", risk_analysis['portfolio_summary']['total_delta'])\nprint(\"Gamma Exposure:\", risk_analysis['risk_metrics']['gamma_exposure'])\n```\n\n### Real-Time Deribit Integration\n\n```python\nfrom crypto_bs import get_btc_forward_price, get_option_data, validate_deribit_pricing\n\n# Get live data\nF = get_btc_forward_price()\noption_data = get_option_data('BTC-3SEP25-105000-C')\n\n# Validate model against exchange\nvalidation = validate_deribit_pricing(\n deribit_price_btc=option_data['mark_price'],\n spot=F,\n strike=105000,\n time_to_maturity=1/365,\n option_type='call'\n)\nprint(f\"Model vs Exchange difference: {validation['price_difference_btc']:.6f} BTC\")\n```\n\n### Breakeven for Coin-Settled Options\n\nFor coin-settled options where the premium is paid in coin units (e.g., BTC):\n\n```python\nfrom crypto_bs import breakeven_price_coin_based\n\nK = 105000\npremium_btc = 0.0123 # premium in BTC\n\nbe = breakeven_price_coin_based(K, premium_btc, 'call')\nprint(f\"Coin-based breakeven: ${be:.2f}\")\n```\n\n\n## \ud83d\udcca API Reference\n\n### Core Functions\n- `price_option(F, K, T, sigma, option_type)` - Basic Black-76 pricing\n- `delta(F, K, T, sigma, option_type)` - Option delta\n- `gamma(F, K, T, sigma)` - Option gamma\n- `vega(F, K, T, sigma)` - Option vega\n- `theta(F, K, T, sigma, option_type)` - Option theta\n- `breakeven_price(K, premium, option_type)` - Breakeven calculation\n\n### Advanced Classes\n- `BlackScholesModel` - Advanced pricing with coin-based support\n- `GreeksCalculator` - Portfolio-level Greeks and risk analysis\n- `OptionParameters` - Structured option parameters\n- `PortfolioGreeks` - Portfolio Greeks aggregation\n\n### Data Integration\n- `get_btc_forward_price()` - BTC perpetual price from Deribit\n- `get_option_data(instrument)` - Option data from Deribit\n- `get_available_instruments()` - List available options\n\n## \u2705 Validation Results\n\n**Real Deribit Data Test (Sept 2025):**\n- **Exchange Price**: 0.0535 BTC\n- **Model Price**: 0.0542 BTC\n- **Difference**: 0.0007 BTC (1.3% relative difference)\n- **Implied Volatility Match**: Within market expectations\n\n## \ud83c\udfaf Use Cases\n\n- **Crypto Options Trading**: Price and risk-manage BTC/ETH options\n- **Portfolio Hedging**: Calculate Greeks for complex option portfolios\n- **Risk Analysis**: Assess gamma exposure and pin risk\n- **Model Validation**: Compare theoretical prices with exchange data\n- **Breakeven Analysis**: Determine profitable exercise points\n\n## \ud83e\uddea Testing\n\nRun the test suite using pytest:\n\n```bash\n# Using pytest (recommended)\npytest tests/ -v\n\n# Or using the test runner script\npython run_tests.py\n\n# Or run tests directly\npython tests/test_pricing.py\n```\n\nAll 16 tests should pass, covering:\n- Basic Black-76 pricing\n- Greeks calculations\n- Coin-based pricing\n- Advanced portfolio analysis\n- Breakeven calculations\n\n---\n\n**Built for cryptocurrency options traders who need accurate, coin-settled pricing models.**\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Seyed Mohammad Hossein Fasihi\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n \n ",
"summary": "Python library for pricing coin-settled crypto options",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/MhmdFasihi/crypto_black_scholes",
"Issues": "https://github.com/MhmdFasihi/crypto_black_scholes/issues",
"Repository": "https://github.com/MhmdFasihi/crypto_black_scholes"
},
"split_keywords": [
"black-scholes",
" black-76",
" options",
" greeks",
" implied-volatility",
" crypto",
" bitcoin",
" deribit",
" pricing",
" risk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0781914ad51f8cada6c03e4ff349448a243307a46686f6e290e93c3df36d6412",
"md5": "ced08e934d526fa317ecd7351899c626",
"sha256": "a5ec4c256d2c1af1dd93c735fce6ed03497961736059df8e9760503269a4fdc5"
},
"downloads": -1,
"filename": "crypto_bs-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ced08e934d526fa317ecd7351899c626",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18605,
"upload_time": "2025-09-03T08:49:52",
"upload_time_iso_8601": "2025-09-03T08:49:52.861039Z",
"url": "https://files.pythonhosted.org/packages/07/81/914ad51f8cada6c03e4ff349448a243307a46686f6e290e93c3df36d6412/crypto_bs-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3253acb5a51927f9e48863707e101f2f5a8587a8447f91ddc52f21ea1459c31c",
"md5": "73a52134aa39b97d01eb72a25cb6eda0",
"sha256": "71c127a6f0aa14650aa7308026ed4875c4c388eb6a5025daa7e93c54c24b1433"
},
"downloads": -1,
"filename": "crypto_bs-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "73a52134aa39b97d01eb72a25cb6eda0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21309,
"upload_time": "2025-09-03T08:49:54",
"upload_time_iso_8601": "2025-09-03T08:49:54.615267Z",
"url": "https://files.pythonhosted.org/packages/32/53/acb5a51927f9e48863707e101f2f5a8587a8447f91ddc52f21ea1459c31c/crypto_bs-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 08:49:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MhmdFasihi",
"github_project": "crypto_black_scholes",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "crypto-bs"
}
