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.

Positions

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:

Field Description Example
quantity The total quantity of the position. 10.4
locked_for_trading The portion of the position reserved for existing open orders. 5
pending_settlement The portion of the total quantity that is not yet settled. The amount for outstanding settlements is always only a positive number, as it is only increased for purchase orders that have not yet been settled. 0
available_for_trading The portion of the position that is available for trading, minus the positions locked for trading and all other locks (e.g., withdrawals, holding periods) that apply to the position. 5.4

Was this page helpful?

On This Page