Trading API

Order placement, modification, cancellation, and position management.

Access via client.trading.

TradingAPI

`TradingAPI`

Trading operations: orders and positions.

Provides methods for order placement, modification, cancellation,
and position management.

Example

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

# Place a market order
request = NewOrderRequest(
    symbol_id=270,
    side=OrderSide.BUY,
    volume=100,  # 0.01 lots
    order_type=OrderType.MARKET,
)
execution = await client.trading.place_order(account_id, request)
print(f"Order {execution.order_id}: {execution.execution_type}")

# Get open positions
positions = await client.trading.get_open_positions(account_id)
for pos in positions:
    print(f"Position {pos.position_id}: {pos.volume} @ {pos.entry_price}")

`place_order(account_id, request, timeout=None)`

Place a new order.

Parameters:

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

Returns:

Type	Description
`ExecutionEvent`	ExecutionEvent with order details.

Note

For market orders, the order may be immediately filled.
Check execution_type to determine the outcome:
- ORDER_ACCEPTED: Pending order created
- ORDER_FILLED: Order fully executed
- ORDER_PARTIAL_FILL: Order partially executed
- ORDER_REJECTED: Order was rejected

Raises:

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

`amend_order(account_id, request, timeout=None)`

Modify a pending order.

Parameters:

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

Returns:

Type	Description
`ExecutionEvent`	ExecutionEvent confirming the amendment.

Raises:

Type	Description
`APIError`	If request fails or order not found.
`CTraderConnectionTimeoutError`	If request times out.

`cancel_order(account_id, order_id, timeout=None)`

Cancel a pending order.

Parameters:

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

Returns:

Type	Description
`ExecutionEvent`	ExecutionEvent confirming cancellation.

Raises:

Type	Description
`APIError`	If request fails or order not found.
`CTraderConnectionTimeoutError`	If request times out.

`close_position(account_id, request, timeout=None)`

Close a position (fully or partially).

Parameters:

Name	Type	Description	Default
`account_id`	`int`	The cTID trader account ID.	required
`request`	`ClosePositionRequest`	Close parameters (position_id and volume required).	required
`timeout`	`float \| None`	Request timeout (uses default if None).	`None`

Returns:

Type	Description
`ExecutionEvent`	ExecutionEvent with closing details.

Raises:

Type	Description
`APIError`	If request fails or position not found.
`CTraderConnectionTimeoutError`	If request times out.

`amend_position(account_id, request, timeout=None)`

Modify position stop loss and take profit.

Parameters:

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

Returns:

Type	Description
`ExecutionEvent`	ExecutionEvent confirming the amendment.

Raises:

Type	Description
`APIError`	If request fails or position not found.
`CTraderConnectionTimeoutError`	If request times out.

`get_open_positions(account_id, timeout=None)`

Get all open positions.

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[Position]`	List of open Position objects.

Raises:

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

`get_pending_orders(account_id, timeout=None)`

Get all pending orders.

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[Order]`	List of pending Order objects.

Raises:

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

`get_deals(account_id, from_timestamp, to_timestamp, timeout=None)`

Get historical deals.

Parameters:

Name	Type	Description	Default
`account_id`	`int`	The cTID trader account ID.	required
`from_timestamp`	`datetime`	Start of time range (inclusive).	required
`to_timestamp`	`datetime`	End of time range (inclusive).	required
`timeout`	`float \| None`	Request timeout (uses default if None).	`None`

Returns:

Type	Description
`list[Deal]`	List of Deal objects in the time range.

Note

The maximum time range may be limited by the server.
For large ranges, consider paginating with smaller windows.

Raises:

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

`get_deals_by_position_id(account_id, position_id)`

Get all deals for a specific position.

Parameters:

Name	Type	Description	Default
`account_id`	`int`	The cTID trader account ID.	required
`position_id`	`int`	The position ID to filter deals by.	required

Returns:

Type	Description
`list[Deal]`	List of Deal objects associated with the position.

Raises:

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

Usage Examples

Place a Market Order

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

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

# Place a 0.1 lot buy order
request = NewOrderRequest(
    symbol_id=270,
    order_type=OrderType.MARKET,
    side=OrderSide.BUY,
    volume=symbol.lots_to_volume(0.1),  # Convert lots to volume
)

result = await client.trading.place_order(account_id, request)
print(f"Order {result.order_id}: {result.execution_type}")

Place a Limit Order

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

request = NewOrderRequest(
    symbol_id=270,
    order_type=OrderType.LIMIT,
    side=OrderSide.BUY,
    volume=symbol.lots_to_volume(0.1),
    limit_price=5000.0,  # Limit price
    stop_loss=4950.0,  # Optional SL
    take_profit=5100.0,  # Optional TP
)

result = await client.trading.place_order(account_id, request)

Place an Order with Relative SL/TP

# Relative SL/TP are specified in price units (distance from entry)
request = NewOrderRequest(
    symbol_id=270,
    order_type=OrderType.MARKET,
    side=OrderSide.BUY,
    volume=symbol.lots_to_volume(0.1),
    relative_stop_loss=50.0,   # 50 points below entry
    relative_take_profit=100.0,  # 100 points above entry
)

result = await client.trading.place_order(account_id, request)

Cancel an Order

result = await client.trading.cancel_order(account_id, order_id)
print(f"Cancelled: {result.execution_type}")

Close a Position

from ctrader_api_client.models import ClosePositionRequest

# First, get the position to know its volume
positions = await client.trading.get_open_positions(account_id)
position = next(p for p in positions if p.position_id == position_id)

# Close the entire position
request = ClosePositionRequest(
    position_id=position.position_id,
    volume=position.volume,  # Use full volume for complete close
)

result = await client.trading.close_position(account_id, request)
print(f"Position closed: {result.execution_type}")

Partial Close a Position

# Get symbol to convert lots
symbol = await client.symbols.get_by_id(account_id, position.symbol_id)

# Close half of a 1-lot position
request = ClosePositionRequest(
    position_id=position.position_id,
    volume=symbol.lots_to_volume(0.5),  # Close 0.5 lots
)

result = await client.trading.close_position(account_id, request)

Modify Position SL/TP

from ctrader_api_client.models import AmendPositionRequest

request = AmendPositionRequest(
    position_id=123456,
    stop_loss=4900.0,
    take_profit=5200.0,
)

result = await client.trading.amend_position(account_id, request)

Get Open Positions

positions = await client.trading.get_open_positions(account_id)

for pos in positions:
    # Get symbol for volume conversion
    symbol = await client.symbols.get_by_id(account_id, pos.symbol_id)
    lots = symbol.volume_to_lots(pos.volume)

    print(f"Position {pos.position_id}: {lots} lots @ {pos.entry_price}")
    print(f"  Swap: {pos.swap}, Commission: {pos.commission}")

Get Pending Orders

orders = await client.trading.get_pending_orders(account_id)

for order in orders:
    print(f"Order {order.order_id}: {order.order_type} {order.side}")

Get Historical Deals

from datetime import datetime, timedelta

deals = await client.trading.get_deals(
    account_id,
    from_timestamp=datetime.now() - timedelta(days=7),
    to_timestamp=datetime.now(),
)

for deal in deals:
    print(f"Deal {deal.deal_id}: {deal.side} {deal.filled_volume}")
    print(f"  Commission: {deal.commission}")

    # Check if this deal closed a position
    if deal.is_closing_deal and deal.close_detail:
        print(f"  Gross P/L: {deal.close_detail.gross_profit}")