Skip to main content

gRPC API

The Prediction Market API exposes a gRPC interface for high-performance, low-latency integration. The gRPC API provides the same functionality as the REST API using Protocol Buffers.

Default Address: {host}:50055 Package: prediction Service: PredictionService

Proto Definition​

The full .proto file is available at src/proto/prediction.proto in the source repository. Below is a summary of all available RPCs.

Market Operations​

CreateMarket​

rpc CreateMarket(CreateMarketRequest) returns (MarketResponse);
FieldTypeDescription
operator_idstringYour operator ID
category_idstringCategory UUID (optional)
titlestringMarket title
descriptionstringMarket description
image_urlstringImage URL
currencystringCurrency code
trading_starts_atint64Unix timestamp (ms)
trading_ends_atint64Unix timestamp (ms)
outcomesMarketOutcomeInput[]Outcome definitions

GetMarket​

rpc GetMarket(GetMarketRequest) returns (MarketResponse);
FieldTypeDescription
idstringMarket UUID
operator_idstringOptional — validates ownership if provided

ListMarkets​

rpc ListMarkets(ListMarketsRequest) returns (ListMarketsResponse);
FieldTypeDescription
operator_idstringFilter by operator
category_idstringFilter by category
statusstring[]Filter by statuses
searchstringSearch title
cursorstringPagination cursor
limitint32Page size

UpdateMarket​

rpc UpdateMarket(UpdateMarketRequest) returns (MarketResponse);

Market Lifecycle​

rpc OpenMarket(MarketActionRequest) returns (MarketResponse);
rpc SuspendMarket(SuspendMarketRequest) returns (MarketResponse);
rpc ResumeMarket(MarketActionRequest) returns (MarketResponse);
rpc CloseMarket(MarketActionRequest) returns (MarketResponse);
rpc CancelMarket(CancelMarketRequest) returns (MarketResponse);
rpc ResolveMarket(ResolveMarketRequest) returns (MarketResponse);

Category Operations​

CreateCategory​

rpc CreateCategory(CreateCategoryRequest) returns (CategoryResponse);

ListCategories​

rpc ListCategories(ListCategoriesRequest) returns (ListCategoriesResponse);

Trading Operations​

PlaceOrder​

rpc PlaceOrder(PlaceOrderRequest) returns (OrderResultResponse);
FieldTypeDescription
operator_idstringYour operator ID
player_idstringPlayer identifier
market_idstringMarket UUID
outcome_idstringOutcome UUID
sidestringBUY or SELL
typestringMARKET or LIMIT
sharesdoubleNumber of shares
pricedoubleLimit price (required for LIMIT)
transaction_idstringOperator reference key (optional)
expires_atint64Unix timestamp (ms, optional)

Response: OrderResultResponse

FieldTypeDescription
successboolWhether the order was accepted
orderOrderThe order details
tradesTrade[]Executed trades
statusstringOrder status
filled_sharesstringShares filled
avg_fill_pricestringAverage execution price
remaining_sharesstringShares still in the book
error_codestringError code if failed
error_messagestringError details if failed

CancelOrder​

rpc CancelOrder(CancelOrderRequest) returns (OrderResponse);
FieldTypeDescription
operator_idstringYour operator ID
order_idstringOrder UUID

GetOrder​

rpc GetOrder(GetOrderRequest) returns (OrderResponse);

ListOrders​

rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
FieldTypeDescription
operator_idstringYour operator ID
player_idstringFilter by player (optional)
market_idstringFilter by market
outcome_idstringFilter by outcome
sidestringFilter by side
typestringFilter by type
statusstring[]Filter by statuses
cursorstringPagination cursor
limitint32Page size

Position & Trade Operations​

GetPositions​

rpc GetPositions(GetPositionsRequest) returns (GetPositionsResponse);
FieldTypeDescription
operator_idstringYour operator ID
market_idstringFilter by market (optional)
player_idstringFilter by player (optional)

GetTrades​

rpc GetTrades(GetTradesRequest) returns (GetTradesResponse);
FieldTypeDescription
operator_idstringYour operator ID
market_idstringFilter by market
outcome_idstringFilter by outcome
cursorstringPagination cursor
limitint32Page size

Market Data​

GetOrderBook​

rpc GetOrderBook(GetOrderBookRequest) returns (OrderBookResponse);
FieldTypeDescription
market_idstringMarket UUID
outcome_idstringOutcome UUID
depthint32Number of price levels

GetMarketPrices​

rpc GetMarketPrices(GetMarketPricesRequest) returns (MarketPricesResponse);

Settlement Operations​

SettleMarket​

rpc SettleMarket(SettleMarketRequest) returns (SettleMarketResponse);

GetSettlementStatus​

rpc GetSettlementStatus(GetSettlementStatusRequest) returns (SettlementStatusResponse);

RetrySettlements​

rpc RetrySettlements(RetrySettlementsRequest) returns (SettleMarketResponse);

GetOperatorSettlements​

rpc GetOperatorSettlements(GetOperatorSettlementsRequest) returns (GetOperatorSettlementsResponse);
FieldTypeDescription
operator_idstringYour operator ID
market_idstringFilter by market (optional)
player_idstringFilter by player (optional)

Health Check​

rpc HealthCheck(Empty) returns (HealthResponse);

Response:

FieldTypeDescription
healthyboolService health status
versionstringService version
timestampint64Unix timestamp

Message Types​

Order​

message Order {
  string id = 1;
  string market_id = 2;
  string outcome_id = 3;
  string operator_id = 4;
  string player_id = 5;
  string side = 6;
  string type = 7;
  string shares = 8;
  string price = 9;
  string filled_shares = 10;
  string avg_fill_price = 11;
  string remaining_shares = 12;
  string status = 13;
  string transaction_id = 14;
  int64 expires_at = 15;
  int64 created_at = 16;
  int64 updated_at = 17;
}

Trade​

message Trade {
  string id = 1;
  string market_id = 2;
  string outcome_id = 3;
  string buy_order_id = 4;
  string sell_order_id = 5;
  string buyer_operator_id = 6;
  string seller_operator_id = 7;
  string price = 8;
  string shares = 9;
  string buyer_fee = 10;
  string seller_fee = 11;
  int64 created_at = 12;
}

Position​

message Position {
  string id = 1;
  string market_id = 2;
  string outcome_id = 3;
  string operator_id = 4;
  string player_id = 5;
  string shares = 6;
  string avg_price = 7;
  string total_cost = 8;
  string realized_pnl = 9;
  int64 created_at = 10;
  int64 updated_at = 11;
}

Settlement​

message Settlement {
  string id = 1;
  string position_id = 2;
  string market_id = 3;
  string outcome_id = 4;
  string operator_id = 5;
  string player_id = 6;
  string shares = 7;
  string payout_per_share = 8;
  string total_payout = 9;
  string transaction_id = 10;
  string status = 11;
  string error_message = 12;
  int64 settled_at = 13;
  int64 created_at = 14;
  int64 updated_at = 15;
}

Error Handling​

gRPC errors are returned in the response message fields error_code and error_message. The success field indicates whether the operation succeeded. Error codes are the same as those documented in the Error Codes reference.