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 close
  • positions: an account-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"
      },
    ]
  }
}