Positions

A position represents the holdings of a specific instrument in a user’s account.

How positions work

When your first buy order is filled (i.e. fully executed), the resulting quantity of the instrument purchased will be represented as a position that can be queried via the Investment API. Placing buy and sell orders, corporate actions and account transfers can all change the quantity of your securities position.

Securities positions are tracked at account level, which means that a user can hold multiple positions in the same instrument.

Interpreting instrument positions

Prerequisites

Once you have an active user with an account group and a corresponding open account, you can already query positions for the account.

When trading instruments via the Investment API, positions can be locked for trading or other purposes (i.e. an account transfer). We provide full visibility of the current state of each position, allowing full insight into the permitted actions that affect the position:

Field	Description
Quantity	Total quantity of the position.
Locked for trading	Portion of the position that is reserved for existing open orders.
Available for trading	Portion of the position that is available for trading minus locked for trading and any other locks (i.e. withdrawals, holding periods) imposed on the position.

Interacting with positions

You can query positions in two different ways: per instrument ID or as a list of all positions per account.

List positions with GET /accounts/{account_id}/positions

Example response

{
  "meta": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "total_count": 1,
    "sort": "id",
    "order": "ASC"
  },
  "data": [
    {
      "account_id": "c5161455-4d27-4781-bc74-f05532e49a77",
      "instrument": {
        "isin": "US0378331005",
        "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
      },
      "quantity": "10.4",
      "locked_for_trading": "5",
      "pending_settlement": "0",
      "available_for_trading": "5.4"
    }
  ]
} 

Retrieve a single position by instrument ID with GET /accounts/{account_id}/positions/{instrument_id}

Example response

{
  "account_id": "c5161455-4d27-4781-bc74-f05532e49a77",
  "instrument": {
    "isin": "US0378331005",
    "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
  },
  "quantity": "10.4",
  "locked_for_trading": "5",
  "pending_settlement": "0",
  "available_for_trading": "5.4"
}

Next steps

Next you can have a look at our "Reporting guides".