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

Position Endpoints


Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
accountID path AccountID Account Identifier [required]

Responses

Response Body Schema (application/json)

{
    # 
    # The list of Account Positions.
    # 
    positions : (Array[Position]),

    # 
    # 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>/positions"
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:35 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6381", 
  "positions": [
    {
      "instrument": "CHF_JPY", 
      "long": {
        "pl": "-2.34608", 
        "resettablePL": "-2.34608", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-2.34608", 
      "resettablePL": "-2.34608", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "AUD_JPY", 
      "long": {
        "pl": "-230.54045", 
        "resettablePL": "-230.54045", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-230.54045", 
      "resettablePL": "-230.54045", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "AUD_USD", 
      "long": {
        "pl": "-2.31173", 
        "resettablePL": "-2.31173", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-2.31173", 
      "resettablePL": "-2.31173", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "EUR_CAD", 
      "long": {
        "pl": "0.35963", 
        "resettablePL": "0.35963", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "0.35963", 
      "resettablePL": "0.35963", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "EUR_GBP", 
      "long": {
        "pl": "-21.81721", 
        "resettablePL": "-21.81721", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-21.81721", 
      "resettablePL": "-21.81721", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "EUR_CZK", 
      "long": {
        "pl": "-0.11620", 
        "resettablePL": "-0.11620", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-0.11620", 
      "resettablePL": "-0.11620", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "EUR_CHF", 
      "long": {
        "pl": "-868.95147", 
        "resettablePL": "-868.95147", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-868.95147", 
      "resettablePL": "-868.95147", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "GBP_JPY", 
      "long": {
        "pl": "-0.32444", 
        "resettablePL": "-0.32444", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-0.32444", 
      "resettablePL": "-0.32444", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "EUR_USD", 
      "long": {
        "pl": "-54344.85056", 
        "resettablePL": "-54344.85056", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-54300.44169", 
      "resettablePL": "-54300.44169", 
      "short": {
        "pl": "44.40887", 
        "resettablePL": "44.40887", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "USD_JPY", 
      "long": {
        "pl": "-20.20008", 
        "resettablePL": "-20.20008", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-20.20008", 
      "resettablePL": "-20.20008", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "USD_CAD", 
      "long": {
        "pl": "-483.91941", 
        "resettablePL": "-483.91941", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-486.16662", 
      "resettablePL": "-486.16662", 
      "short": {
        "pl": "-2.24721", 
        "resettablePL": "-2.24721", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "USD_DKK", 
      "long": {
        "pl": "-84.23588", 
        "resettablePL": "-84.23588", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-84.23588", 
      "resettablePL": "-84.23588", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }, 
    {
      "instrument": "GBP_CHF", 
      "long": {
        "pl": "-17.36306", 
        "resettablePL": "-17.36306", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-17.36306", 
      "resettablePL": "-17.36306", 
      "short": {
        "pl": "0.00000", 
        "resettablePL": "0.00000", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "0.00000"
    }
  ]
}

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
accountID path AccountID Account Identifier [required]

Responses

Response Body Schema (application/json)

{
    # 
    # The list of open Positions in the Account.
    # 
    positions : (Array[Position]),

    # 
    # 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>/openPositions"
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:35 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6387", 
  "positions": [
    {
      "instrument": "EUR_USD", 
      "long": {
        "averagePrice": "1.13032", 
        "pl": "-54344.85056", 
        "resettablePL": "-54344.85056", 
        "tradeIDs": [
          "6383", 
          "6385"
        ], 
        "units": "350", 
        "unrealizedPL": "-0.04700"
      }, 
      "pl": "-54300.44169", 
      "resettablePL": "-54300.44169", 
      "short": {
        "pl": "44.40887", 
        "resettablePL": "44.40887", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "unrealizedPL": "-0.04700"
    }, 
    {
      "instrument": "USD_CAD", 
      "long": {
        "pl": "-483.91941", 
        "resettablePL": "-483.91941", 
        "units": "0", 
        "unrealizedPL": "0.00000"
      }, 
      "pl": "-486.16662", 
      "resettablePL": "-486.16662", 
      "short": {
        "averagePrice": "1.28241", 
        "pl": "-2.24721", 
        "resettablePL": "-2.24721", 
        "tradeIDs": [
          "6387"
        ], 
        "units": "-600", 
        "unrealizedPL": "-0.08525"
      }, 
      "unrealizedPL": "-0.08525"
    }
  ]
}

Request

Name Located In Type Description
Authorization header string The authorization bearer token previously obtained by the client [required]
accountID path AccountID Account Identifier [required]
instrument path InstrumentName Name of the Instrument [required]

Responses

Response Body Schema (application/json)

{
    # 
    # The requested Position.
    # 
    position : (Position),

    # 
    # 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>/positions/EUR_USD"
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:35 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6387", 
  "position": {
    "instrument": "EUR_USD", 
    "long": {
      "averagePrice": "1.13032", 
      "pl": "-54344.85056", 
      "resettablePL": "-54344.85056", 
      "tradeIDs": [
        "6383", 
        "6385"
      ], 
      "units": "350", 
      "unrealizedPL": "-0.04700"
    }, 
    "pl": "-54300.44169", 
    "resettablePL": "-54300.44169", 
    "short": {
      "pl": "44.40887", 
      "resettablePL": "44.40887", 
      "units": "0", 
      "unrealizedPL": "0.00000"
    }, 
    "unrealizedPL": "-0.04700"
  }
}

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]
instrument path InstrumentName Name of the Instrument [required]
Request Body Schema (application/json)

{
    # 
    # Indication of how much of the long Position to closeout. Either the
    # string “ALL”, the string “NONE”, or a DecimalNumber representing how many
    # units of the long position to close using a PositionCloseout MarketOrder.
    # The units specified must always be positive.
    # 
    longUnits : (string, default=ALL),

    # 
    # The client extensions to add to the MarketOrder used to close the long
    # position.
    # 
    longClientExtensions : (ClientExtensions),

    # 
    # Indication of how much of the short Position to closeout. Either the
    # string “ALL”, the string “NONE”, or a DecimalNumber representing how many
    # units of the short position to close using a PositionCloseout
    # MarketOrder. The units specified must always be positive.
    # 
    shortUnits : (string, default=ALL),

    # 
    # The client extensions to add to the MarketOrder used to close the short
    # position.
    # 
    shortClientExtensions : (ClientExtensions)
}

Responses

Response Headers

  • Location - A link to the Position that was just closed out
Response Body Schema (application/json)

{
    # 
    # The MarketOrderTransaction created to close the long Position.
    # 
    longOrderCreateTransaction : (MarketOrderTransaction),

    # 
    # OrderFill Transaction that closes the long Position
    # 
    longOrderFillTransaction : (OrderFillTransaction),

    # 
    # OrderCancel Transaction that cancels the MarketOrder created to close the
    # long Position
    # 
    longOrderCancelTransaction : (OrderCancelTransaction),

    # 
    # The MarketOrderTransaction created to close the short Position.
    # 
    shortOrderCreateTransaction : (MarketOrderTransaction),

    # 
    # OrderFill Transaction that closes the short Position
    # 
    shortOrderFillTransaction : (OrderFillTransaction),

    # 
    # OrderCancel Transaction that cancels the MarketOrder created to close the
    # short Position
    # 
    shortOrderCancelTransaction : (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 created that rejects the creation of a MarketOrder to
    # close the long Position.
    # 
    longOrderRejectTransaction : (MarketOrderRejectTransaction),

    # 
    # The Transaction created that rejects the creation of a MarketOrder to
    # close the short Position.
    # 
    shortOrderRejectTransaction : (MarketOrderRejectTransaction),

    # 
    # 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 created that rejects the creation of a MarketOrder to
    # close the long Position. Only present if the Account exists and a long
    # Position was specified.
    # 
    longOrderRejectTransaction : (MarketOrderRejectTransaction),

    # 
    # The Transaction created that rejects the creation of a MarketOrder to
    # close the short Position. Only present if the Account exists and a short
    # Position was specified.
    # 
    shortOrderRejectTransaction : (MarketOrderRejectTransaction),

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

Examples

Request
body=$(cat << EOF
{
  "longUnits": "99"
}
EOF
)

curl \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d "$body" \
  "<URL>/v3/accounts/<ACCOUNT>/positions/EUR_USD/close"
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
Location: <URL>/v3/accounts/<ACCOUNT>/positions/EUR_USD
Date: Wed, 22 Jun 2016 18:41:35 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6389", 
  "longOrderCreateTransaction": {
    "accountID": "<ACCOUNT>", 
    "batchID": "6388", 
    "id": "6388", 
    "instrument": "EUR_USD", 
    "longPositionCloseout": {
      "instrument": "EUR_USD", 
      "units": "99"
    }, 
    "positionFill": "REDUCE_ONLY", 
    "reason": "POSITION_CLOSEOUT", 
    "time": "2016-06-22T18:41:35.029424520Z", 
    "timeInForce": "FOK", 
    "type": "MARKET_ORDER", 
    "units": "-99", 
    "userID": <USERID>
  }, 
  "longOrderFillTransaction": {
    "accountBalance": "43650.73177", 
    "accountID": "<ACCOUNT>", 
    "batchID": "6388", 
    "financing": "0.00000", 
    "id": "6389", 
    "instrument": "EUR_USD", 
    "orderID": "6388", 
    "pl": "-0.01329", 
    "price": "1.13018", 
    "reason": "MARKET_ORDER_POSITION_CLOSEOUT", 
    "time": "2016-06-22T18:41:35.029424520Z", 
    "tradeReduced": {
      "financing": "0.00000", 
      "realizedPL": "-0.01329", 
      "tradeID": "6383", 
      "units": "-99"
    }, 
    "type": "ORDER_FILL", 
    "units": "-99", 
    "userID": <USERID>
  }, 
  "relatedTransactionIDs": [
    "6388", 
    "6389"
  ]
}
Request
body=$(cat << EOF
{
  "longUnits": "ALL"
}
EOF
)

curl \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d "$body" \
  "<URL>/v3/accounts/<ACCOUNT>/positions/EUR_USD/close"
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
Location: <URL>/v3/accounts/<ACCOUNT>/positions/EUR_USD
Date: Wed, 22 Jun 2016 18:41:35 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT, PATCH, POST, GET, OPTIONS, DELETE
Content-Type: application/json
Response Body
{
  "lastTransactionID": "6391", 
  "longOrderCreateTransaction": {
    "accountID": "<ACCOUNT>", 
    "batchID": "6390", 
    "id": "6390", 
    "instrument": "EUR_USD", 
    "longPositionCloseout": {
      "instrument": "EUR_USD", 
      "units": "ALL"
    }, 
    "positionFill": "REDUCE_ONLY", 
    "reason": "POSITION_CLOSEOUT", 
    "time": "2016-06-22T18:41:35.034041665Z", 
    "timeInForce": "FOK", 
    "type": "MARKET_ORDER", 
    "units": "-251", 
    "userID": <USERID>
  }, 
  "longOrderFillTransaction": {
    "accountBalance": "43650.69807", 
    "accountID": "<ACCOUNT>", 
    "batchID": "6390", 
    "financing": "0.00000", 
    "id": "6391", 
    "instrument": "EUR_USD", 
    "orderID": "6390", 
    "pl": "-0.03370", 
    "price": "1.13018", 
    "reason": "MARKET_ORDER_POSITION_CLOSEOUT", 
    "time": "2016-06-22T18:41:35.034041665Z", 
    "tradesClosed": [
      {
        "financing": "0.00000", 
        "realizedPL": "-0.00013", 
        "tradeID": "6383", 
        "units": "-1"
      }, 
      {
        "financing": "0.00000", 
        "realizedPL": "-0.03357", 
        "tradeID": "6385", 
        "units": "-250"
      }
    ], 
    "type": "ORDER_FILL", 
    "units": "-251", 
    "userID": <USERID>
  }, 
  "relatedTransactionIDs": [
    "6390", 
    "6391"
  ]
}