Documentation Index
Fetch the complete documentation index at: https://mintlify.com/deniszidbaev-cmyk/polyclaw-trading/llms.txt
Use this file to discover all available pages before exploring further.
PolyClaw Trading enforces a deep, layered risk model: every candidate trade must pass per-trade sizing checks, daily budget checks, open-exposure checks, drawdown-mode checks, market-quality filters, signal-confidence thresholds, and freshness checks before execution is permitted. All parameters are read from the process environment at startup and validated by EngineConfig.from_env().
ConfigError is raised for any invalid, out-of-range, or internally inconsistent value. The engine never silently repairs a misconfiguration — a bad parameter fails the startup check and the system halts. Missing values receive documented defaults; malformed values fail closed.
Trade sizing
These variables set the absolute dollar bounds on each order and the risk percentage used for position sizing.
| Variable | Default | Description |
|---|
MIN_TRADE_USD | 0.25 | Minimum order size in USD; orders below this floor are rejected |
MAX_TRADE_USD | 1.00 | Maximum order size in USD; sized position is clamped to this ceiling |
BASE_RISK_PER_TRADE_PCT | 1.0 | Fraction of bankroll risked per trade (percentage) |
MAX_POSITION_BANKROLL_PCT | 5.0 | Maximum single-position size as a percentage of bankroll |
MIN_TRADE_RISK_PCT | 1 | Minimum per-trade risk percentage (legacy path; used by earlier risk sizing code) |
MAX_TRADE_RISK_PCT | 2 | Maximum per-trade risk percentage (legacy path; upper bound on risk sizing) |
MIN_TRADE_USD cannot exceed MAX_TRADE_USD; the validator raises ConfigError if they are swapped.
Daily & exposure limits
These caps are evaluated fresh before every execution attempt, using the running totals in runtime/bankroll_state.json.
| Variable | Default | Description |
|---|
MAX_DAILY_RISK_PCT | 8 | Maximum percentage of bankroll that may be risked across all trades in one calendar day |
MAX_DAILY_NOTIONAL_PCT | 20 | Maximum notional dollar value deployed in one calendar day, as a percentage of bankroll |
MAX_OPEN_EXPOSURE_PCT | 20.0 | Maximum percentage of bankroll that may be simultaneously in open positions |
MAX_OPEN_BANK_EXPOSURE_PCT | 50 | Maximum percentage of the total bank balance that may be in open positions (broader cap) |
MAX_TRADES_PER_DAY | 6 | Hard cap on the number of executions per calendar day |
Drawdown management
When realized losses breach the trigger threshold, the engine enters drawdown mode and applies reduced risk limits until the recovery threshold is satisfied.
| Variable | Default | Description |
|---|
DRAWDOWN_TRIGGER_PCT | 10 | Drawdown percentage of bankroll that activates reduced-risk mode |
DRAWDOWN_RECOVERY_PCT | 5 | Drawdown must fall back below this level to exit reduced-risk mode |
DRAWDOWN_REDUCED_TRADE_RISK_PCT | 1 | Per-trade risk percentage applied while in drawdown mode |
DRAWDOWN_REDUCED_DAILY_RISK_PCT | 10 | Daily risk cap applied while in drawdown mode |
DAILY_PROFIT_RESERVE_SHARE | 0.50 | Fraction of intraday profits locked away as reserve |
DAILY_PROFIT_RESERVE_TRIGGER_PCT | 5 | Daily profit percentage that activates the reserve lock |
DAILY_PROFIT_RESERVE_LOCK_PCT | 50 | Percentage of accumulated profit locked once the trigger fires |
DRAWDOWN_RECOVERY_PCT must be strictly less than DRAWDOWN_TRIGGER_PCT; swapping them raises ConfigError.
Stop/take levels
ATR-based stop and take-profit multipliers must satisfy the configured reward/risk ratio, or startup validation fails.
| Variable | Default | Description |
|---|
MIN_REWARD_RISK_RATIO | 1.5 | Minimum ratio of expected reward to risk required before entry |
STOP_LOSS_ATR_MULTIPLIER | 1.5 | Stop-loss distance expressed as a multiple of ATR |
TAKE_PROFIT_ATR_MULTIPLIER | 2.5 | Take-profit distance expressed as a multiple of ATR |
MAX_ENTRY_SLIPPAGE_PCT | 0.05 | Maximum tolerated price slippage as a fraction of entry price |
TAKE_PROFIT_ATR_MULTIPLIER / STOP_LOSS_ATR_MULTIPLIER >= MIN_REWARD_RISK_RATIO.
Market filters
Markets that fail any of these filters are silently skipped — they never reach the signal stage.
| Variable | Default | Description |
|---|
MIN_MARKET_LIQUIDITY_USD | 100 | Minimum on-book liquidity in USD |
MIN_MARKET_VOLUME_24H_USD | 100 | Minimum 24-hour traded volume in USD |
MAX_MARKET_MINUTES_TO_EXPIRY | 1440 | Skip markets expiring more than this many minutes in the future |
MIN_MARKET_MINUTES_TO_EXPIRY | 30 | Skip markets expiring sooner than this many minutes in the future |
MIN_ENTRY_PRICE | 0.05 | Minimum YES-token price (must be strictly inside (0, 1)) |
MAX_ENTRY_PRICE | 0.95 | Maximum YES-token price (must be strictly inside (0, 1)) |
MAX_MARKET_MINUTES_TO_EXPIRY must exceed MIN_MARKET_MINUTES_TO_EXPIRY; MIN_ENTRY_PRICE must be less than MAX_ENTRY_PRICE and both must be strictly inside (0, 1).
Signal thresholds
| Variable | Default | Description |
|---|
MIN_EXECUTION_CONFIDENCE | 0.72 | Minimum composite signal confidence score to allow execution |
MIN_SEMANTIC_MAPPING_CONFIDENCE | 0.90 | Minimum confidence that the market question maps to a supported BTC binary outcome |
ALLOW_EXTREME_PRICE_STRATEGY | 0 | When 0, markets near MIN_ENTRY_PRICE or MAX_ENTRY_PRICE boundaries are rejected |
MIN_CONVICTION | 0.55 | Minimum internal conviction score used in earlier signal stages |
Signal score weights
SIGNAL_SCORE_WEIGHTS is a JSON object that controls how each signal component contributes to the final composite confidence. All weights must sum to exactly 1.0; any deviation raises ConfigError.
{
"trend": 0.25,
"rsi": 0.15,
"patterns": 0.25,
"candle_quality": 0.15,
"market_quality": 0.10,
"poc_context": 0.05,
"timeframe": 0.05
}
.env.local:
SIGNAL_SCORE_WEIGHTS={"trend":0.25,"rsi":0.15,"patterns":0.25,"candle_quality":0.15,"market_quality":0.10,"poc_context":0.05,"timeframe":0.05}
ConfigError. Each weight must be a finite number in [0, 1].
Penalties
Penalty values are subtracted from the raw signal score when the corresponding condition is detected. Each must be in [0, 1].
| Variable | Default | Description |
|---|
CONTRADICTION_PENALTY | 0.35 | Applied when 5m and 15m signals directly contradict each other |
SPARSITY_PENALTY | 0.15 | Applied when candle density is too low to be reliable |
EXPIRY_PENALTY | 0.20 | Applied when the market is approaching the MIN_MARKET_MINUTES_TO_EXPIRY boundary |
EXTREME_PRICE_PENALTY | 0.15 | Applied when the YES-token price is near an extreme bound |
OVEREXTENSION_PENALTY | 0.15 | Applied when price is extended far beyond the EMA by more than MAX_EMA_EXTENSION_ATR ATRs |
TIMEFRAME_CONFLICT_PENALTY | 0.35 | Applied when the two timeframes disagree without a clear directional read |
TIMEFRAME_NEUTRAL_PENALTY | 0.10 | Applied when one timeframe is neutral rather than confirming |
TIMEFRAME_ALIGNMENT_BONUS | 0.10 | Bonus added when both timeframes agree on direction |
Cooldowns & circuit breaker
| Variable | Default | Description |
|---|
FAILED_ORDER_COOLDOWN_SEC | 1800 | Per-market cooldown in seconds after a failed live order |
MAX_DECISION_AGE_SEC | 600 | Maximum age in seconds of a cached decision before it must be regenerated |
MAX_MARKET_AGE_SEC | 600 | Maximum age in seconds of fetched market data |
MAX_CANDLE_AGE_SEC | 1200 | Maximum age in seconds of the candle dataset |
MAX_BANKROLL_AGE_SEC | 600 | Maximum age in seconds of the bankroll state snapshot |
PANIC_STOP | 0 | Hard halt for all trade-gate execution (1 = halted) |
PANIC_AUTO_THRESHOLD | 5 | Number of consecutive failed live orders that automatically trip PANIC_STOP; 0 disables |
Indicator parameters
These control the core technical indicators used by the deterministic signal engine.
EMA & RSI
Candle quality
Candle patterns
| Variable | Default | Description |
|---|
EMA_FAST_PERIOD | 8 | Fast EMA period (candles) |
EMA_SLOW_PERIOD | 21 | Slow EMA period (candles); must exceed EMA_FAST_PERIOD |
RSI_PERIOD | 14 | RSI lookback period (candles) |
ATR_PERIOD | 14 | ATR lookback period (candles) |
BULLISH_RSI_MIN | 52 | Lower bound of the bullish RSI zone |
BULLISH_RSI_MAX | 72 | Upper bound of the bullish RSI zone |
BEARISH_RSI_MIN | 28 | Lower bound of the bearish RSI zone |
BEARISH_RSI_MAX | 48 | Upper bound of the bearish RSI zone |
RSI_OVERBOUGHT | 75 | RSI level considered overbought |
RSI_OVERSOLD | 25 | RSI level considered oversold |
MIN_EMA_SPREAD_PCT | 0.003 | Minimum fractional spread between fast and slow EMA required for a trend signal |
MAX_EMA_EXTENSION_ATR | 2.0 | Maximum ATR multiples of EMA extension before OVEREXTENSION_PENALTY applies |
EMA_FAST_PERIOD < EMA_SLOW_PERIOD; BULLISH_RSI_MIN <= BULLISH_RSI_MAX; BEARISH_RSI_MIN <= BEARISH_RSI_MAX; bearish and bullish RSI zones must not overlap (BEARISH_RSI_MAX < BULLISH_RSI_MIN); RSI_OVERSOLD < RSI_OVERBOUGHT.| Variable | Default | Description |
|---|
MIN_CANDLES_5M | 30 | Minimum 5-minute candles required to run analysis |
MIN_CANDLES_15M | 30 | Minimum 15-minute candles required to run analysis |
MIN_CANDLE_QUALITY_SCORE | 0.65 | Minimum quality score for a candle series to be usable |
AUTO_TRADE_CANDLE_QUALITY_SCORE | 0.75 | Quality score at or above which fully automated execution is permitted |
MAX_SINGLE_SAMPLE_CANDLE_RATIO | 0.50 | Maximum fraction of candles that may be single-sample before quality fails |
MAX_FLAT_CANDLE_RATIO | 0.60 | Maximum fraction of flat (zero-body) candles before quality fails |
MAX_MISSING_BUCKET_RATIO | 0.20 | Maximum fraction of missing time buckets before quality fails |
REQUIRE_15M_CONFIRMATION | 1 | When 1, a 15m signal must confirm the 5m signal before execution |
MIN_CANDLE_QUALITY_SCORE cannot exceed AUTO_TRADE_CANDLE_QUALITY_SCORE.| Variable | Default | Description |
|---|
ENGULFING_BODY_MULTIPLIER | 2.0 | How many times larger the engulfing candle body must be vs. the prior candle |
HARAMI_BODY_MAX_RATIO | 0.60 | Maximum inner-candle body size relative to outer candle for a harami pattern |
TWEEZER_WICK_DIFFERENCE_PCT | 0.10 | Maximum fractional difference between the two wicks in a tweezer pattern |
STAR_MIN_RETRACE_RATIO | 0.60 | Minimum retrace ratio to qualify as a star pattern |
STAR_STRONG_RETRACE_RATIO | 0.70 | Retrace ratio that qualifies as a strong star; must be >= STAR_MIN_RETRACE_RATIO |
STAR_MIDDLE_BODY_MAX_RATIO | 0.40 | Maximum middle-candle body size for a valid star pattern |
THREE_CANDLE_PATTERN_LENGTH | 3 | Fixed; must remain 3 |
THREE_CANDLE_MIN_BODY_ATR_RATIO | 0.20 | Minimum body-to-ATR ratio for candles in three-candle patterns |
THREE_CANDLE_MAX_COUNTER_WICK_BODY_RATIO | 0.75 | Maximum counter-wick-to-body ratio for three-candle patterns |
SHADOW_BREAKOUT_ATR_MULTIPLIER | 1.5 | Minimum wick length (in ATR multiples) to qualify as a shadow breakout |
SHADOW_CLOSE_LOCATION_MIN | 0.65 | Minimum close location in the candle range (must be > 0.5) |
ORDER_BLOCK_SWEEP_PCT | 0.02 | Fractional distance the price must sweep past an order block to confirm it |
ORDER_BLOCK_LOOKBACK | 20 | Number of candles to look back when identifying order blocks |
IMPULSE_BODY_MULTIPLIER | 2.0 | Minimum body-to-average ratio defining an impulse candle |
IMPULSE_BODY_LOOKBACK | 20 | Lookback window for the impulse body average |
POC_CONTEXT_DISTANCE_PCT | 0.01 | Fractional distance within which price is considered “at the POC” |
POC_BIN_SIZE | 0.01 | Bin width for the volume-at-price histogram used to find the POC |
