Overview
Retrieves the positions held in the specified account.
Description

This API returns information on positions held in an account. The response includes the total count of positions and information about each one - market symbol, type, strike price, expiration date.

Note that some of the properties in the response are complex - that is, they contain sub-properties. The marginAccountBalance, dtBalance, and cashAccountBalance all contain multiple sub-properties, as seen below.

Since an account may have a large number of positions, the API allows you to page through them in small groups by specifying how many to return at a time (the count) and the starting point for each group (the marker).

URL
https://etws.etrade.com/accounts/rest/accountpositions/{accountId}
HTTP Method: GET
Request Parameters
The only required parameter is the accountId. If the typeCode is OPTN, you must specify some additional parameters: the type code, CALL or PUT, the strike price, and the expiration date.
Property Type Required? Description
accountId path required Numeric account ID
count integer optional The number of positions to return in the response. If not specified, defaults to 25. Used for paging as described in the Notes below.
marker string optional Specifies the desired starting point of the set of items to return. Used for paging as described in the Notes below.
typeCode string optional The type of security. Possible values are: EQ (equity), OPTN (option), INDX (index), MF (mutual fund), FI (fixed income). If set to OPTN, must specify callPut, strikePrice, expYear, expMonth, and expDay.
symbol string conditional The market symbol. Required if typeCode is OPTN.
callPut enum conditional Specifies which type of option(s) to return. Possible values are: CALL or PUT. Required if typeCode is OPTN.
strikePrice double conditional Specifies the strikePrice of the desired option. Required if typeCode is OPTN.
expYear string conditional The year the option will expire, as specified in the option contract. Required if typeCode is OPTN.
expMonth integer conditional The year the option will expire, as specified in the option contract. Required if typeCode is OPTN.
expDay integer conditional The year the option will expire, as specified in the option contract. Required if typeCode is OPTN.
Sample Request 1 - Equities
GET https://etws.etrade.com/account/rest/accountpositions/83405188
Sample Request 2 - Options
GET https://etws.etrade.com/account/rest/accountpositions/83405188?typeCode=OPTN&symbol=GOOG&callPut=CALL&strikePrice=100&expYear=2011&expMonth=1&expDay=1
Response Properties
Property Type Description
accountId string Numeric account ID
count integer The number of positions contained in the response. If a count is not specified in the request, the defaults to a maximum of 25.
marker string Specifies the starting point for the next set of positions, if any. This property is empty if there are no more positions in the account after these.
AccountPositions complex Container for one or more account position elements
AccountPosition complex Container for information on a position. Only appears if the account has at least one position.
   costBasis double The amount the user paid for this position
   description string Text description of the position (e.g., company name)
   longOrShort string Whether the position is long or short. Possible values are: LONG, SHORT.
   marginable boolean Boolean that specifies whether the position counts toward your margin (true) or does not count toward your margin (false)
   qty double The number of shares held in this position. May include fractional shares.
   currentPrice double Current market price (last sale price)
   closePrice double Previous day's closing price
   marketValue double The value of a position, based on the quantity and previous day's closing price
   quoteType string Expiry type, if the product is an option. Possible values are: QUARTERLY, MONTHLY, or WEEKLY.
   adjustedOption boolean If TRUE, the option has been adjusted. Default is FALSE.
   deliverableStr string Display-formatted product identifier. For equities, this is a symbol; for options, this is a string containing symbol,"call" or "put", strike price, and expiration date.
   productId complex Container for product information for this position
      symbol string The market trading symbol for the option
      typeCode string The type of security. Possible values are: EQ (equity), OPTN (option), INDX (index), MF (mutual fund), FI (fixed income).
      callPut string Specifies whether options are being bought (call) or sold (put), as specified in the option order. Possible values are: CALL, PUT. Appears for options only.
      strikePrice double The strike price for the option. Appears for options only.
      expYear integer The year the option will expire. Appears for options only.
      expMonth integer The month (1-12) the option will expire. Appears for options only.
      expDay integer The day (1-31) the option will expire. Appears for options only.
Sample Response 1 - XML
<AccountPositionsResponse>
  <accountId>30049872</accountId>
  <count>2</count>
  <marker></marker>
  <AccountPositions>
    <AccountPosition>
      <costBasis>63.10</costBasis>
      <description>DU PONT E I DE NEMOURS & CO COM</description>
      <longOrShort>LONG</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>DD</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>10</qty>
      <currentPrice>49.76</currentPrice>
      <closePrice>49.34</closePrice>
      <marketValue>497.60</marketValue>
      <quoteType>2</quoteType>
      <adjustedOption>0</adjustedOption>
      <deliverableStr></deliverableStr>
    </AccountPosition>
    <AccountPosition>
      <costBasis>192.00</costBasis>
      <description>DELL INC COM</description>
      <longOrShort>LONG</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>DELL</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>20</qty>
      <currentPrice>9.59</currentPrice>
      <closePrice>9.55</closePrice>
      <marketValue>191.80</marketValue>
      <quoteType>2</quoteType>
      <adjustedOption>0</adjustedOption>
      <deliverableStr></deliverableStr>
    </AccountPosition>
  </AccountPositions>
</AccountPositionsResponse>
Sample Response 1 - JSON
{
  "AccountPositionsResponse": {
    "accountId": "83405188",
    "count": "2",
    "AccountPositions": {
      "AccountPosition": [
        {
          "costBasis": "1096.44",
          "description": "GOOGLE INC CL A",
          "longOrShort": "LONG",
          "marginable": "FALSE",
          "productId": {
            "symbol": "GOOG",
            "typeCode": "EQ"
          },
          "qty": "2",
          "marketValue": "1086.44"
        },
        {
          "costBasis": "54.30",
          "description": "HELMERICH AND PAYNE INC COM",
          "longOrShort": "LONG",
          "marginable": "TRUE",
          "productId": {
            "symbol": "HP",
            "typeCode": "EQ"
          },
          "qty": "1",
          "marketValue": "44.30"
        }
      ]
    }
  }
}
Sample Response 2 - XML
<AccountPositionsResponse>
  <accountId>83405188</accountId>
  <count>1</count>
  <marker></marker>
  <AccountPositions>
    <AccountPosition>
      <costBasis>31.40</costBasis>
      <description>GOOG Feb 20 '10 $500 Call</description>
      <longOrShort>SHORT</longOrShort>
      <productId>
        <symbol>GOP</symbol>
        <typeCode>OPTN</typeCode>
        <callPut>CALL</callPut>
        <strikePrice>500</strikePrice>
        <expYear>2010</expYear>
        <expMonth>2</expMonth>
        <expDay>20</expDay>
      </productId>
      <qty>-1</qty>
      <currentPrice>-3.32</currentPrice>
      <marketValue>-3320.00</marketValue>
    </AccountPosition>
  </AccountPositions>
</AccountPositionsResponse>
Sample Response 2 - JSON
{
  "AccountPositionsResponse": {
    "accountId": "83405188",
    "count": "1",
    "AccountPositions": {
      "AccountPosition": {
        "costBasis": "31.40",
        "description": "GOOG Feb 20 '10 $500 Call",
        "longOrShort": "SHORT",
        "productId": {
          "symbol": "GOP",
          "typeCode": "OPTN",
          "callPut": "CALL",
          "strikePrice": "500",
          "expYear": "2010",
          "expMonth": "2",
          "expDay": "20"
        },
        "qty": "-1",
        "currentPrice": "-3.32",
        "marketValue": "-3320.00"
      }
    }
  }
}
Notes
  • To page through a large number of items, use the count property to specify how many items to return in a group (the default is 25), and the marker property to specify the starting point (the default is the newest). For instance, a request with no count and no marker retrieves the newest 25 items. Each response includes a marker that points to the beginning of the next group. To page through all the items, repeat the request with the marker from each previous response until you receive a response with an empty marker, indicating that there are no more items.
  • The API does not explicitly provide for bi-directional paging. Your application can support paging backward and forward either by saving and re-using markers within the series (that is, to re-issue the requests for earlier pages in the series), or saving and re-displaying the items that are returned.
Sample use cases
Some possible use cases and workflows are described below.
Purpose Workflow Related APIs
List accounts,
display account details
Display the type, description, and net value for each of the user's accounts as well as a detail display for each account, including balances and positions. List Accounts,
Get Account Balance,
Get Account Positions
List and display positions Navigate from a detail display of account positions to an order list to possibly place orders and modify positions. List Orders,
Get Account Positions
Sandbox Samples

The following shows a typical request and response in the sandbox environment.

Request
GET https://etwssandbox.etrade.com/accounts/sandbox/rest/accountpositions/83405188?typeCode=EQ&symbol=IBM
Response
<AccountPositionsResponse>
  <accountId>83405188</accountId>
  <count>11</count>
  <marker></marker>
  <AccountPositions>
    <AccountPosition>
      <costBasis>1096.44</costBasis>
      <description>GOOGLE INC CL A</description>
      <longOrShort>LONG</longOrShort>
      <marginable>false</marginable>
      <productId>
        <symbol>GOOG</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>2</qty>
      <marketValue>1086.44</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>54.30</costBasis>
      <description>HELMERICH & PAYNE INC COM</description>
      <longOrShort>LONG</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>HP</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>1</qty>
      <marketValue>44.30</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>54.30</costBasis>
      <description>HELMERICH & PAYNE INC COM</description>
      <longOrShort>LONG</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>HP</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>1</qty>
      <marketValue>44.30</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>9595.75</costBasis>
      <description>INTERNATIONAL BUSINESS MACHS COM</description>
      <longOrShort>LONG</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>IBM</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>75</qty>
      <marketValue>9585.75</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>127.81</costBasis>
      <description>INTERNATIONAL BUSINESS MACHS COM</description>
      <longOrShort>SHORT</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>IBM</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>-1</qty>
      <marketValue>-127.81</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>2094.00</costBasis>
      <description>INTEL CORP COM</description>
      <longOrShort>LONG</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>INTC</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>100</qty>
      <marketValue>2084.00</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>67.94</costBasis>
      <description>MICROSOFT CORP COM</description>
      <longOrShort>LONG</longOrShort>
      <marginable>true</marginable>
      <productId>
        <symbol>MSFT</symbol>
        <typeCode>EQ</typeCode>
      </productId>
      <qty>2</qty>
      <marketValue>57.94</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>12.00</costBasis>
      <description>A Mar 20 '10 $35 Call</description>
      <longOrShort>LONG</longOrShort>
      <productId>
        <symbol>A</symbol>
        <typeCode>OPTN</typeCode>
        <callPut>CALL</callPut>
        <strikePrice>35</strikePrice>
        <expYear>2010</expYear>
        <expMonth>3</expMonth>
        <expDay>20</expDay>
      </productId>
      <qty>2</qty>
      <marketValue>200.00</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>31.40</costBasis>
      <description>GOOG Feb 20 '10 $500 Call</description>
      <longOrShort>SHORT</longOrShort>
      <productId>
        <symbol>GOP</symbol>
        <typeCode>OPTN</typeCode>
        <callPut>CALL</callPut>
        <strikePrice>500</strikePrice>
        <expYear>2010</expYear>
        <expMonth>2</expMonth>
        <expDay>20</expDay>
      </productId>
      <qty>-1</qty>
      <marketValue>-3320.00</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>14.70</costBasis>
      <description>HP Feb 20 '10 $37.5 Call</description>
      <longOrShort>LONG</longOrShort>
      <productId>
        <symbol>HP</symbol>
        <typeCode>OPTN</typeCode>
        <callPut>CALL</callPut>
        <strikePrice>37.50</strikePrice>
        <expYear>2010</expYear>
        <expMonth>2</expMonth>
        <expDay>20</expDay>
      </productId>
      <qty>1</qty>
      <marketValue>470.00</marketValue>
    </AccountPosition>
    <AccountPosition>
      <costBasis>0.10</costBasis>
      <description>YUM Apr 17 '10 $45 Call</description>
      <longOrShort>SHORT</longOrShort>
      <productId>
        <symbol>UUG</symbol>
        <typeCode>OPTN</typeCode>
        <callPut>CALL</callPut>
        <strikePrice>45</strikePrice>
        <expYear>2010</expYear>
        <expMonth>4</expMonth>
        <expDay>17</expDay>
      </productId>
      <qty>-1</qty>
      <marketValue>-5.00</marketValue>
    </AccountPosition>
  </AccountPositions>
</AccountPositionsResponse>
Related APIs

List Accounts, Get Account Balance, Get Transaction History, Get Transaction Details

PLEASE READ THE IMPORTANT DISCLOSURES BELOW

By using E*TRADE API ("API") and accepting the terms of the Application Programming Interface License Agreement and the Application Programming Interface User Agreement, you agree that API may employ security policies, procedures and systems of Third Party providers which may or may not be less stringent and secure than the policies, procedures and systems of E*TRADE Securities LLC ("E*TRADE") or its affiliates. Material provided on API may have been produced by independent third parties not affiliated or endorsed by E*TRADE or its affiliates ("Third Party"). To the extent that API or Third Party providers express opinions or make recommendations, you understand that such opinions or recommendations are expressed by the Third Party provider and are not the opinions or recommendations of E*TRADE or its affiliates. E*TRADE is not responsible for the accuracy of market data displayed on API or made available by Third Party providers. There may be latency between the time an order (or other information) is submitted from API and the time the order is received by E*TRADE. The E*TRADE Two Second Execution Guarantee or any similar guarantee does not apply for orders placed through API and Third Party provider web sites. The E*TRADE CompleteTM Protection Guarantee does not apply. Orders created and submitted through API are not vetted until they are received by E*TRADE. It is possible that E*TRADE may reject an order placed through API. Please see the Application Programming Interface License Agreement and the Application Programming Interface User Agreement for more information.


The E*TRADE family of companies provides financial services including trading, investing, and related banking products and services to retail investors.


Securities products and services offered by E*TRADE Securities LLC, Member FINRA/SIPC.


System response and account access times may vary due to a variety of factors, including trading volumes, market conditions, system performance, and other factors.