Symbols API

Symbol information lookup and search operations.

Access via client.symbols.

SymbolsAPI

`SymbolsAPI`

Symbol information and search operations.

Provides methods to list, retrieve, and search trading symbols.

Example

# List all available symbols
symbols = await client.symbols.list_all(account_id)

# Search for EUR pairs
eur_pairs = await client.symbols.search(account_id, "EUR")

# Get full details for specific symbols
eurusd = await client.symbols.get_by_id(account_id, 270)

`list_all(account_id, timeout=None)`

List all available symbols (lightweight info).

Returns basic symbol information without full trading parameters.
Use get_by_ids() for complete symbol details.

Parameters:

Name	Type	Description	Default
`account_id`	`int`	The cTID trader account ID.	required
`timeout`	`float \| None`	Request timeout (uses default if None).	`None`

Returns:

Type	Description
`list[SymbolInfo]`	List of SymbolInfo objects with basic symbol data.

Raises:

Type	Description
`APIError`	If request fails.
`CTraderConnectionTimeoutError`	If request times out.

`get_by_ids(account_id, symbol_ids, timeout=None)`

Get full symbol details by IDs.

Parameters:

Name	Type	Description	Default
`account_id`	`int`	The cTID trader account ID.	required
`symbol_ids`	`list[int]`	List of symbol IDs to retrieve.	required
`timeout`	`float \| None`	Request timeout (uses default if None).	`None`

Returns:

Type	Description
`list[Symbol]`	List of Symbol objects with full trading parameters.

Raises:

Type	Description
`APIError`	If request fails.
`CTraderConnectionTimeoutError`	If request times out.

`get_by_id(account_id, symbol_id, timeout=None)`

Get a single symbol by ID.

Parameters:

Name	Type	Description	Default
`account_id`	`int`	The cTID trader account ID.	required
`symbol_id`	`int`	The symbol ID.	required
`timeout`	`float \| None`	Request timeout (uses default if None).	`None`

Returns:

Type	Description
`Symbol`	Symbol with full trading parameters.

Raises:

Type	Description
`ValueError`	If symbol not found.
`APIError`	If request fails.
`CTraderConnectionTimeoutError`	If request times out.

`search(account_id, query, timeout=None)`

Search symbols by name.

Performs case-insensitive substring matching on symbol names.

Parameters:

Name	Type	Description	Default
`account_id`	`int`	The cTID trader account ID.	required
`query`	`str`	Search string (e.g., "EUR", "BTCUSD").	required
`timeout`	`float \| None`	Request timeout (uses default if None).	`None`

Returns:

Type	Description
`list[SymbolInfo]`	List of matching SymbolInfo objects.

Raises:

Type	Description
`APIError`	If request fails.
`CTraderConnectionTimeoutError`	If request times out.

Usage Examples

List All Symbols

# Get lightweight info for all symbols
symbols = await client.symbols.list_all(account_id)

for sym in symbols:
    print(f"{sym.symbol_id}: {sym.name}")

Get Symbol by ID

# Get full symbol details
symbol = await client.symbols.get_by_id(account_id, 270)

print(f"Digits: {symbol.digits}")
print(f"Lot size: {symbol.lot_size}")
print(f"Min volume: {symbol.min_volume}")
print(f"Max volume: {symbol.max_volume}")

Get Multiple Symbols

symbols = await client.symbols.get_by_ids(account_id, [270, 271, 272])

for sym in symbols:
    print(f"{sym.name}: {sym.digits} digits, lot_size={sym.lot_size}")

Search Symbols

# Find all EUR pairs
eur_pairs = await client.symbols.search(account_id, "EUR")

for sym in eur_pairs:
    print(sym.name)

Volume Conversion

The cTrader API uses volume in "cents" (smallest volume units). The relationship between lots and volume depends on the symbol's lot_size:

symbol = await client.symbols.get_by_id(account_id, 270)

# Lots to volume (for placing orders)
volume = symbol.lots_to_volume(1.0)    # e.g., 10000000 for standard forex

# Volume to lots (for display)
lots = symbol.volume_to_lots(10000000)   # e.g., 1.0 for standard forex

Note: Different instruments have different lot sizes. Always use the symbol's methods for conversion:

# Standard forex (lot_size=100000)
forex_symbol = await client.symbols.get_by_id(account_id, 1)  # EURUSD (lot_size=10000000)
forex_volume = forex_symbol.lots_to_volume(0.1)  # 1000000

# Index CFD might have different lot_size
index_symbol = await client.symbols.get_by_id(account_id, 270)  # US500 (lot_size=100)
index_volume = index_symbol.lots_to_volume(0.1)  # 10