Consume market data
The supplier exposes market_data.v1.MarketDataService on port 8080 by default.
Both RPCs are server streams and require x-api-key metadata. gRPC health checks
are unauthenticated. Set MARKET_DATA_API_KEY in the supplier’s environment.
Read dataframe snapshots
Section titled “Read dataframe snapshots”GetDataframe combines stocks and commodities into option and base frames.
Both payloads are Arrow IPC files, not JSON or protobuf rows. Use Polars
read_ipc to decode them. The response timestamp is the snapshot capture time.
import asyncioimport ioimport os
import grpcimport polars as plfrom marketdata.v1 import service_pb2 as pbfrom marketdata.v1 import service_pb2_grpc as stubs
async def main(): # Backend connection; use a secure_channel with TLS credentials at the proxy. async with grpc.aio.insecure_channel( "127.0.0.1:8080", options=[("grpc.max_receive_message_length", 64 * 1024 * 1024)], ) as connection: client = stubs.MarketDataServiceStub(connection) metadata = (("x-api-key", os.environ["MARKET_DATA_API_KEY"]),) async for snapshot in client.GetDataframe( pb.GetDataframeRequest(interval=1), metadata=metadata, timeout=60, ): options = pl.read_ipc(io.BytesIO(snapshot.option_data)) bases = pl.read_ipc(io.BytesIO(snapshot.base_data)) print(snapshot.timestamp, options.height, bases.height)
asyncio.run(main())Replace the backend address with your reachable endpoint. Compose does not publish 8080 on the host by default.
interval is in seconds; zero uses one second. The service emits an initial
snapshot, then periodically publishes while streaming is active. Outside active
streaming, it waits unless the initial-fill revision changes. Silence is not
evidence of an RPC failure or a fresh market.
Filter and select
Section titled “Filter and select”The request has independent option/base filter and select expression fields.
An empty byte string means no expression. Nonempty values contain serialized
Polars expressions, produced with expression.meta.serialize(). Keep clients on
the server’s pinned Polars 2.1.0 to match the expression format.
request = pb.GetDataframeRequest( option_filter_expression=(pl.col("buyIv") > 0).meta.serialize(), base_select_expression=pl.col(["isin", "lastPrice"]).meta.serialize(), interval=2,)Malformed expressions or invalid filters/selections return INVALID_ARGUMENT.
Selection changes the returned columns; the default schemas
describe unfiltered, unselected output. There is no market_type request field;
its old field number and name are reserved.
Receive book rows
Section titled “Receive book rows”Call GetBestLimits with catalogue ISINs and max_rows (zero defaults to one).
Rows are one-based and bounded by the configured dataframe depth and allocated
storage. The stream sends current rows first, then updates for the requested ISINs.
async for row in client.GetBestLimits( pb.GetBestLimitsRequest(isins=["YOUR_CATALOGUE_ISIN"], max_rows=5), metadata=metadata, timeout=60,): buy_count = row.buy_count if row.HasField("buy_count") else None sell_count = row.sell_count if row.HasField("sell_count") else None print(row.isin, row.row, row.buy_price, buy_count, sell_count)Order counts have explicit optional presence. An absent count is not a known zero. Prices and volumes are ordinary proto3 scalars and do not have that presence flag. The row timestamp describes the book row; do not replace it with your receive time.
Reconnect a closed stream with your desired ISINs to receive current rows again. The contract has no replay cursor or historical delta recovery.
Freshness and fake mode
Section titled “Freshness and fake mode”Snapshot capture time and book-row time answer different questions. A new snapshot can contain an old or missing quote. Inspect row timestamps and missing values when deciding whether a quote is usable.
MARKET_DATA_FAKE_ENABLED=true selects synthetic feeds using stored instrument
metadata. It bypasses brokers and market hours, preserves API authentication and
schemas, and disables daily collection, cache persistence and recording. It still
needs the configured database and catalogue.