trader-mcp/strategies/AGENTS.md

Strategies AGENTS

Purpose

This folder holds strategy modules and their adjacent contract notes.

The code in strategies/*.py should stay focused on strategy behavior. Shared mechanics belong in src/trader_mcp/.

---

Shared Rules

• Keep strategy modules narrow: strategy logic, state transitions, and placement decisions.
• Put shared sizing, balance, fee, and venue-awareness logic in src/trader_mcp/strategy_context.py and src/trader_mcp/strategy_sizing.py.
• Treat StrategyContext as the authoritative place for venue/account-aware order sizing and balance access.
• Do not duplicate dust handling, minimum-order checks, or fee math inside a strategy unless there is a strategy-specific reason that cannot live in shared helpers.
• Keep adjacent strategies/*.md files aligned with what the code actually does.
• Preserve uncertainty in docs when behavior is still provisional. Use TODO instead of guessing.

---

Shared Helper Map

• StrategyContext.suggest_order_amount() is the venue/account-aware sizing primitive.
• src/trader_mcp/strategy_sizing.py is the policy layer for quote-sized helpers and balance-target helpers.
• StrategyContext.get_account_info() and StrategyContext.get_open_orders() are the primary live inputs for balance and order-shape decisions.
• StrategyContext.cancel_all_orders_confirmed() is the preferred cancel contract when a strategy needs authoritative cleanup semantics.

---

Grid Trader

Grid Shape

• grid_trader must compare the active order shape against the best possible funded grid.
• The best possible grid includes both free balances and funds already locked in active orders.
• The shape check must use the same side-aware funded capacity that seeding uses.
• A mismatch between the best possible shape and the actual active orders should trigger a full rebuild.
• Do not treat the grid as paired buy/sell levels. Each side is filled independently.

Seeding And Rebuilds

• Seeding should place as many levels as are actually fundable on each side.
• Rebuilds should remain full-grid rebuilds, not partial top-ups.
• Restart should not suppress mismatch-driven reseed checks.
• Track and log rebuild reasons clearly in the strategy debug log.

Sizing Boundary

• grid_trader should not implement its own dust or fee policy.
• If sizing behavior changes, update the shared helpers first and keep the strategy thin.
• The strategy may ask for a size and may compare funded capacity, but it should not re-encode venue rules.

Live Trace

• state["debug_log"] is the live trace for the strategy.
• The DB snapshot stores the current state, not a separate event log table.

---

Wiki References

• Grid Trader for the implementation page.
• Mean Reversion and Grid Trading for the strategy concepts.
• Inventory Rebalancing for the inventory-bias concept.
• Dumb Trader and Side-Only Execution for the side-only execution contract.
• Exposure Protector for the companion defensive strategy.

---

Future Strategy Sections

• dumb_trader: TODO
• trend_follower: TODO
• exposure_protector: TODO
• any new strategy: document its own shape, sizing, and restart invariants here