Full reference

Field definitions, proto messages, example updates, and comparisons for this stream live on the BBO Book dataset page. This page covers the method signature and client snippets.

Please note that this method is metered based on data consumption at 0.00165 MB = 10 API credits.

Parameters

coins

repeated string

List of symbols to subscribe to (e.g., 'BTC', 'ETH'). Empty means all coins

Returns

stream

stream<BboBookUpdate>

Stream of BboBookUpdate messages, one per coin whose best bid or ask changed

coin

string

Trading pair symbol

time

uint64

Block timestamp in milliseconds

block_number

uint64

Block number

bid

L2Level

Best bid level containing px (price), sz (total size), and n (order count). Absent if there is no resting bid

ask

L2Level

Best ask level containing px (price), sz (total size), and n (order count). Absent if there is no resting ask

Request

1
// StreamBboBook Example - Stream top-of-book best bid/ask changes via gRPC
2
package main
3

4
import (
5
	"context"
6
	"flag"
7
	"fmt"
8
	"io"
9
	"log"
10
	"math"
11
	"strings"
12
	"time"
13

14
	"google.golang.org/grpc"
15
	"google.golang.org/grpc/codes"
16
	"google.golang.org/grpc/credentials"
17
	"google.golang.org/grpc/metadata"
18
	"google.golang.org/grpc/status"
19

20
	pb "hyperliquid-orderbook-example/proto"
21
)
22

23
const (
24
	grpcEndpoint = "your-endpoint.hype-mainnet.quiknode.pro:10000"
25
	authToken    = "your-auth-token"
26
	maxRetries   = 10
27
	baseDelay    = 2 * time.Second
28
)
29

30
func streamBboBook(coins []string) error {
31
	fmt.Println(strings.Repeat("=", 60))
32
	fmt.Printf("Streaming BBO Book for %s\n", strings.Join(coins, ", "))
33
	fmt.Println("Auto-reconnect: true")
34
	fmt.Println(strings.Repeat("=", 60) + "\n")
35

36
	retryCount := 0
37

38
	for retryCount < maxRetries {
39
		creds := credentials.NewClientTLSFromCert(nil, "")
40
		conn, err := grpc.Dial(grpcEndpoint,
41
			grpc.WithTransportCredentials(creds),
42
			grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(100*1024*1024)))
43
		if err != nil {
44
			return fmt.Errorf("failed to connect: %w", err)
45
		}
46

47
		client := pb.NewOrderBookStreamingClient(conn)
48
		ctx := metadata.AppendToOutgoingContext(context.Background(), "x-token", authToken)
49

50
		request := &pb.BboBookRequest{
51
			Coins: coins,
52
		}
53

54
		if retryCount > 0 {
55
			fmt.Printf("\n🔄 Reconnecting (attempt %d/%d)...\n", retryCount+1, maxRetries)
56
		} else {
57
			fmt.Printf("Connecting to %s...\n", grpcEndpoint)
58
		}
59

60
		stream, err := client.StreamBboBook(ctx, request)
61
		if err != nil {
62
			conn.Close()
63
			return fmt.Errorf("failed to start stream: %w", err)
64
		}
65

66
		msgCount := 0
67
		shouldRetry := false
68

69
		for {
70
			update, err := stream.Recv()
71
			if err == io.EOF {
72
				break
73
			}
74
			if err != nil {
75
				st, ok := status.FromError(err)
76
				if ok && st.Code() == codes.DataLoss {
77
					fmt.Printf("\n⚠️  Server reinitialized: %s\n", st.Message())
78
					retryCount++
79
					if retryCount < maxRetries {
80
						delay := baseDelay * time.Duration(math.Pow(2, float64(retryCount-1)))
81
						fmt.Printf("⏳ Waiting %v before reconnecting...\n", delay)
82
						time.Sleep(delay)
83
						shouldRetry = true
84
						break
85
					} else {
86
						fmt.Printf("\n❌ Max retries (%d) reached. Giving up.\n", maxRetries)
87
						conn.Close()
88
						return nil
89
					}
90
				}
91
				conn.Close()
92
				return fmt.Errorf("stream error: %w", err)
93
			}
94

95
			msgCount++
96
			if msgCount == 1 {
97
				fmt.Println("✓ First BBO update received!\n")
98
				retryCount = 0 // Reset on success
99
			}
100

101
			// Display BBO update
102
			fmt.Println("\n" + strings.Repeat("─", 60))
103
			fmt.Printf("Block: %d | Time: %d | Coin: %s\n", update.BlockNumber, update.Time, update.Coin)
104
			fmt.Println(strings.Repeat("─", 60))
105

106
			// Display best ask
107
			if update.Ask != nil {
108
				fmt.Printf("  BEST ASK: %12s | %12s | (%d orders)\n", update.Ask.Px, update.Ask.Sz, update.Ask.N)
109
			} else {
110
				fmt.Println("  BEST ASK: (none)")
111
			}
112

113
			// Display best bid
114
			if update.Bid != nil {
115
				fmt.Printf("  BEST BID: %12s | %12s | (%d orders)\n", update.Bid.Px, update.Bid.Sz, update.Bid.N)
116
			} else {
117
				fmt.Println("  BEST BID: (none)")
118
			}
119

120
			// Display spread
121
			if update.Bid != nil && update.Ask != nil {
122
				fmt.Printf("  SPREAD:   (best bid: %s, best ask: %s)\n", update.Bid.Px, update.Ask.Px)
123
			}
124

125
			fmt.Printf("\n  Messages received: %d\n", msgCount)
126
		}
127

128
		conn.Close()
129

130
		if !shouldRetry {
131
			break
132
		}
133
	}
134

135
	return nil
136
}
137

138
func main() {
139
	coinsFlag := flag.String("coins", "BTC", "Comma-separated coin symbols to stream (e.g., BTC,ETH)")
140

141
	flag.Parse()
142

143
	coins := strings.Split(*coinsFlag, ",")
144

145
	fmt.Println("\n" + strings.Repeat("=", 60))
146
	fmt.Println("Hyperliquid StreamBboBook Example")
147
	fmt.Printf("Endpoint: %s\n", grpcEndpoint)
148
	fmt.Println(strings.Repeat("=", 60))
149

150
	if err := streamBboBook(coins); err != nil {
151
		log.Fatal(err)
152
	}
153
}
154

1
// StreamBboBook Example - Stream top-of-book best bid/ask changes via gRPC
2
package main
3

4
import (
5
	"context"
6
	"flag"
7
	"fmt"
8
	"io"
9
	"log"
10
	"math"
11
	"strings"
12
	"time"
13

14
	"google.golang.org/grpc"
15
	"google.golang.org/grpc/codes"
16
	"google.golang.org/grpc/credentials"
17
	"google.golang.org/grpc/metadata"
18
	"google.golang.org/grpc/status"
19

20
	pb "hyperliquid-orderbook-example/proto"
21
)
22

23
const (
24
	grpcEndpoint = "your-endpoint.hype-mainnet.quiknode.pro:10000"
25
	authToken    = "your-auth-token"
26
	maxRetries   = 10
27
	baseDelay    = 2 * time.Second
28
)
29

30
func streamBboBook(coins []string) error {
31
	fmt.Println(strings.Repeat("=", 60))
32
	fmt.Printf("Streaming BBO Book for %s\n", strings.Join(coins, ", "))
33
	fmt.Println("Auto-reconnect: true")
34
	fmt.Println(strings.Repeat("=", 60) + "\n")
35

36
	retryCount := 0
37

38
	for retryCount < maxRetries {
39
		creds := credentials.NewClientTLSFromCert(nil, "")
40
		conn, err := grpc.Dial(grpcEndpoint,
41
			grpc.WithTransportCredentials(creds),
42
			grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(100*1024*1024)))
43
		if err != nil {
44
			return fmt.Errorf("failed to connect: %w", err)
45
		}
46

47
		client := pb.NewOrderBookStreamingClient(conn)
48
		ctx := metadata.AppendToOutgoingContext(context.Background(), "x-token", authToken)
49

50
		request := &pb.BboBookRequest{
51
			Coins: coins,
52
		}
53

54
		if retryCount > 0 {
55
			fmt.Printf("\n🔄 Reconnecting (attempt %d/%d)...\n", retryCount+1, maxRetries)
56
		} else {
57
			fmt.Printf("Connecting to %s...\n", grpcEndpoint)
58
		}
59

60
		stream, err := client.StreamBboBook(ctx, request)
61
		if err != nil {
62
			conn.Close()
63
			return fmt.Errorf("failed to start stream: %w", err)
64
		}
65

66
		msgCount := 0
67
		shouldRetry := false
68

69
		for {
70
			update, err := stream.Recv()
71
			if err == io.EOF {
72
				break
73
			}
74
			if err != nil {
75
				st, ok := status.FromError(err)
76
				if ok && st.Code() == codes.DataLoss {
77
					fmt.Printf("\n⚠️  Server reinitialized: %s\n", st.Message())
78
					retryCount++
79
					if retryCount < maxRetries {
80
						delay := baseDelay * time.Duration(math.Pow(2, float64(retryCount-1)))
81
						fmt.Printf("⏳ Waiting %v before reconnecting...\n", delay)
82
						time.Sleep(delay)
83
						shouldRetry = true
84
						break
85
					} else {
86
						fmt.Printf("\n❌ Max retries (%d) reached. Giving up.\n", maxRetries)
87
						conn.Close()
88
						return nil
89
					}
90
				}
91
				conn.Close()
92
				return fmt.Errorf("stream error: %w", err)
93
			}
94

95
			msgCount++
96
			if msgCount == 1 {
97
				fmt.Println("✓ First BBO update received!\n")
98
				retryCount = 0 // Reset on success
99
			}
100

101
			// Display BBO update
102
			fmt.Println("\n" + strings.Repeat("─", 60))
103
			fmt.Printf("Block: %d | Time: %d | Coin: %s\n", update.BlockNumber, update.Time, update.Coin)
104
			fmt.Println(strings.Repeat("─", 60))
105

106
			// Display best ask
107
			if update.Ask != nil {
108
				fmt.Printf("  BEST ASK: %12s | %12s | (%d orders)\n", update.Ask.Px, update.Ask.Sz, update.Ask.N)
109
			} else {
110
				fmt.Println("  BEST ASK: (none)")
111
			}
112

113
			// Display best bid
114
			if update.Bid != nil {
115
				fmt.Printf("  BEST BID: %12s | %12s | (%d orders)\n", update.Bid.Px, update.Bid.Sz, update.Bid.N)
116
			} else {
117
				fmt.Println("  BEST BID: (none)")
118
			}
119

120
			// Display spread
121
			if update.Bid != nil && update.Ask != nil {
122
				fmt.Printf("  SPREAD:   (best bid: %s, best ask: %s)\n", update.Bid.Px, update.Ask.Px)
123
			}
124

125
			fmt.Printf("\n  Messages received: %d\n", msgCount)
126
		}
127

128
		conn.Close()
129

130
		if !shouldRetry {
131
			break
132
		}
133
	}
134

135
	return nil
136
}
137

138
func main() {
139
	coinsFlag := flag.String("coins", "BTC", "Comma-separated coin symbols to stream (e.g., BTC,ETH)")
140

141
	flag.Parse()
142

143
	coins := strings.Split(*coinsFlag, ",")
144

145
	fmt.Println("\n" + strings.Repeat("=", 60))
146
	fmt.Println("Hyperliquid StreamBboBook Example")
147
	fmt.Printf("Endpoint: %s\n", grpcEndpoint)
148
	fmt.Println(strings.Repeat("=", 60))
149

150
	if err := streamBboBook(coins); err != nil {
151
		log.Fatal(err)
152
	}
153
}
154

1
// StreamBboBook Example - Stream top-of-book best bid/ask changes via gRPC
2
const grpc = require('@grpc/grpc-js');
3
const protoLoader = require('@grpc/proto-loader');
4
const path = require('path');
5

6
const GRPC_ENDPOINT = 'your-endpoint.hype-mainnet.quiknode.pro:10000';
7
const AUTH_TOKEN = 'your-auth-token';
8
const PROTO_PATH = path.join(__dirname, 'proto', 'orderbook.proto');
9

10
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
11
  keepCase: true,
12
  longs: String,
13
  enums: String,
14
  defaults: true,
15
  oneofs: true
16
});
17
const proto = grpc.loadPackageDefinition(packageDefinition).hyperliquid;
18

19
function createClient() {
20
  return new proto.OrderBookStreaming(
21
    GRPC_ENDPOINT,
22
    grpc.credentials.createSsl(),
23
    { 'grpc.max_receive_message_length': 100 * 1024 * 1024 }
24
  );
25
}
26

27
// Stream best bid/offer updates
28
async function streamBboBook(coins, autoReconnect = true, retryCount = 0) {
29
  console.log('='.repeat(60));
30
  console.log(`Streaming BBO Book for ${coins.length > 0 ? coins.join(', ') : 'all coins'}`);
31
  console.log(`Auto-reconnect: ${autoReconnect}`);
32
  console.log('='.repeat(60) + '\n');
33

34
  const maxRetries = 10;
35
  const baseDelay = 2000;
36

37
  while (retryCount < maxRetries) {
38
    const client = createClient();
39
    const metadata = new grpc.Metadata();
40
    metadata.add('x-token', AUTH_TOKEN);
41

42
    const request = {
43
      coins: coins
44
    };
45

46
    try {
47
      if (retryCount > 0) {
48
        console.log(`\n🔄 Reconnecting (attempt ${retryCount + 1}/${maxRetries})...`);
49
      } else {
50
        console.log(`Connecting to ${GRPC_ENDPOINT}...`);
51
      }
52

53
      let msgCount = 0;
54
      const call = client.StreamBboBook(request, metadata);
55

56
      call.on('data', (update) => {
57
        msgCount++;
58

59
        if (msgCount === 1) {
60
          console.log('✓ First BBO update received!\n');
61
          retryCount = 0; // Reset on success
62
        }
63

64
        console.log('\n' + '─'.repeat(60));
65
        console.log(`Block: ${update.block_number} | Time: ${update.time} | Coin: ${update.coin}`);
66
        console.log('─'.repeat(60));
67

68
        // Display best ask
69
        if (update.ask) {
70
          console.log(`  BEST ASK: ${update.ask.px.padStart(12)} | ${update.ask.sz.padStart(12)} | (${update.ask.n} orders)`);
71
        } else {
72
          console.log('  BEST ASK: (none)');
73
        }
74

75
        // Display best bid
76
        if (update.bid) {
77
          console.log(`  BEST BID: ${update.bid.px.padStart(12)} | ${update.bid.sz.padStart(12)} | (${update.bid.n} orders)`);
78
        } else {
79
          console.log('  BEST BID: (none)');
80
        }
81

82
        // Display spread
83
        if (update.bid && update.ask) {
84
          const bestBid = parseFloat(update.bid.px);
85
          const bestAsk = parseFloat(update.ask.px);
86
          const spread = bestAsk - bestBid;
87
          const spreadBps = (spread / bestBid) * 10000;
88
          console.log(`  SPREAD:   ${spread.toFixed(2)} (${spreadBps.toFixed(2)} bps)`);
89
        }
90

91
        console.log(`\n  Messages received: ${msgCount}`);
92
      });
93

94
      call.on('error', (err) => {
95
        if (err.code === grpc.status.DATA_LOSS && autoReconnect) {
96
          console.log(`\n⚠️  Server reinitialized: ${err.message}`);
97
          retryCount++;
98
          if (retryCount < maxRetries) {
99
            const delay = baseDelay * Math.pow(2, retryCount - 1);
100
            console.log(`⏳ Waiting ${delay / 1000}s before reconnecting...`);
101
            setTimeout(() => streamBboBook(coins, autoReconnect, retryCount), delay);
102
          } else {
103
            console.log(`\n❌ Max retries (${maxRetries}) reached. Giving up.`);
104
          }
105
        } else {
106
          console.error('\ngRPC error:', err.code, '-', err.message);
107
        }
108
      });
109

110
      call.on('end', () => {
111
        console.log('\nStream ended');
112
      });
113

114
      // Wait for stream to complete
115
      await new Promise((resolve) => {
116
        call.on('end', resolve);
117
        call.on('error', resolve);
118
      });
119

120
      break; // Exit retry loop on success
121

122
    } catch (err) {
123
      console.error('Error:', err.message);
124
      break;
125
    }
126
  }
127
}
128

129
// Parse command line args
130
const args = process.argv.slice(2);
131
const coins = (args.find(a => a.startsWith('--coins='))?.split('=')[1] || 'BTC').split(',');
132

133
console.log('\n' + '='.repeat(60));
134
console.log('Hyperliquid StreamBboBook Example');
135
console.log(`Endpoint: ${GRPC_ENDPOINT}`);
136
console.log('='.repeat(60));
137

138
streamBboBook(coins);
139

1
// StreamBboBook Example - Stream top-of-book best bid/ask changes via gRPC
2
const grpc = require('@grpc/grpc-js');
3
const protoLoader = require('@grpc/proto-loader');
4
const path = require('path');
5

6
const GRPC_ENDPOINT = 'your-endpoint.hype-mainnet.quiknode.pro:10000';
7
const AUTH_TOKEN = 'your-auth-token';
8
const PROTO_PATH = path.join(__dirname, 'proto', 'orderbook.proto');
9

10
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
11
  keepCase: true,
12
  longs: String,
13
  enums: String,
14
  defaults: true,
15
  oneofs: true
16
});
17
const proto = grpc.loadPackageDefinition(packageDefinition).hyperliquid;
18

19
function createClient() {
20
  return new proto.OrderBookStreaming(
21
    GRPC_ENDPOINT,
22
    grpc.credentials.createSsl(),
23
    { 'grpc.max_receive_message_length': 100 * 1024 * 1024 }
24
  );
25
}
26

27
// Stream best bid/offer updates
28
async function streamBboBook(coins, autoReconnect = true, retryCount = 0) {
29
  console.log('='.repeat(60));
30
  console.log(`Streaming BBO Book for ${coins.length > 0 ? coins.join(', ') : 'all coins'}`);
31
  console.log(`Auto-reconnect: ${autoReconnect}`);
32
  console.log('='.repeat(60) + '\n');
33

34
  const maxRetries = 10;
35
  const baseDelay = 2000;
36

37
  while (retryCount < maxRetries) {
38
    const client = createClient();
39
    const metadata = new grpc.Metadata();
40
    metadata.add('x-token', AUTH_TOKEN);
41

42
    const request = {
43
      coins: coins
44
    };
45

46
    try {
47
      if (retryCount > 0) {
48
        console.log(`\n🔄 Reconnecting (attempt ${retryCount + 1}/${maxRetries})...`);
49
      } else {
50
        console.log(`Connecting to ${GRPC_ENDPOINT}...`);
51
      }
52

53
      let msgCount = 0;
54
      const call = client.StreamBboBook(request, metadata);
55

56
      call.on('data', (update) => {
57
        msgCount++;
58

59
        if (msgCount === 1) {
60
          console.log('✓ First BBO update received!\n');
61
          retryCount = 0; // Reset on success
62
        }
63

64
        console.log('\n' + '─'.repeat(60));
65
        console.log(`Block: ${update.block_number} | Time: ${update.time} | Coin: ${update.coin}`);
66
        console.log('─'.repeat(60));
67

68
        // Display best ask
69
        if (update.ask) {
70
          console.log(`  BEST ASK: ${update.ask.px.padStart(12)} | ${update.ask.sz.padStart(12)} | (${update.ask.n} orders)`);
71
        } else {
72
          console.log('  BEST ASK: (none)');
73
        }
74

75
        // Display best bid
76
        if (update.bid) {
77
          console.log(`  BEST BID: ${update.bid.px.padStart(12)} | ${update.bid.sz.padStart(12)} | (${update.bid.n} orders)`);
78
        } else {
79
          console.log('  BEST BID: (none)');
80
        }
81

82
        // Display spread
83
        if (update.bid && update.ask) {
84
          const bestBid = parseFloat(update.bid.px);
85
          const bestAsk = parseFloat(update.ask.px);
86
          const spread = bestAsk - bestBid;
87
          const spreadBps = (spread / bestBid) * 10000;
88
          console.log(`  SPREAD:   ${spread.toFixed(2)} (${spreadBps.toFixed(2)} bps)`);
89
        }
90

91
        console.log(`\n  Messages received: ${msgCount}`);
92
      });
93

94
      call.on('error', (err) => {
95
        if (err.code === grpc.status.DATA_LOSS && autoReconnect) {
96
          console.log(`\n⚠️  Server reinitialized: ${err.message}`);
97
          retryCount++;
98
          if (retryCount < maxRetries) {
99
            const delay = baseDelay * Math.pow(2, retryCount - 1);
100
            console.log(`⏳ Waiting ${delay / 1000}s before reconnecting...`);
101
            setTimeout(() => streamBboBook(coins, autoReconnect, retryCount), delay);
102
          } else {
103
            console.log(`\n❌ Max retries (${maxRetries}) reached. Giving up.`);
104
          }
105
        } else {
106
          console.error('\ngRPC error:', err.code, '-', err.message);
107
        }
108
      });
109

110
      call.on('end', () => {
111
        console.log('\nStream ended');
112
      });
113

114
      // Wait for stream to complete
115
      await new Promise((resolve) => {
116
        call.on('end', resolve);
117
        call.on('error', resolve);
118
      });
119

120
      break; // Exit retry loop on success
121

122
    } catch (err) {
123
      console.error('Error:', err.message);
124
      break;
125
    }
126
  }
127
}
128

129
// Parse command line args
130
const args = process.argv.slice(2);
131
const coins = (args.find(a => a.startsWith('--coins='))?.split('=')[1] || 'BTC').split(',');
132

133
console.log('\n' + '='.repeat(60));
134
console.log('Hyperliquid StreamBboBook Example');
135
console.log(`Endpoint: ${GRPC_ENDPOINT}`);
136
console.log('='.repeat(60));
137

138
streamBboBook(coins);
139

1
#!/usr/bin/env python3
2
"""
3
StreamBboBook Example - Stream top-of-book best bid/ask changes via gRPC
4

5
Setup:
6
    pip install grpcio grpcio-tools protobuf zstandard
7
    python -m grpc_tools.protoc -I../../proto --python_out=. --grpc_python_out=. ../../proto/orderbook.proto
8

9
Usage:
10
    python stream_bbo_example.py --coins BTC,ETH
11
"""
12

13
import grpc
14
import sys
15
import time
16
import argparse
17

18
try:
19
    import orderbook_pb2 as pb
20
    import orderbook_pb2_grpc as pb_grpc
21
except ImportError:
22
    print("Error: Proto files not generated. Run:")
23
    print("  python -m grpc_tools.protoc -I../../proto --python_out=. --grpc_python_out=. ../../proto/orderbook.proto")
24
    sys.exit(1)
25

26
# Configuration
27
GRPC_ENDPOINT = "your-endpoint.hype-mainnet.quiknode.pro:10000"
28
AUTH_TOKEN = "your-auth-token"
29

30

31
def stream_bbo_book(coins: list, auto_reconnect: bool = True):
32
    """
33
    Stream best bid/offer (top-of-book) updates for one or more coins.
34

35
    Args:
36
        coins: Symbols to stream (e.g., ["BTC", "ETH"]). Empty list means all coins
37
        auto_reconnect: Auto-reconnect on DATA_LOSS errors (default True)
38
    """
39
    print(f"\n{'='*60}")
40
    print(f"Streaming BBO Book for {', '.join(coins) if coins else 'all coins'}")
41
    print(f"Auto-reconnect: {auto_reconnect}")
42
    print(f"{'='*60}\n")
43

44
    retry_count = 0
45
    max_retries = 10
46
    base_delay = 2
47

48
    while retry_count < max_retries:
49
        channel = grpc.secure_channel(
50
            GRPC_ENDPOINT,
51
            grpc.ssl_channel_credentials(),
52
            options=[
53
                ('grpc.max_receive_message_length', 100 * 1024 * 1024),
54
                ('grpc.keepalive_time_ms', 30000),
55
            ]
56
        )
57
        stub = pb_grpc.OrderBookStreamingStub(channel)
58

59
        # Build request
60
        request = pb.BboBookRequest(coins=coins)
61

62
        msg_count = 0
63

64
        try:
65
            if retry_count > 0:
66
                print(f"\n🔄 Reconnecting (attempt {retry_count + 1}/{max_retries})...")
67
            else:
68
                print(f"Connecting to {GRPC_ENDPOINT}...")
69

70
            for update in stub.StreamBboBook(request, metadata=[('x-token', AUTH_TOKEN)]):
71
                msg_count += 1
72

73
                if msg_count == 1:
74
                    print(f"✓ First BBO update received!\n")
75
                    retry_count = 0  # Reset retry count on successful connection
76

77
                # Display the BBO update
78
                print(f"\n{'─'*60}")
79
                print(f"Block: {update.block_number} | Time: {update.time} | Coin: {update.coin}")
80
                print(f"{'─'*60}")
81

82
                # Show best ask
83
                if update.HasField('ask'):
84
                    print(f"  BEST ASK: {update.ask.px:>12} | {update.ask.sz:>12} | ({update.ask.n} orders)")
85
                else:
86
                    print("  BEST ASK: (none)")
87

88
                # Show best bid
89
                if update.HasField('bid'):
90
                    print(f"  BEST BID: {update.bid.px:>12} | {update.bid.sz:>12} | ({update.bid.n} orders)")
91
                else:
92
                    print("  BEST BID: (none)")
93

94
                # Show spread
95
                if update.HasField('bid') and update.HasField('ask'):
96
                    best_bid = float(update.bid.px)
97
                    best_ask = float(update.ask.px)
98
                    spread = best_ask - best_bid
99
                    spread_bps = (spread / best_bid) * 10000 if best_bid > 0 else 0
100
                    print(f"  SPREAD:   {spread:.2f} ({spread_bps:.2f} bps)")
101

102
                print(f"\n  Messages received: {msg_count}")
103

104
        except grpc.RpcError as e:
105
            if e.code() == grpc.StatusCode.DATA_LOSS and auto_reconnect:
106
                print(f"\n⚠️  Server reinitialized: {e.details()}")
107
                retry_count += 1
108
                if retry_count < max_retries:
109
                    delay = base_delay * (2 ** (retry_count - 1))  # Exponential backoff
110
                    print(f"⏳ Waiting {delay}s before reconnecting...")
111
                    time.sleep(delay)
112
                    channel.close()
113
                    continue
114
                else:
115
                    print(f"\n❌ Max retries ({max_retries}) reached. Giving up.")
116
                    break
117
            else:
118
                print(f"\ngRPC error: {e.code()} - {e.details()}")
119
                break
120
        except KeyboardInterrupt:
121
            print("\nStopping BBO stream...")
122
            break
123
        finally:
124
            channel.close()
125

126
        # If we get here without error, break the retry loop
127
        break
128

129

130
def main():
131
    parser = argparse.ArgumentParser(description='Stream Hyperliquid best bid/offer data via gRPC')
132
    parser.add_argument('--coins', default='BTC', help='Comma-separated coin symbols to stream (e.g., BTC,ETH)')
133

134
    args = parser.parse_args()
135
    coins = [c.strip() for c in args.coins.split(',') if c.strip()]
136

137
    print(f"\n{'='*60}")
138
    print("Hyperliquid StreamBboBook Example")
139
    print(f"Endpoint: {GRPC_ENDPOINT}")
140
    print(f"{'='*60}")
141

142
    try:
143
        stream_bbo_book(coins)
144
    except Exception as e:
145
        print(f"\nError: {e}")
146
        import traceback
147
        traceback.print_exc()
148
        sys.exit(1)
149

150

151
if __name__ == "__main__":
152
    main()
153

1
#!/usr/bin/env python3
2
"""
3
StreamBboBook Example - Stream top-of-book best bid/ask changes via gRPC
4

5
Setup:
6
    pip install grpcio grpcio-tools protobuf zstandard
7
    python -m grpc_tools.protoc -I../../proto --python_out=. --grpc_python_out=. ../../proto/orderbook.proto
8

9
Usage:
10
    python stream_bbo_example.py --coins BTC,ETH
11
"""
12

13
import grpc
14
import sys
15
import time
16
import argparse
17

18
try:
19
    import orderbook_pb2 as pb
20
    import orderbook_pb2_grpc as pb_grpc
21
except ImportError:
22
    print("Error: Proto files not generated. Run:")
23
    print("  python -m grpc_tools.protoc -I../../proto --python_out=. --grpc_python_out=. ../../proto/orderbook.proto")
24
    sys.exit(1)
25

26
# Configuration
27
GRPC_ENDPOINT = "your-endpoint.hype-mainnet.quiknode.pro:10000"
28
AUTH_TOKEN = "your-auth-token"
29

30

31
def stream_bbo_book(coins: list, auto_reconnect: bool = True):
32
    """
33
    Stream best bid/offer (top-of-book) updates for one or more coins.
34

35
    Args:
36
        coins: Symbols to stream (e.g., ["BTC", "ETH"]). Empty list means all coins
37
        auto_reconnect: Auto-reconnect on DATA_LOSS errors (default True)
38
    """
39
    print(f"\n{'='*60}")
40
    print(f"Streaming BBO Book for {', '.join(coins) if coins else 'all coins'}")
41
    print(f"Auto-reconnect: {auto_reconnect}")
42
    print(f"{'='*60}\n")
43

44
    retry_count = 0
45
    max_retries = 10
46
    base_delay = 2
47

48
    while retry_count < max_retries:
49
        channel = grpc.secure_channel(
50
            GRPC_ENDPOINT,
51
            grpc.ssl_channel_credentials(),
52
            options=[
53
                ('grpc.max_receive_message_length', 100 * 1024 * 1024),
54
                ('grpc.keepalive_time_ms', 30000),
55
            ]
56
        )
57
        stub = pb_grpc.OrderBookStreamingStub(channel)
58

59
        # Build request
60
        request = pb.BboBookRequest(coins=coins)
61

62
        msg_count = 0
63

64
        try:
65
            if retry_count > 0:
66
                print(f"\n🔄 Reconnecting (attempt {retry_count + 1}/{max_retries})...")
67
            else:
68
                print(f"Connecting to {GRPC_ENDPOINT}...")
69

70
            for update in stub.StreamBboBook(request, metadata=[('x-token', AUTH_TOKEN)]):
71
                msg_count += 1
72

73
                if msg_count == 1:
74
                    print(f"✓ First BBO update received!\n")
75
                    retry_count = 0  # Reset retry count on successful connection
76

77
                # Display the BBO update
78
                print(f"\n{'─'*60}")
79
                print(f"Block: {update.block_number} | Time: {update.time} | Coin: {update.coin}")
80
                print(f"{'─'*60}")
81

82
                # Show best ask
83
                if update.HasField('ask'):
84
                    print(f"  BEST ASK: {update.ask.px:>12} | {update.ask.sz:>12} | ({update.ask.n} orders)")
85
                else:
86
                    print("  BEST ASK: (none)")
87

88
                # Show best bid
89
                if update.HasField('bid'):
90
                    print(f"  BEST BID: {update.bid.px:>12} | {update.bid.sz:>12} | ({update.bid.n} orders)")
91
                else:
92
                    print("  BEST BID: (none)")
93

94
                # Show spread
95
                if update.HasField('bid') and update.HasField('ask'):
96
                    best_bid = float(update.bid.px)
97
                    best_ask = float(update.ask.px)
98
                    spread = best_ask - best_bid
99
                    spread_bps = (spread / best_bid) * 10000 if best_bid > 0 else 0
100
                    print(f"  SPREAD:   {spread:.2f} ({spread_bps:.2f} bps)")
101

102
                print(f"\n  Messages received: {msg_count}")
103

104
        except grpc.RpcError as e:
105
            if e.code() == grpc.StatusCode.DATA_LOSS and auto_reconnect:
106
                print(f"\n⚠️  Server reinitialized: {e.details()}")
107
                retry_count += 1
108
                if retry_count < max_retries:
109
                    delay = base_delay * (2 ** (retry_count - 1))  # Exponential backoff
110
                    print(f"⏳ Waiting {delay}s before reconnecting...")
111
                    time.sleep(delay)
112
                    channel.close()
113
                    continue
114
                else:
115
                    print(f"\n❌ Max retries ({max_retries}) reached. Giving up.")
116
                    break
117
            else:
118
                print(f"\ngRPC error: {e.code()} - {e.details()}")
119
                break
120
        except KeyboardInterrupt:
121
            print("\nStopping BBO stream...")
122
            break
123
        finally:
124
            channel.close()
125

126
        # If we get here without error, break the retry loop
127
        break
128

129

130
def main():
131
    parser = argparse.ArgumentParser(description='Stream Hyperliquid best bid/offer data via gRPC')
132
    parser.add_argument('--coins', default='BTC', help='Comma-separated coin symbols to stream (e.g., BTC,ETH)')
133

134
    args = parser.parse_args()
135
    coins = [c.strip() for c in args.coins.split(',') if c.strip()]
136

137
    print(f"\n{'='*60}")
138
    print("Hyperliquid StreamBboBook Example")
139
    print(f"Endpoint: {GRPC_ENDPOINT}")
140
    print(f"{'='*60}")
141

142
    try:
143
        stream_bbo_book(coins)
144
    except Exception as e:
145
        print(f"\nError: {e}")
146
        import traceback
147
        traceback.print_exc()
148
        sys.exit(1)
149

150

151
if __name__ == "__main__":
152
    main()
153

Don't have an account yet?

Create your Quicknode endpoint in seconds and start building

Get started for free