Add Binance announcement WebSocket support

Author: 0x0001

v2/annouancement_service.go

@@ -0,0 +1,56 @@
+package binance
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/adshao/go-binance/v2/common"
+)
+
+// CreateAnnouncementParam creates a new WsAnnouncementParam for use with WsAnnouncementServe.
+//
+// Currently supports only WithRecvWindow option, which defaults to 6000 milliseconds
+// if not specified.
+func (c *Client) CreateAnnouncementParam(opts ...RequestOption) (WsAnnouncementParam, error) {
+	if c.APIKey == "" || c.SecretKey == "" {
+		return WsAnnouncementParam{}, errors.New("miss apikey or secret key")
+	}
+	kt := c.KeyType
+	if kt == "" {
+		kt = common.KeyTypeHmac
+	}
+	req := new(request)
+	for _, opt := range opts {
+		opt(req)
+	}
+	if req.recvWindow == 0 {
+		req.recvWindow = 6000
+	}
+
+	sf, err := common.SignFunc(kt)
+	if err != nil {
+		return WsAnnouncementParam{}, err
+	}
+	r := make([]byte, 16)
+	rand.Read(r)
+	random := hex.EncodeToString(r)
+	timestamp := time.Now().UnixMilli()
+	recvWindow := req.recvWindow
+
+	param := WsAnnouncementParam{
+		Random:     random,
+		Topic:      "com_announcement_en",
+		RecvWindow: recvWindow,
+		Timestamp:  timestamp,
+		ApiKey:     c.APIKey,
+	}
+	signature, err := sf(c.SecretKey, fmt.Sprintf("random=%s&topic=%s&recvWindow=%d&timestamp=%d", param.Random, param.Topic, param.RecvWindow, param.Timestamp))
+	if err != nil {
+		return WsAnnouncementParam{}, err
+	}
+	param.Signature = *signature
+	return param, nil
+}

v2/websocket.go

@@ -17,6 +17,7 @@ type ErrHandler func(err error)
 // WsConfig webservice configuration
 type WsConfig struct {
 	Endpoint string
+	Header   *http.Header
 	Proxy    *string
 }
 
@@ -42,7 +43,7 @@ var wsServe = func(cfg *WsConfig, handler WsHandler, errHandler ErrHandler) (don
 		EnableCompression: true,
 	}
 
-	c, _, err := Dialer.Dial(cfg.Endpoint, nil)
+	c, _, err := Dialer.Dial(cfg.Endpoint, *cfg.Header)
 	if err != nil {
 		return nil, nil, err
 	}

v2/websocket_service.go

@@ -2,7 +2,9 @@ package binance
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
+	"net/http"
 	"strings"
 	"time"
 
@@ -17,6 +19,7 @@ var (
 	BaseCombinedTestnetURL = "wss://stream.testnet.binance.vision/stream?streams="
 	BaseWsApiMainURL       = "wss://ws-api.binance.com:443/ws-api/v3"
 	BaseWsApiTestnetURL    = "wss://ws-api.testnet.binance.vision/ws-api/v3"
+	BaseWsAnnouncementURL  = "wss://api.binance.com/sapi/wss"
 
 	// WebsocketTimeout is an interval for sending ping/pong messages if WebsocketKeepalive is enabled
 	WebsocketTimeout = time.Second * 600
@@ -135,20 +138,20 @@ func WsCombinedPartialDepthServe(symbolLevels map[string]string, handler WsParti
 		event.Symbol = strings.ToUpper(symbol)
 		data := j.Get("data").MustMap()
 		event.LastUpdateID, _ = data["lastUpdateId"].(json.Number).Int64()
-		bidsLen := len(data["bids"].([]interface{}))
+		bidsLen := len(data["bids"].([]any))
 		event.Bids = make([]Bid, bidsLen)
 		for i := 0; i < bidsLen; i++ {
-			item := data["bids"].([]interface{})[i].([]interface{})
+			item := data["bids"].([]any)[i].([]any)
 			event.Bids[i] = Bid{
 				Price:    item[0].(string),
 				Quantity: item[1].(string),
 			}
 		}
-		asksLen := len(data["asks"].([]interface{}))
+		asksLen := len(data["asks"].([]any))
 		event.Asks = make([]Ask, asksLen)
 		for i := 0; i < asksLen; i++ {
 
-			item := data["asks"].([]interface{})[i].([]interface{})
+			item := data["asks"].([]any)[i].([]any)
 			event.Asks[i] = Ask{
 				Price:    item[0].(string),
 				Quantity: item[1].(string),
@@ -258,20 +261,20 @@ func wsCombinedDepthServe(endpoint string, handler WsDepthHandler, errHandler Er
 		event.Time, _ = data["E"].(json.Number).Int64()
 		event.LastUpdateID, _ = data["u"].(json.Number).Int64()
 		event.FirstUpdateID, _ = data["U"].(json.Number).Int64()
-		bidsLen := len(data["b"].([]interface{}))
+		bidsLen := len(data["b"].([]any))
 		event.Bids = make([]Bid, bidsLen)
 		for i := 0; i < bidsLen; i++ {
-			item := data["b"].([]interface{})[i].([]interface{})
+			item := data["b"].([]any)[i].([]any)
 			event.Bids[i] = Bid{
 				Price:    item[0].(string),
 				Quantity: item[1].(string),
 			}
 		}
-		asksLen := len(data["a"].([]interface{}))
+		asksLen := len(data["a"].([]any))
 		event.Asks = make([]Ask, asksLen)
 		for i := 0; i < asksLen; i++ {
 
-			item := data["a"].([]interface{})[i].([]interface{})
+			item := data["a"].([]any)[i].([]any)
 			event.Asks[i] = Ask{
 				Price:    item[0].(string),
 				Quantity: item[1].(string),
@@ -872,6 +875,80 @@ func WsApiInitReadWriteConn() (*websocket.Conn, error) {
 	return conn, err
 }
 
+type WsAnnouncementEvent struct {
+	CatalogID   int64  `json:"catalogId"`
+	CatalogName string `json:"catalogName"`
+	PublishDate int64  `json:"publishDate"`
+	Title       string `json:"title"`
+	Body        string `json:"body"`
+	Disclaimer  string `json:"disclaimer"`
+}
+
+type WsAnnouncementParam struct {
+	Random     string
+	Topic      string
+	RecvWindow int64
+	Timestamp  int64
+	Signature  string
+	ApiKey     string
+}
+type WsAnnouncementHandler func(event *WsAnnouncementEvent)
+
+// WsAnnouncementServe establishes a WebSocket connection to listen for Binance announcements.
+// See API documentation: https://developers.binance.com/docs/cms/announcement
+//
+// Parameters:
+//
+//	params - Should be created using client.CreateAnnouncementParam
+//	handler - Callback function to handle incoming announcement messages
+//	errHandler - Error callback function for connection errors
+//
+// Returns:
+//
+//	doneC - Channel that closes when the connection terminates
+//	stopC - Channel that can be closed to stop the connection
+//	err - Any initial connection error
+func WsAnnouncementServe(params WsAnnouncementParam, handler WsAnnouncementHandler, errHandler ErrHandler) (doneC, stopC chan struct{}, err error) {
+	if UseTestnet {
+		return nil, nil, errors.New("not support testnet")
+	}
+	endpoint := fmt.Sprintf("%s?random=%s&topic=%s&recvWindow=%d&timestamp=%d&signature=%s",
+		BaseWsAnnouncementURL, params.Random, params.Topic, params.RecvWindow, params.Timestamp, params.Signature,
+	)
+
+	cfg := newWsConfig(endpoint)
+	cfg.Header = &http.Header{}
+	cfg.Header.Add("X-MBX-APIKEY", params.ApiKey)
+	wsHandler := func(message []byte) {
+		event := struct {
+			Type  string `json:"type"`
+			Topic string `json:"topic"`
+			Data  string `json:"data"`
+		}{}
+
+		err := json.Unmarshal(message, &event)
+		if err != nil {
+			errHandler(err)
+			return
+		}
+
+		if event.Type != "DATA" {
+			errHandler(errors.New("type is not DATA: " + event.Type))
+			return
+		}
+
+		if event.Topic != "com_announcement_en" {
+			errHandler(errors.New("topic is not com_announcement_en: " + event.Topic))
+			return
+		}
+
+		e := new(WsAnnouncementEvent)
+		json.Unmarshal([]byte(event.Data), &e)
+		handler(e)
+	}
+	return wsServe(cfg, wsHandler, errHandler)
+}
+
 // getWsApiEndpoint return the base endpoint of the API WS according the UseTestnet flag
 func getWsApiEndpoint() string {
 	if UseTestnet {

v2/websocket_service_test.go

@@ -1678,3 +1678,45 @@ func (s *websocketServiceTestSuite) assertWsBookTickerEvent(e, a *WsBookTickerEv
 	r.Equal(e.BestAskPrice, a.BestAskPrice, "BestAskPrice")
 	r.Equal(e.BestAskQty, a.BestAskQty, "BestAskQty")
 }
+
+// https://binance-docs.github.io/apidocs/spot/en/#all-book-tickers-stream
+func (s *websocketServiceTestSuite) TestWsAnnouncementServe() {
+	data := []byte(`{
+  "type": "DATA",
+  "topic": "com_announcement_en",
+  "data": "{\"catalogId\":161,\"catalogName\":\"Delisting\",\"publishDate\":1753257631403,\"title\":\"Notice of...\",\"body\":\"This is...\",\"disclaimer\":\"Trade on-the-go...\"}"
+}`)
+	fakeErrMsg := "fake error"
+	s.mockWsServe(data, errors.New(fakeErrMsg))
+	defer s.assertWsServe()
+
+	doneC, stopC, err := WsAnnouncementServe(WsAnnouncementParam{}, func(event *WsAnnouncementEvent) {
+		e := &WsAnnouncementEvent{
+			CatalogID:   161,
+			CatalogName: "Delisting",
+			PublishDate: 1753257631403,
+			Title:       "Notice of...",
+			Body:        "This is...",
+			Disclaimer:  "Trade on-the-go...",
+		}
+		_ = e
+		s.assertWsAnnouncementEvent(e, event)
+	},
+		func(err error) {
+			s.r().EqualError(err, fakeErrMsg)
+		})
+
+	s.r().NoError(err)
+	stopC <- struct{}{}
+	<-doneC
+}
+
+func (s *websocketServiceTestSuite) assertWsAnnouncementEvent(e, a *WsAnnouncementEvent) {
+	r := s.r()
+	r.Equal(e.CatalogID, a.CatalogID, "CatalogID")
+	r.Equal(e.CatalogName, a.CatalogName, "CatalogName")
+	r.Equal(e.PublishDate, a.PublishDate, "PublishDate")
+	r.Equal(e.Title, a.Title, "Title")
+	r.Equal(e.Body, a.Body, "Body")
+	r.Equal(e.Disclaimer, a.Disclaimer, "Disclaimer")
+}