Real-Time Push

The Go SDK's PushClient maintains a persistent WebSocket connection to the Tiger OpenAPI server. It supports automatic reconnection, heartbeat keep-alive, and callback-based delivery of market data and account events.

Quick Start

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/tigerfintech/openapi-sdks/go/config"
	"github.com/tigerfintech/openapi-sdks/go/push"
)

func main() {
	cfg, err := config.NewClientConfig(
		config.WithPropertiesFile("tiger_openapi_config.properties"),
	)
	if err != nil {
		log.Fatal(err)
	}

	pc := push.NewPushClient(cfg)

	// Register all callbacks before connecting
	pc.SetCallbacks(push.Callbacks{
		OnConnect: func() {
			fmt.Println("Connected to push server")
		},
		OnDisconnect: func() {
			fmt.Println("Disconnected from push server")
		},
		OnError: func(err error) {
			fmt.Println("Push error:", err)
		},
		OnKickout: func(reason string) {
			fmt.Println("Kicked out, reason:", reason)
		},
		OnQuote: func(data *push.QuoteData) {
			fmt.Printf("Quote: %s  price=%.2f  volume=%d\n",
				data.Symbol, data.LatestPrice, data.Volume)
		},
		OnTick: func(data *push.TickData) {
			fmt.Printf("Tick: %s  price=%.2f  size=%d\n",
				data.Symbol, data.Price, data.Size)
		},
		OnOrder: func(data *push.OrderData) {
			fmt.Printf("Order update: id=%d  status=%s\n",
				data.ID, data.Status)
		},
		OnAsset: func(data *push.AssetData) {
			fmt.Println("Asset change received")
		},
		OnPosition: func(data *push.PositionData) {
			fmt.Println("Position change received")
		},
		OnTransaction: func(data *push.TransactionData) {
			fmt.Println("Transaction received")
		},
	})

	// Establish the WebSocket connection
	if err := pc.Connect(); err != nil {
		log.Fatal(err)
	}
	defer pc.Disconnect()

	// Subscribe to market data
	pc.SubscribeQuote([]string{"AAPL", "TSLA"})
	pc.SubscribeTick([]string{"AAPL"})
	pc.SubscribeDepth([]string{"AAPL"})
	pc.SubscribeKline([]string{"AAPL"})

	// Subscribe to account events (pass "" to use the account from config)
	pc.SubscribeAsset("")
	pc.SubscribeOrder("")
	pc.SubscribePosition("")
	pc.SubscribeTransaction("")

	// Keep the program alive to receive push data
	time.Sleep(60 * time.Second)
}

Client Lifecycle

NewPushClient

func NewPushClient(cfg *config.ClientConfig, opts ...PushClientOption) *PushClient

Creates a new PushClient. The client is idle until Connect() is called.

Parameter	Type	Description
`cfg`	*config.ClientConfig	Loaded configuration (credentials, server URL)
`opts`	...PushClientOption	Optional functional options

SetCallbacks

func (pc *PushClient) SetCallbacks(cb Callbacks)

Registers the callback functions that will be invoked when push events arrive. Call this before Connect().

Connect

func (pc *PushClient) Connect() error

Opens the WebSocket connection and starts the background receive loop. Blocks until the handshake is complete.

if err := pc.Connect(); err != nil {
    log.Fatal("failed to connect:", err)
}

Disconnect

func (pc *PushClient) Disconnect() error

Gracefully closes the WebSocket connection and stops all background goroutines.

defer pc.Disconnect()

State

func (pc *PushClient) State() ConnectionState

Returns the current connection state (Connecting, Connected, Disconnected).

fmt.Println("Current state:", pc.State())

Callbacks Reference

The Callbacks struct holds all event handler functions. All fields are optional — assign only the ones you need.

Field	Signature	Triggered when
`OnConnect`	`func()`	Connection established
`OnDisconnect`	`func()`	Connection closed
`OnError`	`func(error)`	A transport or protocol error occurs
`OnKickout`	`func(string)`	Server forces disconnection
`OnQuote`	`func(*QuoteData)`	Real-time quote update
`OnTick`	`func(*TickData)`	Trade tick received
`OnDepth`	`func(*DepthData)`	Order-book depth update
`OnOption`	`func(*OptionData)`	Option quote update
`OnFuture`	`func(*FutureData)`	Futures quote update
`OnKline`	`func(*KlineData)`	K-line bar update
`OnAsset`	`func(*AssetData)`	Account asset change
`OnPosition`	`func(*PositionData)`	Position change
`OnOrder`	`func(*OrderData)`	Order status change
`OnTransaction`	`func(*TransactionData)`	Fill / execution received

pc.SetCallbacks(push.Callbacks{
    OnQuote: func(data *push.QuoteData) {
        fmt.Printf("%s: %.2f (%.2f%%)\n",
            data.Symbol, data.LatestPrice, data.ChangeRatio*100)
    },
    OnDepth: func(data *push.DepthData) {
        fmt.Printf("Depth update for %s: %d bid levels\n",
            data.Symbol, len(data.Bids))
    },
    OnKline: func(data *push.KlineData) {
        fmt.Printf("Kline %s: O=%.2f H=%.2f L=%.2f C=%.2f\n",
            data.Symbol, data.Open, data.High, data.Low, data.Close)
    },
    OnError: func(err error) {
        log.Println("push error:", err)
    },
})

Market Data Subscriptions

SubscribeQuote / UnsubscribeQuote

func (pc *PushClient) SubscribeQuote(symbols []string)
func (pc *PushClient) UnsubscribeQuote(symbols []string)

Subscribe to or unsubscribe from real-time best-bid/ask and last-price updates.

pc.SubscribeQuote([]string{"AAPL", "TSLA", "MSFT"})
// Later, remove one symbol
pc.UnsubscribeQuote([]string{"TSLA"})

SubscribeTick / UnsubscribeTick

func (pc *PushClient) SubscribeTick(symbols []string)
func (pc *PushClient) UnsubscribeTick(symbols []string)

Subscribe to tick-by-tick trade data (each individual executed trade).

pc.SubscribeTick([]string{"AAPL"})
pc.UnsubscribeTick([]string{"AAPL"})

SubscribeDepth / UnsubscribeDepth

func (pc *PushClient) SubscribeDepth(symbols []string)
func (pc *PushClient) UnsubscribeDepth(symbols []string)

Subscribe to Level 2 order-book depth updates (up to 10 bid/ask levels).

pc.SubscribeDepth([]string{"AAPL"})
pc.UnsubscribeDepth([]string{"AAPL"})

SubscribeOption / UnsubscribeOption

func (pc *PushClient) SubscribeOption(symbols []string)
func (pc *PushClient) UnsubscribeOption(symbols []string)

Subscribe to real-time option quote updates using OCC-style identifiers.

pc.SubscribeOption([]string{"AAPL  250117C00150000"})
pc.UnsubscribeOption([]string{"AAPL  250117C00150000"})

SubscribeFuture / UnsubscribeFuture

func (pc *PushClient) SubscribeFuture(symbols []string)
func (pc *PushClient) UnsubscribeFuture(symbols []string)

Subscribe to real-time futures quote updates.

pc.SubscribeFuture([]string{"ES2506", "NQ2506"})
pc.UnsubscribeFuture([]string{"ES2506"})

SubscribeKline / UnsubscribeKline

func (pc *PushClient) SubscribeKline(symbols []string)
func (pc *PushClient) UnsubscribeKline(symbols []string)

Subscribe to real-time K-line bar updates (1-minute bars by default).

pc.SubscribeKline([]string{"AAPL"})
pc.UnsubscribeKline([]string{"AAPL"})

Account Subscriptions

SubscribeAsset / UnsubscribeAsset

func (pc *PushClient) SubscribeAsset(account string)
func (pc *PushClient) UnsubscribeAsset()

Subscribe to account asset changes (cash balance, net liquidation value, buying power).

// Pass "" to use the account in the config file
pc.SubscribeAsset("")
// Or specify an explicit account
pc.SubscribeAsset("DU123456")

pc.UnsubscribeAsset()

SubscribePosition / UnsubscribePosition

func (pc *PushClient) SubscribePosition(account string)
func (pc *PushClient) UnsubscribePosition()

Subscribe to position updates (new position opened, quantity changed, position closed).

pc.SubscribePosition("")
pc.UnsubscribePosition()

SubscribeOrder / UnsubscribeOrder

func (pc *PushClient) SubscribeOrder(account string)
func (pc *PushClient) UnsubscribeOrder()

Subscribe to order status changes (submitted, partially filled, fully filled, cancelled).

pc.SubscribeOrder("")
pc.UnsubscribeOrder()

SubscribeTransaction / UnsubscribeTransaction

func (pc *PushClient) SubscribeTransaction(account string)
func (pc *PushClient) UnsubscribeTransaction()

Subscribe to individual fill (execution) events.

pc.SubscribeTransaction("")
pc.UnsubscribeTransaction()

Complete Subscription Reference

// Market data subscriptions
pc.SubscribeQuote([]string{"AAPL", "TSLA"})
pc.SubscribeTick([]string{"AAPL"})
pc.SubscribeDepth([]string{"AAPL"})
pc.SubscribeOption([]string{"AAPL  250117C00150000"})
pc.SubscribeFuture([]string{"ES2506"})
pc.SubscribeKline([]string{"AAPL"})

// Account subscriptions
pc.SubscribeAsset("")
pc.SubscribePosition("")
pc.SubscribeOrder("")
pc.SubscribeTransaction("")

// Unsubscribe from market data
pc.UnsubscribeQuote([]string{"TSLA"})
pc.UnsubscribeTick([]string{"AAPL"})
pc.UnsubscribeDepth([]string{"AAPL"})
pc.UnsubscribeOption([]string{"AAPL  250117C00150000"})
pc.UnsubscribeFuture([]string{"ES2506"})
pc.UnsubscribeKline([]string{"AAPL"})

// Unsubscribe from account events
pc.UnsubscribeAsset()
pc.UnsubscribePosition()
pc.UnsubscribeOrder()
pc.UnsubscribeTransaction()