Skip to content
DonaldSimpsonPublic

About

Self-hosted market risk filter for Freqtrade and other trading bots. One API call says whether conditions are safe to trade: risk score, regime, volatility and reasons. The engine behind the retired remora-ai.com, now one docker compose up.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Remora: Self-Hosted Market Risk Engine for Trading Bots

License: MIT

Blog Freqtrade Integration Backtests Freqtrade Docker

Remora Risk Engine - Stop Bad Trades Before They Happen

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

What Remora Does

  • ✅ 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

What Remora Does NOT Do

  • ❌ 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

Table of Contents


Quick Start

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 --build

Give 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.tool

Example 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.


Using It from Freqtrade

The snippet, examples and RemoraClient in remora-freqtrade work with your instance. Point them at it:

export REMORA_URL=http://localhost:8000

The 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.


API

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"}'

Configuration

Everything is set in .env. See .env.example for the full list.

  • Market data: EXCHANGE_NAME (via ccxt; default kraken) and BTC_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 the ADX_* and VOLATILITY_* settings in app/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.


Want Proof?

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.


Project Layout

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

Resources & Links

GitHub Repositories

Blog Post

Freqtrade

  • Freqtrade: open-source cryptocurrency trading bot

Contributing & Feedback

PRs, issues and feature requests are welcome.

Licence

MIT. See LICENSE.

About

Self-hosted market risk filter for Freqtrade and other trading bots. One API call says whether conditions are safe to trade: risk score, regime, volatility and reasons. The engine behind the retired remora-ai.com, now one docker compose up.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages