401 lines
11 KiB
Markdown
401 lines
11 KiB
Markdown
# 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.
|