Client

The main entry point for the SDK. EToroTrading wraps REST endpoints, WebSocket streaming, and instrument resolution behind a single async interface.

EToroTrading

class etoropy.EToroTrading(config=None, **kwargs)[source]

Bases: object

High-level async client for the eToro Public API.

Wraps REST endpoints, WebSocket streaming, and instrument resolution behind a single entry point. Supports both "demo" and "real" trading modes (set via EToroConfig.mode).

Use as an async context manager for automatic cleanup:

async with EToroTrading() as etoro:
    etoro.resolver.load_bundled_csv()
    await etoro.connect()
    rates = await etoro.get_rates(["AAPL"])
    ...
# WebSocket closed, HTTP client released

Events (register with etoro.on(event, handler)):

"price"          -> (symbol, instrument_id, WsInstrumentRate)
"order:update"   -> (WsPrivateEvent)
"connected"      -> ()
"disconnected"   -> ()
"error"          -> (Exception)
"ws:message"     -> (WsEnvelope)
Parameters:

  • config (EToroConfig | None (default: None)) – SDK configuration. When None, settings are read from ETORO_-prefixed environment variables.

  • kwargs (Any) – Forwarded to EToroConfig when config is None.

on(event, handler)[source]

Register handler for event.

Parameters:
Return type:

EToroTrading

off(event, handler)[source]

Unregister handler from event.

Parameters:
Return type:

EToroTrading

once(event, handler)[source]

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

Parameters:
Return type:

EToroTrading

remove_all_listeners(event=None)[source]

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

Parameters:

event (str | None (default: None))

Return type:

EToroTrading

async connect()[source]

Open the WebSocket connection and authenticate.

Must be called before stream_prices() or wait_for_order(). Emits the "connected" event on success.

Return type:

None

async disconnect()[source]

Close the WebSocket and release the HTTP client.

Emits the "disconnected" event. Called automatically when exiting the async with block.

Return type:

None

async buy_by_amount(symbol_or_id, amount, options=None)[source]

Open a long (buy) market order for a dollar amount.

Parameters:

  • symbol_or_id (str | int) – Instrument symbol ("AAPL") or numeric ID.

  • amount (float) – Dollar amount to invest.

  • options (OrderOptions | None (default: None)) – Optional leverage, stop-loss, and take-profit settings.

Return type:

OrderForOpenResponse

Returns:

The order response including the assigned order ID.

async buy_by_units(symbol_or_id, units, options=None)[source]

Open a long (buy) market order for a number of units.

Parameters:

  • symbol_or_id (str | int) – Instrument symbol or numeric ID.

  • units (float) – Number of units to buy.

  • options (OrderOptions | None (default: None)) – Optional leverage, stop-loss, and take-profit settings.

Return type:

OrderForOpenResponse

Returns:

The order response including the assigned order ID.

async sell_by_amount(symbol_or_id, amount, options=None)[source]

Open a short (sell) market order for a dollar amount.

Parameters:

  • symbol_or_id (str | int) – Instrument symbol or numeric ID.

  • amount (float) – Dollar amount to invest.

  • options (OrderOptions | None (default: None)) – Optional leverage, stop-loss, and take-profit settings.

Return type:

OrderForOpenResponse

Returns:

The order response including the assigned order ID.

async sell_by_units(symbol_or_id, units, options=None)[source]

Open a short (sell) market order for a number of units.

Parameters:

  • symbol_or_id (str | int) – Instrument symbol or numeric ID.

  • units (float) – Number of units to sell.

  • options (OrderOptions | None (default: None)) – Optional leverage, stop-loss, and take-profit settings.

Return type:

OrderForOpenResponse

Returns:

The order response including the assigned order ID.

async close_position(position_id, units_to_deduct=None)[source]

Close an open position.

Parameters:

  • position_id (int) – The position to close.

  • units_to_deduct (float | None (default: None)) – If given, perform a partial close.

Raises:

EToroValidationError – If position_id is not found in the portfolio.

Return type:

OrderForCloseResponse

async close_all_positions()[source]

Close all open positions in the portfolio (runs in parallel).

Return type:

list[OrderForCloseResponse]

async place_limit_order(symbol_or_id, is_buy, trigger_rate, amount, options=None)[source]

Place a limit order that triggers at trigger_rate.

Parameters:

  • symbol_or_id (str | int) – Instrument symbol or numeric ID.

  • is_buy (bool) – True for buy, False for sell.

  • trigger_rate (float) – Price at which the order triggers.

  • amount (float) – Dollar amount to invest.

  • options (OrderOptions | None (default: None)) – Optional leverage, stop-loss, and take-profit settings.

Return type:

TokenResponse

async cancel_order(order_id)[source]

Cancel a pending market order.

Parameters:

order_id (int)

Return type:

TokenResponse

async cancel_limit_order(order_id)[source]

Cancel a pending limit order.

Parameters:

order_id (int)

Return type:

TokenResponse

async cancel_all_orders()[source]

Cancel all pending market orders (runs in parallel).

Return type:

list[TokenResponse]

async cancel_all_limit_orders()[source]

Cancel all pending limit orders (runs in parallel).

Return type:

list[TokenResponse]

async get_portfolio()[source]

Fetch the full portfolio (positions, mirrors, pending orders).

Return type:

PortfolioResponse

async get_positions()[source]

Fetch all open positions.

Return type:

list[Position]

async get_pending_orders()[source]

Fetch all pending orders (limit orders and orders-for-open).

Return type:

list[PendingOrder]

async get_pnl()[source]

Fetch the current profit & loss summary.

Return type:

PnlResponse

async get_trade_history(min_date, page=None, page_size=None)[source]

Fetch closed trade history.

Parameters:

  • min_date (str) – Earliest date to include ("YYYY-MM-DD").

  • page (int | None (default: None)) – Page number (1-based).

  • page_size (int | None (default: None)) – Number of results per page.

Return type:

list[TradeHistoryEntry]

async get_rates(symbols_or_ids)[source]

Fetch live bid/ask rates for the given instruments.

Parameters:

symbols_or_ids (list[str | int])

Return type:

list[InstrumentRate]

async get_candles(symbol_or_id, interval, count, direction=CandleDirection.DESC)[source]

Fetch historical candlestick data.

Parameters:

  • symbol_or_id (str | int) – Instrument symbol or numeric ID.

  • interval (CandleInterval) – Candle interval (e.g. CandleInterval.ONE_DAY).

  • count (int) – Number of candles to fetch (max 1000).

  • direction (CandleDirection (default: <CandleDirection.DESC: 'desc'>)) – Sort direction (ASC or DESC).

Return type:

CandlesResponse

async stream_prices(symbols_or_ids, snapshot=True)[source]

Subscribe to real-time price updates for the given instruments.

Price ticks are emitted as "price" events with (symbol, instrument_id, WsInstrumentRate) arguments. Requires a prior call to connect().

Parameters:

  • symbols_or_ids (list[str | int]) – Instruments to stream.

  • snapshot (bool (default: True)) – If True, request an initial snapshot on subscribe.

Return type:

None

async stop_streaming_prices(symbols_or_ids)[source]

Unsubscribe from price updates for the given instruments.

Parameters:

symbols_or_ids (list[str | int])

Return type:

None

subscribe_to_private_events()[source]

Subscribe to private account events (order fills, cancellations, etc.).

Return type:

None

unsubscribe_from_private_events()[source]

Unsubscribe from private account events.

Return type:

None

async wait_for_order(order_id, timeout_s=30.0)[source]

Block until an order reaches a terminal state.

Uses a hybrid approach: listens for WebSocket private events and, after a 3-second grace period, starts polling the REST GET /orders/{id} endpoint as a fallback.

Parameters:

  • order_id (int) – The order ID to monitor.

  • timeout_s (float (default: 30.0)) – Maximum wait time in seconds.

Return type:

WsPrivateEvent

Returns:

The WsPrivateEvent describing the terminal state.

Raises:

EToroError – If the order fails, is cancelled, or times out.

async resolve_instrument(symbol_or_id)[source]

Resolve an instrument symbol to its numeric ID.

Parameters:

symbol_or_id (str | int)

Return type:

int

async preload_instruments(symbols)[source]

Pre-resolve a list of symbols so later lookups are instant.

Parameters:

symbols (list[str])

Return type:

None

async get_display_name(symbol_or_id)[source]

Return the human-readable display name for an instrument.

Parameters:

symbol_or_id (str | int)

Return type:

str

async get_instrument_info(symbol_or_id)[source]

Fetch full metadata for an instrument.

Parameters:

symbol_or_id (str | int)

Return type:

InstrumentInfo

async get_instrument_info_batch(symbols_or_ids)[source]

Fetch metadata for multiple instruments in one call.

Parameters:

symbols_or_ids (list[str | int])

Return type:

list[InstrumentInfo]

async preload_instrument_metadata(instrument_ids)[source]

Pre-fetch and cache display metadata for the given instrument IDs.

Parameters:

instrument_ids (list[int])

Return type:

None

OrderOptions

class etoropy.OrderOptions(leverage=1, stop_loss=None, take_profit=None, trailing_stop_loss=None)[source]

Bases: object

Optional parameters for market and limit orders.

Parameters:

  • leverage (int (default: 1)) – Leverage multiplier (1 = no leverage).

  • stop_loss (float | None (default: None)) – Stop-loss rate (absolute price level).

  • take_profit (float | None (default: None)) – Take-profit rate (absolute price level).

  • trailing_stop_loss (bool | None (default: None)) – Enable trailing stop-loss.

leverage: int = 1
stop_loss: float | None = None
take_profit: float | None = None
trailing_stop_loss: bool | None = None

InstrumentResolver

class etoropy.InstrumentResolver(market_data)[source]

Bases: object

Translate human-readable symbols to eToro integer instrument IDs.

Resolution goes through three tiers, in order:

  1. In-memory cache – populated from the bundled CSV (load_bundled_csv()) or via register(). Instant, no network call.

  2. API exact match – queries /market-data/search with the internalSymbolFull filter.

  3. API text search – free-text fallback on the same endpoint.

Every successful lookup is cached for the lifetime of the resolver, so repeated calls for the same symbol are free.

Example:

resolver = InstrumentResolver(market_data_client)
resolver.load_bundled_csv()
instrument_id = await resolver.resolve("AAPL")
info = await resolver.get_instrument_info("AAPL")
Parameters:

market_data (MarketDataClient) – The MarketDataClient used for API lookups.

register(symbol, instrument_id)[source]

Manually register a symbol-to-ID mapping.

Parameters:

  • symbol (str)

  • instrument_id (int)

Return type:

None

register_many(entries)[source]

Register multiple symbol-to-ID mappings at once.

Parameters:

entries (list[tuple[str, int]])

Return type:

None

load_from_csv(csv_content)[source]

Parse a CSV string and register all valid symbol mappings.

Parameters:

csv_content (str) – Raw CSV text (header + rows).

Return type:

int

Returns:

Number of symbols successfully loaded.

load_bundled_csv()[source]

Load the bundled instruments.csv (5,200+ symbols).

Return type:

int

Returns:

Number of symbols loaded.

async resolve(symbol_or_id)[source]

Resolve a symbol or ID to an instrument ID.

If symbol_or_id is already an int, it is returned as-is. Otherwise, the three-tier lookup (cache, exact match, text search) is applied.

Parameters:

symbol_or_id (str | int) – Ticker symbol ("AAPL") or numeric ID.

Return type:

int

Returns:

The eToro instrument ID.

Raises:

EToroValidationError – If the symbol cannot be resolved.

async get_instrument_info(symbol_or_id)[source]

Fetch display metadata for a single instrument.

Parameters:

symbol_or_id (str | int) – Ticker symbol or numeric ID.

Raises:

EToroValidationError – If metadata cannot be found.

Return type:

InstrumentInfo

async get_instrument_info_batch(instrument_ids)[source]

Fetch display metadata for multiple instruments.

Only uncached IDs trigger an API call.

Parameters:

instrument_ids (list[int])

Return type:

list[InstrumentInfo]

async get_display_name(symbol_or_id)[source]

Return the human-readable display name for an instrument.

Parameters:

symbol_or_id (str | int)

Return type:

str

async get_symbol_full(symbol_or_id)[source]

Return the full ticker symbol for an instrument.

Parameters:

symbol_or_id (str | int)

Return type:

str

get_cached_display_name(instrument_id)[source]

Return the cached display name, or None if not yet fetched.

Parameters:

instrument_id (int)

Return type:

str | None

get_cached_info(instrument_id)[source]

Return cached InstrumentInfo, or None.

Parameters:

instrument_id (int)

Return type:

InstrumentInfo | None

get_symbol(instrument_id)[source]

Return the cached symbol for an instrument ID, or None.

Parameters:

instrument_id (int)

Return type:

str | None

get_cached_id(symbol)[source]

Return the cached instrument ID for a symbol, or None.

Parameters:

symbol (str)

Return type:

int | None

async preload(symbols)[source]

Resolve a list of symbols so later lookups are instant.

Parameters:

symbols (list[str])

Return type:

None

async preload_metadata(instrument_ids)[source]

Pre-fetch and cache display metadata for the given IDs.

Parameters:

instrument_ids (list[int])

Return type:

None

clear_cache()[source]

Clear all cached symbol mappings and metadata.

Return type:

None

property size: int

Number of cached symbol-to-ID mappings.

property metadata_size: int

Number of cached instrument metadata entries.

InstrumentInfo

class etoropy.InstrumentInfo(instrument_id, display_name, symbol_full, instrument_type_id, exchange_id, instrument_type_sub_category_id=None, price_source='', has_expiration_date=False, is_internal_instrument=False, image_url=None)[source]

Bases: object

Metadata for a resolved instrument.

Parameters:

  • instrument_id (int) – eToro numeric instrument ID.

  • display_name (str) – Human-readable name (e.g. "Apple Inc").

  • symbol_full (str) – Ticker symbol (e.g. "AAPL").

  • instrument_type_id (int) – Instrument type category.

  • exchange_id (int) – Exchange identifier.

  • instrument_type_sub_category_id (int | None (default: None)) – Sub-category, if any.

  • price_source (str (default: '')) – Price feed source.

  • has_expiration_date (bool (default: False)) – Whether the instrument expires.

  • is_internal_instrument (bool (default: False)) – Whether it is an internal instrument.

  • image_url (str | None (default: None)) – URL to the instrument logo, if available.

instrument_id: int
display_name: str
symbol_full: str
instrument_type_id: int
exchange_id: int
instrument_type_sub_category_id: int | None = None
price_source: str = ''
has_expiration_date: bool = False
is_internal_instrument: bool = False
image_url: str | None = None