Models

High-level Pythonic models for API requests and responses.

Request Models

Request for placing a new order.

NewOrderRequest

Bases: FrozenModel

Request to place a new order.

Attributes:

Name	Type	Description
symbol_id	int	Symbol to trade.
side	OrderSide	Order direction (BUY/SELL).
volume	int	Volume in cents. Will yield lots = volume / symbol.lot_size
order_type	OrderType	Type of order.
limit_price	float | None	Limit price for LIMIT/STOP_LIMIT orders.
stop_price	float | None	Stop trigger price for STOP/STOP_LIMIT orders.
stop_loss	float | None	Stop loss price.
take_profit	float | None	Take profit price.
time_in_force	TimeInForce	Order duration type.
expiration_timestamp	datetime | None	Expiration for GTD orders.
position_id	int | None	Position ID to close (for closing orders).
client_order_id	str	User-defined order ID.
label	str	User-defined label (max 100 chars).
comment	str	User-defined comment (max 256 chars).
base_slippage_price	float | None	Base price for slippage calculation.
slippage_in_points	int | None	Max allowed slippage.
guaranteed_stop_loss	bool	Enable guaranteed stop loss.
relative_stop_loss	float | None	Stop loss distance in price units.
relative_take_profit	float | None	Take profit distance in price units.
trailing_stop_loss	bool	Enable trailing stop loss.
stop_trigger_method	StopTriggerMethod | None	How to trigger stop orders.

to_proto(account_id)

Convert to proto message.

Parameters:

Name	Type	Description	Default
account_id	int	The trading account ID.	required

Returns:

Type	Description
ProtoOANewOrderReq	Proto request message.

Example:

from ctrader_api_client.models import NewOrderRequest
from ctrader_api_client.enums import OrderType, OrderSide, TimeInForce

# Get symbol for volume conversion
symbol = await client.symbols.get_by_id(account_id, 270)

# Market order
market_order = NewOrderRequest(
    symbol_id=270,
    order_type=OrderType.MARKET,
    side=OrderSide.BUY,
    volume=symbol.lots_to_volume(0.01),  # 0.01 lots
)

# Limit order with SL/TP
limit_order = NewOrderRequest(
    symbol_id=270,
    order_type=OrderType.LIMIT,
    side=OrderSide.BUY,
    volume=symbol.lots_to_volume(0.1),
    limit_price=5000.0,
    stop_loss=4950.0,
    take_profit=5100.0,
    time_in_force=TimeInForce.GOOD_TILL_CANCEL,
)

# Order with relative SL/TP (distance from entry price)
relative_order = NewOrderRequest(
    symbol_id=270,
    order_type=OrderType.MARKET,
    side=OrderSide.BUY,
    volume=symbol.lots_to_volume(0.1),
    relative_stop_loss=50.0,   # 50 price units below entry
    relative_take_profit=100.0,  # 100 price units above entry
)

# Stop order
stop_order = NewOrderRequest(
    symbol_id=270,
    order_type=OrderType.STOP,
    side=OrderSide.SELL,
    volume=symbol.lots_to_volume(0.1),
    stop_price=4900.0,
)

AmendOrderRequest

Bases: FrozenModel

Request to modify a pending order.

Only include fields you want to change.

Attributes:

Name	Type	Description
order_id	int	The order to modify.
volume	int | None	New volume in cents.
limit_price	float | None	New limit price.
stop_price	float | None	New stop trigger price.
stop_loss	float | None	New stop loss price.
take_profit	float | None	New take profit price.
expiration_timestamp	datetime | None	New expiration time.
slippage_in_points	int | None	New max slippage.
trailing_stop_loss	bool | None	Enable/disable trailing stop.
guaranteed_stop_loss	bool | None	Enable/disable guaranteed stop.
relative_stop_loss	float | None	New relative stop loss in price units.
relative_take_profit	float | None	New relative take profit in price units.
stop_trigger_method	StopTriggerMethod | None	New trigger method.

to_proto(account_id)

Convert to proto message.

Parameters:

Name	Type	Description	Default
account_id	int	The trading account ID.	required

Returns:

Type	Description
ProtoOAAmendOrderReq	Proto request message.

ClosePositionRequest

Bases: FrozenModel

Request to close a position.

Attributes:

Name	Type	Description
position_id	int	The position to close.
volume	int	Volume to close in cents. Use position's full volume for complete close, or partial volume for partial close.

to_proto(account_id)

Convert to proto message.

Parameters:

Name	Type	Description	Default
account_id	int	The trading account ID.	required

Returns:

Type	Description
ProtoOAClosePositionReq	Proto request message.

Example:

from ctrader_api_client.models import ClosePositionRequest

# Get position to know its volume
positions = await client.trading.get_open_positions(account_id)
position = positions[0]

# Close entire position
close_all = ClosePositionRequest(
    position_id=position.position_id,
    volume=position.volume,  # Must match position volume for full close
)

# Partial close - close half of the position
symbol = await client.symbols.get_by_id(account_id, position.symbol_id)
current_lots = symbol.volume_to_lots(position.volume)
partial_close = ClosePositionRequest(
    position_id=position.position_id,
    volume=symbol.lots_to_volume(current_lots / 2),  # Close half
)

AmendPositionRequest

Bases: FrozenModel

Request to modify a position's stop loss and take profit.

Attributes:

Name	Type	Description
position_id	int	The position to modify.
stop_loss	float | None	New stop loss price, or None to remove.
take_profit	float | None	New take profit price, or None to remove.
trailing_stop_loss	bool	Enable/disable trailing stop.
guaranteed_stop_loss	bool	Enable/disable guaranteed stop.
stop_loss_trigger_method	StopTriggerMethod | None	Trigger method for stop loss.

to_proto(account_id)

Convert to proto message.

Parameters:

Name	Type	Description	Default
account_id	int	The trading account ID.	required

Returns:

Type	Description
ProtoOAAmendPositionSLTPReq	Proto request message.

Response/Data Models

Position

Bases: FrozenModel

An open or closed trading position.

Represents a position with all trading details including entry price,
stop loss, take profit, and P&L information.

Attributes:

Name	Type	Description
position_id	int	Unique position identifier.
symbol_id	int	The symbol being traded.
side	OrderSide	Position direction (BUY/SELL).
volume	int	Position volume in cents.
entry_price	float	Entry price as float from API.
status	PositionStatus	Current position status.
open_timestamp	datetime	When the position was opened.
money_digits	int	Decimal places for monetary values.
stop_loss	float | None	Stop loss price as float, or None if not set.
take_profit	float | None	Take profit price as float, or None if not set.
trailing_stop_loss	bool	Whether trailing stop is enabled.
guaranteed_stop_loss	bool	Whether guaranteed stop loss is enabled.
stop_loss_trigger_method	StopTriggerMethod	Method for triggering stop loss.
swap	float	Accumulated swap (raw integer).
commission	float	Total commission paid (raw integer).
used_margin	float	Margin allocated to position (raw integer).
margin_rate	float | None	Margin rate for the position.
label	str	User-defined label.
comment	str	User-defined comment.
last_update_timestamp	datetime | None	When the position was last updated.
close_timestamp	datetime | None	When the position was closed, if applicable.

from_proto(proto)

Create Position from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOAPosition	The proto message to convert.	required

Returns:

Type	Description
Position	A new Position instance.

Order

Bases: FrozenModel

A trading order (pending or historical).

Represents an order with all details including type, prices, volume,
and execution information.

Attributes:

Name	Type	Description
order_id	int	Unique order identifier.
symbol_id	int	The symbol being traded.
side	OrderSide	Order direction (BUY/SELL).
order_type	OrderType	Type of order (MARKET, LIMIT, STOP, etc.).
status	OrderStatus	Current order status.
volume	int	Order volume in cents.
time_in_force	TimeInForce	Order duration type.
open_timestamp	datetime	When the order was created.
limit_price	float | None	Limit price as float, or None.
stop_price	float | None	Stop trigger price as float, or None.
stop_loss	float | None	Stop loss price as float, or None.
take_profit	float | None	Take profit price as float, or None.
execution_price	float | None	Average fill price as float, or None.
executed_volume	int	Volume that has been filled, in cents.
expiration_timestamp	datetime | None	When the order expires, or None.
position_id	int | None	Associated position ID, or None.
base_slippage_price	float | None	Base price for slippage calculation.
slippage_in_points	int | None	Max allowed slippage in points.
relative_stop_loss	int | None	Stop loss distance in points.
relative_take_profit	int | None	Take profit distance in points.
is_closing_order	bool	Whether this order closes a position.
is_stop_out	bool	Whether this order was triggered by stop-out.
trailing_stop_loss	bool	Whether trailing stop is enabled.
guaranteed_stop_loss	bool	Whether guaranteed stop loss is enabled.
stop_trigger_method	StopTriggerMethod	Method for triggering stop orders.
client_order_id	str	User-defined order ID.
label	str	User-defined label.
comment	str	User-defined comment.
last_update_timestamp	datetime | None	When the order was last modified.

is_pending

Whether this is a pending order.

is_filled

Whether this order has been fully filled.

from_proto(proto)

Create Order from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOAOrder	The proto message to convert.	required

Returns:

Type	Description
Order	A new Order instance.

Deal

Bases: FrozenModel

A trade execution (deal).

Represents a single execution that fills an order. An order may have
multiple deals if it's filled in parts.

Attributes:

Name	Type	Description
deal_id	int	Unique deal identifier.
order_id	int	The order that was executed.
position_id	int	The position affected by this deal.
symbol_id	int	The symbol traded.
side	OrderSide	Trade direction (BUY/SELL).
volume	int	Requested volume in cents.
filled_volume	int	Actually filled volume in cents.
execution_price	float	Price at which the deal was executed.
execution_timestamp	datetime	When the deal was executed.
status	DealStatus	Deal status.
commission	float	Commission charged.
create_timestamp	datetime | None	When the deal was created.
last_update_timestamp	datetime | None	When the deal was last updated.
margin_rate	float | None	Margin rate for the deal.
base_to_usd_rate	float | None	Conversion rate from base currency to USD.
close_detail	CloseDetail | None	Details if this deal closed a position, or None.

is_closing_deal

Whether this deal closed (or partially closed) a position.

from_proto(proto)

Create Deal from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOADeal	The proto message to convert.	required

Returns:

Type	Description
Deal	A new Deal instance.

CloseDetail

Bases: FrozenModel

Details about position closure from a deal.

Present only when a deal results in closing (fully or partially)
a position.

Attributes:

Name	Type	Description
entry_price	float	Original entry price of the position.
closed_volume	int	Volume that was closed in cents.
gross_profit	float	Gross profit/loss.
swap	float	Swap charged.
commission	float	Commission charged.
balance	float	Account balance after close.
pnl_conversion_fee	float	Fee for P&L currency conversion.
quote_to_deposit_rate	float | None	Conversion rate from quote to deposit currency.
balance_version	int | None	Version number for balance updates.

from_proto(proto)

Create CloseDetail from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOAClosePositionDetail	The proto message to convert.	required

Returns:

Type	Description
CloseDetail	A new CloseDetail instance.

Symbol

Bases: FrozenModel

Full symbol trading parameters.

Contains all information needed for trading calculations including
pip position, lot size, volume limits, and swap rates.

Attributes:

Name	Type	Description
symbol_id	int	The unique symbol identifier.
digits	int	Price decimal places.
pip_position	int	Position of pip in price (e.g., 4 means 0.0001).
lot_size	int	Contract size in base units (e.g., 100000 for forex).
min_volume	int	Minimum order volume in cents.
max_volume	int	Maximum order volume in cents.
step_volume	int	Volume step in cents.
trading_mode	TradingMode	Current trading mode.
swap_long	float	Swap rate for long positions.
swap_short	float	Swap rate for short positions.
commission	int	Commission rate.
max_exposure	int | None	Maximum allowed exposure.
leverage_id	int | None	ID of dynamic leverage profile, if any.
enable_short_selling	bool	Whether short selling is allowed.
guaranteed_stop_loss	bool	Whether guaranteed stop loss is available.
sl_distance	int	Minimum stop loss distance.
tp_distance	int	Minimum take profit distance.
schedule_timezone	str	Timezone for trading schedule.
measurement_units	str	Measurement units (e.g., "oz" for gold).

volume_to_lots(volume_cents)

Convert volume in cents to lots.

Parameters:

Name	Type	Description	Default
volume_cents	int	Volume in cents	required

Returns:

Type	Description
float	Volume in lots.

lots_to_volume(lots)

Convert lots to volume in cents.

Parameters:

Name	Type	Description	Default
lots	float	Volume in lots.	required

Returns:

Type	Description
int	Volume in cents for API.

from_proto(proto)

Create Symbol from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOASymbol	The proto message to convert.	required

Returns:

Type	Description
Symbol	A new Symbol instance.

SymbolInfo

Bases: FrozenModel

Basic symbol information from symbol list.

This is the lightweight representation returned when listing symbols.
Use Symbol for full trading parameters.

Attributes:

Name	Type	Description
symbol_id	int	The unique symbol identifier.
name	str	Symbol name (e.g., "EURUSD").
enabled	bool	Whether the symbol is enabled for trading.
base_asset_id	int	Asset ID of the base currency.
quote_asset_id	int	Asset ID of the quote currency.
category_id	int | None	Symbol category ID.
description	str	Human-readable description.

from_proto(proto)

Create SymbolInfo from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOALightSymbol	The proto message to convert.	required

Returns:

Type	Description
SymbolInfo	A new SymbolInfo instance.

Account

Bases: FrozenModel

Full trading account details.

Retrieved after authorizing a specific account. Contains balance,
leverage, and other trading parameters.

Attributes:

Name	Type	Description
account_id	int	The cTID trader account ID.
trader_login	int	The trader's login number.
balance	float	Account balance
leverage_in_cents	int	Account leverage in cents (e.g., 10000 = 1:100).
account_type	AccountType	Account type (HEDGED, NETTED, SPREAD_BETTING).
access_rights	AccessRights	Current access rights for the account.
broker_name	str	Name of the broker.
deposit_asset_id	int	Asset ID of the deposit currency.
swap_free	bool	Whether account is swap-free (Islamic Banking).
is_limited_risk	bool	Whether account has limited risk mode.
registration_timestamp	datetime | None	When the account was registered.
max_leverage	int | None	Maximum allowed leverage.
balance_version	int | None	Version number for balance updates.
manager_bonus	float | None	Manager bonus amount
ib_bonus	float | None	IB bonus amount
non_withdrawable_bonus	float | None	Non-withdrawable bonus amount

get_leverage()

Get leverage as human-readable string.

Returns:

Type	Description
str	Leverage string like "1:100".

from_proto(proto)

Create Account from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOATrader	The proto message to convert.	required

Returns:

Type	Description
Account	A new Account instance.

AccountSummary

Bases: FrozenModel

Summary of a trading account from account list.

This is the lightweight representation returned when listing accounts
associated with an access token. Use Account for full details after
authorization.

Attributes:

Name	Type	Description
account_id	int	The cTID trader account ID.
is_live	bool	True if this is a live account, False for demo.
trader_login	int	The trader's login number.
broker_name	str	Short name of the broker.
last_closing_deal_timestamp	datetime | None	Timestamp of last closing deal, or None.
last_balance_update_timestamp	datetime | None	Timestamp of last balance update, or None.

from_proto(proto)

Create AccountSummary from proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOACtidTraderAccount	The proto message to convert.	required

Returns:

Type	Description
AccountSummary	A new AccountSummary instance.

Trendbar

Bases: FrozenModel

Historical OHLC bar (candlestick).

Note: The raw proto stores prices as deltas from low. This model
exposes computed open/high/close values.

Attributes:

Name	Type	Description
timestamp	datetime	Bar open time.
period	TrendbarPeriod	Bar period (M1, H1, D1, etc.).
low	float	Low price
open	float	Open price
high	float	High price
close	float	Close price
volume	int	Bar volume in ticks.

from_proto(proto, bid_price=None, historical=False)

Create a Trendbar from a proto message.

Parameters:

Name	Type	Description	Default
proto	ProtoOATrendbar	Source proto message.	required
bid_price	float | None	Bid price used as close when the API omits delta_close on live updates.	None
historical	bool	If False, raises on delta_close == 0 instead of silently returning low == close.	False

TickData

Bases: FrozenModel

Historical tick data point.

Represents a single price tick from tick history.

Attributes:

Name	Type	Description
timestamp	datetime	Tick time.
price	float	Tick price.

from_proto(proto)

Create TickData from proto message.

Note that price needs to be converted from a raw integer to a float by dividing by 1e5.

Parameters:

Name	Type	Description	Default
proto	ProtoOATickData	The proto message.	required

Returns:

Type	Description
TickData	A new TickData instance.

from_proto_list(protos)

Convert list of proto tick data to list of TickData.

Note that proto timestamps and prices are stored as deltas from the previous timestamp and price, with
the first data point being an absolute value.
This method converts them to absolute values.

Additionally, price needs to be converted from a raw integer to a float by dividing by 1e5.

Parameters:

Name	Type	Description	Default
protos	list[ProtoOATickData]	List of proto tick data messages.	required

Returns:

Type	Description
Sequence[TickData]	List of TickData instances.

Volume Conversion

Volumes in the cTrader API are expressed in cents relative to the symbol's lot_size:

• For standard forex (lot_size=100000): 100000 = 1.0 lots, 10000 = 0.1 lots, 1000 = 0.01 lots
• For other instruments, lot_size may vary

Use the Symbol model for conversions:

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

# Convert lots to volume for orders
volume = symbol.lots_to_volume(0.1)  # Returns volume in cents

# Convert volume to lots for display
lots = symbol.volume_to_lots(position.volume)  # Returns lots as float

Price Values

Prices in events and models (bid, ask, OHLC, execution prices, etc.) are returned as floats - no conversion needed:

@client.on(SpotEvent)
async def on_price(event: SpotEvent):
    # bid and ask are already floats
    spread = event.ask - event.bid
    print(f"Spread: {spread}")

# Trendbar OHLC are floats
for bar in trendbars:
    range_size = bar.high - bar.low
    print(f"Range: {range_size}")

# Account balance is a float
account = await client.accounts.get_trader(account_id)
print(f"Balance: {account.balance}")

# Position values are floats
for pos in positions:
    print(f"Swap: {pos.swap}, Commission: {pos.commission}")