Metadata-Version: 2.4
Name: avellaneda-stoikov
Version: 0.1.0
Summary: Rigorous Avellaneda–Stoikov optimal market-making solver (PDE value function + adverse selection).
Project-URL: Homepage, https://github.com/Gavr625/avellaneda-stoikov
Project-URL: Issues, https://github.com/Gavr625/avellaneda-stoikov/issues
Author: Gavr625
License: MIT
License-File: LICENSE
Keywords: avellaneda,hft,market-maker,market-making,optimal-execution,order-book,quant,stoikov,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.6; extra == 'plot'
Description-Content-Type: text/markdown

# avellaneda-stoikov

[![PyPI](https://img.shields.io/pypi/v/avellaneda-stoikov.svg)](https://pypi.org/project/avellaneda-stoikov/)
[![CI](https://github.com/Gavr625/avellaneda-stoikov/actions/workflows/ci.yml/badge.svg)](https://github.com/Gavr625/avellaneda-stoikov/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**A rigorous Avellaneda–Stoikov optimal market-making solver** — the PDE value
function with adverse selection, asymmetric fill rates, and inventory-aware quoting.

```bash
pip install avellaneda-stoikov
```

## Quickstart
```python
from avellaneda_stoikov import ASParams, solve_value_function, optimal_depths

p = ASParams(sigma=0.6, lam_plus=1.0, lam_minus=1.0,
             kappa_plus=100.0, kappa_minus=100.0,
             phi=1e-4, alpha=1e-3, q_max=5, T=60.0, n_steps=600)

t_grid, h_grid = solve_value_function(p)          # solve once
ask, bid = optimal_depths(h_grid, t_grid, p.q_max, t=0.0, q=2,
                          kappa_plus=p.kappa_plus, kappa_minus=p.kappa_minus)
print(ask, bid)   # optimal ask/bid depths when long 2 units (ask < bid: skew to sell)
```

## The model
Solves the Avellaneda–Stoikov / Cartea Ch. 10 market-making problem. Ansatz
`H(t,x,S,q)=x+q·S+h(t,q)`; the HJB reduces to an ODE system in inventory `q`,
integrated backward from `h(T,q) = −α·q²`. Optimal feedback depths:

```
δ⁺* = 1/κ⁺ + ε⁺ + h(t,q) − h(t,q−1)     (ask)
δ⁻* = 1/κ⁻ + ε⁻ + h(t,q) − h(t,q+1)     (bid)
```

![inventory skew](docs/quotes.png)

## Why this one
Most open-source A-S implementations are minimal and unmaintained. This one adds:
- **Adverse selection** (`ε⁺/ε⁻`, Cartea §10.4) — quote wider when fills predict mid moves.
- **Asymmetric fill rates** `κ⁺ ≠ κ⁻` solved directly in the PDE.
- **Finite-difference PDE solver** (not just the closed-form approximation).
- **Inventory skew, boundary and overshoot handling**, validated by tests.

Typed, `mypy --strict`, tested, MIT.

## API
- `ASParams(...)` — model + strategy parameters (`validate()`).
- `solve_value_function(p) -> (t_grid, h_grid)` — solve once.
- `optimal_depths(h_grid, t_grid, q_max, t, q, kappa_plus, kappa_minus, epsilon_plus=0, epsilon_minus=0)` — `(δ⁺, δ⁻)`, `None` on a boundary.
- `reservation_price_and_spread(...)` — `(r, bid, ask)`.

## References
- Avellaneda & Stoikov (2008), *High-frequency trading in a limit order book*.
- Cartea, Jaimungal & Penalva, *Algorithmic and High-Frequency Trading*, Ch. 10.

## Honest note
Extracted from a live trading bot. This is the **solver** — calibration (estimating
λ, κ, ε), execution and risk are left to you; that's where the edge lives. Out of
scope for now: regime switching, order-flow drift (§10.5), non-linear fill models.

## License
MIT.
