What Voltnir actually does.

Two upstream transports. Voltnir reaches M7 over a WebSocket connection and an AMQP connection, each carrying a public and a private side. The WebSocket runs over mutual TLS and carries the market_data and private_data streams; AMQP carries a public broadcast channel and a per-session private channel. Voltnir supervises every connection with automatic reconnect, exponential backoff, and primary/secondary host failover.

Snapshot, then deltas. On connect, M7 sends one full order-book snapshot per subscribed (delivery_area, product) key, a SynchronizationComplete marker, then incremental deltas. Voltnir holds the complete book in memory and recomputes top of book (best bid and best ask, with the cumulative size resting at that price) on every change. Clients receive the same model and derive whatever depth they need by sorting.

Sequenced, or resynced. Every snapshot and delta carries a sequence number that must be exactly one past the last, per (delivery_area, product). A gap or duplicate is treated as corruption: Voltnir drops the stream, marks the feed unsynchronised, and reconnects for a fresh snapshot rather than serve a torn book. Liveness is tracked by heartbeat (a missed-pong window), not by delta arrival, so a genuinely quiet market is never mistaken for a dead feed.

Contracts. A contract is one delivery period of a product in a delivery area, identified by (delivery_area, product, delivery_start) and addressable by its M7 contract id. Delivery areas are EIC codes; duration is carried verbatim as decimal hours (0.25, 0.5, 1.0). Voltnir stores only the delivery areas you configure. Once a contract's delivery end passes it is marked inactive and a delete is pushed to subscribers; an hour later it is tombstoned (its book cleared but its identity and trade history retained), so settled-contract P&L still resolves.

The public trade tape. Executed public prints are deduplicated by trade id and held in a rolling in-memory window of about twelve hours; on connect Voltnir backfills the last six hours so a fresh start is not blind. Each print carries price, quantity, execution time, the buy and sell delivery areas, a self-trade flag, and a state: ACTI is the active default state, while the recall and cancellation states (CNCL, RGRA, and related) mark a print the exchange has undone.

Cross-border capacity. The hub-to-hub feed is the XBID available-transfer-capacity (ATC) matrix between delivery areas: how many megawatts can still flow each way across each border. Capacity is passed through in M7's units (megawatts, and it can be negative), enriched with each border's current best bid and ask so the cross-zone spread reads in one feed, and resynced in full whenever its heartbeat drops. It is an opt-in feature; when disabled the matrix is simply empty.

Authenticated, but unpermissioned. Reading market data needs a valid session and nothing more: no specific permission gates the book, the tape, or the capacity matrix on any transport, and none of it is exposed unauthenticated.

Capturing the feed. Market-data capture is off by default and configured under market_data as two independent streams: the public trade tape (public_trades) and the raw order-book frames (order_book, snapshots and deltas alike). Each opts in through its own persist setting, postgresql or parquet. A postgresql tape is written into and queried from the main audit database, which must itself be PostgreSQL or the gateway refuses to start; parquet writes export-only rotating files and works on any audit backend, SQLite included. Order-book capture is never queryable through the API; it is replay and backtest material only, written either to its own (or the audit database's inherited) PostgreSQL connection in daily partitions or to rotating Parquet files. Retention is per stream: the tape keeps one week by default, order-book capture keeps everything by default, and pruning only ever drops whole daily partitions or whole files, never row by row. Capture is fire-and-forget over a bounded channel: under overload it drops rows and logs rather than ever stall the live feed.

Feed health is a trading gate. The order-book feed's state (connected, synchronised, sequence-healthy, last-pong age) together with the measured per-delta processing time and end-to-end latency are exposed as rolling averages on GET /api/v1/state. The numbers are observed, not asserted. A new order is rejected with 503 when the feed is not green (§03), so an order is never sent against a stale or torn book.

Observing changes. An order's revision increments on every state change; fills and cancellations surface as it reaches a terminal state. A client reads the current state three ways: a one-shot query of a single order or the list, the always-on WebSocket orders stream, or the gRPC WatchOrders server-stream, which emits on add, change, and terminal state. The states are PENDING (sent to M7 but not yet rested by an order execution report), ACTIVE (resting and matchable), HIBERNATED (resting but not matching, such as a good-till-cancel order outside session hours), INACTIVE (fully filled or cancelled), and REJECTED. PENDING is a Voltnir-local state, not an M7 one: the order has been accepted by the gateway and published, and M7 may already have acknowledged receipt of the message, but the order stays PENDING until the execution report puts it on the book or a refusal rejects it.

Member isolation, on reads and on writes. By default a caller is confined to the virtual members assigned to it, and the confinement governs both seeing orders and acting on them. A read returns only orders tagged with an assigned member; untagged house-account orders are withheld. A modify or cancel is permitted only when the caller is assigned to the order's own member, with BypassMemberCheck acting across every member and TradeGlobal required for an untagged house order. The write check reads the order's existing member, never a value the caller supplies, so an order cannot be hijacked or re-tagged onto another desk. It is the same authorization that gates order placement, enforced again at every mutation.

Reading is not acting. ReadOrders grants visibility and nothing more: a read-only or compliance account can be given the firm-wide book, every member plus the house account, with no ability to place, modify, or cancel anything in it. The view grant and the act grant are independent and separately auditable, so oversight never implies authority.

A denied action is indistinguishable from a missing one. A modify or cancel the caller is not authorized for returns the same 404 not-found as a genuinely unknown id, never a 403. The mutation surface is therefore not an existence oracle: a desk cannot probe for, or enumerate, orders it may not act on. On the read path a cross-member filter is refused (REST 403, gRPC PermissionDenied, WS PermissionDenied), and the default scope is fail-closed: a session sees no orders until its scope is resolved.

Modifying. A modify targets a live order by id. A price or quantity change can grow exposure, so it re-runs the risk gates under the same position_check_lock as a new order: the two-sided position limit, the per-member limit, and the cash limit, each evaluated against the change in exposure, then the kill-switch and health gate. It runs neither the self-trade nor the idempotency check. A pure activate or deactivate leaves the net position unchanged and skips the risk gates. A second modify of the same order while the first is unconfirmed is refused with 409. The call returns 202 Accepted, and the new revision is confirmed asynchronously on the order stream.

Cancelling. A cancel only reduces exposure, so it runs no limit checks and is exempt from the kill-switch: a resting order can be pulled even while trading is halted. It confirms the order is live and not already mid-modify, refusing with 409 otherwise, then returns 202 Accepted; the order moves to INACTIVE once M7 confirms. Cancel-all respects the same isolation: a caller authorized across the whole account (BypassMemberCheck and TradeGlobal) gets the atomic exchange-side bulk cancel, while a member-scoped caller cancels only the orders it may act on, one per order, leaving other desks' and the house's orders untouched.

Attributable. Every placement, modify, and cancel is checked against the caller's permissions and member assignment at the gateway boundary and recorded with the acting user and virtual member in the audit trail (§09), queryable by user, member, and time.

Net versus exposure. Net position is your signed, executed-trade volume on a contract: the megawatts you are actually carrying, and the basis for realized P&L. Only trades in M7's active (ACTI) state count, so a cancelled trade backs out. Exposure adds every resting order, including an iceberg's hidden quantity, as a two-sided (max_short, max_long) pair, the worst case each way if everything resting fills. The position-limit check reads exposure, not net, so a limit is never breached by a fill you could already see coming.

Two-sided, with a carve-out. Each side is bounded independently against the configured limit. An order is refused only when it pushes the bound on the side it grows past the limit and makes it worse; an order that only reduces an over-limit side always passes. A limit of 0 therefore means reductions only, a hard freeze you can still trade out of.

Scoped. Every quantity is tracked per delivery-area/contract, per virtual member, and for the global house account. A member-tagged order must clear both its member's max_position and the account-wide limit.

Cash exposure, in money. Alongside megawatts, monetary exposure is bounded: executed trades back to the 16:00-UTC working-day boundary plus open orders, against a configured cash limit. EUR and GBP are separate pools with no FX between them, so each order is checked only against its own currency; GBP follows ECC's reservation methodology, and a money-making sell floors at zero. A member's cash limit is capped at the global one.

Operator-set, live. The position limit, the cash limit, the self-trade policy, and the trading kill-switch are all set by the operator and switchable at runtime over REST, gRPC, and WS, with no restart. They live in the gateway's profile store rather than static config, so a desk can tighten risk mid-session.

Realized: weighted-average cost. Your trades are replayed in execution order through a running position and a weighted-average open price. A trade on the same side as the position adds to that average; a trade on the opposite side closes against it and books closed × (close_price - avg_open_price), signed by whether you were long or short. A partial close leaves the average unchanged on the remainder; a larger opposite trade flips the position and re-opens the residual at the new price. Only trades in M7's active (ACTI) state count. Every trade is an execution; ACTI is its default state, and it drops out of P&L only if M7 cancels or recalls it (CNCL, RGRA, and the related recall and cancellation states). Open and pending orders never contribute, since an order is not an execution.

Unrealized: marked to the book. The open position is marked at the contract's reference price: the mid of the best bid and ask when both sides of the book hold resting quantity, otherwise the last traded price, otherwise nothing (and unrealized is then zero). Every row reports which of the three produced its mark, so an unmarked position is explained rather than silent. Liveness is read from resting quantity on each side, not the price sign, because power contracts clear at zero and at negative prices and those marks are valid.

Scopes and membership. Every figure is produced at four scopes: per contract, per (area, product), per virtual member per contract, and per (member, product). A member's position and realized P&L are computed from only that member's leg of each trade, independent of any other member on the same contract; an untagged trade rolls into the house account but into no member. Access is least-visibility by default: a caller sees only the members assigned to them, and the firm-wide per-contract and per-product books (which aggregate every member plus the house account) are withheld. The read_pnl permission (or bypass_member_check) returns the firm-wide snapshot. A v_member_short_id filter narrows to one member and is refused (REST 403, gRPC PermissionDenied, WS Forbidden) unless the caller is assigned to it or holds broad read; the same scope applies to the always-on P&L stream.

What counts, and the units. P&L counts filled trades only, so the displayed net position is trades-only and agrees with it; the position-limit check in §05 is the one place open orders are counted. On the wire, money is in q8 units (euro × 100,000, so divide by 100,000 for euro), price is €/MWh × 100, and position is MW × 1000. After a contract delists, realized P&L is preserved (the trades remain the source of truth) and unrealized drops to zero.

Shared implementation. Each unary operation runs one code path regardless of transport, so fields, units, permissions, and error semantics do not diverge between REST, WebSocket, and gRPC. The three surfaces are asserted against each other at build time so they stay in step.

Versioning. REST is served under /api/v1; the WebSocket handshake accepts /ws/v1 (with / and /v1 as transition aliases, unknown versions rejected at upgrade); the gRPC service is voltnir.api.v1. The protocol version is echoed in the WebSocket config payload. Incompatible changes are published under a new version path; v1 is not mutated in place.

Transports. REST: JSON request/response on port 3000, usable from curl. WebSocket: port 9001, authenticate with {action:'auth', token} after connect, then issue subscriptions and commands on the same socket; stream frames are zstd-compressed binary, command responses are plain-text {type:'response', req_id, op, ok, result|error}. gRPC: service voltnir.api.v1 over HTTP/2 on port 3443, with an in-tree Python SDK generated from the service .proto.

Streaming. On WebSocket, the account streams (orders, trades, messages, status, P&L) are active once authenticated; contracts stream per delivery-area and product; public trades, the trade tape, and the hub-to-hub matrix are opt-in subscriptions. gRPC exposes the same data as server-streaming Watch* RPCs. There is no REST streaming surface. Market-data streams are covered in §02.

Encoding. Prices, quantities, and limits cross the wire as fixed-point integers: price in cents, quantity in thousandths of a MW. There are no floats in the API. API keys are SHA-256 hashed at rest and returned once at creation; the raw key is not stored and cannot be recovered.

A user with CreateOrder but not DeleteOrder can place orders and not cancel them: not their own, not anyone's. Trading entitlements (CreateOrder / ModifyOrder / DeleteOrder) are separate from operational ones (ToggleTrading, SetPositionLimit, RestartSystem), from read entitlements (ReadAudit for the audit log, ReadPnl for the firm-wide P&L), and from administrative ones (ManageUsers, ManageMembers). BypassMemberCheck is the deliberate exception that lets a privileged user act without virtual-member binding, and since it already lifts member restriction it also confers the firm-wide P&L read.

Attribution travels with every action: which user, which virtual member, which EPEX user_id, recovered even on the exchange acknowledgement because the member tag rides in the M7 free-text field.