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 TradeStateFilter The state to filter the requested Trades by. [default=OPEN]
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
  • RequestID - The unique identifier generated for the request
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 Headers

  • RequestID - The unique identifier generated for the request
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 Headers

  • RequestID - The unique identifier generated for the request
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 Headers

  • RequestID - The unique identifier generated for the request
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 Headers

  • RequestID - The unique identifier generated for the request
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 Headers

  • RequestID - The unique identifier generated for the request
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