Inspector — risk management overview

What is the Inspector?

The Inspector is a separate Barfinex service for risk management:

• Monitors positions and keeps them under control
• Places and maintains stop orders (stop-loss, take-profit)
• Limits losses and publishes risk events to the event bus when policies are breached

It distinguishes between:

• Legacy positions — Opened before the current Inspector session. For these, the Inspector only notifies (e.g. via Telegram); it does not auto-close or modify stops.
• Runtime-managed positions — Opened while the Inspector is running. For these it has full control: ensures stops, trailing logic, and can close positions via the Provider API.

The Inspector runs as its own process or container. It connects to the event bus for incoming events and to the Provider REST API for executing orders and fetching account snapshots. It registers with the Provider (App Registry) as type inspector so Studio and API clients can reach it through the Provider proxy.

Where the Inspector gets data

Event bus (channels)

The Inspector subscribes to:

• Provider market data — Trades, order book, candles, symbols, prices
• Provider account and orders — Account events, order create/close
• Detector position requests — Open, close, reduce, flip requests

From these it updates its price cache, order book (spread), symbol list, and positions, then recomputes risk and—for runtime-managed positions—places or updates stops or closes positions when needed.

Provider REST API

• Execution — POST /api/orders to open/close market orders and protective orders (e.g. STOP_MARKET, TAKE_PROFIT_MARKET). Orders are marked as source “inspector”.
• Account data — GET /api/accounts/:connectorType/:marketType for account and position snapshots when starting a session and updating state.

The Inspector does not call Detector execution endpoints; all trading actions go through the Provider.

What the Inspector publishes

• Risk limit breach — When a throttle policy fires (e.g. daily loss, drawdown, too many losing trades, consecutive losses). The payload can tell the Detector to throttle or pause signal generation.
• Kill switch — Emergency shutdown when implemented.
• Other risk-related event types as the product evolves.

Installation and run

1. Environment — Same event bus and network as the Provider (e.g. shared Docker network). Set event bus host/port, Provider API URL, and optionally API token.
2. Registration — On startup the Inspector registers with the Provider (register + heartbeat). You configure app key (default inspector), public host, and API port (default 8008).
3. Docker — Use the Barfinex Inspector image in your compose file, with the same network as Provider and event bus, and the same env file.
4. Config — Risk and trade parameters (stop loss %, take profit %, limits, etc.) are set in the Inspector config file (e.g. config.inspector.json or equivalent). See Inspector risk policies for the main options.

What you see in Studio and logs

• Studio — Risk dashboard and audit are available through the Provider proxy, e.g. risk dashboard, KPI, runtime positions, audit. Inspector events also stream to Studio in real time via the Provider WebSocket (/ws).
• Logs — Inspector process/container logs show startup, connection to the bus and Provider, event handling, stop placement, throttle actions, and Telegram notifications (if enabled).

Quick check after install

• Call GET /api/inspectors/<appKey>/health through the Provider (or directly on port 8008). You should get ok: true and connector info.
• In Inspector logs: no repeated connection errors to the event bus or Provider API.
• In Provider logs: Inspector heartbeats appear in the app registry.

Next steps

• Inspector risk policies — Policies and configuration options
• Barfinex architecture — How components connect
• Inspector API reference — REST endpoints