Inspector — risk governance

What the Inspector Is

The Inspector is the risk governance layer of Barfinex. Its role in the pipeline is clear and non-negotiable: every execution intent from Advisor must pass through Inspector before any order reaches the exchange.

Inspector does not make trading decisions. It enforces the rules you configure: position size limits, drawdown thresholds, exposure caps, loss streak controls, cooldown periods. It also manages the protective order lifecycle — stop-loss and take-profit — for every position it opens.

What Inspector Governs

Policy validation

Before forwarding any execution intent, Inspector evaluates it against your configured risk policies:

• Position size — maximum position size per symbol, in absolute or percentage terms
• Portfolio exposure — maximum total open exposure across all symbols
• Drawdown — maximum drawdown from session high, or absolute loss limit
• Loss controls — maximum consecutive losses, maximum losing trades per session
• Cooldown — mandatory pause after a loss before new entries are allowed
• Time restrictions — no-trade windows (e.g. before major economic events)

When a policy is breached, Inspector takes a configurable action:

Protective order management

For every position opened through Inspector, it maintains the full protective order lifecycle:

1. Places initial stop-loss and take-profit orders immediately after the entry is filled
2. Adjusts stop orders as price moves (trailing logic where configured)
3. Cancels protective orders when a position is closed by other means
4. Tracks partial fills and adjusts protective order sizes accordingly

All orders are placed through Provider's REST API. Inspector never calls the exchange directly.

Position classification

Inspector distinguishes between two types of positions:

Runtime-managed positions — opened while Inspector is running. Inspector has full control: it places stops, trails them, and can close these positions by policy or manual trigger.

Legacy positions — existed before the current Inspector session started. Inspector detects these on startup and sends a notification (Telegram if configured). It does not auto-close or modify legacy positions. They remain the operator's responsibility.

Post-Trade Audit

Every filled order is recorded in the audit log with:

• Entry and exit prices
• Slippage vs. expected price
• Fill rate (full vs. partial)
• Fees
• Time from signal to fill (latency)
• Source attribution (which Detector instance and Advisor cycle originated the trade)

This data is accessible through Inspector's REST API and visible in Studio's audit view.

Reconciliation

Inspector runs a periodic reconciliation pass that compares its internal position state against the actual account state from Provider. Discrepancies trigger a reconciliation event, and depending on severity, may trigger a STAND_DOWN until the state is resolved.

This prevents silent divergence between what Inspector believes the portfolio holds and what is actually on the exchange.

How Inspector Connects

• Event bus — Inspector subscribes to market data events from Provider (for price feeds and spread monitoring) and to execution intent events from Advisor.
• Provider REST API — All order placement and account queries go through Provider. Inspector does not bypass Provider to reach the exchange.
• App registry — Inspector registers with Provider at startup. Studio and API clients reach it through Provider's proxy at /api/inspectors/<appKey>/....

What You See in Studio

• Risk dashboard — current policy status, active limits, breach history
• Position list — runtime-managed positions with stop levels and P&L
• KPI panel — session drawdown, win/loss ratio, exposure utilization
• Audit log — every trade with slippage, fill quality, and attribution
• Throttle events — when and why signal generation was reduced or paused

Quick Verification After Installation

GET /api/inspectors/<appKey>/health

Through Provider (or directly on port 8008). Expected response: ok: true with connector info.

Check Inspector logs for:

• Successful connection to the event bus
• Successful registration with Provider
• Heartbeat confirmation from Provider

Next Steps

• Inspector risk policies — Full policy configuration reference
• Barfinex architecture — How Inspector fits into the full pipeline
• Inspector API reference — REST endpoints