Protobuf Schema & Code Generation

syntax = "proto3";

package ondo.gm.backend.v1;

option go_package = "github.com/ondoprotocol/gm/pkg/proto/ondo/gm/backend/v1;backendv1";

// This file is the public, client-facing subset of the Ondo Global Markets
// backend gRPC API.
//
// The package and message definitions here are kept wire-compatible with the
// server. Generate clients from this file with `buf generate` or `protoc`.
//
// Request/response access to pricing, quotes, attestations, and token
// metadata is served over the REST API; see the OpenAPI specification at
// https://docs.ondo.finance/openapi.json.

// BackendService exposes the real-time streaming surface of the Ondo Global
// Markets API. All requests must include an API key in the `x-api-key`
// metadata header.
service BackendService {
  // HealthCheck returns the service status. Does not require authentication.
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);

  // StreamPriceUpdates streams real-time price updates for the requested
  // assets. Clients subscribe to one or more symbols and receive price
  // updates as they occur. Updates are batched into each response message.
  rpc StreamPriceUpdates(StreamPriceUpdatesRequest) returns (stream StreamPriceUpdatesResponse);

  // StreamOHLC streams real-time OHLC (open/high/low/close) updates, bucketed
  // by minute and updated per tick. Updates are batched into each response
  // message.
  rpc StreamOHLC(StreamOHLCRequest) returns (stream StreamOHLCResponse);
}

// HealthCheckRequest is the request message for the HealthCheck RPC.
message HealthCheckRequest {}

// HealthCheckResponse is the response message for the HealthCheck RPC.
message HealthCheckResponse {
  string status = 1;
}

// StreamPriceUpdatesRequest subscribes to price updates for a set of assets.
message StreamPriceUpdatesRequest {
  // List of asset symbols to subscribe to. If empty, updates for all assets
  // are streamed.
  repeated string symbols = 1;
}

// PriceUpdate is a single price update streamed to clients.
message PriceUpdate {
  // Underlying stock ticker.
  string ticker = 1;
  // Ondo GM asset symbol.
  string symbol = 2;
  // Underlying stock price.
  string stock_price = 3;
  // Token price.
  string token_price = 4;
  // Unix timestamp of the price update, in nanoseconds.
  uint64 timestamp = 5;
}

// StreamPriceUpdatesResponse batches one or more price updates into a single
// stream message.
message StreamPriceUpdatesResponse {
  repeated PriceUpdate updates = 1;
}

// StreamOHLCRequest subscribes to OHLC updates for a set of assets.
message StreamOHLCRequest {
  // List of asset symbols to subscribe to. If empty, updates for all assets
  // are streamed.
  repeated string symbols = 1;
}

// OHLCUpdate is one partial or closed minute OHLC update for a single symbol.
message OHLCUpdate {
  message PrimaryMarket {
    string symbol = 1;
    string open = 2;
    string high = 3;
    string low = 4;
    string close = 5;
  }
  message UnderlyingMarket {
    string ticker = 1;
    string open = 2;
    string high = 3;
    string low = 4;
    string close = 5;
  }
  PrimaryMarket primary_market = 1;
  UnderlyingMarket underlying_market = 2;
  // is_closed marks the final emission for the bucket (the minute boundary
  // crossed). Subsequent updates with a higher timestamp belong to the next
  // bucket.
  bool is_closed = 3;
  // timestamp is the bucket start (minute floor) in nanoseconds since epoch.
  // Stable across all partials and the final closed update for a given bucket.
  uint64 timestamp = 4;
}

// StreamOHLCResponse batches one or more OHLC updates into a single stream
// message so subscribers to many assets receive one wire frame per drain
// window rather than one frame per candle.
message StreamOHLCResponse {
  repeated OHLCUpdate updates = 1;
}