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
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 OrderState The state to filter the requested Orders by
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
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 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
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
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 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 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