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.

Interacting with 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.

1. Retrieving 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"
}

2. Interpreting instruments positions

When trading instruments via the Investment API, positions can be locked for trading or other purposes (e.g., an account transfer). We provide full transparency on the current status of each position and allow full insight into the permitted actions that affect the position: