Layer-add, hold and flatten decisions for an averaged martingale position, with the drawdown trigger, the rebound exit and a hard layer cap kept as three independent inputs. Ships no thresholds and no sizing.
A martingale is not one decision, it is three: when do I add, when do I give up, and when do I take the exit. Most implementations collapse all three into one threshold and then discover the failure mode the hard way - the ladder keeps doubling until the account is gone. This package keeps them separate. add and flatten are driven by the deviation of price from your average entry; max_layers is an independent, absolute ceiling that no amount of drawdown can override. The returned layer index tells your executor which rung of the ladder the current signal belongs to, so the executor - not the strategy - decides the actual order size. WHEN TO USE THIS • An agent holds an averaged position and must decide whether the next drawdown step justifies another add. • You need to demonstrate, mechanically, why a martingale without a layer cap is a ruin strategy rather than a recovery strategy. • A risk layer wants a single boolean: has this ladder hit its ceiling? Do not use this to justify leverage you have not sized. The package returns a layer index; converting that into notional exposure is entirely your call and is deliberately not implemented here. WHAT THIS PACKAGE DELIBERATELY DOES NOT CONTAIN This is a framework release, not the tuned production build. Specifically: • No position sizing. base_amount, the doubling multiplier and the resulting notional are all absent. You own that arithmetic. • No leverage or margin-mode handling. Spot and perpetual behave differently; that belongs in your executor. • No average-entry calculator. You pass avg_entry and layers in, so the strategy never guesses your book from exchange trade history. • No tuned threshold values. • No default thresholds in code. scripts/martingale_layer.py raises PARAM_INCOMPLETE rather than falling back to a number. A silent default would make you believe you are running a calibrated system when you are running someone else's parameters. Every decision boundary is an input. That is the whole contract. DECISION CONTRACT • action: Meaning - Executor responsibility • seed: Book is flat, nothing to manage - Open the first clip if you want exposure • add: Drawdown crossed your trigger and the cap allows another rung - Size it yourself; the layer field says which rung • flatten: Rebound crossed your exit trigger - Close the entire ladder, not one rung • wait: Inside the band, or the cap is reached - Do nothing Inputs: drop_threshold and rebound_threshold are positive fractions (0.02 = 2%), max_layers is an integer ceiling >= 1. State: avg_entry, layers, optionally price. OUTPUT SCHEMA { "action": "add", "layer": 3, "price": 61250.0, "reason": "drawdown -2.61% <= -2.50% - double into layer 3 of 4" } action is the only field you must branch on. reason is meant for logs and for an agent to quote back to a human — do not parse it. RUN IT python3 scripts/martingale_layer.py \ --params references/params-example.json \ --symbol BTC/USDT \ --interval 15m references/params-example.json holds round, obviously-illustrative numbers. They exist so the command runs on the first try, not because they are good. Feeding position state in: python3 scripts/martingale_layer.py --params my.json --state '{"avg_entry": 61250.5, "layers": 2}' CALIBRATING THE THRESHOLDS 1. drop_threshold - the step size of the ladder. Smaller means more rungs and a smoother average, but each rung is reached sooner, so the clip you open on rung 1 must be smaller. Calibrate it against the typical adverse excursion of your symbol on the timeframe you actually trade, not against the calendar. 2. rebound_threshold - the exit. It must be reachable. A rebound threshold far above the average drawdown step produces a ladder that never closes and eventually hits the cap. A common shape is a rebound trigger at or slightly above the drop step. 3. max_layers - the only input that protects you. Work backwards: with a doubling ladder, total exposure is base (2^n - 1). Pick the largest n whose total you can survive, then keep base small enough to make that true. Treat this as a capital constraint, not a tuning knob - and never raise it mid-ladder. Split your history 70/30 in time; choose on the first block, verify on the second. A parameter set that only survives the first block is curve-fitted. KNOWN LIMITS • The structure has no inherent edge. A martingale converts many small wins into rare catastrophic losses; separating the thresholds does not change that distribution, it only makes the ruin boundary explicit. • avg_entry is taken on trust. If your executor reports a stale or wrong average, every downstream decision is wrong. • The package is direction-agnostic and knows nothing about funding, liquidation price, or borrow cost, all of which dominate a long-running ladder. • Two consecutive add signals at the same layers value mean your executor did not fill; the strategy is stateless by design and will not deduplicate for you. DISCLAIMER This is a decision framework for research and education. It is not investment advice, not a profit claim, and not a backtest result. Crypto derivatives can lose more than the deposit. You are responsible for the parameters you choose and for every order your executor places.
ipfs://bafkreif3qs2dlueicivxgqg3hktaihu65cpff6bln34snarqvzlwug255a
The primary-document hash is the SHA-256 of the plaintext primary Markdown file. The content-commitment hash covers the verified SkillRoot structure, or plaintext ZIP for older Skills; it is not the hash of the downloaded file.
Opaque identifiers and fingerprints are hidden from the primary experience but remain available for exact verification.
0xaf8f63f2c946aa56ed5ae422237a1e784c7c5efce6926ce00e54947b204305270x089bb3abde1a3f32cca89b52e3695e044bcf43760ac3e5f07616a0aafcf1ec9c