Trading Models¶
OANDA Reference: Trade Data Definitions | Position Data Definitions
Models for trade lifecycle management, position tracking, and P&L calculations.
Trade Models¶
Trade¶
Represents an open trade position.
🔗 OANDA Definition: Trade
🔗 Source: Trade
| Field | Type | Required | Description |
|---|---|---|---|
id |
TradeID | ✅ | Trade's identifier, unique within the Account (OANDA-assigned positive integer as string) |
instrument |
InstrumentName | ✅ | Trade's Instrument (e.g., "EUR_USD") |
price |
PriceValue | ✅ | Execution price of the Trade (string for precision) |
open_time |
DateTime | ✅ | Date/time when Trade was opened |
state |
TradeState | ✅ | Current state of the Trade (OPEN, CLOSED, CLOSE_WHEN_TRADEABLE) |
initial_units |
Decimal | ✅ | Initial size of the Trade (positive for long, negative for short) |
initial_margin_required |
AccountUnits | ✅ | Margin required when trade was opened |
current_units |
Decimal | ✅ | Units currently open (reduces toward 0 when closed) |
realized_pl |
AccountUnits | ✅ | Total profit/loss realized on closed portion of Trade (string) |
unrealized_pl |
AccountUnits | âž– | Unrealized profit/loss on open portion using current market prices (string, not present for closed trades) |
margin_used |
AccountUnits | âž– | Margin currently used by the Trade (string, not present for closed trades) |
average_close_price |
PriceValue | âž– | Average price of closed portions |
closing_transaction_ids |
list[TransactionID] | ✅ | IDs of transactions that closed portions of this trade |
dividend_adjustment |
AccountUnits | âž– | Total dividend adjustments paid for the Trade (string, applicable to equity CFDs) |
financing |
AccountUnits | âž– | Total financing paid/collected for the Trade (string, overnight swap charges/credits) |
close_time |
DateTime | âž– | Date/time when Trade was fully closed (only present for CLOSED trades) |
client_extensions |
ClientExtensions | âž– | Client extensions of the Trade |
take_profit_order |
TakeProfitOrder | âž– | Full Take Profit Order representation (if exists) |
stop_loss_order |
StopLossOrder | âž– | Full Stop Loss Order representation (if exists) |
guaranteed_stop_loss_order |
GuaranteedStopLossOrder | âž– | Full Guaranteed Stop Loss Order representation (if exists) |
trailing_stop_loss_order |
TrailingStopLossOrder | âž– | Full Trailing Stop Loss Order representation (if exists) |
TradeSummary¶
Condensed trade information for lists and overviews.
🔗 OANDA Definition: TradeSummary
🔗 Source: TradeSummary
| Field | Type | Required | Description |
|---|---|---|---|
id |
TradeID | ✅ | Trade's identifier, unique within the Account |
instrument |
InstrumentName | ✅ | Trade's Instrument |
price |
PriceValue | ✅ | Execution price of the Trade (string for precision) |
open_time |
DateTime | ✅ | Date/time when Trade was opened |
state |
TradeState | ✅ | Current state of the Trade (OPEN, CLOSED, CLOSE_WHEN_TRADEABLE) |
initial_units |
Decimal | ✅ | Initial size of the Trade (positive for long, negative for short) |
initial_margin_required |
AccountUnits | ✅ | Margin required when trade was opened |
current_units |
Decimal | ✅ | Units currently open (reduces toward 0 when closed) |
realized_pl |
AccountUnits | ✅ | Total profit/loss realized on closed portion of Trade (string) |
unrealized_pl |
AccountUnits | âž– | Unrealized profit/loss on open portion using current market prices (not present for closed trades) |
margin_used |
AccountUnits | âž– | Margin currently used by the Trade (not present for closed trades) |
average_close_price |
PriceValue | âž– | Average price of closed portions |
closing_transaction_ids |
list[TransactionID] | ✅ | IDs of transactions that closed portions of this trade |
financing |
AccountUnits | âž– | Total financing paid/collected for the Trade |
dividend_adjustment |
AccountUnits | âž– | Total dividend adjustments paid for the Trade |
close_time |
DateTime | âž– | Date/time when Trade was fully closed |
client_extensions |
ClientExtensions | âž– | Client extensions of the Trade |
take_profit_order_id |
OrderID | âž– | Take Profit Order ID (if exists) |
stop_loss_order_id |
OrderID | âž– | Stop Loss Order ID (if exists) |
guaranteed_stop_loss_order_id |
OrderID | âž– | Guaranteed Stop Loss Order ID (if exists) |
trailing_stop_loss_order_id |
OrderID | âž– | Trailing Stop Loss Order ID (if exists) |
TradeSpecifier¶
The identification of a Trade as referred to by clients.
🔗 OANDA Definition: TradeSpecifier
🔗 Source: TradeSpecifier
| Type | Format | Description |
|---|---|---|
| str | Trade ID or Client ID | Either the Trade's OANDA-assigned TradeID or the Trade's client-provided ClientID prefixed by the "@" symbol |
Examples:
"1523"- OANDA-assigned Trade ID"@my_trade_id"- Client-provided ID with @ prefix
CalculatedTradeState¶
The dynamic (calculated) state of an open Trade.
🔗 OANDA Definition: CalculatedTradeState
🔗 Source: CalculatedTradeState
| Field | Type | Required | Description |
|---|---|---|---|
id |
TradeID | ✅ | Trade's identifier |
unrealized_pl |
AccountUnits | ✅ | Trade's unrealized profit/loss |
margin_used |
AccountUnits | ✅ | Margin currently used by the Trade |
Position Models¶
Position¶
Aggregated position information for an instrument.
🔗 OANDA Definition: Position
🔗 Source: Position
| Field | Type | Required | Description |
|---|---|---|---|
instrument |
InstrumentName | ✅ | Position's Instrument |
long |
PositionSide | ✅ | Long side details (aggregation of all long trades) |
short |
PositionSide | ✅ | Short side details (aggregation of all short trades) |
pl |
AccountUnits | ✅ | Lifetime realized profit/loss for the Position |
unrealized_pl |
AccountUnits | âž– | Unrealized profit/loss from all open Trades (not present for closed positions) |
margin_used |
AccountUnits | âž– | Margin currently used by the Position (not present for closed positions) |
resettable_pl |
AccountUnits | ✅ | Realized profit/loss since last reset |
financing |
AccountUnits | âž– | Total financing paid/collected for the Position (lifetime) |
commission |
AccountUnits | âž– | Total commission paid for the Position (lifetime) |
dividend_adjustment |
AccountUnits | âž– | Total dividend adjustments for the Position (lifetime) |
guaranteed_execution_fees |
AccountUnits | âž– | Total guaranteed stop loss fees for the Position (lifetime) |
PositionSide¶
One side (long or short) of a position.
🔗 OANDA Definition: PositionSide
🔗 Source: PositionSide
| Field | Type | Required | Description |
|---|---|---|---|
units |
Decimal | ✅ | Position units (positive for long, negative for short) |
average_price |
PriceValue | âž– | Volume-weighted average open price for this side |
trade_ids |
list[TradeID] | ✅ | Open Trade IDs contributing to this position side |
pl |
AccountUnits | ✅ | Lifetime realized profit/loss for this side |
unrealized_pl |
AccountUnits | âž– | Unrealized profit/loss from open Trades on this side (not present for closed positions) |
resettable_pl |
AccountUnits | ✅ | Realized profit/loss since last reset for this side |
financing |
AccountUnits | âž– | Total financing for this side (lifetime) |
dividend_adjustment |
AccountUnits | âž– | Total dividend adjustments for this side |
guaranteed_execution_fees |
AccountUnits | âž– | Total guaranteed stop loss fees for this side (lifetime) |
CalculatedPositionState¶
Dynamic calculated state of a position with real-time P&L calculations.
🔗 OANDA Definition: CalculatedPositionState
🔗 Source: CalculatedPositionState
| Field | Type | Required | Description |
|---|---|---|---|
instrument |
InstrumentName | ✅ | Position's instrument identifier |
net_unrealized_pl |
AccountUnits | ✅ | Net unrealized profit/loss for the entire position |
long_unrealized_pl |
AccountUnits | ✅ | Unrealized profit/loss for the long position side |
short_unrealized_pl |
AccountUnits | ✅ | Unrealized profit/loss for the short position side |
margin_used |
AccountUnits | âž– | Current margin used by the position |