gRPC Interface

For partners supporting modern protocols, Velo offers a high-performance gRPC interface using Protocol Buffers.

Service Definition

syntax = "proto3";
package velo.v1;

service VeloGame {
  // Round lifecycle
  rpc GetCurrentRound (Empty) returns (RoundInfo);
  rpc StreamRounds (Empty) returns (stream RoundEvent);
  
  // Betting
  rpc PlaceBet (BetRequest) returns (BetResponse);
  rpc GetBetStatus (BetStatusRequest) returns (BetStatusResponse);
}

service WalletService {
  rpc Debit (BetRequest) returns (WalletResponse);
  rpc Credit (WinRequest) returns (WalletResponse);
  rpc GetBalance (BalanceRequest) returns (WalletResponse);
}

Messages

Round Messages

message RoundInfo {
  string round_id = 1;
  double entry_price = 2;
  int64 start_time = 3;
  int64 end_time = 4;
  RoundStatus status = 5;
  double current_price = 6;
  Odds current_odds = 7;
}

enum RoundStatus {
  WAITING = 0;
  ACTIVE = 1;
  LOCKED = 2;
  SETTLING = 3;
  SETTLED = 4;
}

message Odds {
  double up = 1;
  double down = 2;
  double prob_up = 3;
  double vig_pct = 4;
}

message RoundEvent {
  oneof event {
    RoundInfo round_start = 1;
    RoundInfo round_lock = 2;
    RoundSettlement round_settle = 3;
    PriceUpdate price_update = 4;
  }
}

message RoundSettlement {
  string round_id = 1;
  double entry_price = 2;
  double settlement_price = 3;
  string result = 4;  // "up" or "down"
  string chainlink_proof = 5;
}

message PriceUpdate {
  double price = 1;
  int64 timestamp = 2;
  Odds odds = 3;
}

Wallet Messages

message BetRequest {
  string transaction_id = 1;
  double amount = 2;
  string player_id = 3;
  string round_id = 4;
  string side = 5;  // "up" or "down"
  double odds = 6;
}

message WinRequest {
  string transaction_id = 1;
  string reference_bet_id = 2;
  double amount = 3;
  string player_id = 4;
  string round_id = 5;
}

message WalletResponse {
  string status = 1;
  double new_balance = 2;
  string transaction_id = 3;
}

message BalanceRequest {
  string player_id = 1;
  string currency = 2;
}

Connection

grpc://rgs.velo.games:443

Authentication via metadata:

x-operator-id: YOUR_OPERATOR_ID
x-api-key: YOUR_API_KEY

Why gRPC?

Feature	gRPC	REST
Payload size	40-70% smaller (binary)	Larger (JSON text)
Latency	Lower (HTTP/2, multiplexing)	Higher (HTTP/1.1)
Streaming	Native bidirectional	Requires WebSocket
Type safety	Protobuf schema enforced	Manual validation

TIP

Use gRPC for internal high-frequency paths (price streaming, bet placement). Use REST for standard operator integration where gRPC support may be limited.