Positions #
The positions API provides information about an account’s current open positions. The response will include information such as cost basis, shares traded, and market value, which will be updated live as price information is updated. Once a position is closed, it will no longer be queryable through this API.
The Position Object #
Sample Position Object #
{
"asset_id": "904837e3-3b76-47ec-b432-046db621571b",
"symbol": "AAPL",
"exchange": "NASDAQ",
"asset_class": "us_equity",
"avg_entry_price": "100.0",
"qty": "5",
"side": "long",
"market_value": "600.0",
"cost_basis": "500.0",
"unrealized_pl": "100.0",
"unrealized_plpc": "0.20",
"unrealized_intraday_pl": "10.0",
"unrealized_intraday_plpc": "0.0084",
"current_price": "120.0",
"lastday_price": "119.0",
"change_today": "0.0084"
}
Attributes #
Attribute | Type | Notes |
---|---|---|
asset_id |
string/UUID | Asset ID |
symbol |
string | Asset symbol |
exchange |
string | Exchange name of the asset |
asset_class |
string | Asset class name |
avg_entry_price |
string/number | Average entry price of the position |
qty |
string/int | The number of shares |
side |
string | long |
market_value |
string/number | Total dollar amount of the position |
cost_basis |
string/number | Total cost basis in dollar |
unrealized_pl |
string/number | Unrealized profit/loss in dollars |
unrealized_plpc |
string/number | Unrealized profit/loss percent (by a factor of 1) |
unrealized_intraday_pl |
string/number | Unrealized profit/loss in dollars for the day |
unrealized_intraday_plpc |
string/number | Unrealized profit/loss percent (by a factor of 1) |
current_price |
string/number | Current asset price per share |
lastday_price |
string/number | Last day’s asset price per share based on the closing value of the last trading day |
change_today |
string/number | Percent change from last day price (by a factor of 1) |
swap_rate |
string/number | |
usd |
string/number | |
avg_entry_swap_rate |
string/number |
Getting All Positions #
GET /v1/trading/accounts/{account_id}/positions
Retrieves a list of the account’s open positions.
Request #
N/A
Response #
An array of Position objects
Getting an Open Position #
GET /v1/trading/accounts/{account_id}/positions/{symbol}
Retrieves the account’s open position for the given symbol
or asset_id
.
Request #
Parameters #
Attribute | Type | Notes |
---|---|---|
symbol |
string | PATH - The symbol or asset_id |
Response #
The requested Position object
Error Codes #
404
- Not Found: Position is not found
Close All Positions #
DELETE /v1/trading/accounts/{account_id}/positions
Closes (liquidates) all of the account’s open long and short positions. A response will be provided for each order that is attempted to be cancelled. If an order is no longer cancelable, the server will respond with status 500 and reject the request.
Request #
Parameters #
Attribute | Type | Notes |
---|---|---|
cancel_orders |
boolean | QUERY - If true is specified, cancel all open orders before liquidating all positions. |
Response #
HTTP 207 Multi-Status with body; an array of objects that include the order id and http status code for each status request.
Error Codes #
500
- Failed to liquidate
Closing a Position #
DELETE /v1/trading/accounts/{account_id}/positions/{symbol}
Closes (liquidates) the account’s open position for the given symbol
. Works for both long and short positions.
Request #
Parameters #
Attribute | Type | Notes |
---|---|---|
symbol |
string | PATH - symbol or asset_id |
qty |
string | QUERY - The number of shares to liquidate |
percentage |
string | QUERY - Percentage of position you want to liquidate |
Response #
An Order object
Error Codes #
404
- Not Found: Order is not found
Bulk fetching all accounts positions #
GET /v1/accounts/positions
Retrieves a list of the account’s open positions.
Request #
Parameters #
Attribute | Type | Notes |
---|---|---|
page |
integer | The number of the page of the results to be fetched. |
Response #
The response contains two fields:
asof
: the timestamp for which the positions are returned. It is always the last market closepositions
: anaccount-id
to position list map, contains the requested page’s accounts
The positions map is empty for the last page.
Note: when fetching bulk positions, which can take multiple minutes depending on the number of accounts managed have, a market close can happen, and after that a new set of results might be returned. To make sure results are consistent, please always check that the as_of
field didn’t change during the whole fetching process.
Sample Response #
{
"as_of": "2022-08-04T16:00:00-04:00",
"positions": {
"000c8a47-7487-430b-94e1-e628a71cd123": [
{
"asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
"symbol": "AAPL",
"exchange": "NASDAQ",
"asset_class": "us_equity",
"asset_marginable": true,
"qty": "0.079145874",
"avg_entry_price": "172.34",
"side": "long",
"market_value": "13.14850404762",
"cost_basis": "13.63999992516",
"unrealized_pl": "-0.49149587754",
"unrealized_plpc": "-0.0360334223047464",
"unrealized_intraday_pl": "0",
"unrealized_intraday_plpc": "0",
"current_price": "166.13",
"lastday_price": "166.13",
"change_today": "0",
"qty_available": "0.079145874"
},
]
}
}