ws

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 25, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package ws provides a WebSocket client for live Polymarket order book and order updates.

Connecting

Basic (read-only order book): 

wsClient, err := ws.New(ws.Config{Host: ""})

With authentication for order notifications: 

wsClient, err := ws.New(ws.Config{
    Signer:      polyauth.NewSigner(privateKey),
    Credentials: &ws.Credentials{Key: "...", Secret: "...", Passphrase: "..."},
    ChainID:     137,
})

Subscriptions 

wsClient.SubscribeOrderBook("token-id")  // order book snapshots
wsClient.SubscribeOrders()               // order fill/status (requires auth)

Reading Updates 

for update := range wsClient.Channel { ... }

Disconnection

The client does NOT auto-reconnect. Handle ErrConnectionLost and re-subscribe.

Index

Constants

View Source 
const DefaultHost = "wss://ws-subscriptions-clob.polymarket.com"

Variables

This section is empty.

Functions

This section is empty.

Types

type BaseEvent 

type BaseEvent struct {
	// EventType identifies the specific event variant.
	EventType EventType `json:"event_type"`
}

BaseEvent is the common prefix of all WebSocket event payloads.

type BestBidAskEvent 

type BestBidAskEvent struct {
	BaseEvent
	// Market is the condition ID.
	Market string `json:"market"`
	// AssetID is the conditional token identifier.
	AssetID string `json:"asset_id"`
	// BestBid is the highest bid price.
	BestBid string `json:"best_bid"`
	// BestAsk is the lowest ask price.
	BestAsk string `json:"best_ask"`
	// Spread is the difference.
	Spread string `json:"spread"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

BestBidAskEvent carries top-of-book bid/ask update.

type BookEvent 

type BookEvent struct {
	BaseEvent
	// AssetID is the conditional token identifier.
	AssetID string `json:"asset_id"`
	// Bids are buy order levels.
	Bids []clob.OrderSummary `json:"bids"`
	// Asks are sell order levels.
	Asks []clob.OrderSummary `json:"asks"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

BookEvent carries an order book update.

type Channel 

type Channel string

Channel identifies the WebSocket subscription target. 

const (
	// ChannelMarket subscribes to order book updates.
	ChannelMarket Channel = "market"
	// ChannelUser subscribes to user-specific order and trade events.
	ChannelUser Channel = "user"
)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func New 

func New(config Config) *Client

New creates a CLOB WebSocket client.

func (*Client) Host 

func (c *Client) Host() string

Host returns the configured WebSocket host.

func (*Client) MarketURL 

func (c *Client) MarketURL() string

MarketURL returns the market-channel WebSocket URL.

func (*Client) SportsURL 

func (c *Client) SportsURL() string

SportsURL returns the public sports-channel WebSocket URL.

func (*Client) UserURL 

func (c *Client) UserURL() string

UserURL returns the user-channel WebSocket URL.

type Config 

type Config struct {
	Host       string
	HTTPClient *http.Client
}

Config configures a CLOB WebSocket client.

type Event 

type Event interface {
	// contains filtered or unexported methods
}

Event is the discriminated-union interface for WebSocket events.

func DecodeEvent 

func DecodeEvent(data []byte) (Event, error)

DecodeEvent decodes a raw CLOB WebSocket event payload into a typed Event.

type EventMessage 

type EventMessage struct {
	// ID is the message identifier.
	ID string `json:"id"`
	// Ticker is the sports ticker symbol.
	Ticker string `json:"ticker"`
	// Slug is the event slug.
	Slug string `json:"slug"`
	// Title is the event title.
	Title string `json:"title"`
	// Description is the event description.
	Description string `json:"description"`
}

EventMessage is the embedded sports event metadata.

type EventType 

type EventType string

EventType identifies the kind of WebSocket event. 

const (
	// EventTypeBook is an order book snapshot or delta.
	EventTypeBook EventType = "book"
	// EventTypePriceChange signals a price update.
	EventTypePriceChange EventType = "price_change"
	// EventTypeTickSizeChange signals a tick size update.
	EventTypeTickSizeChange EventType = "tick_size_change"
	// EventTypeLastTradePrice signals a new trade.
	EventTypeLastTradePrice EventType = "last_trade_price"
	// EventTypeOrder is an order status change notification.
	EventTypeOrder EventType = "order"
	// EventTypeTrade is a trade confirmation.
	EventTypeTrade EventType = "trade"
	// EventTypeBestBidAsk is the top-of-book update.
	EventTypeBestBidAsk EventType = "best_bid_ask"
	// EventTypeNewMarket signals market listing.
	EventTypeNewMarket EventType = "new_market"
	// EventTypeMarketResolved signals market resolution.
	EventTypeMarketResolved EventType = "market_resolved"
)

type LastTradePriceEvent 

type LastTradePriceEvent struct {
	BaseEvent
	// AssetID is the conditional token identifier.
	AssetID string `json:"asset_id"`
	// Market is the condition ID.
	Market string `json:"market"`
	// Price is the trade price.
	Price string `json:"price"`
	// Size is the trade quantity.
	Size string `json:"size"`
	// Side is the trade direction.
	Side clob.Side `json:"side"`
	// FeeRateBps is the fee rate in basis points.
	FeeRateBps string `json:"fee_rate_bps"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

LastTradePriceEvent carries the most recent trade price.

type MarketResolvedEvent 

type MarketResolvedEvent struct {
	BaseEvent
	// ID is the market condition identifier.
	ID string `json:"id"`
	// Question is the market question text.
	Question string `json:"question,omitempty"`
	// Market is the market name.
	Market string `json:"market"`
	// Slug is the URL-friendly slug.
	Slug string `json:"slug,omitempty"`
	// Description is the market description.
	Description string `json:"description,omitempty"`
	// AssetIDs lists the conditional token identifiers.
	AssetIDs []string `json:"asset_ids"`
	// Outcomes lists the outcome labels.
	Outcomes []string `json:"outcomes,omitempty"`
	// WinningAssetID is the resolved winning token ID.
	WinningAssetID string `json:"winning_asset_id"`
	// WinningOutcome is the resolved outcome label.
	WinningOutcome string `json:"winning_outcome"`
	// EventMessage is optional embedded event metadata.
	EventMessage *EventMessage `json:"event_message,omitempty"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

MarketResolvedEvent signals a market has been resolved.

type MarketSubscription 

type MarketSubscription struct {
	// Type must be ChannelMarket.
	Type Channel `json:"type"`
	// Operation is "subscribe" or "unsubscribe".
	Operation string `json:"operation,omitempty"`
	// Markets optionally limits to specific condition IDs.
	Markets []string `json:"markets,omitempty"`
	// AssetIDs optionally limits to specific token IDs.
	AssetIDs []string `json:"asset_ids,omitempty"`
	// InitialDump requests a full order book on subscribe.
	InitialDump bool `json:"initial_dump,omitempty"`
	// CustomFeatureEnabled enables extended features.
	CustomFeatureEnabled bool `json:"custom_feature_enabled,omitempty"`
}

MarketSubscription is sent to subscribe to market-channel events.

type NewMarketEvent 

type NewMarketEvent struct {
	BaseEvent
	// ID is the market condition identifier.
	ID string `json:"id"`
	// Question is the market question text.
	Question string `json:"question"`
	// Market is the market name.
	Market string `json:"market"`
	// Slug is the URL-friendly slug.
	Slug string `json:"slug"`
	// Description is the market description.
	Description string `json:"description"`
	// AssetIDs lists the conditional token identifiers.
	AssetIDs []string `json:"asset_ids"`
	// Outcomes lists the outcome labels.
	Outcomes []string `json:"outcomes"`
	// EventMessage is optional embedded event metadata.
	EventMessage *EventMessage `json:"event_message,omitempty"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

NewMarketEvent signals a new market listing via WebSocket.

type OrderEvent 

type OrderEvent struct {
	BaseEvent
	// OrderID is the affected order identifier.
	OrderID string `json:"order_id"`
	// AssetID is the conditional token identifier.
	AssetID string `json:"asset_id"`
	// Market is the condition ID.
	Market string `json:"market"`
	// Price is the order price.
	Price string `json:"price"`
	// Size is the order quantity.
	Size string `json:"size"`
	// Side is the order direction.
	Side clob.Side `json:"side"`
	// Status is the updated order status.
	Status OrderStatus `json:"status"`
	// Reason explains why the order changed state.
	Reason string `json:"reason,omitempty"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

OrderEvent carries an order status change (fill, cancel, expiry).

type OrderStatus 

type OrderStatus string

OrderStatus identifies the lifecycle state of an order. 

const (
	// OrderStatusOpen is an active unfilled order.
	OrderStatusOpen OrderStatus = "OPEN"
	// OrderStatusCanceled has been canceled by the user.
	OrderStatusCanceled OrderStatus = "CANCELED"
	// OrderStatusFilled is fully matched.
	OrderStatusFilled OrderStatus = "FILLED"
	// OrderStatusExpired has passed its expiry time.
	OrderStatusExpired OrderStatus = "EXPIRED"
	// OrderStatusRetrying is being re-submitted after failure.
	OrderStatusRetrying OrderStatus = "RETRYING"
	// OrderStatusFailed was rejected or failed processing.
	OrderStatusFailed OrderStatus = "FAILED"
)

type PriceChangeEvent 

type PriceChangeEvent struct {
	BaseEvent
	// AssetID is the conditional token identifier.
	AssetID string `json:"asset_id"`
	// Price is the trade price.
	Price string `json:"price"`
	// Size is the trade quantity.
	Size string `json:"size"`
	// Side is the trade direction.
	Side clob.Side `json:"side"`
}

PriceChangeEvent carries a single trade price update.

type SportsResultUpdate 

type SportsResultUpdate struct {
	// Slug is the sports match slug.
	Slug string `json:"slug"`
	// Live is true when the match is live.
	Live bool `json:"live"`
	// Ended is true when the match has ended.
	Ended bool `json:"ended"`
	// Score is the current score.
	Score string `json:"score"`
	// Period is the current match period.
	Period string `json:"period"`
	// Elapsed is the elapsed match time.
	Elapsed string `json:"elapsed"`
	// LastUpdate is the last update timestamp.
	LastUpdate clob.Time `json:"last_update"`
}

SportsResultUpdate is a real-time sports match update from the sports channel.

type TickSizeChangeEvent 

type TickSizeChangeEvent struct {
	BaseEvent
	// AssetID is the conditional token identifier.
	AssetID string `json:"asset_id"`
	// Market is the condition ID.
	Market string `json:"market"`
	// OldTickSize is the previous tick size.
	OldTickSize clob.TickSize `json:"old_tick_size"`
	// NewTickSize is the updated tick size.
	NewTickSize clob.TickSize `json:"new_tick_size"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

TickSizeChangeEvent carries a tick size update notification.

type TradeEvent 

type TradeEvent struct {
	BaseEvent
	// TradeID is the trade identifier.
	TradeID string `json:"trade_id"`
	// AssetID is the conditional token identifier.
	AssetID string `json:"asset_id"`
	// Market is the condition ID.
	Market string `json:"market"`
	// Price is the execution price.
	Price string `json:"price"`
	// Size is the matched quantity.
	Size string `json:"size"`
	// Side is the trade direction.
	Side clob.Side `json:"side"`
	// Status is the trade processing status.
	Status TradeStatus `json:"status"`
	// Timestamp is the event time.
	Timestamp string `json:"timestamp"`
}

TradeEvent carries a matched trade notification.

type TradeStatus 

type TradeStatus string

TradeStatus identifies the processing state of a trade. 

const (
	// TradeStatusMatched is a completed trade.
	TradeStatusMatched TradeStatus = "matched"
	// TradeStatusRetrying is being re-submitted.
	TradeStatusRetrying TradeStatus = "RETRYING"
	// TradeStatusFailed was rejected or failed processing.
	TradeStatusFailed TradeStatus = "FAILED"
)

type UserSubscription 

type UserSubscription struct {
	// Type must be ChannelUser.
	Type Channel `json:"type"`
	// Auth contains WebSocket credentials.
	Auth clob.WSAuth `json:"auth"`
	// Markets optionally scopes subscriptions.
	Markets []string `json:"markets,omitempty"`
	// Operation is "subscribe" or "unsubscribe".
	Operation string `json:"operation,omitempty"`
}

UserSubscription is sent to subscribe to user-channel events.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.