ws_v2.md

websocket

-- import "github.com/bitfinexcom/bitfinex-api-go/v2/websocket"

Usage

const (
	ChanBook    = "book"
	ChanTrades  = "trades"
	ChanTicker  = "ticker"
	ChanCandles = "candles"
	ChanStatus  = "status"
)

Available channels

const (
	EventSubscribe   = "subscribe"
	EventUnsubscribe = "unsubscribe"
	EventPing        = "ping"
)

Events

const (
	ErrorCodeUnknownEvent         int = 10000
	ErrorCodeUnknownPair          int = 10001
	ErrorCodeUnknownBookPrecision int = 10011
	ErrorCodeUnknownBookLength    int = 10012
	ErrorCodeSubscriptionFailed   int = 10300
	ErrorCodeAlreadySubscribed    int = 10301
	ErrorCodeUnknownChannel       int = 10302
	ErrorCodeUnsubscribeFailed    int = 10400
	ErrorCodeNotSubscribed        int = 10401
)

error codes pulled from v2 docs & API usage

const DMSCancelOnDisconnect int = 4

DMSCancelOnDisconnect cancels session orders on disconnect.

const KEEP_ALIVE_TIMEOUT = 10

seconds to wait in between re-sending the keep alive ping

const MaxChannels = 25

const WS_READ_CAPACITY = 10

size of channel that the websocket reader routine pushes websocket updates into

const WS_WRITE_CAPACITY = 5000

size of channel that the websocket writer routine pulls from

var (
	ErrWSNotConnected     = fmt.Errorf("websocket connection not established")
	ErrWSAlreadyConnected = fmt.Errorf("websocket connection already established")
)

ws-specific errors

func ConvertBytesToJsonNumberArray

func ConvertBytesToJsonNumberArray(b []byte) ([]interface{}, error)

type Asynchronous

type Asynchronous interface {
	Connect() error
	Send(ctx context.Context, msg interface{}) error
	Listen() <-chan []byte
	Close()
	Done() <-chan error
}

Asynchronous interface decouples the underlying transport from API logic.

type AsynchronousFactory

type AsynchronousFactory interface {
	Create() Asynchronous
}

AsynchronousFactory provides an interface to re-create asynchronous transports during reconnect events.

func NewWebsocketAsynchronousFactory

func NewWebsocketAsynchronousFactory(parameters *Parameters) AsynchronousFactory

NewWebsocketAsynchronousFactory creates a new websocket factory with a given URL.

type AuthEvent

type AuthEvent struct {
	Event   string       `json:"event"`
	Status  string       `json:"status"`
	ChanID  int64        `json:"chanId,omitempty"`
	UserID  int64        `json:"userId,omitempty"`
	SubID   string       `json:"subId"`
	AuthID  string       `json:"auth_id,omitempty"`
	Message string       `json:"msg,omitempty"`
	Caps    Capabilities `json:"caps"`
}

type AuthState

type AuthState authState // prevent user construction of authStates

AuthState provides a typed authentication state.

const (
	NoAuthentication         AuthState = 0
	PendingAuthentication    AuthState = 1
	SuccessfulAuthentication AuthState = 2
	RejectedAuthentication   AuthState = 3
)

Authentication states

type BookFactory

type BookFactory struct {
}

func (*BookFactory) Build

func (f *BookFactory) Build(sub *subscription, objType string, raw []interface{}, b []byte) (interface{}, error)

func (*BookFactory) BuildSnapshot

func (f *BookFactory) BuildSnapshot(sub *subscription, raw [][]interface{}, b []byte) (interface{}, error)

func (BookFactory) Close

func (s BookFactory) Close()

Close is terminal. Do not call heartbeat after close.

func (BookFactory) ListenDisconnect

func (s BookFactory) ListenDisconnect() <-chan HeartbeatDisconnect

ListenDisconnect returns an error channel which receives a message when a heartbeat has expired a channel.

func (BookFactory) ResetAll

func (s BookFactory) ResetAll()

Removes all tracked subscriptions

func (BookFactory) ResetSocketSubscriptions

func (s BookFactory) ResetSocketSubscriptions(socketId SocketId) []*subscription

Reset clears all subscriptions assigned to the given socket ID, and returns a slice of the existing subscriptions prior to reset

type CandlesFactory

type CandlesFactory struct {
}

func (*CandlesFactory) Build

func (f *CandlesFactory) Build(sub *subscription, objType string, raw []interface{}, raw_bytes []byte) (interface{}, error)

func (*CandlesFactory) BuildSnapshot

func (f *CandlesFactory) BuildSnapshot(sub *subscription, raw [][]interface{}, raw_bytes []byte) (interface{}, error)

func (CandlesFactory) Close

func (s CandlesFactory) Close()

Close is terminal. Do not call heartbeat after close.

func (CandlesFactory) ListenDisconnect

func (s CandlesFactory) ListenDisconnect() <-chan HeartbeatDisconnect

ListenDisconnect returns an error channel which receives a message when a heartbeat has expired a channel.

func (CandlesFactory) ResetAll

func (s CandlesFactory) ResetAll()

Removes all tracked subscriptions

func (CandlesFactory) ResetSocketSubscriptions

func (s CandlesFactory) ResetSocketSubscriptions(socketId SocketId) []*subscription

Reset clears all subscriptions assigned to the given socket ID, and returns a slice of the existing subscriptions prior to reset

type Capabilities

type Capabilities struct {
	Orders    Capability `json:"orders"`
	Account   Capability `json:"account"`
	Funding   Capability `json:"funding"`
	History   Capability `json:"history"`
	Wallets   Capability `json:"wallets"`
	Withdraw  Capability `json:"withdraw"`
	Positions Capability `json:"positions"`
}

type Capability

type Capability struct {
	Read  int `json:"read"`
	Write int `json:"write"`
}

type Client

type Client struct {
	Authentication AuthState
}

Client provides a unified interface for users to interact with the Bitfinex V2 Websocket API. nolint:megacheck,structcheck

func New

func New() *Client

New creates a default client.

func NewWithAsyncFactory

func NewWithAsyncFactory(async AsynchronousFactory) *Client

NewWithAsyncFactory creates a new default client with a given asynchronous transport factory interface.

func NewWithAsyncFactoryNonce

func NewWithAsyncFactoryNonce(async AsynchronousFactory, nonce utils.NonceGenerator) *Client

NewWithAsyncFactoryNonce creates a new default client with a given asynchronous transport factory and nonce generator.

func NewWithParams

func NewWithParams(params *Parameters) *Client

NewWithParams creates a new default client with a given set of parameters.

func NewWithParamsAsyncFactory

func NewWithParamsAsyncFactory(params *Parameters, async AsynchronousFactory) *Client

NewWithParamsAsyncFactory creates a new default client with a given set of parameters and asynchronous transport factory interface.

func NewWithParamsAsyncFactoryNonce

func NewWithParamsAsyncFactoryNonce(params *Parameters, async AsynchronousFactory, nonce utils.NonceGenerator) *Client

NewWithParamsAsyncFactoryNonce creates a new client with a given set of parameters, asynchronous transport factory, and nonce generator interfaces.

func NewWithParamsNonce

func NewWithParamsNonce(params *Parameters, nonce utils.NonceGenerator) *Client

NewWithParamsNonce creates a new default client with a given set of parameters and nonce generator.

func (*Client) AvailableCapacity

func (c *Client) AvailableCapacity() int

Get the available capacity of the current websocket connections

func (*Client) CancelOnDisconnect

func (c *Client) CancelOnDisconnect(cxl bool) *Client

CancelOnDisconnect ensures all orders will be canceled if this API session is disconnected.

func (*Client) Close

func (c *Client) Close()

Close the websocket client which will cause for all active sockets to be exited and the Done() function to be called

func (*Client) CloseFundingCredit

func (c *Client) CloseFundingCredit(ctx context.Context, fundingOffer *fundingcredit.CancelRequest) error

CloseFundingCredit - cancels funding credit by ID. Emits an error if not authenticated.

func (*Client) CloseFundingLoan

func (c *Client) CloseFundingLoan(ctx context.Context, flcr *fundingloan.CancelRequest) error

CloseFundingLoan - cancels funding loan by ID. Emits an error if not authenticated.

func (*Client) Connect

func (c *Client) Connect() error

Connect to the Bitfinex API, this should only be called once.

func (*Client) ConnectionCount

func (c *Client) ConnectionCount() int

Gen the count of currently active websocket connections

func (*Client) Credentials

func (c *Client) Credentials(key string, secret string) *Client

Credentials assigns authentication credentials to a connection request.

func (*Client) EnableFlag

func (c *Client) EnableFlag(ctx context.Context, flag int) (string, error)

Submit a request to enable the given flag

func (*Client) GetAuthenticatedSocket

func (c *Client) GetAuthenticatedSocket() (*Socket, error)

Get the authenticated socket. Due to rate limitations there can only be one authenticated socket active at a time

func (*Client) GetOrderbook

func (c *Client) GetOrderbook(symbol string) (*Orderbook, error)

Retrieve the Orderbook for the given symbol which is managed locally. This requires ManageOrderbook=True and an active chanel subscribed to the given symbols orderbook

func (*Client) IsConnected

func (c *Client) IsConnected() bool

Returns true if the underlying asynchronous transport is connected to an endpoint.

func (*Client) Listen

func (c *Client) Listen() <-chan interface{}

Listen for all incoming api websocket messages When a websocket connection is terminated, the publisher channel will close.

func (*Client) LookupSubscription

func (c *Client) LookupSubscription(subID string) (*SubscriptionRequest, error)

Get a subscription request using a subscription ID

func (*Client) Send

func (c *Client) Send(ctx context.Context, msg interface{}) error

Send publishes a generic message to the Bitfinex API.

func (*Client) StartNewConnection

func (c *Client) StartNewConnection() error

Start a new websocket connection. This function is only exposed in case you want to implicitly add new connections otherwise connection management is already handled for you.

func (*Client) SubmitCancel

func (c *Client) SubmitCancel(ctx context.Context, ocr *order.CancelRequest) error

Submit a cancel request for an existing order

func (*Client) SubmitFundingCancel

func (c *Client) SubmitFundingCancel(ctx context.Context, fundingOffer *fundingoffer.CancelRequest) error

Submit a request to cancel and existing funding offer

func (*Client) SubmitFundingOffer

func (c *Client) SubmitFundingOffer(ctx context.Context, fundingOffer *fundingoffer.SubmitRequest) error

Submit a new funding offer request

func (*Client) SubmitOrder

func (c *Client) SubmitOrder(ctx context.Context, onr *order.NewRequest) error

Submit a request to create a new order

func (*Client) SubmitUpdateOrder

func (c *Client) SubmitUpdateOrder(ctx context.Context, our *order.UpdateRequest) error

Submit and update request to change an existing orders values

func (*Client) Subscribe

func (c *Client) Subscribe(ctx context.Context, req *SubscriptionRequest) (string, error)

Submit a request to subscribe to the given SubscriptionRequuest

func (*Client) SubscribeBook

func (c *Client) SubscribeBook(ctx context.Context, symbol string, precision common.BookPrecision, frequency common.BookFrequency, priceLevel int) (string, error)

Submit a subscription request for market data for the given symbol, at the given frequency, with the given precision, returning no more than priceLevels price entries. Default values are Precision0, Frequency0, and priceLevels=25.

func (*Client) SubscribeCandles

func (c *Client) SubscribeCandles(ctx context.Context, symbol string, resolution common.CandleResolution) (string, error)

Submit a subscription request to receive candle updates

func (*Client) SubscribeStatus

func (c *Client) SubscribeStatus(ctx context.Context, symbol string, sType common.StatusType) (string, error)

Submit a subscription request for status updates

func (*Client) SubscribeTicker

func (c *Client) SubscribeTicker(ctx context.Context, symbol string) (string, error)

Submit a request to receive ticker updates

func (*Client) SubscribeTrades

func (c *Client) SubscribeTrades(ctx context.Context, symbol string) (string, error)

Submit a request to receive trade updates

func (*Client) Unsubscribe

func (c *Client) Unsubscribe(ctx context.Context, id string) error

Unsubscribe from the existing subscription with the given id

type ConfEvent

type ConfEvent struct {
	Flags int `json:"flags"`
}

type ErrorEvent

type ErrorEvent struct {
	Code    int    `json:"code"`
	Message string `json:"msg"`

	// also contain members related to subscription reject
	SubID     string `json:"subId"`
	Channel   string `json:"channel"`
	ChanID    int64  `json:"chanId"`
	Symbol    string `json:"symbol"`
	Precision string `json:"prec,omitempty"`
	Frequency string `json:"freq,omitempty"`
	Key       string `json:"key,omitempty"`
	Len       string `json:"len,omitempty"`
	Pair      string `json:"pair"`
}

type FlagRequest

type FlagRequest struct {
	Event string `json:"event"`
	Flags int    `json:"flags"`
}

type Heartbeat

type Heartbeat struct {
}

type HeartbeatDisconnect

type HeartbeatDisconnect struct {
	Subscription *subscription
	Error        error
}

type InfoEvent

type InfoEvent struct {
	Version  float64      `json:"version"`
	ServerId string       `json:"serverId"`
	Platform PlatformInfo `json:"platform"`
	Code     int          `json:"code"`
	Msg      string       `json:"msg"`
}

type Orderbook

type Orderbook struct {
}

func (*Orderbook) Asks

func (ob *Orderbook) Asks() []book.Book

func (*Orderbook) Bids

func (ob *Orderbook) Bids() []book.Book

func (*Orderbook) Checksum

func (ob *Orderbook) Checksum() uint32

func (*Orderbook) SetWithSnapshot

func (ob *Orderbook) SetWithSnapshot(bs *book.Snapshot)

func (*Orderbook) Symbol

func (ob *Orderbook) Symbol() string

func (*Orderbook) UpdateWith

func (ob *Orderbook) UpdateWith(b *book.Book)

type Parameters

type Parameters struct {
	AutoReconnect     bool
	ReconnectInterval time.Duration
	ReconnectAttempts int

	ShutdownTimeout       time.Duration
	CapacityPerConnection int
	Logger                *logging.Logger

	ResubscribeOnReconnect bool

	HeartbeatTimeout time.Duration
	LogTransport     bool

	URL             string
	ManageOrderbook bool
}

Parameters defines adapter behavior.

func NewDefaultParameters

func NewDefaultParameters() *Parameters

type PlatformInfo

type PlatformInfo struct {
	Status int `json:"status"`
}

type RawEvent

type RawEvent struct {
	Data interface{}
}

type Socket

type Socket struct {
	Id SocketId
	Asynchronous
	IsConnected        bool
	ResetSubscriptions []*subscription
	IsAuthenticated    bool
}

type SocketId

type SocketId int

type StatsFactory

type StatsFactory struct {
}

func (*StatsFactory) Build

func (f *StatsFactory) Build(sub *subscription, objType string, raw []interface{}, raw_bytes []byte) (interface{}, error)

func (*StatsFactory) BuildSnapshot

func (f *StatsFactory) BuildSnapshot(sub *subscription, raw [][]interface{}, raw_bytes []byte) (interface{}, error)

func (StatsFactory) Close

func (s StatsFactory) Close()

Close is terminal. Do not call heartbeat after close.

func (StatsFactory) ListenDisconnect

func (s StatsFactory) ListenDisconnect() <-chan HeartbeatDisconnect

ListenDisconnect returns an error channel which receives a message when a heartbeat has expired a channel.

func (StatsFactory) ResetAll

func (s StatsFactory) ResetAll()

Removes all tracked subscriptions

func (StatsFactory) ResetSocketSubscriptions

func (s StatsFactory) ResetSocketSubscriptions(socketId SocketId) []*subscription

Reset clears all subscriptions assigned to the given socket ID, and returns a slice of the existing subscriptions prior to reset

type SubscribeEvent

type SubscribeEvent struct {
	SubID     string `json:"subId"`
	Channel   string `json:"channel"`
	ChanID    int64  `json:"chanId"`
	Symbol    string `json:"symbol"`
	Precision string `json:"prec,omitempty"`
	Frequency string `json:"freq,omitempty"`
	Key       string `json:"key,omitempty"`
	Len       string `json:"len,omitempty"`
	Pair      string `json:"pair"`
}

type SubscriptionRequest

type SubscriptionRequest struct {
	SubID string `json:"subId"`
	Event string `json:"event"`

	// authenticated
	APIKey      string   `json:"apiKey,omitempty"`
	AuthSig     string   `json:"authSig,omitempty"`
	AuthPayload string   `json:"authPayload,omitempty"`
	AuthNonce   string   `json:"authNonce,omitempty"`
	Filter      []string `json:"filter,omitempty"`
	DMS         int      `json:"dms,omitempty"` // dead man switch

	// unauthenticated
	Channel   string `json:"channel,omitempty"`
	Symbol    string `json:"symbol,omitempty"`
	Precision string `json:"prec,omitempty"`
	Frequency string `json:"freq,omitempty"`
	Key       string `json:"key,omitempty"`
	Len       string `json:"len,omitempty"`
	Pair      string `json:"pair,omitempty"`
}

func (*SubscriptionRequest) String

func (s *SubscriptionRequest) String() string

type SubscriptionSet

type SubscriptionSet []*subscription

SubscriptionSet is a typed version of an array of subscription pointers, intended to meet the sortable interface. We need to sort Reset()'s return values for tests with more than 1 subscription (range map order is undefined)

func (SubscriptionSet) Len

func (s SubscriptionSet) Len() int

func (SubscriptionSet) Less

func (s SubscriptionSet) Less(i, j int) bool

func (SubscriptionSet) RemoveByChannelId

func (s SubscriptionSet) RemoveByChannelId(chanId int64) SubscriptionSet

func (SubscriptionSet) RemoveBySubscriptionId

func (s SubscriptionSet) RemoveBySubscriptionId(subID string) SubscriptionSet

func (SubscriptionSet) Swap

func (s SubscriptionSet) Swap(i, j int)

type TickerFactory

type TickerFactory struct {
}

func (*TickerFactory) Build

func (f *TickerFactory) Build(sub *subscription, objType string, raw []interface{}, raw_bytes []byte) (interface{}, error)

func (*TickerFactory) BuildSnapshot

func (f *TickerFactory) BuildSnapshot(sub *subscription, raw [][]interface{}, raw_bytes []byte) (interface{}, error)

func (TickerFactory) Close

func (s TickerFactory) Close()

Close is terminal. Do not call heartbeat after close.

func (TickerFactory) ListenDisconnect

func (s TickerFactory) ListenDisconnect() <-chan HeartbeatDisconnect

ListenDisconnect returns an error channel which receives a message when a heartbeat has expired a channel.

func (TickerFactory) ResetAll

func (s TickerFactory) ResetAll()

Removes all tracked subscriptions

func (TickerFactory) ResetSocketSubscriptions

func (s TickerFactory) ResetSocketSubscriptions(socketId SocketId) []*subscription

Reset clears all subscriptions assigned to the given socket ID, and returns a slice of the existing subscriptions prior to reset

type TradeFactory

type TradeFactory struct {
}

func (*TradeFactory) Build

func (f *TradeFactory) Build(sub *subscription, objType string, raw []interface{}, raw_bytes []byte) (interface{}, error)

func (*TradeFactory) BuildSnapshot

func (f *TradeFactory) BuildSnapshot(sub *subscription, raw [][]interface{}, raw_bytes []byte) (interface{}, error)

func (TradeFactory) Close

func (s TradeFactory) Close()

Close is terminal. Do not call heartbeat after close.

func (TradeFactory) ListenDisconnect

func (s TradeFactory) ListenDisconnect() <-chan HeartbeatDisconnect

ListenDisconnect returns an error channel which receives a message when a heartbeat has expired a channel.

func (TradeFactory) ResetAll

func (s TradeFactory) ResetAll()

Removes all tracked subscriptions

func (TradeFactory) ResetSocketSubscriptions

func (s TradeFactory) ResetSocketSubscriptions(socketId SocketId) []*subscription

Reset clears all subscriptions assigned to the given socket ID, and returns a slice of the existing subscriptions prior to reset

type UnsubscribeEvent

type UnsubscribeEvent struct {
	Status string `json:"status"`
	ChanID int64  `json:"chanId"`
}

type UnsubscribeRequest

type UnsubscribeRequest struct {
	Event  string `json:"event"`
	ChanID int64  `json:"chanId"`
}

type WebsocketAsynchronousFactory

type WebsocketAsynchronousFactory struct {
}

WebsocketAsynchronousFactory creates a websocket-based asynchronous transport.

func (*WebsocketAsynchronousFactory) Create

func (w *WebsocketAsynchronousFactory) Create() Asynchronous

Create returns a new websocket transport.