Grid bookkeeping in integer rung space: buy one step below the last filled rung, exit one step above the average entry, and return an explicit stop state when price leaves the band rather than silently continuing to buy.
A grid is arithmetic, and most grid code is wrong in the same three places: it compares prices instead of rung indices, so floating-point noise re-triggers fills; it has no concept of outside the band, so it keeps buying below the floor; and it has no exit, so it accumulates inventory forever. This package reduces price to an integer rung index first and makes every decision in index space. That removes the re-trigger problem structurally. It also returns a distinct stop action when price closes below the floor - the grid is not "still working", it is invalidated, and the difference matters when a human asks why the bot kept buying. WHEN TO USE THIS • An agent runs a range-bound accumulation plan and needs rung-level decisions. • You must detect that a grid has been structurally broken, not merely unprofitable. • You want a worked example of index-space versus price-space grid logic. Actively harmful in a downtrend. The band is the whole risk control, and the package has no view on where you set it. WHAT THIS PACKAGE DELIBERATELY DOES NOT CONTAIN This is a framework release, not the tuned production build. Specifically: • No quote-per-rung amount. amount_per_grid is deliberately absent, so the package cannot tell you the capital a full ladder would consume - compute that yourself from grids before you start. • No auto-ranging. The band is an input. If you set it from recent price, that logic is yours to own. • No tuned band or rung count. • No default thresholds in code. scripts/grid_ladder.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: Condition • seed: No rung recorded yet - record level and open the first clip • buy: Current rung is below the last recorded rung • exit: Price is at least one step above your average entry • stop: Price is below the floor - the ladder is invalidated • wait: None of the above Response carries level, step and grids so the caller can reconcile its own bookkeeping against the rung index instead of a float price. OUTPUT SCHEMA { "action": "buy", "price": 58840.0, "level": 2, "step": 583.33, "grids": 24, "avg_entry": 60020.0, "reason": "rung 2 is below the last filled rung 3" } 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/grid_ladder.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/grid_ladder.py --params my.json --state '{"avg_entry": 61250.5, "layers": 2}' CALIBRATING THE THRESHOLDS 1. lower / upper - the band is the entire risk model. Set it from a range you believe in structurally, not from a moving average you recompute daily: a band that follows price guarantees the floor is tested. 2. grids - rung count. More rungs means a smoother average and a smaller step, which is good in a range and fatal in a trend because the ladder fills faster on the way down. Total capital is grids amount_per_grid; size the rung count after you size the clip, never before. 3. Sanity check: (upper - lower) / grids should be larger than your symbol's typical bar range. If a single bar spans several rungs, the grid is too fine. Backtest across at least one full range-to-trend transition. A grid that looks profitable in a quiet sample is usually just reporting unrealised inventory. KNOWN LIMITS • The ladder is one-sided: it buys down and exits on the average, it does not sell up through the band. Symmetric grid behaviour is not implemented. • avg_entry is trusted from the caller. A stale average makes the exit test meaningless. • Rung index uses floor division on a float step, so a price sitting exactly on a rung boundary can flip index between calls. Treat buy on the same rung twice as an executor de-duplication problem. • No funding, borrow, or fee accounting; in a long-lived grid those costs dominate. 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://bafkreidgnr6ticfotbkx2unljmkxkccd7pnxuiuh3osq56yxecwrhdjkxy
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.
0xba134e14dcf2dd17122e308d332c8cf72c2177d8fe05c4254768b8318390fca80x1175c0bcb1a6ba9cccc6b98b4431ff477be7e47089c776cdd3cd389332063ede