WebSocket

Real-time streaming via the eToro WebSocket API.

WsClient

class etoropy.WsClient(options)

Bases: object

Low-level WebSocket client for the eToro streaming API.

Handles authentication, automatic reconnection with exponential backoff, heartbeat (via the websockets library’s built-in ping_interval), and topic subscription tracking.

Message dispatch uses a lightweight event-emitter pattern: on() / off() / once().

Emitted events:

"open"            -> ()                     # TCP connection established
"authenticated"   -> ()                     # auth handshake succeeded
"message"         -> (WsEnvelope)           # raw data envelope
"instrument:rate" -> (instrument_id, WsInstrumentRate)
"private:event"   -> (WsPrivateEvent)       # order status changes
"close"           -> (code, reason)          # connection closed
"error"           -> (Exception)

Parameters:

options (WsClientOptions) – Connection and reconnection settings.

on(event, handler)

Register handler for event.

Parameters:

• event (str)

• handler (Callable[..., Any])

Return type:

WsClient

off(event, handler)

Unregister handler from event.

Parameters:

• event (str)

• handler (Callable[..., Any])

Return type:

WsClient

once(event, handler)

Register handler for event, then auto-unregister after the first call.

Parameters:

• event (str)

• handler (Callable[..., Any])

Return type:

WsClient

remove_all_listeners(event=None)

Remove all listeners, or only those for event if given.

Parameters:

event (str | None (default: None))

Return type:

WsClient

property last_pong_at: float

Timestamp of the last pong received.

property is_connected: bool

Whether the WebSocket connection is open.

property is_authenticated: bool

Whether authentication has completed successfully.

async connect()

Open the WebSocket, authenticate, and start the receive loop.

Raises:

EToroAuthError – If authentication fails or times out.

Return type:

None

subscribe(topics, snapshot=False)

Subscribe to WebSocket topics.

Parameters:

• topics (list[str]) – Topic strings (e.g. ["instrument:1001", "private"]).

• snapshot (bool (default: False)) – Request an initial data snapshot on subscribe.

Return type:

None

unsubscribe(topics)

Unsubscribe from WebSocket topics.

Parameters:

topics (list[str])

Return type:

None

async disconnect()

Close the WebSocket connection gracefully.

Return type:

None

WsClientOptions

class etoropy.WsClientOptions(api_key='', user_key='', ws_url='wss://ws.etoro.com/ws', reconnect_attempts=10, reconnect_delay=1.0, auth_timeout=10.0, heartbeat_interval=30.0, heartbeat_timeout=10.0)

Bases: object

Connection options for WsClient.

Parameters:

• api_key (str (default: ''))

• user_key (str (default: ''))

• ws_url (str (default: 'wss://ws.etoro.com/ws'))

• reconnect_attempts (int (default: 10))

• reconnect_delay (float (default: 1.0))

• auth_timeout (float (default: 10.0))

• heartbeat_interval (float (default: 30.0))

• heartbeat_timeout (float (default: 10.0))

api_key: str = ''

user_key: str = ''

ws_url: str = 'wss://ws.etoro.com/ws'

reconnect_attempts: int = 10

reconnect_delay: float = 1.0

auth_timeout: float = 10.0

heartbeat_interval: float = 30.0

heartbeat_timeout: float = 10.0

Message Parser

class etoropy.ws.message_parser.ParsedInstrumentRate(instrument_id, rate)

Bases: object

Parameters:

• instrument_id (int)

• rate (WsInstrumentRate)

instrument_id: int

rate: WsInstrumentRate

class etoropy.ws.message_parser.ParsedPrivateEvent(event)

Bases: object

Parameters:

event (WsPrivateEvent)

event: WsPrivateEvent

class etoropy.ws.message_parser.ParsedMessage(type, data=None)

Bases: object

Parameters:

• type (str)

• data (ParsedInstrumentRate | ParsedPrivateEvent | Any (default: None))

type: str

data: ParsedInstrumentRate | ParsedPrivateEvent | Any = None

etoropy.ws.message_parser.parse_envelope(data)

Parameters:

data (str)

Return type:

WsEnvelope

etoropy.ws.message_parser.parse_messages(envelope)

Parse a WebSocket envelope into a list of typed messages.

Recognises two topic patterns:

• instrument:<id> – parsed as instrument:rate with a ParsedInstrumentRate payload.

• private – parsed as private:event with a ParsedPrivateEvent payload (order status changes).

Any other topic is returned as "unknown".

Parameters:

envelope (WsEnvelope)

Return type:

list[ParsedMessage]

Subscription Tracker

class etoropy.ws.WsSubscriptionTracker

Bases: object

Tracks active WebSocket topic subscriptions.

Used internally by WsClient to re-subscribe to all topics after an automatic reconnection.

add(topics)

Parameters:

topics (list[str])

Return type:

None

remove(topics)

Parameters:

topics (list[str])

Return type:

None

get_all()

Return type:

list[str]

has(topic)

Parameters:

topic (str)

Return type:

bool

clear()

Return type:

None

property size: int