Which API should I use?

  • Use v20 REST API only if you have a v20 account
  • Use v1 REST API if your account id contains only digits (ie. 2534253) as it is a legacy account

Account Definitions


Type string
Format “-“-delimited string with format “{siteID}-{divisionID}-{userID}-{accountNumber}”
Example 001-011-5838423-001

Account is an application/json object with the following Schema:

{
    # 
    # The Account’s identifier
    # 
    id : (AccountID),

    # 
    # Client-assigned alias for the Account. Only provided if the Account has
    # an alias set
    # 
    alias : (string),

    # 
    # The home currency of the Account
    # 
    currency : (Currency),

    # 
    # The current balance of the Account. Represented in the Account’s home
    # currency.
    # 
    balance : (AccountUnits),

    # 
    # ID of the user that created the Account.
    # 
    createdByUserID : (integer),

    # 
    # The date/time when the Account was created.
    # 
    createdTime : (DateTime),

    # 
    # The total profit/loss realized over the lifetime of the Account.
    # Represented in the Account’s home currency.
    # 
    pl : (AccountUnits),

    # 
    # The total realized profit/loss for the Account since it was last reset by
    # the client. Represented in the Account’s home currency.
    # 
    resettablePL : (AccountUnits),

    # 
    # The date/time that the Account’s resettablePL was last reset.
    # 
    resettabledPLTime : (DateTime),

    # 
    # Client-provided margin rate override for the Account. The effective
    # margin rate of the Account is the lesser of this value and the OANDA
    # margin rate for the Account’s division. This value is only provided if a
    # margin rate override exists for the Account.
    # 
    marginRate : (DecimalNumber),

    # 
    # The date/time when the Account entered a margin call state. Only provided
    # if the Account is in a margin call.
    # 
    marginCallEnterTime : (DateTime),

    # 
    # The number of times that the Account’s current margin call was extended.
    # 
    marginCallExtensionCount : (integer),

    # 
    # The date/time of the Account’s last margin call extension.
    # 
    lastMarginCallExtensionTime : (DateTime),

    # 
    # The number of Trades currently open in the Account.
    # 
    openTradeCount : (integer),

    # 
    # The number of Positions currently open in the Account.
    # 
    openPositionCount : (integer),

    # 
    # The number of Orders currently pending in the Account.
    # 
    pendingOrderCount : (integer),

    # 
    # Flag indicating that the Account has hedging enabled.
    # 
    hedgingEnabled : (boolean),

    # 
    # The total unrealized profit/loss for all Trades currently open in the
    # Account. Represented in the Account’s home currency.
    # 
    unrealizedPL : (AccountUnits),

    # 
    # The net asset value of the Account. Equal to Account balance +
    # unrealizedPL. Represented in the Account’s home currency.
    # 
    NAV : (AccountUnits),

    # 
    # Margin currently used for the Account. Represented in the Account’s home
    # currency.
    # 
    marginUsed : (AccountUnits),

    # 
    # Margin available for Account. Represented in the Account’s home currency.
    # 
    marginAvailable : (AccountUnits),

    # 
    # The value of the Account’s open positions represented in the Account’s
    # home currency.
    # 
    positionValue : (AccountUnits),

    # 
    # The Account’s margin closeout unrealized PL.
    # 
    marginCloseoutUnrealizedPL : (AccountUnits),

    # 
    # The Account’s margin closeout NAV.
    # 
    marginCloseoutNAV : (AccountUnits),

    # 
    # The Account’s margin closeout margin used.
    # 
    marginCloseoutMarginUsed : (AccountUnits),

    # 
    # The Account’s margin closeout percentage. When this value is 1.0 or above
    # the Account is in a margin closeout situation.
    # 
    marginCloseoutPercent : (DecimalNumber),

    # 
    # The value of the Account’s open positions as used for margin closeout
    # calculations represented in the Account’s home currency.
    # 
    marginCloseoutPositionValue : (DecimalNumber),

    # 
    # The current WithdrawalLimit for the account which will be zero or a
    # positive value indicating how much can be withdrawn from the account.
    # 
    withdrawalLimit : (AccountUnits),

    # 
    # The Account’s margin call margin used.
    # 
    marginCallMarginUsed : (AccountUnits),

    # 
    # The Account’s margin call percentage. When this value is 1.0 or above the
    # Account is in a margin call situation.
    # 
    marginCallPercent : (DecimalNumber),

    # 
    # The ID of the last Transaction created for the Account.
    # 
    lastTransactionID : (TransactionID),

    # 
    # The details of the Trades currently open in the Account.
    # 
    trades : (Array[TradeSummary]),

    # 
    # The details all Account Positions.
    # 
    positions : (Array[Position]),

    # 
    # The details of the Orders currently pending in the Account.
    # 
    orders : (Array[Order])
}

AccountChangesState is an application/json object with the following Schema:

{
    # 
    # The total unrealized profit/loss for all Trades currently open in the
    # Account. Represented in the Account’s home currency.
    # 
    unrealizedPL : (AccountUnits),

    # 
    # The net asset value of the Account. Equal to Account balance +
    # unrealizedPL. Represented in the Account’s home currency.
    # 
    NAV : (AccountUnits),

    # 
    # Margin currently used for the Account. Represented in the Account’s home
    # currency.
    # 
    marginUsed : (AccountUnits),

    # 
    # Margin available for Account. Represented in the Account’s home currency.
    # 
    marginAvailable : (AccountUnits),

    # 
    # The value of the Account’s open positions represented in the Account’s
    # home currency.
    # 
    positionValue : (AccountUnits),

    # 
    # The Account’s margin closeout unrealized PL.
    # 
    marginCloseoutUnrealizedPL : (AccountUnits),

    # 
    # The Account’s margin closeout NAV.
    # 
    marginCloseoutNAV : (AccountUnits),

    # 
    # The Account’s margin closeout margin used.
    # 
    marginCloseoutMarginUsed : (AccountUnits),

    # 
    # The Account’s margin closeout percentage. When this value is 1.0 or above
    # the Account is in a margin closeout situation.
    # 
    marginCloseoutPercent : (DecimalNumber),

    # 
    # The value of the Account’s open positions as used for margin closeout
    # calculations represented in the Account’s home currency.
    # 
    marginCloseoutPositionValue : (DecimalNumber),

    # 
    # The current WithdrawalLimit for the account which will be zero or a
    # positive value indicating how much can be withdrawn from the account.
    # 
    withdrawalLimit : (AccountUnits),

    # 
    # The Account’s margin call margin used.
    # 
    marginCallMarginUsed : (AccountUnits),

    # 
    # The Account’s margin call percentage. When this value is 1.0 or above the
    # Account is in a margin call situation.
    # 
    marginCallPercent : (DecimalNumber),

    # 
    # The price-dependent state of each pending Order in the Account.
    # 
    orders : (Array[DynamicOrderState]),

    # 
    # The price-dependent state for each open Trade in the Account.
    # 
    trades : (Array[CalculatedTradeState]),

    # 
    # The price-dependent state for each open Position in the Account.
    # 
    positions : (Array[CalculatedPositionState])
}

AccountProperties is an application/json object with the following Schema:

{
    # 
    # The Account’s identifier
    # 
    id : (AccountID),

    # 
    # The Account’s associated MT4 Account ID. This field will not be present
    # if the Account is not an MT4 account.
    # 
    mt4AccountID : (integer),

    # 
    # The Account’s tags
    # 
    tags : (Array[string])
}

Implemented by: Account

AccountSummary is an application/json object with the following Schema:

{
    # 
    # The Account’s identifier
    # 
    id : (AccountID),

    # 
    # Client-assigned alias for the Account. Only provided if the Account has
    # an alias set
    # 
    alias : (string),

    # 
    # The home currency of the Account
    # 
    currency : (Currency),

    # 
    # The current balance of the Account. Represented in the Account’s home
    # currency.
    # 
    balance : (AccountUnits),

    # 
    # ID of the user that created the Account.
    # 
    createdByUserID : (integer),

    # 
    # The date/time when the Account was created.
    # 
    createdTime : (DateTime),

    # 
    # The total profit/loss realized over the lifetime of the Account.
    # Represented in the Account’s home currency.
    # 
    pl : (AccountUnits),

    # 
    # The total realized profit/loss for the Account since it was last reset by
    # the client. Represented in the Account’s home currency.
    # 
    resettablePL : (AccountUnits),

    # 
    # The date/time that the Account’s resettablePL was last reset.
    # 
    resettabledPLTime : (DateTime),

    # 
    # Client-provided margin rate override for the Account. The effective
    # margin rate of the Account is the lesser of this value and the OANDA
    # margin rate for the Account’s division. This value is only provided if a
    # margin rate override exists for the Account.
    # 
    marginRate : (DecimalNumber),

    # 
    # The date/time when the Account entered a margin call state. Only provided
    # if the Account is in a margin call.
    # 
    marginCallEnterTime : (DateTime),

    # 
    # The number of times that the Account’s current margin call was extended.
    # 
    marginCallExtensionCount : (integer),

    # 
    # The date/time of the Account’s last margin call extension.
    # 
    lastMarginCallExtensionTime : (DateTime),

    # 
    # The number of Trades currently open in the Account.
    # 
    openTradeCount : (integer),

    # 
    # The number of Positions currently open in the Account.
    # 
    openPositionCount : (integer),

    # 
    # The number of Orders currently pending in the Account.
    # 
    pendingOrderCount : (integer),

    # 
    # Flag indicating that the Account has hedging enabled.
    # 
    hedgingEnabled : (boolean),

    # 
    # The total unrealized profit/loss for all Trades currently open in the
    # Account. Represented in the Account’s home currency.
    # 
    unrealizedPL : (AccountUnits),

    # 
    # The net asset value of the Account. Equal to Account balance +
    # unrealizedPL. Represented in the Account’s home currency.
    # 
    NAV : (AccountUnits),

    # 
    # Margin currently used for the Account. Represented in the Account’s home
    # currency.
    # 
    marginUsed : (AccountUnits),

    # 
    # Margin available for Account. Represented in the Account’s home currency.
    # 
    marginAvailable : (AccountUnits),

    # 
    # The value of the Account’s open positions represented in the Account’s
    # home currency.
    # 
    positionValue : (AccountUnits),

    # 
    # The Account’s margin closeout unrealized PL.
    # 
    marginCloseoutUnrealizedPL : (AccountUnits),

    # 
    # The Account’s margin closeout NAV.
    # 
    marginCloseoutNAV : (AccountUnits),

    # 
    # The Account’s margin closeout margin used.
    # 
    marginCloseoutMarginUsed : (AccountUnits),

    # 
    # The Account’s margin closeout percentage. When this value is 1.0 or above
    # the Account is in a margin closeout situation.
    # 
    marginCloseoutPercent : (DecimalNumber),

    # 
    # The value of the Account’s open positions as used for margin closeout
    # calculations represented in the Account’s home currency.
    # 
    marginCloseoutPositionValue : (DecimalNumber),

    # 
    # The current WithdrawalLimit for the account which will be zero or a
    # positive value indicating how much can be withdrawn from the account.
    # 
    withdrawalLimit : (AccountUnits),

    # 
    # The Account’s margin call margin used.
    # 
    marginCallMarginUsed : (AccountUnits),

    # 
    # The Account’s margin call percentage. When this value is 1.0 or above the
    # Account is in a margin call situation.
    # 
    marginCallPercent : (DecimalNumber),

    # 
    # The ID of the last Transaction created for the Account.
    # 
    lastTransactionID : (TransactionID)
}

AccountChanges is an application/json object with the following Schema:

{
    # 
    # The Orders created. These Orders may have been filled, cancelled or
    # triggered in the same period.
    # 
    ordersCreated : (Array[Order]),

    # 
    # The Orders cancelled.
    # 
    ordersCancelled : (Array[Order]),

    # 
    # The Orders filled.
    # 
    ordersFilled : (Array[Order]),

    # 
    # The Orders triggered.
    # 
    ordersTriggered : (Array[Order]),

    # 
    # The Trades opened.
    # 
    tradesOpened : (Array[TradeSummary]),

    # 
    # The Trades reduced.
    # 
    tradesReduced : (Array[TradeSummary]),

    # 
    # The Trades closed.
    # 
    tradesClosed : (Array[TradeSummary]),

    # 
    # The Positions changed.
    # 
    positions : (Array[Position]),

    # 
    # The Transactions that have been generated.
    # 
    transactions : (Array[Transaction])
}

Value Description
NO_FINANCING No financing is paid/charged for open Trades in the Account
SECOND_BY_SECOND Second-by-second financing is paid/charged for open Trades in the Account, both daily and when the the Trade is closed
DAILY A full day’s worth of financing is paid/charged for open Trades in the Account daily at 5pm New York time

Value Description
ABSOLUTE_SUM The Position value or margin for each side (long and short) of the Position are computed independently and added together.
MAXIMAL_SIDE The Position value or margin for each side (long and short) of the Position are computed independently. The Position value or margin chosen is the maximal absolute value of the two.
NET_SUM The units for each side (long and short) of the Position are netted together and the resulting value (long or short) is used to compute the Position value or margin.