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.

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

SituationResult
Entry fits inside max_size_fraction for the assetPasses untouched
Entry would take the asset over the limitStake is cut to the room that is left
No room left, or blocked_actions contains NEW_TRADESEntry is refused
API unreachable, key rejected, or malformed responseRefused (fail_mode: "closed", the default)
Last good policy is older than 15 minutesTreated as no policy
Pair is not BTC or ETHNot 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:

CallbackWhat the guard does
custom_stake_amountCaps the stake of a new trade
confirm_trade_entryChecks again right before the order goes out
adjust_trade_positionCaps 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.

OptionDefaultMeaning
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_fraction1.0Your own ceiling per asset. Applies always, including when RiskState is down
max_policy_age_s900A cached policy older than this is not used
refresh_s300Re-fetch at least this often
request_timeout_s10HTTP timeout
retry_s30After 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_ratio and available_capital shrink 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