Full reference

Field definitions, proto messages, example updates, and comparisons for this stream live on the L4 Order 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.0165 MB = 10 API credits.

Parameters

coin

string

Trading pair symbol (e.g., 'BTC', 'ETH')

Returns

stream

stream<L4BookUpdate>

Stream of L4BookUpdate messages containing either a snapshot or diff

snapshot

L4BookSnapshot

Initial full orderbook state with all active orders (sent once at connection start)

diff

L4BookDiff

Incremental block-level changes containing order statuses and book modifications (sent for each subsequent block)

Request

1
// StreamL4Book Example - Stream individual order data via gRPC
2
package main
3

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

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

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

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

31
func streamL4Orderbook(coin string, maxMessages int) error {
32
	fmt.Println(strings.Repeat("=", 60))
33
	fmt.Printf("Streaming L4 Orderbook for %s\n", coin)
34
	fmt.Println("Auto-reconnect: true")
35
	fmt.Println(strings.Repeat("=", 60) + "\n")
36

37
	retryCount := 0
38
	totalMsgCount := 0
39

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

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

52
		request := &pb.L4BookRequest{
53
			Coin: coin,
54
		}
55

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

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

68
		snapshotReceived := false
69
		shouldRetry := false
70

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

97
			totalMsgCount++
98

99
			if snapshot := update.GetSnapshot(); snapshot != nil {
100
				snapshotReceived = true
101
				retryCount = 0 // Reset on success
102

103
				fmt.Println("\n✓ L4 Snapshot Received!")
104
				fmt.Println(strings.Repeat("─", 60))
105
				fmt.Printf("Coin: %s\n", snapshot.Coin)
106
				fmt.Printf("Height: %d\n", snapshot.Height)
107
				fmt.Printf("Time: %d\n", snapshot.Time)
108
				fmt.Printf("Bids: %d orders\n", len(snapshot.Bids))
109
				fmt.Printf("Asks: %d orders\n", len(snapshot.Asks))
110
				fmt.Println(strings.Repeat("─", 60))
111

112
				// Sample bids
113
				if len(snapshot.Bids) > 0 {
114
					fmt.Println("\nSample Bids (first 5):")
115
					bidCount := len(snapshot.Bids)
116
					if bidCount > 5 {
117
						bidCount = 5
118
					}
119
					for i := 0; i < bidCount; i++ {
120
						order := snapshot.Bids[i]
121
						userShort := order.User
122
						if len(userShort) > 10 {
123
							userShort = userShort[:10] + "..."
124
						}
125
						fmt.Printf("  OID: %d | Price: %s | Size: %s | User: %s\n",
126
							order.Oid, order.LimitPx, order.Sz, userShort)
127
					}
128
				}
129

130
				// Sample asks
131
				if len(snapshot.Asks) > 0 {
132
					fmt.Println("\nSample Asks (first 5):")
133
					askCount := len(snapshot.Asks)
134
					if askCount > 5 {
135
						askCount = 5
136
					}
137
					for i := 0; i < askCount; i++ {
138
						order := snapshot.Asks[i]
139
						userShort := order.User
140
						if len(userShort) > 10 {
141
							userShort = userShort[:10] + "..."
142
						}
143
						fmt.Printf("  OID: %d | Price: %s | Size: %s | User: %s\n",
144
							order.Oid, order.LimitPx, order.Sz, userShort)
145
					}
146
				}
147

148
			} else if diff := update.GetDiff(); diff != nil {
149
				if !snapshotReceived {
150
					fmt.Println("\n⚠ Received diff before snapshot")
151
				}
152

153
				var diffData map[string]interface{}
154
				if err := json.Unmarshal([]byte(diff.Data), &diffData); err == nil {
155
					orderStatuses := []interface{}{}
156
					bookDiffs := []interface{}{}
157

158
					if os, ok := diffData["order_statuses"].([]interface{}); ok {
159
						orderStatuses = os
160
					}
161
					if bd, ok := diffData["book_diffs"].([]interface{}); ok {
162
						bookDiffs = bd
163
					}
164

165
					fmt.Printf("\n[Block %d] L4 Diff:\n", diff.Height)
166
					fmt.Printf("  Time: %d\n", diff.Time)
167
					fmt.Printf("  Order Statuses: %d\n", len(orderStatuses))
168
					fmt.Printf("  Book Diffs: %d\n", len(bookDiffs))
169

170
					if len(bookDiffs) > 0 && len(bookDiffs) <= 5 {
171
						pretty, _ := json.MarshalIndent(bookDiffs, "  ", "  ")
172
						fmt.Printf("  Diffs: %s\n", pretty)
173
					}
174
				}
175
			}
176

177
			if maxMessages > 0 && totalMsgCount >= maxMessages {
178
				fmt.Printf("\nReached max messages (%d), stopping...\n", maxMessages)
179
				conn.Close()
180
				return nil
181
			}
182
		}
183

184
		conn.Close()
185

186
		if !shouldRetry {
187
			break
188
		}
189
	}
190

191
	return nil
192
}
193

194
func main() {
195
	coin := flag.String("coin", "BTC", "Coin symbol to stream")
196
	maxMessages := flag.Int("max-messages", 0, "Maximum messages (0 = unlimited)")
197

198
	flag.Parse()
199

200
	fmt.Println("\n" + strings.Repeat("=", 60))
201
	fmt.Println("Hyperliquid StreamL4Book Example")
202
	fmt.Printf("Endpoint: %s\n", grpcEndpoint)
203
	fmt.Println(strings.Repeat("=", 60))
204

205
	if err := streamL4Orderbook(*coin, *maxMessages); err != nil {
206
		log.Fatal(err)
207
	}
208
}
209

1
// StreamL4Book Example - Stream individual order data via gRPC
2
package main
3

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

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

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

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

31
func streamL4Orderbook(coin string, maxMessages int) error {
32
	fmt.Println(strings.Repeat("=", 60))
33
	fmt.Printf("Streaming L4 Orderbook for %s\n", coin)
34
	fmt.Println("Auto-reconnect: true")
35
	fmt.Println(strings.Repeat("=", 60) + "\n")
36

37
	retryCount := 0
38
	totalMsgCount := 0
39

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

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

52
		request := &pb.L4BookRequest{
53
			Coin: coin,
54
		}
55

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

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

68
		snapshotReceived := false
69
		shouldRetry := false
70

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

97
			totalMsgCount++
98

99
			if snapshot := update.GetSnapshot(); snapshot != nil {
100
				snapshotReceived = true
101
				retryCount = 0 // Reset on success
102

103
				fmt.Println("\n✓ L4 Snapshot Received!")
104
				fmt.Println(strings.Repeat("─", 60))
105
				fmt.Printf("Coin: %s\n", snapshot.Coin)
106
				fmt.Printf("Height: %d\n", snapshot.Height)
107
				fmt.Printf("Time: %d\n", snapshot.Time)
108
				fmt.Printf("Bids: %d orders\n", len(snapshot.Bids))
109
				fmt.Printf("Asks: %d orders\n", len(snapshot.Asks))
110
				fmt.Println(strings.Repeat("─", 60))
111

112
				// Sample bids
113
				if len(snapshot.Bids) > 0 {
114
					fmt.Println("\nSample Bids (first 5):")
115
					bidCount := len(snapshot.Bids)
116
					if bidCount > 5 {
117
						bidCount = 5
118
					}
119
					for i := 0; i < bidCount; i++ {
120
						order := snapshot.Bids[i]
121
						userShort := order.User
122
						if len(userShort) > 10 {
123
							userShort = userShort[:10] + "..."
124
						}
125
						fmt.Printf("  OID: %d | Price: %s | Size: %s | User: %s\n",
126
							order.Oid, order.LimitPx, order.Sz, userShort)
127
					}
128
				}
129

130
				// Sample asks
131
				if len(snapshot.Asks) > 0 {
132
					fmt.Println("\nSample Asks (first 5):")
133
					askCount := len(snapshot.Asks)
134
					if askCount > 5 {
135
						askCount = 5
136
					}
137
					for i := 0; i < askCount; i++ {
138
						order := snapshot.Asks[i]
139
						userShort := order.User
140
						if len(userShort) > 10 {
141
							userShort = userShort[:10] + "..."
142
						}
143
						fmt.Printf("  OID: %d | Price: %s | Size: %s | User: %s\n",
144
							order.Oid, order.LimitPx, order.Sz, userShort)
145
					}
146
				}
147

148
			} else if diff := update.GetDiff(); diff != nil {
149
				if !snapshotReceived {
150
					fmt.Println("\n⚠ Received diff before snapshot")
151
				}
152

153
				var diffData map[string]interface{}
154
				if err := json.Unmarshal([]byte(diff.Data), &diffData); err == nil {
155
					orderStatuses := []interface{}{}
156
					bookDiffs := []interface{}{}
157

158
					if os, ok := diffData["order_statuses"].([]interface{}); ok {
159
						orderStatuses = os
160
					}
161
					if bd, ok := diffData["book_diffs"].([]interface{}); ok {
162
						bookDiffs = bd
163
					}
164

165
					fmt.Printf("\n[Block %d] L4 Diff:\n", diff.Height)
166
					fmt.Printf("  Time: %d\n", diff.Time)
167
					fmt.Printf("  Order Statuses: %d\n", len(orderStatuses))
168
					fmt.Printf("  Book Diffs: %d\n", len(bookDiffs))
169

170
					if len(bookDiffs) > 0 && len(bookDiffs) <= 5 {
171
						pretty, _ := json.MarshalIndent(bookDiffs, "  ", "  ")
172
						fmt.Printf("  Diffs: %s\n", pretty)
173
					}
174
				}
175
			}
176

177
			if maxMessages > 0 && totalMsgCount >= maxMessages {
178
				fmt.Printf("\nReached max messages (%d), stopping...\n", maxMessages)
179
				conn.Close()
180
				return nil
181
			}
182
		}
183

184
		conn.Close()
185

186
		if !shouldRetry {
187
			break
188
		}
189
	}
190

191
	return nil
192
}
193

194
func main() {
195
	coin := flag.String("coin", "BTC", "Coin symbol to stream")
196
	maxMessages := flag.Int("max-messages", 0, "Maximum messages (0 = unlimited)")
197

198
	flag.Parse()
199

200
	fmt.Println("\n" + strings.Repeat("=", 60))
201
	fmt.Println("Hyperliquid StreamL4Book Example")
202
	fmt.Printf("Endpoint: %s\n", grpcEndpoint)
203
	fmt.Println(strings.Repeat("=", 60))
204

205
	if err := streamL4Orderbook(*coin, *maxMessages); err != nil {
206
		log.Fatal(err)
207
	}
208
}
209

1
// StreamL4Book Example - Stream individual order data 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 L4 (individual orders) orderbook
28
async function streamL4Orderbook(coin, maxMessages = null, autoReconnect = true, retryCount = 0) {
29
  console.log('='.repeat(60));
30
  console.log(`Streaming L4 Orderbook for ${coin}`);
31
  console.log(`Auto-reconnect: ${autoReconnect}`);
32
  console.log('='.repeat(60) + '\n');
33

34
  const maxRetries = 10;
35
  const baseDelay = 2000;
36
  let totalMsgCount = 0;
37

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

43
    const request = { coin: coin };
44

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

52
      let snapshotReceived = false;
53
      const call = client.StreamL4Book(request, metadata);
54

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

58
        if (update.snapshot) {
59
          const snapshot = update.snapshot;
60
          snapshotReceived = true;
61
          retryCount = 0; // Reset on success
62

63
          console.log('\n✓ L4 Snapshot Received!');
64
          console.log('─'.repeat(60));
65
          console.log(`Coin: ${snapshot.coin}`);
66
          console.log(`Height: ${snapshot.height}`);
67
          console.log(`Time: ${snapshot.time}`);
68
          console.log(`Bids: ${snapshot.bids.length} orders`);
69
          console.log(`Asks: ${snapshot.asks.length} orders`);
70
          console.log('─'.repeat(60));
71

72
          // Sample bids
73
          if (snapshot.bids.length > 0) {
74
            console.log('\nSample Bids (first 5):');
75
            snapshot.bids.slice(0, 5).forEach(order => {
76
              console.log(`  OID: ${order.oid} | Price: ${order.limit_px} | Size: ${order.sz} | User: ${order.user.substring(0, 10)}...`);
77
            });
78
          }
79

80
          // Sample asks
81
          if (snapshot.asks.length > 0) {
82
            console.log('\nSample Asks (first 5):');
83
            snapshot.asks.slice(0, 5).forEach(order => {
84
              console.log(`  OID: ${order.oid} | Price: ${order.limit_px} | Size: ${order.sz} | User: ${order.user.substring(0, 10)}...`);
85
            });
86
          }
87

88
        } else if (update.diff) {
89
          const diff = update.diff;
90

91
          if (!snapshotReceived) {
92
            console.log('\n⚠ Received diff before snapshot');
93
          }
94

95
          try {
96
            const diffData = JSON.parse(diff.data);
97
            const orderStatuses = diffData.order_statuses || [];
98
            const bookDiffs = diffData.book_diffs || [];
99

100
            console.log(`\n[Block ${diff.height}] L4 Diff:`);
101
            console.log(`  Time: ${diff.time}`);
102
            console.log(`  Order Statuses: ${orderStatuses.length}`);
103
            console.log(`  Book Diffs: ${bookDiffs.length}`);
104

105
            if (bookDiffs.length > 0 && bookDiffs.length <= 5) {
106
              console.log(`  Diffs: ${JSON.stringify(bookDiffs, null, 2)}`);
107
            }
108
          } catch (e) {
109
            console.log(`  Error parsing diff: ${e.message}`);
110
          }
111
        }
112

113
        if (maxMessages && totalMsgCount >= maxMessages) {
114
          console.log(`\nReached max messages (${maxMessages}), stopping...`);
115
          call.cancel();
116
        }
117
      });
118

119
      call.on('error', (err) => {
120
        if (err.code === grpc.status.DATA_LOSS && autoReconnect) {
121
          console.log(`\n⚠️  Server reinitialized: ${err.message}`);
122
          retryCount++;
123
          if (retryCount < maxRetries) {
124
            const delay = baseDelay * Math.pow(2, retryCount - 1);
125
            console.log(`⏳ Waiting ${delay / 1000}s before reconnecting...`);
126
            setTimeout(() => streamL4Orderbook(coin, maxMessages, autoReconnect, retryCount), delay);
127
          } else {
128
            console.log(`\n❌ Max retries (${maxRetries}) reached. Giving up.`);
129
          }
130
        } else if (err.code !== grpc.status.CANCELLED) {
131
          console.error('\ngRPC error:', err.code, '-', err.message);
132
        }
133
      });
134

135
      call.on('end', () => {
136
        console.log('\nStream ended');
137
      });
138

139
      // Wait for stream to complete
140
      await new Promise((resolve) => {
141
        call.on('end', resolve);
142
        call.on('error', resolve);
143
      });
144

145
      break; // Exit retry loop on success
146

147
    } catch (err) {
148
      console.error('Error:', err.message);
149
      break;
150
    }
151
  }
152
}
153

154
// Parse command line args
155
const args = process.argv.slice(2);
156
const coin = args.find(a => a.startsWith('--coin='))?.split('=')[1] || 'BTC';
157
const maxMessages = parseInt(args.find(a => a.startsWith('--max-messages='))?.split('=')[1]) || null;
158

159
console.log('\n' + '='.repeat(60));
160
console.log('Hyperliquid StreamL4Book Example');
161
console.log(`Endpoint: ${GRPC_ENDPOINT}`);
162
console.log('='.repeat(60));
163

164
streamL4Orderbook(coin, maxMessages);
165

1
// StreamL4Book Example - Stream individual order data 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 L4 (individual orders) orderbook
28
async function streamL4Orderbook(coin, maxMessages = null, autoReconnect = true, retryCount = 0) {
29
  console.log('='.repeat(60));
30
  console.log(`Streaming L4 Orderbook for ${coin}`);
31
  console.log(`Auto-reconnect: ${autoReconnect}`);
32
  console.log('='.repeat(60) + '\n');
33

34
  const maxRetries = 10;
35
  const baseDelay = 2000;
36
  let totalMsgCount = 0;
37

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

43
    const request = { coin: coin };
44

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

52
      let snapshotReceived = false;
53
      const call = client.StreamL4Book(request, metadata);
54

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

58
        if (update.snapshot) {
59
          const snapshot = update.snapshot;
60
          snapshotReceived = true;
61
          retryCount = 0; // Reset on success
62

63
          console.log('\n✓ L4 Snapshot Received!');
64
          console.log('─'.repeat(60));
65
          console.log(`Coin: ${snapshot.coin}`);
66
          console.log(`Height: ${snapshot.height}`);
67
          console.log(`Time: ${snapshot.time}`);
68
          console.log(`Bids: ${snapshot.bids.length} orders`);
69
          console.log(`Asks: ${snapshot.asks.length} orders`);
70
          console.log('─'.repeat(60));
71

72
          // Sample bids
73
          if (snapshot.bids.length > 0) {
74
            console.log('\nSample Bids (first 5):');
75
            snapshot.bids.slice(0, 5).forEach(order => {
76
              console.log(`  OID: ${order.oid} | Price: ${order.limit_px} | Size: ${order.sz} | User: ${order.user.substring(0, 10)}...`);
77
            });
78
          }
79

80
          // Sample asks
81
          if (snapshot.asks.length > 0) {
82
            console.log('\nSample Asks (first 5):');
83
            snapshot.asks.slice(0, 5).forEach(order => {
84
              console.log(`  OID: ${order.oid} | Price: ${order.limit_px} | Size: ${order.sz} | User: ${order.user.substring(0, 10)}...`);
85
            });
86
          }
87

88
        } else if (update.diff) {
89
          const diff = update.diff;
90

91
          if (!snapshotReceived) {
92
            console.log('\n⚠ Received diff before snapshot');
93
          }
94

95
          try {
96
            const diffData = JSON.parse(diff.data);
97
            const orderStatuses = diffData.order_statuses || [];
98
            const bookDiffs = diffData.book_diffs || [];
99

100
            console.log(`\n[Block ${diff.height}] L4 Diff:`);
101
            console.log(`  Time: ${diff.time}`);
102
            console.log(`  Order Statuses: ${orderStatuses.length}`);
103
            console.log(`  Book Diffs: ${bookDiffs.length}`);
104

105
            if (bookDiffs.length > 0 && bookDiffs.length <= 5) {
106
              console.log(`  Diffs: ${JSON.stringify(bookDiffs, null, 2)}`);
107
            }
108
          } catch (e) {
109
            console.log(`  Error parsing diff: ${e.message}`);
110
          }
111
        }
112

113
        if (maxMessages && totalMsgCount >= maxMessages) {
114
          console.log(`\nReached max messages (${maxMessages}), stopping...`);
115
          call.cancel();
116
        }
117
      });
118

119
      call.on('error', (err) => {
120
        if (err.code === grpc.status.DATA_LOSS && autoReconnect) {
121
          console.log(`\n⚠️  Server reinitialized: ${err.message}`);
122
          retryCount++;
123
          if (retryCount < maxRetries) {
124
            const delay = baseDelay * Math.pow(2, retryCount - 1);
125
            console.log(`⏳ Waiting ${delay / 1000}s before reconnecting...`);
126
            setTimeout(() => streamL4Orderbook(coin, maxMessages, autoReconnect, retryCount), delay);
127
          } else {
128
            console.log(`\n❌ Max retries (${maxRetries}) reached. Giving up.`);
129
          }
130
        } else if (err.code !== grpc.status.CANCELLED) {
131
          console.error('\ngRPC error:', err.code, '-', err.message);
132
        }
133
      });
134

135
      call.on('end', () => {
136
        console.log('\nStream ended');
137
      });
138

139
      // Wait for stream to complete
140
      await new Promise((resolve) => {
141
        call.on('end', resolve);
142
        call.on('error', resolve);
143
      });
144

145
      break; // Exit retry loop on success
146

147
    } catch (err) {
148
      console.error('Error:', err.message);
149
      break;
150
    }
151
  }
152
}
153

154
// Parse command line args
155
const args = process.argv.slice(2);
156
const coin = args.find(a => a.startsWith('--coin='))?.split('=')[1] || 'BTC';
157
const maxMessages = parseInt(args.find(a => a.startsWith('--max-messages='))?.split('=')[1]) || null;
158

159
console.log('\n' + '='.repeat(60));
160
console.log('Hyperliquid StreamL4Book Example');
161
console.log(`Endpoint: ${GRPC_ENDPOINT}`);
162
console.log('='.repeat(60));
163

164
streamL4Orderbook(coin, maxMessages);
165

1
#!/usr/bin/env python3
2
"""
3
StreamL4Book Example - Stream individual order data 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_l4_example.py --coin BTC --max-messages 100
11
"""
12

13
import grpc
14
import json
15
import sys
16
import time
17
import argparse
18
from typing import Optional
19

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

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

32

33
def stream_l4_orderbook(coin: str, max_messages: Optional[int] = None, auto_reconnect: bool = True):
34
    """
35
    Stream L4 (individual orders) orderbook updates for a coin.
36

37
    Args:
38
        coin: Symbol to stream (e.g., "BTC", "ETH")
39
        max_messages: Maximum number of messages to receive (None for unlimited)
40
        auto_reconnect: Auto-reconnect on DATA_LOSS errors (default True)
41
    """
42
    print(f"\n{'='*60}")
43
    print(f"Streaming L4 Orderbook for {coin}")
44
    print(f"Auto-reconnect: {auto_reconnect}")
45
    print(f"{'='*60}\n")
46

47
    retry_count = 0
48
    max_retries = 10
49
    base_delay = 2
50
    total_msg_count = 0
51

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

63
        request = pb.L4BookRequest(coin=coin)
64

65
        msg_count = 0
66
        snapshot_received = False
67

68
        try:
69
            if retry_count > 0:
70
                print(f"\n🔄 Reconnecting (attempt {retry_count + 1}/{max_retries})...")
71
            else:
72
                print(f"Connecting to {GRPC_ENDPOINT}...")
73

74
            for update in stub.StreamL4Book(request, metadata=[('x-token', AUTH_TOKEN)]):
75
                msg_count += 1
76
                total_msg_count += 1
77

78
                if update.HasField('snapshot'):
79
                    snapshot = update.snapshot
80
                    snapshot_received = True
81
                    retry_count = 0  # Reset retry count on successful connection
82

83
                    print(f"\n✓ L4 Snapshot Received!")
84
                    print(f"{'─'*60}")
85
                    print(f"Coin: {snapshot.coin}")
86
                    print(f"Height: {snapshot.height}")
87
                    print(f"Time: {snapshot.time}")
88
                    print(f"Bids: {len(snapshot.bids)} orders")
89
                    print(f"Asks: {len(snapshot.asks)} orders")
90
                    print(f"{'─'*60}")
91

92
                    # Show sample of orders
93
                    if snapshot.bids:
94
                        print(f"\nSample Bids (first 5):")
95
                        for order in snapshot.bids[:5]:
96
                            print(f"  OID: {order.oid} | Price: {order.limit_px} | Size: {order.sz} | User: {order.user[:10]}...")
97

98
                    if snapshot.asks:
99
                        print(f"\nSample Asks (first 5):")
100
                        for order in snapshot.asks[:5]:
101
                            print(f"  OID: {order.oid} | Price: {order.limit_px} | Size: {order.sz} | User: {order.user[:10]}...")
102

103
                elif update.HasField('diff'):
104
                    diff = update.diff
105

106
                    if not snapshot_received:
107
                        print(f"\n⚠ Received diff before snapshot")
108

109
                    # Parse the JSON diff data
110
                    try:
111
                        diff_data = json.loads(diff.data)
112
                        order_statuses = diff_data.get('order_statuses', [])
113
                        book_diffs = diff_data.get('book_diffs', [])
114

115
                        print(f"\n[Block {diff.height}] L4 Diff:")
116
                        print(f"  Time: {diff.time}")
117
                        print(f"  Order Statuses: {len(order_statuses)}")
118
                        print(f"  Book Diffs: {len(book_diffs)}")
119

120
                        # Show sample diffs
121
                        if book_diffs and len(book_diffs) <= 5:
122
                            print(f"  Diffs: {json.dumps(book_diffs, indent=4)}")
123

124
                    except json.JSONDecodeError as e:
125
                        print(f"  Error parsing diff data: {e}")
126
                        print(f"  Raw data: {diff.data[:200]}...")
127

128
                if max_messages and total_msg_count >= max_messages:
129
                    print(f"\nReached max messages ({max_messages}), stopping...")
130
                    channel.close()
131
                    return
132

133
        except grpc.RpcError as e:
134
            if e.code() == grpc.StatusCode.DATA_LOSS and auto_reconnect:
135
                print(f"\n⚠️  Server reinitialized: {e.details()}")
136
                retry_count += 1
137
                if retry_count < max_retries:
138
                    delay = base_delay * (2 ** (retry_count - 1))  # Exponential backoff
139
                    print(f"⏳ Waiting {delay}s before reconnecting...")
140
                    time.sleep(delay)
141
                    channel.close()
142
                    continue
143
                else:
144
                    print(f"\n❌ Max retries ({max_retries}) reached. Giving up.")
145
                    break
146
            else:
147
                print(f"\ngRPC error: {e.code()} - {e.details()}")
148
                break
149
        except KeyboardInterrupt:
150
            print("\nStopping L4 stream...")
151
            break
152
        finally:
153
            channel.close()
154

155
        # If we get here without error, break the retry loop
156
        break
157

158

159
def main():
160
    parser = argparse.ArgumentParser(description='Stream Hyperliquid L4 orderbook data via gRPC')
161
    parser.add_argument('--coin', default='BTC', help='Coin symbol to stream')
162
    parser.add_argument('--max-messages', type=int, default=None, help='Maximum number of messages to receive')
163

164
    args = parser.parse_args()
165

166
    print(f"\n{'='*60}")
167
    print("Hyperliquid StreamL4Book Example")
168
    print(f"Endpoint: {GRPC_ENDPOINT}")
169
    print(f"{'='*60}")
170

171
    try:
172
        stream_l4_orderbook(args.coin, max_messages=args.max_messages)
173
    except Exception as e:
174
        print(f"\nError: {e}")
175
        import traceback
176
        traceback.print_exc()
177
        sys.exit(1)
178

179

180
if __name__ == "__main__":
181
    main()
182

1
#!/usr/bin/env python3
2
"""
3
StreamL4Book Example - Stream individual order data 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_l4_example.py --coin BTC --max-messages 100
11
"""
12

13
import grpc
14
import json
15
import sys
16
import time
17
import argparse
18
from typing import Optional
19

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

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

32

33
def stream_l4_orderbook(coin: str, max_messages: Optional[int] = None, auto_reconnect: bool = True):
34
    """
35
    Stream L4 (individual orders) orderbook updates for a coin.
36

37
    Args:
38
        coin: Symbol to stream (e.g., "BTC", "ETH")
39
        max_messages: Maximum number of messages to receive (None for unlimited)
40
        auto_reconnect: Auto-reconnect on DATA_LOSS errors (default True)
41
    """
42
    print(f"\n{'='*60}")
43
    print(f"Streaming L4 Orderbook for {coin}")
44
    print(f"Auto-reconnect: {auto_reconnect}")
45
    print(f"{'='*60}\n")
46

47
    retry_count = 0
48
    max_retries = 10
49
    base_delay = 2
50
    total_msg_count = 0
51

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

63
        request = pb.L4BookRequest(coin=coin)
64

65
        msg_count = 0
66
        snapshot_received = False
67

68
        try:
69
            if retry_count > 0:
70
                print(f"\n🔄 Reconnecting (attempt {retry_count + 1}/{max_retries})...")
71
            else:
72
                print(f"Connecting to {GRPC_ENDPOINT}...")
73

74
            for update in stub.StreamL4Book(request, metadata=[('x-token', AUTH_TOKEN)]):
75
                msg_count += 1
76
                total_msg_count += 1
77

78
                if update.HasField('snapshot'):
79
                    snapshot = update.snapshot
80
                    snapshot_received = True
81
                    retry_count = 0  # Reset retry count on successful connection
82

83
                    print(f"\n✓ L4 Snapshot Received!")
84
                    print(f"{'─'*60}")
85
                    print(f"Coin: {snapshot.coin}")
86
                    print(f"Height: {snapshot.height}")
87
                    print(f"Time: {snapshot.time}")
88
                    print(f"Bids: {len(snapshot.bids)} orders")
89
                    print(f"Asks: {len(snapshot.asks)} orders")
90
                    print(f"{'─'*60}")
91

92
                    # Show sample of orders
93
                    if snapshot.bids:
94
                        print(f"\nSample Bids (first 5):")
95
                        for order in snapshot.bids[:5]:
96
                            print(f"  OID: {order.oid} | Price: {order.limit_px} | Size: {order.sz} | User: {order.user[:10]}...")
97

98
                    if snapshot.asks:
99
                        print(f"\nSample Asks (first 5):")
100
                        for order in snapshot.asks[:5]:
101
                            print(f"  OID: {order.oid} | Price: {order.limit_px} | Size: {order.sz} | User: {order.user[:10]}...")
102

103
                elif update.HasField('diff'):
104
                    diff = update.diff
105

106
                    if not snapshot_received:
107
                        print(f"\n⚠ Received diff before snapshot")
108

109
                    # Parse the JSON diff data
110
                    try:
111
                        diff_data = json.loads(diff.data)
112
                        order_statuses = diff_data.get('order_statuses', [])
113
                        book_diffs = diff_data.get('book_diffs', [])
114

115
                        print(f"\n[Block {diff.height}] L4 Diff:")
116
                        print(f"  Time: {diff.time}")
117
                        print(f"  Order Statuses: {len(order_statuses)}")
118
                        print(f"  Book Diffs: {len(book_diffs)}")
119

120
                        # Show sample diffs
121
                        if book_diffs and len(book_diffs) <= 5:
122
                            print(f"  Diffs: {json.dumps(book_diffs, indent=4)}")
123

124
                    except json.JSONDecodeError as e:
125
                        print(f"  Error parsing diff data: {e}")
126
                        print(f"  Raw data: {diff.data[:200]}...")
127

128
                if max_messages and total_msg_count >= max_messages:
129
                    print(f"\nReached max messages ({max_messages}), stopping...")
130
                    channel.close()
131
                    return
132

133
        except grpc.RpcError as e:
134
            if e.code() == grpc.StatusCode.DATA_LOSS and auto_reconnect:
135
                print(f"\n⚠️  Server reinitialized: {e.details()}")
136
                retry_count += 1
137
                if retry_count < max_retries:
138
                    delay = base_delay * (2 ** (retry_count - 1))  # Exponential backoff
139
                    print(f"⏳ Waiting {delay}s before reconnecting...")
140
                    time.sleep(delay)
141
                    channel.close()
142
                    continue
143
                else:
144
                    print(f"\n❌ Max retries ({max_retries}) reached. Giving up.")
145
                    break
146
            else:
147
                print(f"\ngRPC error: {e.code()} - {e.details()}")
148
                break
149
        except KeyboardInterrupt:
150
            print("\nStopping L4 stream...")
151
            break
152
        finally:
153
            channel.close()
154

155
        # If we get here without error, break the retry loop
156
        break
157

158

159
def main():
160
    parser = argparse.ArgumentParser(description='Stream Hyperliquid L4 orderbook data via gRPC')
161
    parser.add_argument('--coin', default='BTC', help='Coin symbol to stream')
162
    parser.add_argument('--max-messages', type=int, default=None, help='Maximum number of messages to receive')
163

164
    args = parser.parse_args()
165

166
    print(f"\n{'='*60}")
167
    print("Hyperliquid StreamL4Book Example")
168
    print(f"Endpoint: {GRPC_ENDPOINT}")
169
    print(f"{'='*60}")
170

171
    try:
172
        stream_l4_orderbook(args.coin, max_messages=args.max_messages)
173
    except Exception as e:
174
        print(f"\nError: {e}")
175
        import traceback
176
        traceback.print_exc()
177
        sys.exit(1)
178

179

180
if __name__ == "__main__":
181
    main()
182

Don't have an account yet?

Create your Quicknode endpoint in seconds and start building

Get started for free