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