Risk-controlled crypto trading agent built with Binance Agent OS and Binance MCP.
Risk before execution. A risk-controlled crypto agent workflow designed for Binance Agent OS.
RiskPilot turns market snapshots and structured agent proposals into LONG, SHORT or NO_TRADE decisions. A deterministic engine checks every candidate before a local paper fill. Refusals are first-class outputs, with specific reasons and a verifiable audit trail.
Status: final release candidate verified on 2026-09-05; PAPER execution only. Official OAuth, four real read-only tools, concrete schema binding, CLI/UI decisions and risk-refusal audit evidence are complete. Codex owns the credentials. The earlier unauthenticated HTTP 401 probe is historical. Public GitHub, video, X publication and the final survey remain participant actions. See integration verification and security audit.
An AI-generated trade idea can be wrong, oversized or explicitly unsafe. RiskPilot separates proposal from authority: market data and an agent may propose an action, while an independent deterministic engine decides whether it is allowed. This makes refusals, position sizing and the exact policy visible and auditable.
AI can propose a trade, but it cannot override deterministic risk controls.
RiskPilot is not a conventional auto-trading bot. It has no exchange execution adapter. The implemented workflow ends in a local PAPER decision and, when approved, a simulated entry recorded in SQLite.
Offline/public REST modes require Python 3.11+, with no runtime pip dependencies or build step. Agent OS mode additionally requires an installed, authenticated Codex CLI (verified with 0.149.1); no API key is entered into RiskPilot.
On Windows, double-click START_DEMO.cmd. It detects an available Python runtime and opens the page. Keep the server window open.
Portable command, from this repository:
python -m riskpilot serveOpen http://127.0.0.1:8765. If the port is occupied, use python -m riskpilot serve --port 8766 and the URL printed by the server. All servers bind to 127.0.0.1 only. Ctrl+C stops the process. No system security settings need to change.
Optional isolated environment:
python -m venv .venv
# Windows (activation is not required):
.venv\Scripts\python -m riskpilot serve
# macOS/Linux:
.venv/bin/python -m riskpilot serveClick New paper session to start with an empty simulated portfolio while retaining history.
- Select Agent OS MCP · read only, ETH/USDT, then Analyze & check. Confirm
AGENT_OS_HOST_BRIDGE, the current market snapshot and a naturalLONG,SHORTorNO_TRADEresult. Do not force a trade. - Switch to Synthetic demo · offline, select 02 · Valid long, then analyze. Expect
APPROVED, about 2.60:1 net R:R, 0.9933 ETH, $44.94 modeled stop risk, andSIMULATED_FILL. - Select 03 · Unsafe request, then analyze. The request asks for 50x leverage and more size. Expect
REJECTED, includingRISK_LIMIT_EXCEEDED,LEVERAGE_LIMIT_EXCEEDEDandPOSITION_LIMIT_EXCEEDED; no new fill. - Inspect Audit trail, expand the full decision and show the verified chain.
01 · No setup and 04 · Valid short provide reproducible NO_TRADE and SHORT results. The short is a local directional simulation; it does not short spot ETH or open a derivatives account. Synthetic prices are illustrative. Live market prices and decisions will differ.
See the script, shot list and replication guide.
| Mode | Implementation | Evidence / limitations |
|---|---|---|
| Synthetic demo | Deterministic generated hourly candles and a demo command router | Offline, explicitly labeled; no LLM used inside the page |
| Binance public data | Three fixed public GET routes: exchangeInfo, klines, bookTicker | No credentials; no fallback on errors; unfinished candle excluded |
| Local MCP tools | riskpilot_policy, riskpilot_analyze, riskpilot_audit over stdio |
AI hosts can supply structured proposals; every candidate enters the same engine |
| Agent OS host bridge | Codex app-server uses its stored OAuth; verified spot.exchangeInfo, spot.klines and spot.depth feed the same engine |
Authenticated CLI/UI reads, PAPER fill, rejection and audit verified; no LLM turn is required for acquisition |
| Execution | SQLite paper entry simulation only | No LIVE adapter, environment switch, order endpoint or funds-transfer operation |
The page is a reliable demonstration surface, not an LLM chat service. Connect a compatible AI host to the local MCP server to give natural-language reasoning access to the guarded tools. Use the host prompt and connection guide. The model may propose price levels and quantities; it cannot set policy, approve its own trade, or access exchange writes through RiskPilot.
Select Agent OS MCP · read only in the UI to use the authenticated bridge. The CLI binds CodexMarketBridge through AgentOSAdapter; library users can inject the same bridge. Codex must expose exactly spot.ticker24hr, spot.exchangeInfo, spot.klines and spot.depth. tool_execute, account reads and exchange writes are excluded. The bridge rejects unsupported tools and symbols before transport and rejects mismatched schemas/data. Authentication errors never switch silently to REST or fixtures. See setup and actual tool schemas.
The implemented flow is:
Binance MCP read-only market data
↓
validated normalized snapshot
↓
strategy or untrusted agent proposal
↓
deterministic risk engine
↓
NO_TRADE / REJECTED / approved local PAPER fill
↓
hash-linked audit trail
See the detailed architecture.
Immutable policy: $10,000 paper equity, default requested risk 0.5%, maximum risk 1%, minimum net R:R 2, leverage 1–3x, one position ≤30% of equity in notional, ≤3 open positions, total notional ≤100% of equity and aggregate modeled stop risk ≤2%.
Stop loss and take profit are required. Direction, price tick, quantity step, minimum notional, spread ≤20 bps, quote age ≤90 seconds, market/proposal symbol match and entry within 0.3% of midpoint are checked. Public symbol filters are fetched; fixtures use declared paper filters.
Quote age is measured from the public request start, not an exchange event timestamp: bookTicker does not provide one. The last closed hourly bar must end within 3,700 seconds. This is a data validation boundary, not a guarantee that an upstream quote was never delayed.
For entry E, stop S, target T and combined per-side fee/slippage rate c = 0.001 + 0.0005:
loss_per_unit = abs(E - S) + (E + S) * c
reward_per_unit = abs(T - E) - (E + T) * c
net_rr = reward_per_unit / loss_per_unit
risk_budget = equity * min(requested_risk_pct, 0.01)
auto_quantity = floor_to_step(min(risk_budget / loss_per_unit,
equity * 0.30 / E,
available_margin * leverage / E))
Oversized explicit quantities and excessive requested risk are rejected, never silently approved after capping. Leverage changes margin, not the calculation of loss at the stop. Costs are illustrative conservative assumptions, not a representation of a specific Binance fee tier. Stop gaps, liquidity, funding, liquidation, partial fills, stop/target order placement, exits and mark-to-market P&L are not modeled. Actual losses are not bounded by these estimates.
The illustrative strategy uses SMA8/SMA21 separation greater than 0.3%, slow-SMA slope and the last closed price relative to SMA8. Stop distance is the larger of 1.5×ATR14 or 1.2% of price. Target distance is 3.5×stop distance before tick rounding. There is no trained prediction model, optimized backtest or profitability claim.
- Full market snapshots, policy hash/version, proposal, checks, portfolio before/after, decision and execution outcome are logged.
- SQLite
BEGIN IMMEDIATEcommits paper fill, exposure, result and audit events atomically. Audit-write failure rolls back the fill. - A request ID is persistent across restarts. Reusing it returns the stored result; changing its inputs returns
IDEMPOTENCY_CONFLICT. - A second request ID for an identical proposal on the same closed candle is blocked as
DUPLICATE_ACTIONwithin the paper session. - Each audit event hashes its exact payload, sequence and previous hash. Startup and transactions verify the chain.
- New paper sessions retain previous positions and events; they do not claim realized P&L or settlement.
- Hashes detect accidental or partial changes. There is no external anchor: someone controlling files can rewrite a whole chain, truncate its tail, modify other tables or change code. This is not tamper-proof storage.
- Free-form prompts and raw rejected model text are not persisted. Never paste secrets into the demo.
python -m pip install -r requirements-dev.txt
python -m pytest -q
python -m compileall -q riskpilot tests scriptsOptional independent SDK and lint gates, in a project environment:
python -m pip install -r requirements-dev.txt
python -m ruff check .
python -m ruff format --check .
python scripts/verify_sdk.pyThe SDK check starts a real subprocess and tests initialization, tool discovery, paper fill, rejection, retry and audit retrieval. It connects only to local RiskPilot. It does not prove Binance OAuth or a real LLM session. Saved results are in evidence/.
CLI examples:
python -m riskpilot analyze --scenario danger
python -m riskpilot analyze --scenario short
python -m riskpilot analyze --source binance_public --symbol ETHUSDT
python -m riskpilot audit
python -m riskpilot new-session
python -m riskpilot --db runtime/agent.sqlite3 mcpDatabase arguments come before the subcommand. All runtime files are excluded from Git. The sample .env.example is a placeholder; this release reads no credentials and does not load .env. RISKPILOT_MODE=LIVE in the process environment is refused. There is no need to create a Binance API secret.
RiskPilot never asks for or reads an OAuth token. Configure the official endpoint and four-tool allowlist in a supported Codex client, then run codex mcp login binance-mcp-server. The participant must personally complete Binance login, OAuth consent and any 2FA. Keep optional account, trading, borrowing and transfer permissions disabled. Exact configuration and verification steps are in agent/CONNECT.md.
The participant must also personally confirm eligibility, publish the GitHub repository and video, post on X, and submit the Binance survey. Those public or account-bound actions are listed in HUMAN_ACTION_REQUIRED.md.
riskpilot/ domain, market, strategy, risk, paper execution, audit, HTTP and MCP
riskpilot/static/ local HTML/CSS/JS demo
tests/ deterministic risk, data, concurrency, persistence, HTTP, MCP tests
agent/ host prompt, connection template and Agent OS handoff
scripts/ independent MCP SDK check and verification utilities
SUBMISSION/ English project copy, demo script, architecture and human checklist
evidence/ test logs, structured demo results, screenshots, integration status
START_DEMO.cmd Windows launcher
Original implementation, MIT license. Runtime: Python standard library (including bundled SQLite) and browser standards; zero third-party runtime packages or copied trading projects. Optional QA dependencies: Ruff (MIT), official Python MCP SDK (MIT) and its dependencies. See THIRD_PARTY.md. The project is independent and not endorsed by Binance.
Track A material is prepared under SUBMISSION/. Official entry requires the participant's own eligible account and public entry steps. The current source repository is local: no remote repository, X post, public demo video or contest submission has been created. Official rules and exact sources: COMPETITION_RESEARCH.md.
RiskPilot is a hackathon prototype for local PAPER analysis. It does not model real fills, exits, liquidation, funding, slippage under stress, tax, custody or guaranteed stop execution. Market data and software can fail, and historical or simulated behavior does not predict future results.
This project is for technical demonstration and education. It is not financial advice, an offer to trade or a promise of profit. Use of Binance services remains subject to Binance terms, eligibility restrictions and the participant's own judgment.