Skip to content

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.

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 asyncio
import io
import os
import grpc
import polars as pl
from marketdata.v1 import service_pb2 as pb
from 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.

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.

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.

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.