Full reference

Field definitions, proto messages, example updates, and comparisons for this stream live on the L4 Book Updates 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

coins

repeated string

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

Returns

stream

stream<L4BookUpdatesUpdate>

Stream of L4BookUpdatesUpdate messages containing typed per-order diffs per block

time

uint64

Block timestamp in milliseconds

height

uint64

Block height

snapshot

bool

True when the diffs carry a full reset snapshot of all resting orders

diffs

array<L4OrderDiff>

Per-order diffs, each containing diff_type (L4_ORDER_DIFF_TYPE_NEW, L4_ORDER_DIFF_TYPE_UPDATE, or L4_ORDER_DIFF_TYPE_REMOVE), coin, oid (order ID), user (address), side ('A' for ask, 'B' for bid), px (price), and sz (new/current size for new and update diffs; omitted on remove)

Request

1
// StreamL4BookUpdates Example - Stream typed per-order book updates 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
type localOrder struct {
31
	coin string
32
	user string
33
	side string
34
	px   string
35
	sz   string
36
}
37

38
func streamL4BookUpdates(coins []string) error {
39
	fmt.Println(strings.Repeat("=", 60))
40
	fmt.Printf("Streaming L4 Book Updates for %s\n", strings.Join(coins, ", "))
41
	fmt.Println("Auto-reconnect: true")
42
	fmt.Println(strings.Repeat("=", 60) + "\n")
43

44
	retryCount := 0
45

46
	// Simple local order map keyed by oid
47
	orders := make(map[uint64]localOrder)
48

49
	for retryCount < maxRetries {
50
		creds := credentials.NewClientTLSFromCert(nil, "")
51
		conn, err := grpc.Dial(grpcEndpoint,
52
			grpc.WithTransportCredentials(creds),
53
			grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(100*1024*1024)))
54
		if err != nil {
55
			return fmt.Errorf("failed to connect: %w", err)
56
		}
57

58
		client := pb.NewOrderBookStreamingClient(conn)
59
		ctx := metadata.AppendToOutgoingContext(context.Background(), "x-token", authToken)
60

61
		request := &pb.L4BookUpdatesRequest{
62
			Coins: coins,
63
		}
64

65
		if retryCount > 0 {
66
			fmt.Printf("\n🔄 Reconnecting (attempt %d/%d)...\n", retryCount+1, maxRetries)
67
		} else {
68
			fmt.Printf("Connecting to %s...\n", grpcEndpoint)
69
		}
70

71
		stream, err := client.StreamL4BookUpdates(ctx, request)
72
		if err != nil {
73
			conn.Close()
74
			return fmt.Errorf("failed to start stream: %w", err)
75
		}
76

77
		msgCount := 0
78
		shouldRetry := false
79

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

106
			msgCount++
107
			if msgCount == 1 {
108
				fmt.Println("✓ First L4 update received!\n")
109
				retryCount = 0 // Reset on success
110
			}
111

112
			if update.Snapshot {
113
				// Full reset snapshot: rebuild local state
114
				orders = make(map[uint64]localOrder)
115
			}
116

117
			// Display update
118
			fmt.Println("\n" + strings.Repeat("─", 60))
119
			snapshotLabel := ""
120
			if update.Snapshot {
121
				snapshotLabel = " | SNAPSHOT"
122
			}
123
			fmt.Printf("Block: %d | Time: %d%s | Diffs: %d\n", update.Height, update.Time, snapshotLabel, len(update.Diffs))
124
			fmt.Println(strings.Repeat("─", 60))
125

126
			for _, diff := range update.Diffs {
127
				side := "ASK"
128
				if diff.Side == "B" {
129
					side = "BID"
130
				}
131

132
				switch diff.DiffType {
133
				case pb.L4OrderDiffType_L4_ORDER_DIFF_TYPE_NEW:
134
					orders[diff.Oid] = localOrder{coin: diff.Coin, user: diff.User, side: diff.Side, px: diff.Px, sz: diff.Sz}
135
					if !update.Snapshot {
136
						fmt.Printf("  NEW    %s oid: %d | %s %s x %s | %s\n", diff.Coin, diff.Oid, side, diff.Px, diff.Sz, diff.User)
137
					}
138
				case pb.L4OrderDiffType_L4_ORDER_DIFF_TYPE_UPDATE:
139
					if existing, ok := orders[diff.Oid]; ok {
140
						existing.sz = diff.Sz
141
						orders[diff.Oid] = existing
142
					}
143
					fmt.Printf("  UPDATE %s oid: %d | %s %s x %s | %s\n", diff.Coin, diff.Oid, side, diff.Px, diff.Sz, diff.User)
144
				case pb.L4OrderDiffType_L4_ORDER_DIFF_TYPE_REMOVE:
145
					delete(orders, diff.Oid)
146
					fmt.Printf("  REMOVE %s oid: %d | %s %s | %s\n", diff.Coin, diff.Oid, side, diff.Px, diff.User)
147
				}
148
			}
149

150
			fmt.Printf("\n  Resting orders tracked: %d | Messages received: %d\n", len(orders), msgCount)
151
		}
152

153
		conn.Close()
154

155
		if !shouldRetry {
156
			break
157
		}
158
	}
159

160
	return nil
161
}
162

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

166
	flag.Parse()
167

168
	coins := strings.Split(*coinsFlag, ",")
169

170
	fmt.Println("\n" + strings.Repeat("=", 60))
171
	fmt.Println("Hyperliquid StreamL4BookUpdates Example")
172
	fmt.Printf("Endpoint: %s\n", grpcEndpoint)
173
	fmt.Println(strings.Repeat("=", 60))
174

175
	if err := streamL4BookUpdates(coins); err != nil {
176
		log.Fatal(err)
177
	}
178
}
179

1
// StreamL4BookUpdates Example - Stream typed per-order book updates 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
type localOrder struct {
31
	coin string
32
	user string
33
	side string
34
	px   string
35
	sz   string
36
}
37

38
func streamL4BookUpdates(coins []string) error {
39
	fmt.Println(strings.Repeat("=", 60))
40
	fmt.Printf("Streaming L4 Book Updates for %s\n", strings.Join(coins, ", "))
41
	fmt.Println("Auto-reconnect: true")
42
	fmt.Println(strings.Repeat("=", 60) + "\n")
43

44
	retryCount := 0
45

46
	// Simple local order map keyed by oid
47
	orders := make(map[uint64]localOrder)
48

49
	for retryCount < maxRetries {
50
		creds := credentials.NewClientTLSFromCert(nil, "")
51
		conn, err := grpc.Dial(grpcEndpoint,
52
			grpc.WithTransportCredentials(creds),
53
			grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(100*1024*1024)))
54
		if err != nil {
55
			return fmt.Errorf("failed to connect: %w", err)
56
		}
57

58
		client := pb.NewOrderBookStreamingClient(conn)
59
		ctx := metadata.AppendToOutgoingContext(context.Background(), "x-token", authToken)
60

61
		request := &pb.L4BookUpdatesRequest{
62
			Coins: coins,
63
		}
64

65
		if retryCount > 0 {
66
			fmt.Printf("\n🔄 Reconnecting (attempt %d/%d)...\n", retryCount+1, maxRetries)
67
		} else {
68
			fmt.Printf("Connecting to %s...\n", grpcEndpoint)
69
		}
70

71
		stream, err := client.StreamL4BookUpdates(ctx, request)
72
		if err != nil {
73
			conn.Close()
74
			return fmt.Errorf("failed to start stream: %w", err)
75
		}
76

77
		msgCount := 0
78
		shouldRetry := false
79

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

106
			msgCount++
107
			if msgCount == 1 {
108
				fmt.Println("✓ First L4 update received!\n")
109
				retryCount = 0 // Reset on success
110
			}
111

112
			if update.Snapshot {
113
				// Full reset snapshot: rebuild local state
114
				orders = make(map[uint64]localOrder)
115
			}
116

117
			// Display update
118
			fmt.Println("\n" + strings.Repeat("─", 60))
119
			snapshotLabel := ""
120
			if update.Snapshot {
121
				snapshotLabel = " | SNAPSHOT"
122
			}
123
			fmt.Printf("Block: %d | Time: %d%s | Diffs: %d\n", update.Height, update.Time, snapshotLabel, len(update.Diffs))
124
			fmt.Println(strings.Repeat("─", 60))
125

126
			for _, diff := range update.Diffs {
127
				side := "ASK"
128
				if diff.Side == "B" {
129
					side = "BID"
130
				}
131

132
				switch diff.DiffType {
133
				case pb.L4OrderDiffType_L4_ORDER_DIFF_TYPE_NEW:
134
					orders[diff.Oid] = localOrder{coin: diff.Coin, user: diff.User, side: diff.Side, px: diff.Px, sz: diff.Sz}
135
					if !update.Snapshot {
136
						fmt.Printf("  NEW    %s oid: %d | %s %s x %s | %s\n", diff.Coin, diff.Oid, side, diff.Px, diff.Sz, diff.User)
137
					}
138
				case pb.L4OrderDiffType_L4_ORDER_DIFF_TYPE_UPDATE:
139
					if existing, ok := orders[diff.Oid]; ok {
140
						existing.sz = diff.Sz
141
						orders[diff.Oid] = existing
142
					}
143
					fmt.Printf("  UPDATE %s oid: %d | %s %s x %s | %s\n", diff.Coin, diff.Oid, side, diff.Px, diff.Sz, diff.User)
144
				case pb.L4OrderDiffType_L4_ORDER_DIFF_TYPE_REMOVE:
145
					delete(orders, diff.Oid)
146
					fmt.Printf("  REMOVE %s oid: %d | %s %s | %s\n", diff.Coin, diff.Oid, side, diff.Px, diff.User)
147
				}
148
			}
149

150
			fmt.Printf("\n  Resting orders tracked: %d | Messages received: %d\n", len(orders), msgCount)
151
		}
152

153
		conn.Close()
154

155
		if !shouldRetry {
156
			break
157
		}
158
	}
159

160
	return nil
161
}
162

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

166
	flag.Parse()
167

168
	coins := strings.Split(*coinsFlag, ",")
169

170
	fmt.Println("\n" + strings.Repeat("=", 60))
171
	fmt.Println("Hyperliquid StreamL4BookUpdates Example")
172
	fmt.Printf("Endpoint: %s\n", grpcEndpoint)
173
	fmt.Println(strings.Repeat("=", 60))
174

175
	if err := streamL4BookUpdates(coins); err != nil {
176
		log.Fatal(err)
177
	}
178
}
179

1
// StreamL4BookUpdates Example - Stream typed per-order book updates 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 typed per-order L4 book updates
28
async function streamL4BookUpdates(coins, autoReconnect = true, retryCount = 0) {
29
  console.log('='.repeat(60));
30
  console.log(`Streaming L4 Book Updates 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
  // Simple local order map keyed by oid
38
  const orders = new Map();
39

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

45
    const request = {
46
      coins: coins
47
    };
48

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

56
      let msgCount = 0;
57
      const call = client.StreamL4BookUpdates(request, metadata);
58

59
      call.on('data', (update) => {
60
        msgCount++;
61

62
        if (msgCount === 1) {
63
          console.log('✓ First L4 update received!\n');
64
          retryCount = 0; // Reset on success
65
        }
66

67
        if (update.snapshot) {
68
          // Full reset snapshot: rebuild local state
69
          orders.clear();
70
        }
71

72
        console.log('\n' + '─'.repeat(60));
73
        console.log(`Block: ${update.height} | Time: ${update.time}${update.snapshot ? ' | SNAPSHOT' : ''} | Diffs: ${(update.diffs || []).length}`);
74
        console.log('─'.repeat(60));
75

76
        (update.diffs || []).forEach(diff => {
77
          switch (diff.diff_type) {
78
            case 'L4_ORDER_DIFF_TYPE_NEW':
79
              orders.set(diff.oid, { coin: diff.coin, user: diff.user, side: diff.side, px: diff.px, sz: diff.sz });
80
              if (!update.snapshot) {
81
                console.log(`  NEW    ${diff.coin} oid: ${diff.oid} | ${diff.side === 'B' ? 'BID' : 'ASK'} ${diff.px} x ${diff.sz} | ${diff.user}`);
82
              }
83
              break;
84
            case 'L4_ORDER_DIFF_TYPE_UPDATE':
85
              const existing = orders.get(diff.oid);
86
              if (existing) {
87
                existing.sz = diff.sz;
88
              }
89
              console.log(`  UPDATE ${diff.coin} oid: ${diff.oid} | ${diff.side === 'B' ? 'BID' : 'ASK'} ${diff.px} x ${diff.sz} | ${diff.user}`);
90
              break;
91
            case 'L4_ORDER_DIFF_TYPE_REMOVE':
92
              orders.delete(diff.oid);
93
              console.log(`  REMOVE ${diff.coin} oid: ${diff.oid} | ${diff.side === 'B' ? 'BID' : 'ASK'} ${diff.px} | ${diff.user}`);
94
              break;
95
          }
96
        });
97

98
        console.log(`\n  Resting orders tracked: ${orders.size} | Messages received: ${msgCount}`);
99
      });
100

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

117
      call.on('end', () => {
118
        console.log('\nStream ended');
119
      });
120

121
      // Wait for stream to complete
122
      await new Promise((resolve) => {
123
        call.on('end', resolve);
124
        call.on('error', resolve);
125
      });
126

127
      break; // Exit retry loop on success
128

129
    } catch (err) {
130
      console.error('Error:', err.message);
131
      break;
132
    }
133
  }
134
}
135

136
// Parse command line args
137
const args = process.argv.slice(2);
138
const coins = (args.find(a => a.startsWith('--coins='))?.split('=')[1] || 'BTC').split(',');
139

140
console.log('\n' + '='.repeat(60));
141
console.log('Hyperliquid StreamL4BookUpdates Example');
142
console.log(`Endpoint: ${GRPC_ENDPOINT}`);
143
console.log('='.repeat(60));
144

145
streamL4BookUpdates(coins);
146

1
// StreamL4BookUpdates Example - Stream typed per-order book updates 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 typed per-order L4 book updates
28
async function streamL4BookUpdates(coins, autoReconnect = true, retryCount = 0) {
29
  console.log('='.repeat(60));
30
  console.log(`Streaming L4 Book Updates 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
  // Simple local order map keyed by oid
38
  const orders = new Map();
39

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

45
    const request = {
46
      coins: coins
47
    };
48

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

56
      let msgCount = 0;
57
      const call = client.StreamL4BookUpdates(request, metadata);
58

59
      call.on('data', (update) => {
60
        msgCount++;
61

62
        if (msgCount === 1) {
63
          console.log('✓ First L4 update received!\n');
64
          retryCount = 0; // Reset on success
65
        }
66

67
        if (update.snapshot) {
68
          // Full reset snapshot: rebuild local state
69
          orders.clear();
70
        }
71

72
        console.log('\n' + '─'.repeat(60));
73
        console.log(`Block: ${update.height} | Time: ${update.time}${update.snapshot ? ' | SNAPSHOT' : ''} | Diffs: ${(update.diffs || []).length}`);
74
        console.log('─'.repeat(60));
75

76
        (update.diffs || []).forEach(diff => {
77
          switch (diff.diff_type) {
78
            case 'L4_ORDER_DIFF_TYPE_NEW':
79
              orders.set(diff.oid, { coin: diff.coin, user: diff.user, side: diff.side, px: diff.px, sz: diff.sz });
80
              if (!update.snapshot) {
81
                console.log(`  NEW    ${diff.coin} oid: ${diff.oid} | ${diff.side === 'B' ? 'BID' : 'ASK'} ${diff.px} x ${diff.sz} | ${diff.user}`);
82
              }
83
              break;
84
            case 'L4_ORDER_DIFF_TYPE_UPDATE':
85
              const existing = orders.get(diff.oid);
86
              if (existing) {
87
                existing.sz = diff.sz;
88
              }
89
              console.log(`  UPDATE ${diff.coin} oid: ${diff.oid} | ${diff.side === 'B' ? 'BID' : 'ASK'} ${diff.px} x ${diff.sz} | ${diff.user}`);
90
              break;
91
            case 'L4_ORDER_DIFF_TYPE_REMOVE':
92
              orders.delete(diff.oid);
93
              console.log(`  REMOVE ${diff.coin} oid: ${diff.oid} | ${diff.side === 'B' ? 'BID' : 'ASK'} ${diff.px} | ${diff.user}`);
94
              break;
95
          }
96
        });
97

98
        console.log(`\n  Resting orders tracked: ${orders.size} | Messages received: ${msgCount}`);
99
      });
100

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

117
      call.on('end', () => {
118
        console.log('\nStream ended');
119
      });
120

121
      // Wait for stream to complete
122
      await new Promise((resolve) => {
123
        call.on('end', resolve);
124
        call.on('error', resolve);
125
      });
126

127
      break; // Exit retry loop on success
128

129
    } catch (err) {
130
      console.error('Error:', err.message);
131
      break;
132
    }
133
  }
134
}
135

136
// Parse command line args
137
const args = process.argv.slice(2);
138
const coins = (args.find(a => a.startsWith('--coins='))?.split('=')[1] || 'BTC').split(',');
139

140
console.log('\n' + '='.repeat(60));
141
console.log('Hyperliquid StreamL4BookUpdates Example');
142
console.log(`Endpoint: ${GRPC_ENDPOINT}`);
143
console.log('='.repeat(60));
144

145
streamL4BookUpdates(coins);
146

1
#!/usr/bin/env python3
2
"""
3
StreamL4BookUpdates Example - Stream typed per-order book updates 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_updates_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_l4_book_updates(coins: list, auto_reconnect: bool = True):
32
    """
33
    Stream typed per-order L4 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 L4 Book Updates 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
    # Simple local order map keyed by oid
49
    orders = {}
50

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

62
        # Build request
63
        request = pb.L4BookUpdatesRequest(coins=coins)
64

65
        msg_count = 0
66

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

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

76
                if msg_count == 1:
77
                    print(f"✓ First L4 update received!\n")
78
                    retry_count = 0  # Reset retry count on successful connection
79

80
                if update.snapshot:
81
                    # Full reset snapshot: rebuild local state
82
                    orders.clear()
83

84
                # Display the update
85
                print(f"\n{'─'*60}")
86
                snapshot_label = " | SNAPSHOT" if update.snapshot else ""
87
                print(f"Block: {update.height} | Time: {update.time}{snapshot_label} | Diffs: {len(update.diffs)}")
88
                print(f"{'─'*60}")
89

90
                for diff in update.diffs:
91
                    side = "BID" if diff.side == "B" else "ASK"
92

93
                    if diff.diff_type == pb.L4_ORDER_DIFF_TYPE_NEW:
94
                        orders[diff.oid] = {"coin": diff.coin, "user": diff.user, "side": diff.side, "px": diff.px, "sz": diff.sz}
95
                        if not update.snapshot:
96
                            print(f"  NEW    {diff.coin} oid: {diff.oid} | {side} {diff.px} x {diff.sz} | {diff.user}")
97
                    elif diff.diff_type == pb.L4_ORDER_DIFF_TYPE_UPDATE:
98
                        if diff.oid in orders:
99
                            orders[diff.oid]["sz"] = diff.sz
100
                        print(f"  UPDATE {diff.coin} oid: {diff.oid} | {side} {diff.px} x {diff.sz} | {diff.user}")
101
                    elif diff.diff_type == pb.L4_ORDER_DIFF_TYPE_REMOVE:
102
                        orders.pop(diff.oid, None)
103
                        print(f"  REMOVE {diff.coin} oid: {diff.oid} | {side} {diff.px} | {diff.user}")
104

105
                print(f"\n  Resting orders tracked: {len(orders)} | Messages received: {msg_count}")
106

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

129
        # If we get here without error, break the retry loop
130
        break
131

132

133
def main():
134
    parser = argparse.ArgumentParser(description='Stream Hyperliquid typed per-order L4 book updates via gRPC')
135
    parser.add_argument('--coins', default='BTC', help='Comma-separated coin symbols to stream (e.g., BTC,ETH)')
136

137
    args = parser.parse_args()
138
    coins = [c.strip() for c in args.coins.split(',') if c.strip()]
139

140
    print(f"\n{'='*60}")
141
    print("Hyperliquid StreamL4BookUpdates Example")
142
    print(f"Endpoint: {GRPC_ENDPOINT}")
143
    print(f"{'='*60}")
144

145
    try:
146
        stream_l4_book_updates(coins)
147
    except Exception as e:
148
        print(f"\nError: {e}")
149
        import traceback
150
        traceback.print_exc()
151
        sys.exit(1)
152

153

154
if __name__ == "__main__":
155
    main()
156

1
#!/usr/bin/env python3
2
"""
3
StreamL4BookUpdates Example - Stream typed per-order book updates 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_updates_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_l4_book_updates(coins: list, auto_reconnect: bool = True):
32
    """
33
    Stream typed per-order L4 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 L4 Book Updates 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
    # Simple local order map keyed by oid
49
    orders = {}
50

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

62
        # Build request
63
        request = pb.L4BookUpdatesRequest(coins=coins)
64

65
        msg_count = 0
66

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

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

76
                if msg_count == 1:
77
                    print(f"✓ First L4 update received!\n")
78
                    retry_count = 0  # Reset retry count on successful connection
79

80
                if update.snapshot:
81
                    # Full reset snapshot: rebuild local state
82
                    orders.clear()
83

84
                # Display the update
85
                print(f"\n{'─'*60}")
86
                snapshot_label = " | SNAPSHOT" if update.snapshot else ""
87
                print(f"Block: {update.height} | Time: {update.time}{snapshot_label} | Diffs: {len(update.diffs)}")
88
                print(f"{'─'*60}")
89

90
                for diff in update.diffs:
91
                    side = "BID" if diff.side == "B" else "ASK"
92

93
                    if diff.diff_type == pb.L4_ORDER_DIFF_TYPE_NEW:
94
                        orders[diff.oid] = {"coin": diff.coin, "user": diff.user, "side": diff.side, "px": diff.px, "sz": diff.sz}
95
                        if not update.snapshot:
96
                            print(f"  NEW    {diff.coin} oid: {diff.oid} | {side} {diff.px} x {diff.sz} | {diff.user}")
97
                    elif diff.diff_type == pb.L4_ORDER_DIFF_TYPE_UPDATE:
98
                        if diff.oid in orders:
99
                            orders[diff.oid]["sz"] = diff.sz
100
                        print(f"  UPDATE {diff.coin} oid: {diff.oid} | {side} {diff.px} x {diff.sz} | {diff.user}")
101
                    elif diff.diff_type == pb.L4_ORDER_DIFF_TYPE_REMOVE:
102
                        orders.pop(diff.oid, None)
103
                        print(f"  REMOVE {diff.coin} oid: {diff.oid} | {side} {diff.px} | {diff.user}")
104

105
                print(f"\n  Resting orders tracked: {len(orders)} | Messages received: {msg_count}")
106

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

129
        # If we get here without error, break the retry loop
130
        break
131

132

133
def main():
134
    parser = argparse.ArgumentParser(description='Stream Hyperliquid typed per-order L4 book updates via gRPC')
135
    parser.add_argument('--coins', default='BTC', help='Comma-separated coin symbols to stream (e.g., BTC,ETH)')
136

137
    args = parser.parse_args()
138
    coins = [c.strip() for c in args.coins.split(',') if c.strip()]
139

140
    print(f"\n{'='*60}")
141
    print("Hyperliquid StreamL4BookUpdates Example")
142
    print(f"Endpoint: {GRPC_ENDPOINT}")
143
    print(f"{'='*60}")
144

145
    try:
146
        stream_l4_book_updates(coins)
147
    except Exception as e:
148
        print(f"\nError: {e}")
149
        import traceback
150
        traceback.print_exc()
151
        sys.exit(1)
152

153

154
if __name__ == "__main__":
155
    main()
156

Don't have an account yet?

Create your Quicknode endpoint in seconds and start building

Get started for free