die/docs/plans/2026-03-28-binance-event-contract-agent-design.md

Binance Event Contract Agent Design

Summary

Build a high-cohesion single-project quantitative agent platform for Binance event contracts with:

• modular-monolith backend
• React frontend for live visibility and operator control
• multi-agent orchestration built on deepagents
• parallel dry-run strategy execution
• backtesting and experiment management
• self-optimization through validated strategy iteration
• OpenAI-compatible model abstraction for provider-agnostic model switching
• manual confirmation gate for any live order

The system starts as a local development project and should later deploy to a personal cloud server without architectural rework.

Product Goals

• Focus only on Binance event contracts for up/down prediction markets.
• Support dry-run simulation for multiple strategies at the same time.
• Support historical backtesting and forward-style evaluation.
• Support continuous self-improvement through AI-proposed strategy variants that are validated before promotion.
• Avoid single-agent lock-in; the architecture must support multiple cooperating agents.
• Keep deployment simple by using a single repository and a single deployable application.
• Provide a React frontend that exposes data, strategy performance, experiments, and live confirmation actions in real time.

Non-Goals For V1

• Fully automatic live trading without human approval
• Multi-exchange support
• External sentiment, news, or on-chain data ingestion
• Multi-service microservice deployment
• Complex user/team management

Architectural Direction

Use a modular monolith:

• one repository
• one backend application process boundary
• one frontend application
• shared database and cache

Internally, split responsibilities into modules rather than services. This preserves simple deployment while keeping agent logic, experiment logic, data ingestion, and execution control from collapsing into one code path.

Core Modules

Frontend

React application for:

• live market and strategy monitoring
• experiment visibility
• model/config management
• manual live trade confirmation

API/App

Single backend entrypoint exposing:

• HTTP APIs
• WebSocket streams
• job scheduling entrypoints
• configuration management
• audit/log access

Agent Runtime

deepagents-based orchestration layer responsible for:

• agent role definitions
• shared context passing
• structured outputs
• task lifecycle management
• strategy run coordination

Strategy Lab

Holds the strategy lifecycle:

• strategy definitions
• candidate generation
• dry-run execution
• backtest execution
• scoring
• promotion/demotion states

Market Data

Responsible for:

• Binance market/event contract data ingestion
• normalization
• snapshot/versioning
• storage and replay support

V1 uses only base market data and event-contract-related inputs, while preserving extension points for future external datasets.

Execution Ledger

Responsible for:

• simulated orders
• live trade proposals
• manual confirmation workflow
• trade and position records
• audit logs

Multi-Agent Design

V1 uses five agent roles.

Orchestrator Agent

Coordinates runs and experiments. It starts tasks, routes context, and manages the lifecycle of research, dry-run, and backtest sessions. It does not directly own execution rights.

Signal Agent

Produces directional predictions, confidence, and structured rationale from standardized market inputs for a specific strategy instance.

Risk Agent

Evaluates whether a signal should be reduced, skipped, or flagged as unsafe based on explicit risk rules and uncertainty markers.

Evaluator Agent

Analyzes dry-run and backtest outcomes to explain where a strategy is performing well or degrading.

Optimizer Agent

Proposes new strategy variants by changing prompts, thresholds, feature windows, risk parameters, model profiles, or role bindings. It cannot bypass validation.

Control Boundaries

• Agents are proposers, not final executors.
• System state transitions control promotion and execution.
• Live trading always requires explicit human confirmation.
• Invalid model outputs are rejected instead of being silently interpreted.

Strategy Model

Treat every strategy as a versioned experiment unit with:

• strategy id
• version
• agent composition
• model profile bindings
• feature configuration
• risk configuration
• scoring configuration
• current state: draft, candidate, dry-run, approved-for-live, archived
• result summaries and experiment lineage

This enables many strategies to run in parallel without losing comparability.

Time Horizon Design

Binance event contracts impose a minimum short-horizon decision cycle around 10 minutes. The system should therefore:

• align decision opportunities with event contract timing constraints
• keep the trade decision cycle centered on supported market windows such as 10m
• allow feature observation windows to vary and be optimized experimentally

The optimization process may test different observation horizons such as 5m, 15m, 30m, and longer context windows, but the underlying tradeable event window remains grounded in exchange constraints.

Optimization Objective

The primary optimization target is risk-adjusted return, not raw profit or hit rate.

Recommended scoring inputs:

• net return
• max drawdown penalty
• stability across windows
• minimum sample sufficiency
• overtrading penalty

This prevents the optimizer from overfitting to noisy short-term gains.

Data Scope

V1 implements only core market data and event-contract-relevant inputs, while preserving extension points for future external sources.

This means:

• ingest and store normalized core market data first
• do not block the architecture on sentiment/news/on-chain feeds
• model the feature pipeline so external factors can be added later without redesign

Core Pipelines

1. Real-Time Observation Pipeline

market-data -> normalization -> storage/cache -> websocket/frontend

This pipeline produces trustworthy current-state inputs and never fabricates strategy outputs.

2. Dry-Run Decision Pipeline

For every active strategy and decision point:

market-data snapshot -> Signal Agent -> Risk Agent -> simulated order -> settlement -> ledger

Parallel dry-run strategies are a first-class feature.

3. Backtest and Experiment Pipeline

For every proposed candidate variant:

historical window selection -> replay -> scoring -> ranking -> persistence

Backtest results determine candidate quality but do not directly authorize live trading.

4. Optimization Feedback Loop

Evaluator Agent -> structured diagnosis -> Optimizer Agent proposal -> backtest queue -> candidate promotion

AI proposes changes. The platform validates them. Validated results become future input to the AI. This closed loop is central to the project.

Versioning Requirements

The platform should version at least:

• market data snapshots
• strategy definitions
• prompt templates
• model profiles
• experiment runs
• evaluation outputs

Without versioning, later comparisons and regressions become untrustworthy.

Model Abstraction

Use OpenAI-compatible APIs behind a provider-agnostic model profile layer.

Each LLM Profile should include:

• profile name
• provider name
• API base URL
• API key reference
• model name
• generation parameters
• timeout/retry metadata
• structured output capability flags
• optional cost metadata
• optional tags such as fast, cheap, reasoning, production

Model Configuration Layers

Global Defaults

Project-wide fallbacks for model behavior and timeouts.

Agent-Level Binding

Specific agents bind to specific model profiles.

Strategy-Level Override

Individual strategy experiments may override model profile bindings to support controlled comparisons.

This structure supports systematic experiments such as swapping only the Signal Agent model while keeping all else fixed.

Frontend Views

V1 should provide five core views.

Dashboard

Shows:

• current market state
• event contract timing
• active strategy counts
• recent signals
• recent simulated outcomes
• alerts and runtime health

Strategies

Shows:

• strategy version metadata
• current state
• recent performance metrics
• drawdown
• hit rate
• score trend

Experiments

Shows:

• queued/running/completed backtests
• ranking tables
• parameter deltas
• model comparisons
• promotion decisions

Live Confirm

Shows:

• proposed live trade
• confidence
• risk summary
• recent comparable performance
• explicit confirm/reject actions

This screen is the manual gate for all live execution.

Models & Config

Shows and edits:

• OpenAI-compatible model profiles
• agent bindings
• optimization parameters
• risk limits

Realtime Communication

Use:

• HTTP for CRUD and historical queries
• WebSocket for streaming market updates, strategy events, experiment progress, and alerts

Safety, Risk, and Promotion Rules

• Dry-run may be automatic.
• Live execution may not be automatic.
• No strategy may enter live use without explicit human confirmation.
• Candidate promotion requires minimum sample size and drawdown/stability gates.
• Missing or stale data causes a skip, not a fabricated signal.

Error Handling

The platform must explicitly handle:

• market data gaps or staleness
• malformed or timed-out model responses
• replay/backtest alignment failures
• frontend/backend state drift

Rule: when reliability is uncertain, skip the decision and record why.

Testing and Trustworthiness

V1 should include:

• unit tests for scoring, validation, and risk rules
• replay tests for deterministic historical decision reproduction
• integration tests for end-to-end dry-run flow
• benchmark comparisons against simple baselines

Required baselines:

• random direction baseline
• simple momentum baseline
• simple mean-reversion baseline

Any AI-generated strategy must outperform relevant baselines on risk-adjusted criteria before it is considered useful.

Backtest Integrity Rules

• separate training, validation, and forward evaluation windows
• no future leakage
• feature construction only from historically available data
• sample-out performance matters more than in-sample optimization
• strategy promotion uses risk-adjusted metrics, not only peak profit

Deployment Direction

The project should be designed so that:

• local development is straightforward
• later deployment to a personal cloud server does not require architecture changes
• packaging can converge toward a single-command local start and a simple containerized deployment path

Delivery Guidance

V1 should prioritize a narrow but rigorous vertical slice:

• data ingestion
• one decision cycle
• multi-strategy dry-run
• backtest loop
• optimizer proposal loop
• React visibility
• manual live-confirm screen

This is enough to validate the platform without prematurely building a broad trading system.

Constraints And Open Preconditions

• Current workspace is not a Git repository, so the design document cannot be committed yet.
• The implementation plan should assume repository initialization or placement inside a real project repository before coding begins.