Robson is an execution and risk management engine for cryptocurrency futures, operating at fixed 1x leverage. The operator decides the entry and arms it; Robson executes it when the armed condition is met and manages the exit under deterministic risk and reward policies. It does not originate trade ideas, predict prices, or scan for opportunities.
Robson is concerned with what happens after a trading decision is made: position sizing from chart-derived stops, governed order execution, lifecycle management through entry to settlement, and safe failure handling under volatile conditions.
The system provides a single-operator runtime with a slot-based monthly risk model, deterministic execution semantics, and full auditability at every state transition.
- Monthly budget: 4% of
capital_base— hard limit enforced by a circuit breaker - Per-trade risk: 1% of
capital_baseas a worst-case cap (derived from position size, never set directly) - Position sizing:
size = (capital_base × 1%) / (technical_stop_distance + gap_allowance + round_trip_taker_fees)— the budget absorbs execution costs, not just chart distance, so a stop that fills never breaches the cap (ADR-0039) - Technical stop: always from chart analysis (second S/R level, 15m timeframe) — never a percentage of entry price
- Stop enforcement: two independent layers. The software monitor is the primary exit path (discrete trailing, per-tick audit); a robsond-authored reduce-only conditional stop order rests on the exchange as a fail-safe that survives daemon outages (ADR-0039)
- Exit execution: exits and protective stops are always market orders (taker) — non-execution there is an unbounded loss; fee optimization is only ever applied to legs where waiting is costless (ADR-0040)
- Entry capacity: budget-metered (ADR-0043). Each entry is charged its actual planned worst-case loss against the monthly budget, not the full 1% cap — at least 4 full-cap operations per month are guaranteed, and saved risk becomes extra operations. No static cap on concurrent positions or entries per day; the budget is the only constraint
capital_base is set at month start as a pessimistic snapshot: wallet_balance − carried_risk(Entering + Active + Armed). It is immutable during normal operation, but must be recalibrated if reconciliation detects manual account changes outside Robson.
Armed → Entering → Active → Exiting → Closed
└─ Cancelled (disarmed before entry)
└─ Error (unrecoverable, requires operator action)
The operator arms a position by specifying a symbol and direction (Long/Short). In the v2.5 operator surface, Robson processes the entry immediately at ARM time. The request still passes through technical-stop analysis, the query engine, and the risk gate before any order reaches the exchange.
Supported v2.5 entry mode:
immediate: entry intent is generated and processed at ARM time, still subject to the selected approval mode and every risk control
The backend retains confirmed_trend, confirmed_reversal, and
confirmed_key_level for historical event/API compatibility. They are not
operationally accepted for v2.5 and are intentionally unavailable in the
dashboard.
Approval modes (whether human confirmation is required):
automatic: entry proceeds without operator action (default)human_confirmation: operator must approve via dashboard before the order is placed
Most open-source trading systems conflate signal generation with execution. The result is software where risk management is an afterthought bolted onto an indicator library.
Robson inverts this. The execution and risk layers are the primary concern. The operator decides the entry; Robson times and executes it, sizes the position from the technical stop, and manages the exit deterministically.
In futures markets, how you execute matters more than what you execute. Even at 1x, a sound entry with poor exit execution, missing stop logic, or uncontrolled position sizing will lose capital. Robson exists to make the execution path deterministic, auditable, and safe by default.
The canonical runtime is written in Rust and lives at the repository root. The SvelteKit operations dashboard lives under frontend/.
robson-domain/ # Pure domain logic — no external dependencies
robson-engine/ # Decision engine (risk calculations, position sizing)
robson-exec/ # Execution layer (port definitions, orchestration)
robson-connectors/ # Exchange adapters (Binance Futures)
robson-store/ # PostgreSQL persistence (SQLx)
robsond/ # Runtime daemon (Axum HTTP API, control loop)
robson-sim/ # Backtesting and simulation
robson-cli/ # Exceptional operator recovery CLI (Rust)
frontend/ # SvelteKit operations dashboard
docs/
adr/ # Architecture Decision Records
architecture/ # System specs, migration plans, v4 backlog
policies/ # Risk and reconciliation policies
runbooks/ # Operational procedures
Execution Engine — Manages the full position lifecycle through explicit state transitions. Every transition is governed by the query engine and produces an immutable audit event. No implicit side effects.
Risk Engine — Enforces per-position and portfolio-level constraints before and during execution. Position sizing is derived from the Golden Rule. Every exit carries a typed reason code.
Detector — Preserves the governed strategy boundary used by deferred entry
policies. The supported v2.5 immediate mode bypasses strategy waiting but
does not bypass technical-stop analysis, the query engine, or the risk gate.
Reconciliation Worker — Runs startup and periodic USD-M Futures scans and
closes exchange positions that have no matching active local (symbol, side).
Exact originating-order correlation and wider account coverage remain ADR-0022
follow-up work; the authorship invariant itself is non-negotiable.
Query Engine — Every state transition passes through a lifecycle-tracked ExecutionQuery: Accepted → Processing → RiskChecked → Acting → Completed / Denied / Failed. Denials are governed outcomes, not errors.
Event Stream — All domain events are persisted in the canonical event log. A narrow public SSE projection carries incremental runtime updates, while an authenticated REST bootstrap supplies durable events for the dashboard's current UTC day.
GET /health # Health check
GET /status # Positions, slots, monthly risk state
GET /positions?month=YYYY-MM # Monthly position history
GET /positions/{id} # Single position detail
POST /positions # Arm a new position
POST /positions/{id}/signal # Inject entry signal (testing)
DEL /positions/{id} # Cancel Armed / close Active position
POST /queries/{id}/approve # Approve a pending human-confirmation query
GET /monthly-halt # Monthly halt status
POST /monthly-halt # Trigger halt manually (kill switch)
POST /panic # Emergency close all open positions
GET /events/history?date=YYYY-MM-DD # Latest 100 durable events for a UTC day (bearer header)
GET /events # SSE event stream (bearer header)
- Rust stable + nightly (nightly required for
rustfmt) - PostgreSQL
- pnpm — frontend (
frontend/) just— task runner
# Build
cargo build
# Unit and in-memory tests (no database needed)
cargo test --all
# Format (nightly rustfmt)
cargo +nightly fmt --all
# Lint
cargo clippy --all-targets -- -D warnings
# PostgreSQL integration tests (requires DATABASE_URL)
just v2-db-up # start local database container
just test-pg # run integration tests against real DBcd frontend
pnpm install
pnpm dev # development server
pnpm check # type check (svelte-check + tsc)
pnpm build # production buildThe narrow robson-cli binary supports exceptional reconciliation and income-ledger recovery. Routine trading operations use the SvelteKit dashboard or authenticated robsond API.
cargo build --release -p robson-cli
./target/release/robson-cli --helpThe CLI is not currently packaged in the runtime image or published as a versioned artifact. See docs/CLI.md before using it against an operated environment.
Copy .env.example and configure DATABASE_URL and exchange credentials. The daemon reads configuration from environment variables and a robsond.toml file.
Production deployments are performed via GitOps (GitHub Actions + ArgoCD + k3s) with Traefik ingress and cert-manager-managed TLS. Infrastructure automation is managed separately in rbx-infra.
See docs/runbooks/ for deployment and operational procedures.
Canonical AI-first instructions live in AGENTS.md. Vendor-specific files such as CLAUDE.md are compatibility adapters and must remain thin.
Open source. See LICENSE for details.