Metadata-Version: 2.4
Name: getregime
Version: 0.1.0
Summary: Official Python client for the Regime crypto market regime API (bull / bear / chop + confidence). Drop-in regime filter for Freqtrade and trading bots.
Project-URL: Homepage, https://getregime.com
Project-URL: Documentation, https://getregime.com/quickstart
Project-URL: Freqtrade Guide, https://getregime.com/freqtrade
Project-URL: Source, https://github.com/Thordersonjg/regime-intelligence
Author-email: Regime <support@getregime.com>
License: MIT
License-File: LICENSE
Keywords: api-client,bitcoin,bull-bear,crypto,freqtrade,market-regime,quant,regime-detection,trading,trading-bot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# getregime — Python client for the Regime crypto market API

[![PyPI](https://img.shields.io/pypi/v/getregime.svg)](https://pypi.org/project/getregime/)

Official, **zero-dependency** Python client for [Regime](https://getregime.com) — a
real-time crypto market regime API. One call tells you whether the market is in a
**bull**, **bear**, or **chop** regime, with a confidence score, fused from 9 data
sources (price, funding, open interest, Fear & Greed, DeFi TVL, macro, and more).

Built for **Freqtrade** and trading bots: gate your entries on the market regime in
two lines of code.

```bash
pip install getregime
```

Get a free API key at **[getregime.com](https://getregime.com)** — the free tier
works with a ~15-minute delay; [Pro](https://getregime.com/pricing) keys are real-time.

## Quickstart

```python
from getregime import RegimeClient

rc = RegimeClient(api_key="your_key")   # free key is fine
r = rc.freqtrade_regime()

print(r.regime)        # "bull" | "bear" | "chop"
print(r.confidence)    # 0.0 – 1.0
print(r.action)        # "full_position" | "reduce_position" | "exit_or_hedge" | "hold"

if r.is_bull:
    print("Risk-on — confidence", r.confidence)
```

Public endpoints work with no key at all:

```python
rc = RegimeClient()
print(rc.overview())        # BTC, ETH, Fear & Greed, TVL, regime
print(rc.market_regime())   # full classification + signals
print(rc.stats())
```

## Freqtrade in 2 lines

```python
from getregime import RegimeClient
regime = RegimeClient(api_key="your_key").freqtrade_regime()

# in populate_entry_trend(...):
#   only go long when the market is in a bull regime
risk_on = regime.is_bull
```

A complete, runnable strategy is in
[`examples/freqtrade_strategy.py`](https://github.com/Thordersonjg/regime-intelligence/blob/master/clients/python/examples/freqtrade_strategy.py)
— it caches the regime (a market-wide signal) and only takes longs while the
regime is bull, exiting on bear/chop. See the
[Freqtrade integration guide](https://getregime.com/freqtrade) for details.

## API

| Method | Auth | Returns |
| --- | --- | --- |
| `freqtrade_regime()` | any key | `Regime` (bull/bear/chop + action) |
| `overview()` | none | dict — BTC, ETH, F&G, TVL, regime |
| `market_regime()` | none | dict — classification + signals |
| `assets()` | none | list — top assets w/ funding & OI |
| `stats()` | none | dict — snapshot/regime stats |
| `brief()` | Pro+ | dict — regime + crowd + macro + risk |
| `signals()` | Pro+ | dict — strategy signals |

### Errors

```python
from getregime import RegimeClient, AuthError, RateLimitError, RegimeError

try:
    r = RegimeClient(api_key="bad").freqtrade_regime()
except AuthError:
    ...        # 401/403 — bad or missing key
except RateLimitError as e:
    print(e.retry_after)   # 429 — seconds to wait (client auto-retries first)
except RegimeError as e:
    print(e.status)        # any other HTTP / network failure
```

The client retries rate-limit (429) and server (5xx) responses with backoff
automatically.

## Links

- Website & free key: https://getregime.com
- API docs / playground: https://getregime.com/quickstart
- Freqtrade guide: https://getregime.com/freqtrade
- Pricing: https://getregime.com/pricing

## License

MIT
