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

Trade Endpoints


Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]
ids query List of TradeID (csv) List of Trade IDs to retrieve.
state query TradeState The state to filter the requested Trades by.
instrument query InstrumentName The instrument to filter the requested Trades by.
count query integer The maximum number of Trades to return. [default=50, maximum=500]
beforeID query TradeID The maximum Trade ID to return. If not provided the most recent Trades in the Account are returned.

Responses

Response Headers

  • Link - A link to the next page of Trades if the results were paginated
Response Body Schema (application/json)

{
    # 
    # The list of Trade detail objects
    # 
    trades : (Array[Trade]),

    # 
    # The ID of the most recent Transaction created for the Account
    # 
    lastTransactionID : (TransactionID)
}

Other Error Responses: 401, 404, 405

Examples

Request
curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/accounts/<ACCOUNT>/trades?instrument=USD_CAD"
Response Headers
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format
Content-Encoding: gzip
Transfer-Encoding: chunked
Server: openresty/1.7.0.1
Connection: keep-alive
Link: <<URL>/v3/accounts/<ACCOUNT>/trades?beforeID=6397&instrument=USD_CAD>; rel="next"
Date: Wed, 22 Jun 2016 18:41:48 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6397", 
  "trades": [
    {
      "currentUnits": "-600", 
      "financing": "0.00000", 
      "id": "6397", 
      "initialUnits": "-600", 
      "instrument": "USD_CAD", 
      "openTime": "2016-06-22T18:41:48.262344782Z", 
      "price": "1.28241", 
      "realizedPL": "0.00000", 
      "state": "OPEN", 
      "unrealizedPL": "-0.08525"
    }
  ]
}

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]

Responses

Response Body Schema (application/json)

{
    # 
    # The Account’s list of open Trades
    # 
    trades : (Array[Trade]),

    # 
    # The ID of the most recent Transaction created for the Account
    # 
    lastTransactionID : (TransactionID)
}

Other Error Responses: 401, 404, 405

Examples

Request
curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/accounts/<ACCOUNT>/openTrades"
Response Headers
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format
Content-Encoding: gzip
Transfer-Encoding: chunked
Server: openresty/1.7.0.1
Connection: keep-alive
Date: Wed, 22 Jun 2016 18:41:48 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6397", 
  "trades": [
    {
      "currentUnits": "-600", 
      "financing": "0.00000", 
      "id": "6397", 
      "initialUnits": "-600", 
      "instrument": "USD_CAD", 
      "openTime": "2016-06-22T18:41:48.262344782Z", 
      "price": "1.28241", 
      "realizedPL": "0.00000", 
      "state": "OPEN", 
      "unrealizedPL": "-0.08525"
    }, 
    {
      "clientExtensions": {
        "id": "my_eur_usd_trade"
      }, 
      "currentUnits": "100", 
      "financing": "0.00000", 
      "id": "6395", 
      "initialUnits": "100", 
      "instrument": "EUR_USD", 
      "openTime": "2016-06-22T18:41:48.258142231Z", 
      "price": "1.13033", 
      "realizedPL": "0.00000", 
      "state": "OPEN", 
      "unrealizedPL": "-0.01438"
    }
  ]
}

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]
tradeSpecifier path TradeSpecifier Specifier for the Trade [required]

Responses

Response Body Schema (application/json)

{
    # 
    # The Account’s list of open Trades
    # 
    trade : (Trade),

    # 
    # The ID of the most recent Transaction created for the Account
    # 
    lastTransactionID : (TransactionID)
}

Other Error Responses: 401, 404, 405

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]
tradeSpecifier path TradeSpecifier Specifier for the Trade [required]
Request Body Schema (application/json)

{
    # 
    # Indication of how much of the Trade to close. Either the string “ALL”
    # (indicating that all of the Trade should be closed), or a DecimalNumber
    # representing the number of units of the open Trade to Close using a
    # TradeClose MarketOrder. The units specified must always be positive, and
    # the magnitude of the value cannot exceed the magnitude of the Trade’s
    # open units.
    # 
    units : (string, default=ALL)
}

Responses

Response Body Schema (application/json)

{
    # 
    # The MarketOrder Transaction created to close the Trade.
    # 
    orderCreateTransaction : (MarketOrderTransaction),

    # 
    # The OrderFill Transaction that fills the Trade-closing MarketOrder and
    # closes the Trade.
    # 
    orderFillTransaction : (OrderFillTransaction),

    # 
    # The OrderCancel Transaction that immediately cancelled the Trade-closing
    # MarketOrder.
    # 
    orderCancelTransaction : (OrderCancelTransaction),

    # 
    # The IDs of all Transactions that were created while satisfying the
    # request.
    # 
    relatedTransactionIDs : (Array[TransactionID]),

    # 
    # The ID of the most recent Transaction created for the Account
    # 
    lastTransactionID : (TransactionID)
}
Response Body Schema (application/json)

{
    # 
    # The MarketOrderReject Transaction that rejects the creation of the Trade-
    # closing MarketOrder.
    # 
    orderRejectTransaction : (MarketOrderRejectTransaction),

    # 
    # The code of the error that has occurred. This field may not be returned
    # for some errors.
    # 
    errorCode : (string),

    # 
    # The human-readable description of the error that has occurred.
    # 
    errorMessage : (string, required)
}
Response Body Schema (application/json)

{
    # 
    # The MarketOrderReject Transaction that rejects the creation of the Trade-
    # closing MarketOrder. Only present if the Account exists.
    # 
    orderRejectTransaction : (MarketOrderRejectTransaction),

    # 
    # The ID of the most recent Transaction created for the Account. Only
    # present if the Account exists.
    # 
    lastTransactionID : (TransactionID),

    # 
    # The IDs of all Transactions that were created while satisfying the
    # request. Only present if the Account exists.
    # 
    relatedTransactionIDs : (Array[TransactionID]),

    # 
    # The code of the error that has occurred. This field may not be returned
    # for some errors.
    # 
    errorCode : (string),

    # 
    # The human-readable description of the error that has occurred.
    # 
    errorMessage : (string, required)
}

Other Error Responses: 401, 405

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]
tradeSpecifier path TradeSpecifier Specifier for the Trade [required]
Request Body Schema (application/json)

{
    # 
    # The Client Extensions to update the Trade with. Do not add, update, or
    # delete the Client Extensions if your account is associated with MT4.
    # 
    clientExtensions : (ClientExtensions)
}

Responses

Response Body Schema (application/json)

{
    # 
    # The Transaction that updates the Trade’s Client Extensions.
    # 
    tradeClientExtensionsModifyTransaction : (TradeClientExtensionsModifyTransaction),

    # 
    # The IDs of all Transactions that were created while satisfying the
    # request.
    # 
    relatedTransactionIDs : (Array[TransactionID]),

    # 
    # The ID of the most recent Transaction created for the Account
    # 
    lastTransactionID : (TransactionID)
}
Response Body Schema (application/json)

{
    # 
    # The Transaction that rejects the modification of the Trade’s Client
    # Extensions.
    # 
    tradeClientExtensionsModifyRejectTransaction : (TradeClientExtensionsModifyRejectTransaction),

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

    # 
    # The IDs of all Transactions that were created while satisfying the
    # request.
    # 
    relatedTransactionIDs : (Array[TransactionID]),

    # 
    # The code of the error that has occurred. This field may not be returned
    # for some errors.
    # 
    errorCode : (string),

    # 
    # The human-readable description of the error that has occurred.
    # 
    errorMessage : (string, required)
}
Response Body Schema (application/json)

{
    # 
    # The Transaction that rejects the modification of the Trade’s Client
    # Extensions. Only present if the Account exists.
    # 
    tradeClientExtensionsModifyRejectTransaction : (TradeClientExtensionsModifyRejectTransaction),

    # 
    # The ID of the most recent Transaction created for the Account. Only
    # present if the Account exists.
    # 
    lastTransactionID : (TransactionID),

    # 
    # The IDs of all Transactions that were created while satisfying the
    # request. Only present if the Account exists.
    # 
    relatedTransactionIDs : (Array[TransactionID]),

    # 
    # The code of the error that has occurred. This field may not be returned
    # for some errors.
    # 
    errorCode : (string),

    # 
    # The human-readable description of the error that has occurred.
    # 
    errorMessage : (string, required)
}

Other Error Responses: 401, 405

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
Accept-Datetime-Format header AcceptDatetimeFormat Format of DateTime fields in the request and response.
accountID path AccountID Account Identifier [required]
tradeSpecifier path TradeSpecifier Specifier for the Trade [required]
Request Body Schema (application/json)

{
    # 
    # The specification of the Take Profit to create/modify/cancel. If
    # takeProfit is set to null, the Take Profit Order will be cancelled if it
    # exists. If takeProfit is not provided, the exisiting Take Profit Order
    # will not be modified. If a sub-field of takeProfit is not specified, that
    # field will be set to a default value on create, and be inherited by the
    # replacing order on modify.
    # 
    takeProfit : (TakeProfitDetails),

    # 
    # The specification of the Stop Loss to create/modify/cancel. If stopLoss
    # is set to null, the Stop Loss Order will be cancelled if it exists. If
    # stopLoss is not provided, the exisiting Stop Loss Order will not be
    # modified. If a sub-field of stopLoss is not specified, that field will be
    # set to a default value on create, and be inherited by the replacing order
    # on modify.
    # 
    stopLoss : (StopLossDetails),

    # 
    # The specification of the Trailing Stop Loss to create/modify/cancel. If
    # trailingStopLoss is set to null, the Trailing Stop Loss Order will be
    # cancelled if it exists. If trailingStopLoss is not provided, the
    # exisiting Trailing Stop Loss Order will not be modified. If a sub-field
    # of trailngStopLoss is not specified, that field will be set to a default
    # value on create, and be inherited by the replacing order on modify.
    # 
    trailingStopLoss : (TrailingStopLossDetails)
}

Responses

Response Body Schema (application/json)

{
    # 
    # The Transaction created that cancels the Trade’s existing Take Profit
    # Order.
    # 
    takeProfitOrderCancelTransaction : (OrderCancelTransaction),

    # 
    # The Transaction created that creates a new Take Profit Order for the
    # Trade.
    # 
    takeProfitOrderTransaction : (TakeProfitOrderTransaction),

    # 
    # The Transaction created that immediately fills the Trade’s new Take
    # Profit Order. Only provided if the new Take Profit Order was immediately
    # filled.
    # 
    takeProfitOrderFillTransaction : (OrderFillTransaction),

    # 
    # The Transaction created that immediately cancels the Trade’s new Take
    # Profit Order. Only provided if the new Take Profit Order was immediately
    # cancelled.
    # 
    takeProfitOrderCreatedCancelTransaction : (OrderCancelTransaction),

    # 
    # The Transaction created that cancels the Trade’s existing Stop Loss
    # Order.
    # 
    stopLossOrderCancelTransaction : (OrderCancelTransaction),

    # 
    # The Transaction created that creates a new Stop Loss Order for the Trade.
    # 
    stopLossOrderTransaction : (StopLossOrderTransaction),

    # 
    # The Transaction created that immediately fills the Trade’s new Stop
    # Order. Only provided if the new Stop Loss Order was immediately filled.
    # 
    stopLossOrderFillTransaction : (OrderFillTransaction),

    # 
    # The Transaction created that immediately cancels the Trade’s new Stop
    # Loss Order. Only provided if the new Stop Loss Order was immediately
    # cancelled.
    # 
    stopLossOrderCreatedCancelTransaction : (OrderCancelTransaction),

    # 
    # The Transaction created that cancels the Trade’s existing Trailing Stop
    # Loss Order.
    # 
    trailingStopLossOrderCancelTransaction : (OrderCancelTransaction),

    # 
    # The Transaction created that creates a new Trailing Stop Loss Order for
    # the Trade.
    # 
    trailingStopLossOrderTransaction : (TrailingStopLossOrderTransaction),

    # 
    # The IDs of all Transactions that were created while satisfying the
    # request.
    # 
    relatedTransactionIDs : (Array[TransactionID]),

    # 
    # The ID of the most recent Transaction created for the Account
    # 
    lastTransactionID : (TransactionID)
}
Response Body Schema (application/json)

{
    # 
    # An OrderCancelRejectTransaction represents the rejection of the
    # cancellation of an Order in the client’s Account.
    # 
    takeProfitOrderCancelRejectTransaction : (OrderCancelRejectTransaction),

    # 
    # A TakeProfitOrderRejectTransaction represents the rejection of the
    # creation of a TakeProfit Order.
    # 
    takeProfitOrderRejectTransaction : (TakeProfitOrderRejectTransaction),

    # 
    # An OrderCancelRejectTransaction represents the rejection of the
    # cancellation of an Order in the client’s Account.
    # 
    stopLossOrderCancelRejectTransaction : (OrderCancelRejectTransaction),

    # 
    # A StopLossOrderRejectTransaction represents the rejection of the creation
    # of a StopLoss Order.
    # 
    stopLossOrderRejectTransaction : (StopLossOrderRejectTransaction),

    # 
    # An OrderCancelRejectTransaction represents the rejection of the
    # cancellation of an Order in the client’s Account.
    # 
    trailingStopLossOrderCancelRejectTransaction : (OrderCancelRejectTransaction),

    # 
    # A TrailingStopLossOrderRejectTransaction represents the rejection of the
    # creation of a TrailingStopLoss Order.
    # 
    trailingStopLossOrderRejectTransaction : (TrailingStopLossOrderRejectTransaction),

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

    # 
    # The IDs of all Transactions that were created while satisfying the
    # request.
    # 
    relatedTransactionIDs : (Array[TransactionID]),

    # 
    # The code of the error that has occurred. This field may not be returned
    # for some errors.
    # 
    errorCode : (string),

    # 
    # The human-readable description of the error that has occurred.
    # 
    errorMessage : (string, required)
}

Other Error Responses: 401, 404, 405