gRPC API

The only public gRPC surface documented here is PositionsSimulatorService, served by pks-bff on 8443 with TLS. Package: bo.position_sim.v1.

Canonical protobuf sources in bo-canonical (paths relative to the MAVR repo root):

• back-office/crates/bo-canonical/proto/bo_canonical/v1/pks_service.proto — RPCs and request/response messages
• back-office/crates/bo-canonical/proto/bo_canonical/v1/position.proto — PositionUpdated, PositionValuated, PositionViewPatch
• back-office/crates/bo-canonical/proto/bo_canonical/v1/instrument_static.proto — InstrumentStaticRecord, InstrumentStaticUpdate

For field-level tables and narrative aligned with these protos, see docs/pks/api-reference.md (section “gRPC API — PositionsSimulatorService”).

Service definition

service PositionsSimulatorService {
  rpc StreamPositions(StreamPositionsRequest)
      returns (stream PositionViewPatch);

  rpc GetPosition(GetPositionRequest)
      returns (PositionViewResponse);

  rpc GetPositionHistory(GetPositionHistoryRequest)
      returns (stream PositionViewPatch);

  rpc GetInstrumentStatic(GetInstrumentStaticRequest)
      returns (InstrumentStaticRecord);

  rpc BatchGetInstrumentStatic(BatchInstrumentStaticRequest)
      returns (stream InstrumentStaticRecord);

  rpc WatchInstrumentUpdates(WatchInstrumentUpdatesRequest)
      returns (stream InstrumentStaticUpdate);
}

RPC summary

RPC	Kind	Purpose
StreamPositions	server stream	Live position patches for optional book_id / instrument_id filters.
GetPosition	unary	Single position by position_key; returns one PositionViewPatch.
GetPositionHistory	server stream	Historical PositionViewPatch sequence for a book (optional snapshot kind / since_ns).
GetInstrumentStatic	unary	One InstrumentStaticRecord by instrument_id.
BatchGetInstrumentStatic	server stream	Stream of InstrumentStaticRecord — correlate by instrument_id; order not guaranteed.
WatchInstrumentUpdates	server stream	Continuous InstrumentStaticUpdate (record, reason).

Request and unary messages (pks_service.proto)

message GetPositionRequest {
  string position_key = 1;
}

message GetPositionHistoryRequest {
  string book_id               = 1;
  optional string snapshot_kind = 2;
  optional int64 since_ns      = 3;
}

message PositionViewResponse {
  PositionViewPatch view = 1;
}

message StreamPositionsRequest {
  optional string book_id       = 1;
  optional string instrument_id = 2;
}

message GetInstrumentStaticRequest {
  string instrument_id = 1;
}

message BatchInstrumentStaticRequest {
  repeated string instrument_ids = 1;
}

message WatchInstrumentUpdatesRequest {
}

PositionViewPatch, PositionUpdated, and PositionValuated live in position.proto; InstrumentStaticRecord and InstrumentStaticUpdate live in instrument_static.proto.

PositionViewPatch and is_full_snapshot

From position.proto:

message PositionViewPatch {
  string position_key = 1;
  bool is_full_snapshot = 2;

  optional PositionUpdated   core_partial      = 3;
  optional PositionValuated  valuation_partial = 4;

  int64 core_updated_at_ns       = 5;
  int64 valuation_updated_at_ns  = 6;
  int64 valuation_staleness_ms   = 7;
}

Semantics:

• is_full_snapshot = true — treat core_partial / valuation_partial as a full-row replace for this position_key (initial snapshots use this).
• is_full_snapshot = false — merge patches into the existing row: unset optional fields remain unchanged in the client’s merged view.

Timestamps core_updated_at_ns, valuation_updated_at_ns, and valuation_staleness_ms accompany ordering / staleness hints for valuation relative to core.

Instrument static stream

InstrumentStaticUpdate carries InstrumentStaticRecord record and a string reason (human-readable change cause, e.g. corrections or new listings).

Transport

Connect with TLS to 8443. Credential mechanics depend on how pks-bff is deployed in your environment; this page documents only the public protobuf contract.

---