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".
Was this page helpful?