Metadata-Version: 2.4
Name: amaneki
Version: 0.6.0
Summary: Python client for the Amaneki volatility-regime API
Project-URL: Homepage, https://amaneki.com
Project-URL: Documentation, https://amaneki.com/docs
Project-URL: Reference, https://api.amaneki.com/v1/reference
Project-URL: Source, https://amaneki.com/sdk
Project-URL: Issues, https://amaneki.com/security
Author: Amaneki
License: MIT
Keywords: crypto,regime,trading,volatility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# amaneki

Python client for the [Amaneki](https://amaneki.com) volatility-regime API.

```
pip install amaneki
```

## Usage

```python
from amaneki import Client

c = Client(api_key="ak_...")
snap = c.get_regime("btcusdt")
print(snap.regime, snap.z_vol)  # e.g. "normal" -0.83

for t in c.get_history("btcusdt", from_ms=1776000000000):
    print(t.ts_ms, t.from_regime, "→", t.to_regime)
```

### Cross-exchange consensus

```python
cs = c.get_consensus("btcusdt", timeframe="15m")
print(cs.consensus, f"{cs.agreed}/{cs.available}")
for name, v in cs.venues.items():
    print(name, v.regime, v.z_vol)
```

### Backtest

```python
r = c.run_backtest("btcusdt", timeframe="15m", rule="long_low_exit_normal")
print(r.n_trades, r.total_return, r.max_drawdown)
```

Rules: `long_low_exit_normal`, `short_high_exit_normal`, `avoid_high`.
Optional `thresholds={"high_enter": 3.0, ...}` overrides the running preset.

### Impact, lead-lag, conditional returns

```python
# Return distribution at 1h / 4h / 24h after past HIGH transitions.
imp = c.impact("btcusdt", to="high", timeframe="1m", lookback_days=180)
print(imp["sample_size"], imp["horizons"]["1h"]["p75"])
if imp.get("warning"):
    print("small-N:", imp["warning"])

ll = c.lead_lag("btcusdt", "ethusdt", to="high", lookback_days=90)
print(ll["hit_rate"], ll.get("lag"))

cr = c.conditional_returns("btcusdt", timeframe="15m")
print(cr["by_regime"]["high"]["median"], cr["baseline"]["median"])
```

### Top-down alignment and narrative

```python
td = c.top_down("btcusdt", match="any", from_tf="1d", to_tf="15m")
print(td["consensus"], td["alignment_score"], td["aligned_tfs"])

st = c.stories("btcusdt", timeframe="15m", days=7)
for line in st["stories"]:
    print(line)
```

### Public stats (no key required)

```python
s = c.public_stats()
print(s["uptime_observed_pct"], s["uptime_window_days"])

i = c.public_incidents()
print(i["count"], "incidents in the last 30 days")
```

### Async + streaming

```python
import asyncio
from amaneki import AsyncClient

async def main():
    async with AsyncClient(api_key="ak_...") as c:
        async for ev in c.stream():
            print(ev.type, ev.symbol, ev.to_regime)

asyncio.run(main())
```

### No key

`get_regime` and `get_history` are callable without an API key — you
get the free tier, capped at 60 requests/minute per IP.

## Errors

```python
from amaneki import AuthError, RateLimitError, NotFoundError
```

Raised on HTTP 401 / 429 / 404. `RateLimitError.retry_after` holds the
seconds from the `Retry-After` header when the server provides one.
