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

Order Endpoints


POST/v3/accounts/{accountID}/orders

Create an Order for an Account

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]
Request Body Schema (application/json)

{
    # 
    # Specification of the Order to create
    # 
    order : (OrderRequest)
}

Responses

Response Headers

  • Location - A link to the Order that was just created
  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The Transaction that created the Order specified by the request.
    # 
    orderCreateTransaction : (Transaction),

    # 
    # The Transaction that filled the newly created Order. Only provided when
    # the Order was immediately filled.
    # 
    orderFillTransaction : (OrderFillTransaction),

    # 
    # The Transaction that cancelled the newly created Order. Only provided
    # when the Order was immediately cancelled.
    # 
    orderCancelTransaction : (OrderCancelTransaction),

    # 
    # The Transaction that reissues the Order. Only provided when the Order is
    # configured to be reissued for its remaining units after a partial fill
    # and the reissue was successful.
    # 
    orderReissueTransaction : (Transaction),

    # 
    # The Transaction that rejects the reissue of the Order. Only provided when
    # the Order is configured to be reissued for its remaining units after a
    # partial fill and the reissue was rejected.
    # 
    orderReissueRejectTransaction : (Transaction),

    # 
    # 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 rejected the creation of the Order as requested
    # 
    orderRejectTransaction : (Transaction),

    # 
    # 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),

    # 
    # 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 rejected the creation of the Order as requested.
    # Only present if the Account exists.
    # 
    orderRejectTransaction : (Transaction),

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

    # 
    # The ID of the most recent Transaction created for the Account. Only
    # present if the Account exists.
    # 
    lastTransactionID : (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, 403, 405

Examples

Request
body=$(cat << EOF
{
  "order": {
    "units": "100", 
    "instrument": "EUR_USD", 
    "timeInForce": "FOK", 
    "type": "MARKET", 
    "positionFill": "DEFAULT"
  }
}
EOF
)

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d "$body" \
  "<URL>/v3/accounts/<ACCOUNT>/orders"
Response Headers
HTTP/1.1 201 Created
Content-Length: 715
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format
Server: openresty/1.7.0.1
Connection: keep-alive
Location: <URL>/v3/accounts/<ACCOUNT>/orders/6367
Date: Wed, 22 Jun 2016 18:41:29 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6368", 
  "orderCreateTransaction": {
    "accountID": "<ACCOUNT>", 
    "batchID": "6367", 
    "id": "6367", 
    "instrument": "EUR_USD", 
    "positionFill": "DEFAULT", 
    "reason": "CLIENT_ORDER", 
    "time": "2016-06-22T18:41:29.264030555Z", 
    "timeInForce": "FOK", 
    "type": "MARKET_ORDER", 
    "units": "100", 
    "userID": <USERID>
  }, 
  "orderFillTransaction": {
    "accountBalance": "43650.75945", 
    "accountID": "<ACCOUNT>", 
    "batchID": "6367", 
    "financing": "0.00000", 
    "id": "6368", 
    "instrument": "EUR_USD", 
    "orderID": "6367", 
    "pl": "0.00000", 
    "price": "1.13027", 
    "reason": "MARKET_ORDER", 
    "time": "2016-06-22T18:41:29.264030555Z", 
    "tradeOpened": {
      "tradeID": "6368", 
      "units": "100"
    }, 
    "type": "ORDER_FILL", 
    "units": "100", 
    "userID": <USERID>
  }, 
  "relatedTransactionIDs": [
    "6367", 
    "6368"
  ]
}
Request
body=$(cat << EOF
{
  "order": {
    "timeInForce": "GTC", 
    "price": "1.6000", 
    "type": "TAKE_PROFIT", 
    "tradeID": "6368"
  }
}
EOF
)

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d "$body" \
  "<URL>/v3/accounts/<ACCOUNT>/orders"
Response Headers
HTTP/1.1 201 Created
Content-Length: 349
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format
Server: openresty/1.7.0.1
Connection: keep-alive
Location: <URL>/v3/accounts/<ACCOUNT>/orders/6369
Date: Wed, 22 Jun 2016 18:41:29 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6369", 
  "orderCreateTransaction": {
    "accountID": "<ACCOUNT>", 
    "batchID": "6369", 
    "id": "6369", 
    "price": "1.60000", 
    "reason": "CLIENT_ORDER", 
    "time": "2016-06-22T18:41:29.277548700Z", 
    "timeInForce": "GTC", 
    "tradeID": "6368", 
    "triggerCondition": "TRIGGER_DEFAULT", 
    "type": "TAKE_PROFIT_ORDER", 
    "userID": <USERID>
  }, 
  "relatedTransactionIDs": [
    "6369"
  ]
}
Request
body=$(cat << EOF
{
  "order": {
    "price": "1.5000", 
    "stopLossOnFill": {
      "timeInForce": "GTC", 
      "price": "1.7000"
    }, 
    "timeInForce": "GTC", 
    "instrument": "USD_CAD", 
    "units": "-1000", 
    "type": "LIMIT", 
    "positionFill": "DEFAULT"
  }
}
EOF
)

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d "$body" \
  "<URL>/v3/accounts/<ACCOUNT>/orders"
Response Headers
HTTP/1.1 201 Created
Content-Length: 447
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format
Server: openresty/1.7.0.1
Connection: keep-alive
Location: <URL>/v3/accounts/<ACCOUNT>/orders/6372
Date: Wed, 22 Jun 2016 18:41:29 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6372", 
  "orderCreateTransaction": {
    "accountID": "<ACCOUNT>", 
    "batchID": "6372", 
    "id": "6372", 
    "instrument": "USD_CAD", 
    "positionFill": "DEFAULT", 
    "price": "1.50000", 
    "reason": "CLIENT_ORDER", 
    "stopLossOnFill": {
      "price": "1.70000", 
      "timeInForce": "GTC"
    }, 
    "time": "2016-06-22T18:41:29.285982286Z", 
    "timeInForce": "GTC", 
    "triggerCondition": "TRIGGER_DEFAULT", 
    "type": "LIMIT_ORDER", 
    "units": "-1000", 
    "userID": <USERID>
  }, 
  "relatedTransactionIDs": [
    "6372"
  ]
}
Request
body=$(cat << EOF
{
  "order": {
    "price": "1.2000", 
    "timeInForce": "GTC", 
    "instrument": "EUR_CAD", 
    "units": "10000", 
    "clientExtensions": {
      "comment": "New idea for trading", 
      "tag": "strategy_9", 
      "id": "my_order_100"
    }, 
    "type": "MARKET_IF_TOUCHED", 
    "positionFill": "DEFAULT"
  }
}
EOF
)

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d "$body" \
  "<URL>/v3/accounts/<ACCOUNT>/orders"
Response Headers
HTTP/1.1 201 Created
Content-Length: 495
Access-Control-Allow-Headers: Authorization, Content-Type, Accept-Datetime-Format
Server: openresty/1.7.0.1
Connection: keep-alive
Location: <URL>/v3/accounts/<ACCOUNT>/orders/6373
Date: Wed, 22 Jun 2016 18:41:29 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6373", 
  "orderCreateTransaction": {
    "accountID": "<ACCOUNT>", 
    "batchID": "6373", 
    "clientExtensions": {
      "comment": "New idea for trading", 
      "id": "my_order_100", 
      "tag": "strategy_9"
    }, 
    "id": "6373", 
    "instrument": "EUR_CAD", 
    "positionFill": "DEFAULT", 
    "price": "1.20000", 
    "reason": "CLIENT_ORDER", 
    "time": "2016-06-22T18:41:29.290139236Z", 
    "timeInForce": "GTC", 
    "triggerCondition": "TRIGGER_DEFAULT", 
    "type": "MARKET_IF_TOUCHED_ORDER", 
    "units": "10000", 
    "userID": <USERID>
  }, 
  "relatedTransactionIDs": [
    "6373"
  ]
}

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 OrderID (csv) List of Order IDs to retrieve
state query OrderStateFilter The state to filter the requested Orders by [default=PENDING]
instrument query InstrumentName The instrument to filter the requested orders by
count query integer The maximum number of Orders to return [default=50, maximum=500]
beforeID query OrderID The maximum Order ID to return. If not provided the most recent Orders in the Account are returned

Responses

Response Headers

  • Link - A link to the next page of results if the results were paginated
  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The list of Order detail objects
    # 
    orders : (Array[Order]),

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

Other Error Responses: 400, 404, 405

Examples

Request
curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "<URL>/v3/accounts/<ACCOUNT>/orders?instrument=EUR_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>/orders?beforeID=6375&instrument=EUR_CAD>; rel="next"
Date: Wed, 22 Jun 2016 18:41:29 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6375", 
  "orders": [
    {
      "clientExtensions": {
        "comment": "New idea for trading", 
        "id": "my_order_100", 
        "tag": "strategy_9"
      }, 
      "createTime": "2016-06-22T18:41:29.294265338Z", 
      "id": "6375", 
      "instrument": "EUR_CAD", 
      "partialFill": "DEFAULT_FILL", 
      "positionFill": "POSITION_DEFAULT", 
      "price": "1.30000", 
      "replacesOrderID": "6373", 
      "state": "PENDING", 
      "timeInForce": "GTC", 
      "triggerCondition": "TRIGGER_DEFAULT", 
      "type": "MARKET_IF_TOUCHED", 
      "units": "10000"
    }
  ]
}

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 list of pending Order details
    # 
    orders : (Array[Order]),

    # 
    # 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>/pendingOrders"
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:29 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6375", 
  "orders": [
    {
      "clientExtensions": {
        "comment": "New idea for trading", 
        "id": "my_order_100", 
        "tag": "strategy_9"
      }, 
      "createTime": "2016-06-22T18:41:29.294265338Z", 
      "id": "6375", 
      "instrument": "EUR_CAD", 
      "partialFill": "DEFAULT_FILL", 
      "positionFill": "POSITION_DEFAULT", 
      "price": "1.30000", 
      "replacesOrderID": "6373", 
      "state": "PENDING", 
      "timeInForce": "GTC", 
      "triggerCondition": "TRIGGER_DEFAULT", 
      "type": "MARKET_IF_TOUCHED", 
      "units": "10000"
    }, 
    {
      "createTime": "2016-06-22T18:41:29.285982286Z", 
      "id": "6372", 
      "instrument": "USD_CAD", 
      "partialFill": "DEFAULT_FILL", 
      "positionFill": "POSITION_DEFAULT", 
      "price": "1.50000", 
      "state": "PENDING", 
      "stopLossOnFill": {
        "price": "1.70000", 
        "timeInForce": "GTC"
      }, 
      "timeInForce": "GTC", 
      "triggerCondition": "TRIGGER_DEFAULT", 
      "type": "LIMIT", 
      "units": "-1000"
    }, 
    {
      "createTime": "2016-06-22T18:41:29.281617221Z", 
      "id": "6371", 
      "price": "1.70000", 
      "replacesOrderID": "6369", 
      "state": "PENDING", 
      "timeInForce": "GTC", 
      "tradeID": "6368", 
      "triggerCondition": "TRIGGER_DEFAULT", 
      "type": "TAKE_PROFIT"
    }
  ]
}

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]
orderSpecifier path OrderSpecifier The Order Specifier [required]

Responses

Response Headers

  • Link - A link to the next page of results if the results were paginated
  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The details of the Order requested
    # 
    order : (Order),

    # 
    # 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]
orderSpecifier path OrderSpecifier The Order Specifier [required]
Request Body Schema (application/json)

{
    # 
    # Specification of the replacing Order
    # 
    order : (OrderRequest)
}

Responses

Response Headers

  • Location - A link to the replacing Order
  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The Transaction that cancelled the Order to be replaced.
    # 
    orderCancelTransaction : (OrderCancelTransaction),

    # 
    # The Transaction that created the replacing Order as requested.
    # 
    orderCreateTransaction : (Transaction),

    # 
    # The Transaction that filled the replacing Order. This is only provided
    # when the replacing Order was immediately filled.
    # 
    orderFillTransaction : (OrderFillTransaction),

    # 
    # The Transaction that reissues the replacing Order. Only provided when the
    # replacing Order was partially filled immediately and is configured to be
    # reissued for its remaining units.
    # 
    orderReissueTransaction : (Transaction),

    # 
    # The Transaction that rejects the reissue of the Order. Only provided when
    # the replacing Order was paritially filled immediately and was configured
    # to be reissued, however the reissue was rejected.
    # 
    orderReissueRejectTransaction : (Transaction),

    # 
    # The Transaction that cancelled the replacing Order. Only provided when
    # the replacing Order was immediately cancelled.
    # 
    replacingOrderCancelTransaction : (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 Transaction that rejected the creation of the replacing Order
    # 
    orderRejectTransaction : (Transaction),

    # 
    # 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),

    # 
    # 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 rejected the cancellation of the Order to be
    # replaced. Only present if the Account exists.
    # 
    orderCancelRejectTransaction : (Transaction),

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

    # 
    # The ID of the most recent Transaction created for the Account. Only
    # present if the Account exists.
    # 
    lastTransactionID : (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]
orderSpecifier path OrderSpecifier The Order Specifier [required]

Responses

Response Headers

  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The Transaction that cancelled the Order
    # 
    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 Transaction that rejected the cancellation of the Order. Only present
    # if the Account exists.
    # 
    orderCancelRejectTransaction : (OrderCancelRejectTransaction),

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

    # 
    # The ID of the most recent Transaction created for the Account. Only
    # present if the Account exists.
    # 
    lastTransactionID : (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]
orderSpecifier path OrderSpecifier The Order Specifier [required]
Request Body Schema (application/json)

{
    # 
    # The Client Extensions to update for the Order. Do not set, modify, or
    # delete clientExtensions if your account is associated with MT4.
    # 
    clientExtensions : (ClientExtensions),

    # 
    # The Client Extensions to update for the Trade created when the Order is
    # filled. Do not set, modify, or delete clientExtensions if your account is
    # associated with MT4.
    # 
    tradeClientExtensions : (ClientExtensions)
}

Responses

Response Headers

  • RequestID - The unique identifier generated for the request
Response Body Schema (application/json)

{
    # 
    # The Transaction that modified the Client Extensions for the Order
    # 
    orderClientExtensionsModifyTransaction : (OrderClientExtensionsModifyTransaction),

    # 
    # 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])
}
Response Body Schema (application/json)

{
    # 
    # The Transaction that rejected the modification of the Client Extensions
    # for the Order
    # 
    orderClientExtensionsModifyRejectTransaction : (OrderClientExtensionsModifyRejectTransaction),

    # 
    # 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 rejected the modification of the Client Extensions
    # for the Order. Only present if the Account exists.
    # 
    orderClientExtensionsModifyRejectTransaction : (OrderClientExtensionsModifyRejectTransaction),

    # 
    # 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