The risk engine behind Remora, packaged so you can run it yourself. One API call tells your bot whether market conditions are safe to trade, with the reasons why.
Remora answers "Should I be trading at all right now?", not "Is this a good entry?". It watches BTC price action, volatility and market regime, plus optional sentiment and derivatives data. It returns a risk score, a regime label, a safe_to_trade flag and the reasoning behind them.
Note
Remora ran as a hosted API at remora-ai.com from 2025 until November 2026. That service has been retired; this repository is the same engine, ready for docker compose up.
How it works:
Your Strategy → Your Remora Instance → Filtered Trades
↓ ↓ ↓
Entry Signal Risk Assessment Safe Entries Only
- ✅ Tells your bot whether current market conditions are safe to trade in
- ✅ Blocks entries during high-risk periods: volatility spikes, regime changes, extreme fear, panic drops
- ✅ Explains every decision (returns the reasoning, not just a boolean)
- ✅ Combines several data sources and keeps working when any of them are unavailable
- ✅ Runs on your own machine: no account, no API key, no rate limits you didn't set
- ❌ Does not replace your strategy logic
- ❌ Does not optimise entry or exit signals
- ❌ Does not place trades or need exchange keys (it only reads public market data)
- ❌ Is not financial advice. It can stop some bad entries; it does not make a strategy profitable on its own
You need Docker with the Compose plugin.
git clone https://github.com/DonaldSimpson/remora.git
cd remora
cp .env.example .env # set POSTGRES_PASSWORD and REDIS_PASSWORD
docker compose up -d --buildGive it a minute to pull its first candles, then:
curl -s 'http://localhost:8000/health'
curl -s 'http://localhost:8000/v1/risk?pair=BTC/USD' | python3 -m json.toolExample response (trimmed):
{
"risk_score": 0.80,
"risk_class": "very_high",
"regime": "choppy",
"safe_to_trade": false,
"reasoning": [
"Extreme Fear (F&G=11) - blocking trades",
"Trading disabled due to global risk conditions"
],
"blocked_by": ["flag_extreme_fear"]
}Interactive API docs are at http://localhost:8000/docs.
The snippet, examples and RemoraClient in remora-freqtrade work with your instance. Point them at it:
export REMORA_URL=http://localhost:8000The integration is fail-open: if Remora is down or slow, your bot trades as normal. Removing Remora is as simple as deleting a few lines.
Anonymous requests are limited to 10 a minute. A bot checking many pairs will want more. Either add the bot's host to TRUSTED_IPS in .env, or create an API key (below) and set REMORA_API_KEY.
| Endpoint | What it returns |
|---|---|
GET /v1/risk?pair=BTC/USD |
safe_to_trade, risk_score (0 to 1), regime, volatility, flags and reasoning |
GET /v1/context?pair=... |
The same as /v1/risk |
GET /v1/regime |
Current market regime only |
GET /v1/volatility |
Volatility metrics only |
GET /v1/sentiment |
Fear & Greed and news sentiment, where enabled |
GET /health, GET /status |
Liveness and data freshness |
GET /metrics |
Prometheus metrics |
POST /signup |
Self-service API key by email (needs SMTP settings) |
/admin/* |
Users and request analytics. Disabled unless ADMIN_API_KEY is set; send it as X-Admin-Key |
Create an API key for a bot:
curl -s -X POST http://localhost:8000/admin/users \
-H "X-Admin-Key: $ADMIN_API_KEY" -H 'Content-Type: application/json' \
-d '{"email": "[email protected]", "plan": "free"}'Everything is set in .env. See .env.example for the full list.
- Market data:
EXCHANGE_NAME(via ccxt; defaultkraken) andBTC_SYMBOL. - Optional sources: Fear & Greed, funding rates, open interest, liquidations, VIX/DXY (
FRED_API_KEY), and CryptoCompare and CryptoPanic news (both need their own keys). Each source is skipped if it is disabled, unreachable or missing its key. The risk score uses whatever is available. - Thresholds:
PANIC_PRICE_DROP_THRESHOLD,HIGH_VOL_ATR_THRESHOLD, and theADX_*andVOLATILITY_*settings inapp/config.py.
The API listens on 127.0.0.1:8000 only. If you expose it, put a reverse proxy with TLS in front and set PUBLIC_BASE_URL.
6 years of data, 4 strategies, 20 tests. See the Remora Backtests Repository for the full results and a reproducible framework.
| Metric | Improvement |
|---|---|
| Profit | +1.54% |
| Drawdown | -1.55% |
| Trades Filtered | 4.3% (increases to 16-19% during bear markets) |
| Success Rate | 90% (18 out of 20 tests improved) |
The blog post covers the analysis and methodology.
app/ FastAPI service
api/ routes, admin, signup
engine/ risk score, regime and volatility logic
data/ exchange client, external data sources, Postgres
clients/python/ small Python client with caching
integrations/ Freqtrade plugin
examples/ example strategy integration
- This repository: the risk engine (self-host)
- remora-freqtrade: Freqtrade integration snippet and examples
- remora-backtests: full backtest results and analysis
- Advanced Risk Management for Freqtrade: detailed analysis and methodology
- Freqtrade: open-source cryptocurrency trading bot
PRs, issues and feature requests are welcome.
MIT. See LICENSE.
