Freqtrade Integration
riskstate-guard applies RiskState's position limits inside a Freqtrade strategy, before the order is sent. It is a mixin: one import and one base class.
It does not generate signals, and it never places, changes or closes an order. It only caps or refuses entries your strategy already wants to make.
- Package:
riskstate-guardon PyPI (MIT, no dependencies beyond the Python standard library) - Source: github.com/Riskstate/riskstate-guard
Install
pip install riskstate-guard
export RISKSTATE_API_KEY=rs_live_...
The API key is free: request one on the home page. Install the package in the same environment as Freqtrade.
Add it to a strategy
from freqtrade.strategy import IStrategy
from riskstate_guard.freqtrade import RiskStateMixin
class MyStrategy(RiskStateMixin, IStrategy): # mixin first
riskstate = {"mode": "shadow"}
...
That is the whole integration. Your strategy can define custom_stake_amount, confirm_trade_entry and adjust_trade_position itself; the guard is applied to whatever they return, with or without super().
What it enforces
| Situation | Result |
|---|---|
Entry fits inside max_size_fraction for the asset | Passes untouched |
| Entry would take the asset over the limit | Stake is cut to the room that is left |
No room left, or blocked_actions contains NEW_TRADES | Entry is refused |
| API unreachable, key rejected, or malformed response | Refused (fail_mode: "closed", the default) |
| Last good policy is older than 15 minutes | Treated as no policy |
| Pair is not BTC or ETH | Not governed (or refused with unsupported_pairs: "block") |
The limit is on notional per asset: stake × leverage, with the open trade in that asset counted. A 5x futures entry uses five times its stake. Long and short entries are treated the same way.
The guard covers three Freqtrade callbacks:
| Callback | What the guard does |
|---|---|
custom_stake_amount | Caps the stake of a new trade |
confirm_trade_entry | Checks again right before the order goes out |
adjust_trade_position | Caps or drops position increases (DCA). Reductions always pass |
Start in shadow mode
With mode: "shadow" the guard decides and logs, and your orders are not touched. Set log_path and you get one JSON line each time a decision changes:
{"pair": "ETH/USDT:USDT", "asset": "ETH", "allowed": true, "max_notional": 15880.0,
"notional": 15880.0, "proposed_notional": 50000.0, "reason": "SIZE_CAP", "policy_level": 2,
"max_size_fraction": 0.1588, "policy_hash": "95380e5c…", "binding": "MACRO", "mode": "shadow"}
Here the strategy asked for 50,000 of ETH exposure on a 100,000 account and the policy allowed 15,880. Each line carries the policy_hash of the policy it was decided on, so a decision can be matched to the audit log.
Run it next to your strategy for a few weeks, compare, then switch to "enforce".
Options
Set them in the riskstate dictionary of the strategy.
| Option | Default | Meaning |
|---|---|---|
mode | "enforce" | "shadow" logs decisions without changing orders |
fail_mode | "closed" | "open" falls back to local_max_fraction when there is no policy |
local_max_fraction | 1.0 | Your own ceiling per asset. Applies always, including when RiskState is down |
max_policy_age_s | 900 | A cached policy older than this is not used |
refresh_s | 300 | Re-fetch at least this often |
request_timeout_s | 10 | HTTP timeout |
retry_s | 30 | After a failed fetch, wait this long before calling the API again |
unsupported_pairs | "allow" | "block" refuses pairs RiskState does not cover |
log_path | "" | JSON-lines decision log |
Backtesting
The guard is inactive in backtesting and hyperopt. The API serves the current policy, not the policy of a past date, so applying it to historical candles would be wrong. Your backtest results are those of the ungoverned strategy.
What is sent
Each policy fetch sends your API key and the asset symbol (BTC or ETH) to api.riskstate.ai. Pairs, sizes, balances and positions stay on your machine.
Limits
- BTC and ETH only.
- The guard governs entries and position increases. Stops, exits and liquidation risk are yours.
- It sees the trades of the bot it runs in. Positions you hold elsewhere are not counted.
- Portfolio value is what Freqtrade reports as total stake, so
tradable_balance_ratioandavailable_capitalshrink the base the fraction applies to. - It limits exposure. It does not claim to improve a strategy's returns.
How it was tested
Thirty-four unit tests, plus dry-run sessions in Freqtrade 2026.7 on Binance with BTC, ETH and SOL: spot in enforce and shadow mode, a rejected API key, and futures at 5x, long and short, with position increases. In each run the positions Freqtrade recorded matched the limit.
Without Freqtrade
The same check is available as a plain class for any Python bot:
from riskstate_guard import RiskStateGuard, GuardConfig
guard = RiskStateGuard(GuardConfig(api_key="rs_live_..."))
d = guard.check_entry("ETH/USDT", proposed_notional=20_000, portfolio_value=100_000, open_notional=5_000)
if d.allowed:
place_order(notional=d.notional) # already capped
Related
- API Reference (v1): the response the guard reads.
- Three ways a position size limit in Freqtrade fails silently: why the guard is built the way it is.