SignalGuard

Validate the trade before it becomes an order.

SignalGuard is an evidence-backed preflight agent for Binance Agent OS. It turns a natural-language USDⓈ-M Futures intent into a normalized plan, reads current Binance market and account state, applies deterministic risk rules, and produces a tamper-evident decision receipt before any execution is considered.

Live demo: https://signalguard-agent-os.quangminh26050505.chatgpt.site/

56-second demo video: Watch the captioned 1080p walkthrough

The public URL opens in a clearly labeled sanitized demo mode so judges can inspect balances, positions, protective orders, sizing, and receipts without a Binance login. A connected agent can replace the fixture with the current user's authorized Binance MCP snapshot; credentials and account identifiers are never sent to the page.

Why it exists

A trading request can be syntactically valid and still be unsafe to act on: the price may have moved away from entry, the stop and target may be reversed, the spread may be too wide, the evidence may be stale, or the account may not have enough available margin. Language models can explain these problems, but explanations alone are not reproducible.

SignalGuard separates agent reasoning from deterministic validation. Binance Agent OS supplies user-scoped market and account evidence. A small Python core evaluates predefined rules and binds the inputs, policy, findings, and timestamps into stable SHA-256 identities.

flowchart LR
    A[Trade intent] --> B[Normalize]
    B --> C[Binance MCP evidence]
    C --> D[Deterministic policy]
    D --> E{Decision}
    E -->|pass| F[Ready for review]
    E -->|rule failed| G[Blocked]
    E -->|missing or stale evidence| H[Unverified]
    F --> I[Execution preview]
    I --> J[Explicit user confirmation]

What the demo proves

Natural-language intent is normalized into market, side, entry, stop, target, and leverage.
Binance USDⓈ-M Futures mark price and order-book evidence are timestamped independently.
Price orientation, reward/risk, entry drift, spread, freshness, and snapshot coherence are deterministic checks.
READY_FOR_REVIEW, BLOCKED, and UNVERIFIED are distinct outcomes.
Evidence, policy, preflight receipt, and execution preview have separate content-derived IDs.
An execution preview sizes the position from account balance and stop distance, applies Binance filters, and refuses to draft an unprotected entry.
The hosted workspace displays live public Binance candles, funding, countdown, volume, EMA 20, RSI 14, a sanitized account snapshot, and the immutable receipt separately.

READY_FOR_REVIEW is not a recommendation and never places an order. A fresh account snapshot and explicit confirmation are required before any Binance write call. The public demo uses synthetic balances and positions and records execution_performed: false.

Run the deterministic replay

Requires Python 3.11 or newer.

$env:PYTHONPATH = "src"
python -m signalguard.demo

Replay the recorded Binance MCP USDⓈ-M Futures evidence:

$env:PYTHONPATH = "src"
python -m signalguard.cli examples/binance-mcp-futures-read.json

Build an execution preview from an issued preflight receipt and a fresh account snapshot:

$env:PYTHONPATH = "src"
python -m signalguard.execution_cli artifacts/live/execution-preflight-request.json --output artifacts/live/execution-preflight-preview.json

Run the tests:

$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v

Run the workspace

Requires Node.js 22.13 or newer.

cd web
npm install
npm run dev

The page exposes three WebMCP presentation tools:

present_preflight_receipt renders a receipt issued by the deterministic core.
present_execution_preview renders sizing, blockers, order-leg count, and execution status.
present_account_snapshot renders sanitized Futures balances, open positions, and open-order counts without account identifiers.

Binance credentials stay inside the user's Agent OS connection. The hosted workspace receives the sanitized receipt, never the user's password, API key, or OAuth token.

Repository map

src/signalguard/ — parser, evidence adapter, policy evaluator, canonical hashing, payload store, and execution preview.
skills/signalguard/ — reusable agent instructions and Binance MCP workflow reference.
web/ — hosted control desk and WebMCP presentation layer.
examples/ — minimized recorded MCP fixtures for deterministic replay.
artifacts/live/ — example requests, receipts, and content-addressed payloads with no credentials.
docs/ — architecture, authorization boundary, capability matrix, OAuth feasibility, and demo runbook.
tests/ — 24 deterministic unit and fixture tests.

Integrity model

Evidence is captured component by component, including tool name, request parameters, source timestamp, adapter receipt time, and retained-payload hash. Canonical JSON rejects floating-point ambiguity and creates domain-separated IDs for evidence, policies, receipts, and previews. A recorded decision remains immutable; expiration is derived from valid_until without rewriting the original receipt.

The project follows one rule throughout:

Never simulate unsupported execution and never present intended state as executed state.

Current scope

SignalGuard focuses on explicit BTCUSDT USDⓈ-M Futures intents. Live market visualization uses Binance public Futures endpoints. Account reads and any future execution use the current user's separately authorized Binance Agent OS session. The submission demonstrates preflight and an account-aware execution preview; it does not claim that a real order was filled.

License

MIT