E*TRADE Developer Platform ETRADE Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 273 [warning: Documents this large are best viewed by clicking the View PDF Link!]

E*TRADE Developer Platform
Developer Guide and API Reference
December 17, 2012
API Version: v0
Contents
Getting Started .............................................................................................................. 5
Introduction ............................................................................................................................. 6
Architecture ........................................................................................................................ 6
Authorization ....................................................................................................................... 6
Agreements ........................................................................................................................ 7
Support & Community ......................................................................................................... 8
The E*TRADE API .................................................................................................................. 9
About the API...................................................................................................................... 9
API Syntax .........................................................................................................................10
API Documentation ............................................................................................................11
Terminology .......................................................................................................................12
Next Steps .............................................................................................................................13
Developer Guide .......................................................................................................... 14
Authorizing the Application ....................................................................................................15
Overview ............................................................................................................................15
The User Experience .........................................................................................................17
Using OAuth Credentials ...................................................................................................19
The OAuth API Module ......................................................................................................21
The Sandbox Environment ....................................................................................................22
Overview ............................................................................................................................22
Accessing the Sandbox .....................................................................................................22
About Rate Limits ..................................................................................................................24
Overview ............................................................................................................................24
Limits .................................................................................................................................24
Requests for Multiple Items ................................................................................................24
The Get Rate Limits API ....................................................................................................25
About Notifications .................................................................................................................26
Alerts .................................................................................................................................26
Notifications .......................................................................................................................26
Streaming Updates ............................................................................................................26
The Streaming API ................................................................................................................27
Introduction ........................................................................................................................27
Notifications .......................................................................................................................27
Using Comet ......................................................................................................................29
Sample code ......................................................................................................................30
REST API Reference ................................................................................................... 34
Authorization .........................................................................................................................35
Get Request Token ............................................................................................................35
Authorize Application .........................................................................................................37
Get Access Token .............................................................................................................39
Renew Access Token ........................................................................................................41
Revoke Access Token .......................................................................................................43
Accounts ...............................................................................................................................45
List Accounts .....................................................................................................................45
Get Account Balance .........................................................................................................48
Get Account Positions ........................................................................................................53
List Alerts ...........................................................................................................................62
Read Alert ..........................................................................................................................68
Delete Alert ........................................................................................................................71
Get Transaction History .....................................................................................................73
Get Transaction Details .....................................................................................................87
Market ...................................................................................................................................91
Look Up Product ................................................................................................................91
Get Quote ..........................................................................................................................94
Get Option Chains ........................................................................................................... 115
Get Option Expire Dates .................................................................................................. 121
Orders ................................................................................................................................. 124
List Orders ....................................................................................................................... 124
Preview Equity Order ....................................................................................................... 142
Place Equity Order ........................................................................................................... 149
Preview Equity Order Change .......................................................................................... 157
Place Equity Order Change ............................................................................................. 163
Preview Option Order ...................................................................................................... 170
Place Option Order .......................................................................................................... 178
Preview Option Order Change ......................................................................................... 187
Place Option Order Change ............................................................................................. 194
Cancel Order ................................................................................................................... 202
Rate Limits .......................................................................................................................... 205
Get Rate Limits ................................................................................................................ 205
Notifications ......................................................................................................................... 208
Get Notifications .............................................................................................................. 208
Error Handling
................................................................................................................... 212
Overview .......................................................................................................................... 212
HTTP Status Codes ......................................................................................................... 214
Account Module Error Messages ..................................................................................... 215
Market Module Error Messages ....................................................................................... 216
Order Module Error Messages ......................................................................................... 217
Notification Error Messages ............................................................................................. 220
Code Resources ........................................................................................................ 221
Tutorial: Start Developing in Java ........................................................................................ 222
Introduction ...................................................................................................................... 222
Requirements .................................................................................................................. 222
Step 1: OAuth Authorization ............................................................................................. 222
Step 2: Retrieve a list of accounts .................................................................................... 224
What's next? .................................................................................................................... 225
E*TRADE SDK Guides ........................................................................................................ 226
Using the Java SDK ......................................................................................................... 226
Using the PHP SDK ......................................................................................................... 229
Using the VC++ SDK ....................................................................................................... 238
Code Snippets: Accounts .................................................................................................... 259
Initialize Accounts Client .................................................................................................. 259
List Accounts ................................................................................................................... 259
Get Account Balance ....................................................................................................... 259
Get Account Positions ...................................................................................................... 260
List Alerts ......................................................................................................................... 260
Read Alert ........................................................................................................................ 260
Delete Alert ...................................................................................................................... 261
Code Snippets: Market ........................................................................................................ 262
Initialize Market Client ...................................................................................................... 262
Get Quote ........................................................................................................................ 262
Look Up Product .............................................................................................................. 263
Get Option Expire Dates .................................................................................................. 263
Get Option Chains ........................................................................................................... 263
Code Snippets: Order .......................................................................................................... 265
Initialize Order Client ........................................................................................................ 265
List Orders ....................................................................................................................... 265
Preview Equity Order ....................................................................................................... 266
Place Equity Order ........................................................................................................... 266
Preview Equity Order Change .......................................................................................... 267
Place Equity Order Change ............................................................................................. 268
Preview Option Order ...................................................................................................... 269
Place Option Order .......................................................................................................... 270
Preview Option Order Change ......................................................................................... 271
Place Option Order Change ............................................................................................. 272
Cancel Order ................................................................................................................... 273
E*TRADE Developer Platform 5 Getting Started
Getting Started
This section provides a brief overview of the E*TRADE Developer Platform and offers
suggestions on how to start learning and using the API.
E*TRADE Developer Platform 6 Getting Started
Introduction
The E*TRADE Developer Platform enables E*TRADE customers and developers to create their
own investment applications that leverage E*TRADE's extensive market data offerings, order-
routing capabilities, and other services.
The platform's API also allows E*TRADE customers who currently use a third-party trading
platform to view E*TRADE account and market information and place trade orders directly to
E*TRADE from that platform.
Using the E*TRADE Developer Platform, a client application can:
Authenticate E*TRADE customers
Directly manage trading: place orders, modify or cancel orders, and check order status
Review specific information for an account, such as balances and current positions
Retrieve price and other information about an index, stock, or option
Receive system messages from E*TRADE
Architecture
The E*TRADE Developer Platform provides most of its services via a REST API. Most of the
API features are accessed via simple HTTP GET requests. Requests that require detailed
input, such as an order to buy or sell stock, use an HTTP POST request, with the parameters
included as either XML or JSON data. The HTTP DELETE request is also used, with one API,
to delete messages after they have been read.
Although most of the platform uses a RESTful request-response model, a streaming API is also
provided, so that an application can receive timely "push" notifications of order status changes.
Authorization
The E*TRADE REST API uses the OAuth protocol to authorize every service request. In
practice, this means that your application must enable users to log in to their E*TRADE account
and click a consent button to grant access for each session. For your application to do this,
even for testing purposes, requires an OAuth consumer key - a code that uniquely identifies the
application (i.e., the service consumer) and its developer.
Consumer keys
We support two levels of consumer key. An individual key is tied to a single user ID, and allows
access for only that user. This is appropriate for developing applications for personal use, or for
the early stages of a larger development effort. A vendor key, on the other hand, permits
access by multiple users and is appropriate for applications that may be widely distributed.
E*TRADE Developer Platform 7 Getting Started
Note that separate keys are required for accessing "sandbox" data (used for development and
testing purposes) versus actual production data. For this reason, a typical developer has at
least two consumer keys.
Requesting keys
To request a key, you must have an E*TRADE account. (You will also need the account so that
you can log in and use your application.) It can be a personal, professional, or corporate
account. If you don't have one, you can quickly set one up online at http://www.etrade.com.
For development purposes, it is not necessary to fund the account, but to do any actual trading
will require funds.
When you are logged in to your account, request a consumer key via a secure message on this
page: https://us.etrade.com/e/t/accounts/sccreatemsg. Select the subject "Technical Issue" and
the topic "E*TRADE API". Be sure to:
State that you are requesting a consumer key
Explain the type of application you are developing
Specify whether you want an individual or vendor key
You may also want to request that your user account be approved as a non-funded account, so
that you're not required to have funds in the account to keep it open.
Within a few business days, a sandbox consumer key will be sent back to you by secure
message, along with a Developer Agreement which you will need to review and sign. When
we've received your agreement and processed your request, we'll issue you a production
consumer key.
When you get the key, you will be notified of its scheduled expiration date - typically, two years
from its creation date.
Note that if you are assigned an individual key, rather than a vendor key, it will only work with
your E*TRADE account. Attempting to use an individual key with a different user account will
result in an error.
Agreements
Developers and users are asked to sign several types of agreements:
API Agreement - As a developer, you are asked to sign an API agreement before you
will be issued a consumer key for production data. As mentioned earlier, requesting a
key requires that you log in to your E*TRADE account and send a secure message.
Authorization - As a user, whenever the application starts a session with the E*TRADE
platform, you must log in to your E*TRADE account and agree to an authorization
request.
E*TRADE Developer Platform 8 Getting Started
RTQ Agreement - As a user, you must sign the Real-Time Quote Agreement before you
can access data with the quote API. You can do this at http://www.etrade.com.
Extended-hours Agreement - As a user, you must sign the Extended-Hours Disclosure
Agreement before you can perform after-hours trading (if the application supports this
feature). You can do this at http://www.etrade.com.
Support & Community
The E*TRADE Developer Platform discussion board is a rich resource where you can learn
more about the platform and share ideas and information with the E*TRADE developer
community. You may find answers there to technical problems or design challenges. Whether
you're a longtime E*TRADE developer or just getting started, we encourage you to participate in
this active development forum.
E*TRADE Developer Platform 9 Getting Started
The E*TRADE API
The E*TRADE Developer Platform provides a REST API and related resources for creating
customized investing applications, opening the door not just to trading applications but to new
applications and hybrids for algorithmic trading, social investing, and market intelligence. The
API can be used by individual E*TRADE investors building their own custom solutions as well
as third-party vendors building solutions for any E*TRADE customer.
About the API
Most of the platform services are REST APIs that provide information such as account lists,
quotes, and alerts, or functionality such as the ability to submit trade orders. Since the API is
RESTful, it is easy to integrate into your application statelessly, without complex session
management, and it flexibly delivers data in either JSON or XML format.
In addition, the platform supports a streaming API that lets you subscribe to timely "push"
notifications of order status updates.
API Versions
As the E*TRADE API evolves through multiple versions, development of new features always
takes place on the most current version of the API. Previous versions of the API are not revised
except in the case of critical bug fixes.
The original platform version is designated as version 0 or "v0".
API Modules
The APIs are organized into modules as shown in the table below. The module names are
used as part of the API syntax, and the same modules are used to organize the API
documentation.
API Module
Description
APIs
OAuth
Acquire, renew, and revoke OAuth token(s).
Get Request Token, Authorize
Application, Get Access Token,
Renew Access Token, Revoke
Access Token
Accounts
Get information on the user's accounts, including
transaction histories, as well as any alerts for the
user (trade executions, order expirations, bill
payments, etc.).
List Accounts, Get Account
Balance, Get Account Positions,
List Alerts, Read Alert, Delete
Alert, Get Transaction History,
Get Transaction Detail
Market
Look up symbols and company information, get
quotes, fundamentals, and performance history,
and build option tables.
Get Option Chains, Get Option
Expiration Dates, Look Up
Product, Get Quote
E*TRADE Developer Platform 10 Getting Started
Order
Get a list of current orders,
preview/place/modify/cancel orders for equities and
options.
List Orders, Cancel Order,
Preview Equity Order, Place
Equity Order, Preview Equity
Order Change, Place Equity
Order Change, Preview Option
Order, Place Option Order,
Preview Option Order Change,
Place Option Order Change
Streaming API
Subscribe to receive timely push notifications of
order status changes - fulfillment, cancellation, etc.
See documentation for details
on streaming subscriptions.
Notifications
Get notifications about the system and platform,
such as new features.
Get Notifications
Rate Limits
Check the API rate limits and see how many
requests are still available in the current time
interval.
Get Rate Limits
API Syntax
In version v0, most of the REST API calls are GETs, some are POSTs, and one call uses a
DELETE (to delete a message). In most of these, the URL has very similar syntax. Here's an
example:
https://etws.etrade.com/market/rest/quote/MSFT.json?detailFlag=FUNDAMENTAL
After the host (etws.etrade.com) comes the API module (e.g., oauth, account, market, or order),
a standard path element /rest/, and the API endpoint (quote in this example). There may be
path parameters (MSFT in this example). At the end of the path, ".json" may be added to
request JSON output instead of the default XML. Finally, some APIs use query parameters,
such as the detailFlag parameter shown here.
Case sensitivity
The API path and endpoint (market/rest/quote) are case-sensitive and should be lower case, as
should the ".json" parameter. Path parameters (MSFT) and query parameters are not case-
sensitive.
Sandbox syntax
The URL path for the sandbox environment is slightly different. Details can be found in our
Sandbox documentation.
Data formats
APIs that use HTTP POST will accept data in either XML or JSON format.
Responses use XML format by default. To receive JSON instead of XML, add ".json" in lower
case at the end of the path in the request URL.
E*TRADE Developer Platform 11 Getting Started
API Documentation
Our API documentation is organized into groups based on API modules. Within the modules,
each API is detailed separately. The following information is typically provided:
Description
URL
HTTP method(s)
Request parameters, response properties
Sample requests and responses
Notes on usage
Sample use cases
Related APIs
In-depth topics such as authorization, the sandbox test environment, system messages, and
rate limits are discussed separately in Developer Guide articles.
Request parameters
In this documentation, request parameters are shown in tables that indicated whether each
parameter is required (always present), conditional (present under certain circumstances), or
optional (decided by the developer). For example:
Parameter
Type
Description
accountId
path
Numeric account ID
If parameters must contain one of a specific set of values, the table lists the possible values and
the default value (i.e., the value that is assumed if the parameter is not specified).
Response properties
Responses are XML or JSON structures, and some properties of the response may be complex,
meaning that they are parents of sub-properties. In tables that describe these complex
structures, sub-properties are shown indented under the parent, as shown below.
Property
Type
Description
count
integer
Number of transactions in this response
transaction
complex
Container for the elements of a transaction
transactionId
long
Numeric transaction ID
transactionDate
long
Date and time in epoch time
E*TRADE Developer Platform 12 Getting Started
Terminology
This documentation assumes that the developer is familiar with trading concepts and market
terminology. For clarification of market terms, you may find the E*TRADE Financial Help Center
helpful.
Dates and times are all US Eastern Time. Most times and dates in API responses are
represented as epoch time, i.e., the number of seconds since 12:00am on January 1, 1970.
E*TRADE Developer Platform 13 Getting Started
Next Steps
1.
Apply for a consumer key
Follow the instructions in the introduction to get a consumer key so you can access the platform
and run the tutorial. You should receive a sandbox key and Developer Agreement within a few
business days.
2.
Review the documentation
We recommend starting with the developer guides for authorization and the sandbox. Then
familiarize yourself with the APIs. And no matter what language you're using, you may
appreciate the simple Java tutorial, which demonstrates getting authorized and requesting
account data.
3.
Explore the other Developer Platform resources
Our website includes SDKs and sample code for Java, PHP, and VC++. We've posted
information on how to partner with us and links to 3rd-party applications that use the E*TRADE
API. Finally, you may find valuable ideas and information at our News page or our online
Developer Community.
E*TRADE Developer Platform 14 Developer Guide
Developer Guide
This section contains guide chapters that introduce specific topics related to the platform:
Authorizing the Application
The Sandbox Environment
Rate Limits
About Notifications
The Streaming API
E*TRADE Developer Platform 15 Authorizing the Application
Authorizing the Application
Overview
The E*TRADE Developer Platform uses the OAuth authorization protocol, version 1.0a. OAuth
enables an authenticated user to authorize limited access to their account by third-party
applications, without exposing user credentials or other sensitive information.
This document provides a brief summary of OAuth and describes how it is used in our
developer platform. We recommend that developers be familiar with the detailed OAuth
information at: http://oauth.net/core/1.0a/.
OAuth workflow
The three actors in OAuth are:
Role
Definition
Example
Service provider
A service provider that uses OAuth to let a 3rd-party
application have limited access to a user's account
E*TRADE
User
An individual who has an account with the service provider
E*TRADE user who
uses your application
Consumer
A website or application that uses OAuth to access the
service provider with the user's permission
Your application
A core principle of OAuth is that the service provider can authenticate both the user and the
consumer. This provides a secure basis for the user to authorize the consumer for limited
access to the user's account on the service provider.
In principle, OAuth authorization requires three steps:
1. The service provider authenticates the consumer.
2. The service provider authenticates the user.
3. The user authorizes the consumer for limited access to the user's account on the service
provider.
E*TRADE OAuth lifecycle
With the E*TRADE Developer Platform, the process works like this:
E*TRADE Developer Platform 16 Authorizing the Application
1. The application uses its own credentials to acquire a temporary
request token from E*TRADE by calling the Get Request Token API.
2. Using the Authorize Application API, the application redirects the
user, along with the request token, to E*TRADE. There the user logs
in to E*TRADE and grants the application limited access to the user's
account. E*TRADE generates a verification code, which is passed to
the application (manually by the user, or automatically via a callback).
3. The application uses the verification code to acquire an access token
that grants temporary access to that user's account. This is done with
the Get Access Token API.
4. The access token is included with all requests to the E*TRADE API,
identifying the user and authorizing the application.
By default, the token expires after two hours of inactivity. At that time, the token may be
renewed with the Renew Access Token API. When the application terminates or is finished
with the token, we recommend that you revoke the token with the Revoke Access Token API.
Unless otherwise arranged with customer service, production tokens permanently expire at
midnight US Eastern time. A revoked or permanently expired token cannot be renewed.
Instead, a new token must be obtained by starting the OAuth lifecycle again as described
above.
Callbacks
As mentioned above, when the user authorizes the application, the E*TRADE website
generates a verification code that must be passed to the application. One approach is for the
user to simply copy the code and paste it into the application. A much better solution is for
E*TRADE to automatically redirect the user back to the application, using a callback URL with
the verification code added as a query parameter, as shown in these example URLs:
https://myapplicationsite.com/mytradingapp?oauth_verifier=WXYZ89
https://myapplicationsite.com?myapp=trading&oauth_verifier=WXYZ89
Configuring a callback
Using a callback requires that the callback URL be associated with your consumer key in the
E*TRADE system. To request this, log in to your E*TRADE account and send a secure
message to Customer Service. Select the subject "Technical Issues" and the topic "E*TRADE
API". State that you would like to have a callback configured, and specify your consumer key
and the desired callback URL. Your callback URL can be just a simple address, or can also
include query parameters.
Once the callback is configured, two system behaviors are changed:
E*TRADE Developer Platform 17 Authorizing the Application
1. The oauth_callback_confirmed property of the Request Token API returns TRUE
to show that there is a callback URL associated with the consumer key.
2. Users who approve the authorization request are automatically redirected to the callback
URL, with the verification code appended as a query parameter (as shown in the
example URLs above).
The User Experience
At runtime, the application redirects the user to the E*TRADE site to authorize the application.
There, the user authenticates on a webpage that includes a login form similar to this:
Once logged in, the user is presented with a request to authorize the application to access the
account, as shown below.
(Note that an individual consumer key only works with its original user. If any other user
attempts to use that key, a non-specific error message is displayed instead of an authorization
form, and the process halts.)
E*TRADE Developer Platform 18 Authorizing the Application
The name of the application is displayed (based on the consumer key that was passed to the
login page) along with the list of privileges that will be granted - e.g., submit and review orders,
retrieve account information, and retrieve market data. If the user agrees to the request,
E*TRADE generates a verification code that refers to this agreement.
If a callback URL is associated with the consumer key, the browser is automatically redirected
to that URL, with the verification key included as a URL parameter. If not, the user sees a page
that displays the verification code, as shown below, and the user has to manually copy the code
and paste it into a field in the application.
At that point, the application can send a request to E*TRADE for an access token, attaching the
consumer key, the verification code, and an appropriate signature based on the application's
consumer secret. The access token grants limited access to the user account for a fixed period
of time, and must be attached to all API requests as described below.
E*TRADE Developer Platform 19 Authorizing the Application
Using OAuth Credentials
Once the application has acquired OAuth credentials, as described above, they must be
attached to all API requests.
OAuth Credentials
Here are the credentials:
Property
Type
Description
oauth_consumer_key
string
The value used by the consumer to identify itself to the
service provider.
oauth_timestamp
integer
The date and time of the request, in epoch time. Must
be accurate within five minutes.
oauth_nonce
string
A nonce, as described in OAuth 1.0a documentation -
roughly, an arbitrary or random value that cannot be
used again with the same timestamp.
oauth_signature_method
string
The signature method used by the consumer to sign
the request. The only supported option is HMAC-
SHA1.
oauth_signature
string
Signature generated with the shared secret and token
secret using the specified
oauth_signature_method, as described in OAuth
documentation.
oauth_token
string
The consumer's access token issued by the service
provider.
Timestamp
A timestamp must accompany every REST request, stating the date and time of the request in
epoch time (i.e., the number of seconds since 12:00:00 a.m. January 1, 1970 UTC). When the
request is received at E*TRADE, the timestamp must be within five minutes of the current UTC
time.
Nonce
Every request must include a nonce - an arbitrary or random value, used to ensure that each
request is unique. The same nonce can be used for multiple requests, as long as those
requests do not have the same timestamp. A typical solution is to generate a random hash for
each request.
Signature
The application must include a signature as specified in the OAuth documentation at
http://oauth.net/core/1.0a/. The only supported OAuth version is 1.0a, and the only supported
hash method is HMAC-SHA1. For compatibility purposes, we recommend using the libraries
provided at http://oauth.net.
E*TRADE Developer Platform 20 Authorizing the Application
Note that most of the OAuth examples in this documentation are visually correct but
mathematically invalid - i.e., they may not contain values that can be used for testing a signature
algorithm. If you wish to test your signature algorithm, use the following table. Given the
provided input values, your code should produce the same resulting signature.
Item
Value
Key
c5bb4dcb7bd6826c7c4340df3f791188
Secret
7d30246211192cda43ede3abd9b393b9
Access Token
VbiNYl63EejjlKdQM6FeENzcnrLACrZ2JYD6NQROfVI=
Access Secret
XCF9RzyQr4UEPloA+WlC06BnTfYC1P0Fwr3GUw/B0Es=
Timestamp
1344885636
Nonce
0bba225a40d1bbac2430aa0c6163ce44
HTTP Method
GET
URL
https://etws.etrade.com/accounts/rest/accountlist
Resulting signature
%2FXiv96DzZabnUG2bzPZIH2RARHM%3D
Based on this information, your requests should contain the values shown below, although the
variables may be in a different sequence.
HTTP header info
Authorization: OAuth
oauth_nonce="0bba225a40d1bbac2430aa0c6163ce44",oauth_timestamp="1344885636",oauth_cons
umer_key="c5bb4dcb7bd6826c7c4340df3f791188",oauth_token="VbiNYl63EejjlKdQM6FeENzcnrLAC
rZ2JYD6NQROfVI%3D",oauth_signature="%2FXiv96DzZabnUG2bzPZIH2RARHM%3D",oauth_signature_
method="HMAC-SHA1"
GET request
https://etws.etrade.com/accounts/rest/accountlist?oauth_consumer_key=c5bb4dcb7bd6826c7
c4340df3f791188&oauth_nonce=0bba225a40d1bbac2430aa0c6163ce44&oauth_signature=%2FXiv96D
zZabnUG2bzPZIH2RARHM%3D&oauth_signature_method=HMAC-
SHA1&oauth_timestamp=1344885636&oauth_token=VbiNYl63EejjlKdQM6FeENzcnrLACrZ2JYD6NQROfV
I%3D
Submitting credentials
We recommend that you attach the OAuth information to a request by including it in the HTTP
header as XML or JSON, with the header name "Authorization" and the value "OAuth". Here is
an example:
Authorization: OAuth
oauth_consumer_key="282683cc9e4b8fc81dea6bc687d46758",oauth_timestamp="1273254425",
oauth_nonce="LTg2ODUzOTQ5MTEzMTY3MzQwMzE%3D",oauth_signature_method="HMAC-SHA1",
oauth_signature="FjoSQaFDKEDK1FJazlY3xArNflk%3D",oauth_token="FiQRgQCRGPo7Xdk6G8QDSEzX
0Jsy6sKN14cULcDavAGgU"
E*TRADE Developer Platform 21 Authorizing the Application
As an alternative, the OAuth information can be included as URL parameters. This is usually
less desirable, because it creates a long query string and tends to mix API parameters with
OAuth parameters. Below is an example of such a query string, for a query that would
otherwise have been very eimple.
https://etws.etrade.com/market/rest/quote/IBM?oauth_consumer_key=d85df5b910e3cb47b2a4c
f26c20229ae&oauth_nonce=2518627fd47688ae96fec0b2d11b8c24&oauth_signature=FXZWW1N5UkFNc
ayfpoGXWHsgYNc%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1343164357&
oauth_token=eu4zvG1xpZXlA0wGZx4oJDMDPdnna8IsVcVMqNxeKyQ%3D
Note that the E*TRADE API does not recognize OAuth credentials in the body of the HTTP
request. The only supported options are the header or the query string.
The OAuth API Module
The OAuth module of the E*TRADE Developer Platform includes the following REST APIs:
API
Description
Get Request Token
Returns a request token that can be used to initiate authorization.
Authorize Application
Using the request token, redirects the user to the E*TRADE authorization
page, where the user authorizes the consumer application to access the
account. This returns a verification code.
Get Access Token
Using the verification code, requests an access token that can be used to
access the E*TRADE API on the user's behalf
Renew Access Token
Renews the access token when it expires.
Revoke Access Token
Revokes the access token at the end of the session.
Each of these APIs is documented separately in detail.
E*TRADE Developer Platform 22 The Sandbox Environment
The Sandbox Environment
Overview
The E*TRADE Developer Platform provides a sandbox environment where developers can
safely experiment with the REST API and perform limited testing of applications, without
executing any actual transactions in real markets involving real securities or money.
Here's how it works:
No actual transactions are executed.
If you submit a request that contains a syntax error, you receive an appropriate error
message in response.
If you submit a valid request, you receive a sample response from stored data.
Sandbox responses use stored data that's intended to provide typical responses for basic use
cases. So the responses you receive will not contain current data, and may not exactly match
your requests in other ways. For instance, you might request quotes on GOOG and MSFT, and
receive AAPL, ORCL, and CSCO instead.
The sandbox provides a simple way for you to check your syntax, test your deserialization code,
see how data appears on your UI, and so on.
Sandbox Samples
Extensive samples of sandbox requests and responses are included in this documentation for
reference purposes.
Accessing the Sandbox
Sandbox login
To access the sandbox, you need an OAuth consumer key and secret for the sandbox. OAuth
is explained separately under Authorization, and the process of requesting a consumer key is
explained in the Getting Started guide.
To "log in" to the sandbox (i.e., to acquire an OAuth access token and secret for the session),
use your sandbox consumer key and secret, but otherwise use the same OAuth procedure that
you would normally use for actual production data, and the same authorization server.
The access token and secret that you receive in response to this request will only work on the
sandbox environment, not in the production environment. So as long as you are using your
sandbox credentials, there is no chance of accidentally triggering an actual market transaction,
even if you accidentally send your request to a production URL.
E*TRADE Developer Platform 23 The Sandbox Environment
Sandbox URLs
Calls to the sandbox use a slightly different syntax than calls to production. The table below
shows both. The sandbox syntax is different in two ways - the name of the server is different,
and "/sandbox/" is included in the path after the module.
Environment
URL
Production
https://etws.etrade.com/{module}/rest/{API}
Sandbox
https://etwssandbox.etrade.com/{module}/sandbox/rest/{API}
Sample URLs
https://etws.etrade.com/accounts/rest/alerts/1108
https://etwssandbox.etrade.com/accounts/sandbox/rest/alerts/1108
E*TRADE Developer Platform 24 About Rate Limits
About Rate Limits
Overview
The E*TRADE API uses rate limits to manage the volume of incoming requests.
Rate limits are implemented on the Accounts, Market, and Order API modules. The limit is
specified at two levels:
A "throttling" limit defines the maximum number of requests that will be processed per
second. This is designed to encourage a smooth level of activity and avoid large bursts
of requests.
A "consumption" limit defines the maximum requests per hour.
Requests that exceed the limit are not processed. Instead of the expected XML or JSON
response, they return an HTML error page containing the message: " Number of requests
exceeded the rate limit set ", with the HTTP status code 400. (See the separate documentation
on error codes for more information.)
The Get Rate Limits API allows applications to query the limits for the current user and get
current usage status. This allows the application to pace itself as needed and avoid failed
requests or periods of forced inactivity.
Limits
Rate limits are enforced separately for each consumer key, and within that, separately for each
API module. If your application requires higher limits, please contact Customer Service.
The table below shows the limits that are assigned to a typical consumer key. To give a sense
of how these limits work in actual practice, the table lists both the maximum requests per hour
(the typical tracking interval), and how that breaks down into average requests per second.
Module
Throttling Limit
(requests per second per user)
Consumption Limit
(requests per hour per user)
Accounts
2
7000
Market
4
14000
Order
2
7000
Requests for Multiple Items
A single request for multiple data items, such as a call to the Get Quote API that includes 25
different stock symbols as parameters, is treated as a single request.
E*TRADE Developer Platform 25 About Rate Limits
The Get Rate Limits API
For more information on how rate limits may affect your application and how your application
can respond, refer to the documentation on the Get Rate Limits API.
E*TRADE Developer Platform 26 About Notifications
About Notifications
The E*TRADE Developer Platform provides three types of communications from the system (in
addition to HTTP status messages and system error messages).
Alerts
Alert messages are triggered by various account activity or changes in account status. On the
E*TRADE website, you can see examples of alerts listed in a box on the Complete View page,
under the Accounts tab. The alerts may involve trade executions, warnings, margin calls
outstanding, order expirations, account balances, bill payments, direct deposits, debits, and so on.
In the E*TRADE REST API, the Accounts module provides APIs that can list, display, and delete alerts.
A typical application might check for alerts at the start of a session and occasionally throughout the
session, especially when displaying an appropriate page - for instance, a landing page or account status
page.
For more information, see the documentation for the Accounts module, which describes the List Alerts,
Read Alert, and Delete Alert APIs.
Notifications
The Notifications module provides a Get Notifications API that provides system notifications
about the E*TRADE service and developer platform that may be of interest to developers. A
typical user application would not user this API - it is provided as an information source for
developers.
These developer notifications are categorized as either "global" messages that are sent to all
developers, or "platform" messages that are targeted at a specific developer or developers. The
volume of these kinds of notifications is low.
For more information, see the documentation on the Get Notifications API in the Accounts module.
Streaming Updates
The platform provides a streaming API that pushes timely, low-latency messages out to clients
to notify the user of status changes on individual orders - full or partial execution, cancellation,
and so on. This streaming API is a separate service, not part of the REST API. To use this
service, the client must subscribe to the appropriate channels and "listen" to updates for
specified accounts.
Because these order-status updates are time-sensitive and may involve a high volume, a typical
interactive application might display them in a status bar, box, or popup. Alternatively, an
application might forward these notifications to the user as emails, instant messages, or SMS
text messages.
E*TRADE Developer Platform 27 The Streaming API
The Streaming API
Introduction
In addition to the REST APIs, the E*TRADE Developer Platform provides a streaming data
service that can push data out to an application, rather than requiring the application to poll for
the data. This streaming data service is based on the Comet web-service architecture, which
uses delayed responses or very long responses to break out of HTTP's single-page, request-
response model.
The application begins a session by submitting an HTTP request to the streaming data service.
The server sends back a response (containing one or more notifications) when triggered by
relevant events, such as a completed order. The application issues fresh HTTP requests as
needed to keep the session going.
In this way the application receives low-latency data, without any special message protocols, in
a way that does not involve a lot of network traffic or processing.
E*TRADE uses this architecture to push notifications of changes in order status.
Notifications
Notifications are requested by the application on a per-account basis. Notifications are sent
only for orders placed under the specified accounts.
A notification about a change in order status contains information about the specific order only;
it does not contain information about other orders for the account. If an application requests
notifications for an account, and places five orders using that account, then when those orders
are executed at least five separate notifications are triggered.
Notification events
Notifications are triggered by changes to order status, including the following:
Event
Description
Partial completion
Order has been partially executed. The status is still live, but the quantity executed
has changed.
Completion
Order has been filled.
Cancellation
Order has been cancelled.
Rejection
Order has been rejected.
Notification details
Item
Description
E*TRADE Developer Platform 28 The Streaming API
Account Number
Numeric account ID
Order Number
Sequential order number, unique within account
Order Status
Order status: open, pending, executed, cancelled, cancel-requested, etc.
Symbol
Security symbol
Order
Possible values are:
• BUY
• SELL
• SHORT
• COVER
• BUY_TO_OPEN
• SELL_TO_CLOSE
• SELL_TO_OPEN
• BUY_TO_CLOSE
Quantity
Quantity specified in the order. For stocks, this is a number of shares. For mutual
funds, this is a dollar value or, if selling the entire position, "All I Own".
Quantity Filled
Quantity that has been executed.
Price
Possible values are:
• Market
• Market_On_Close
• Limit
• Stop
• Stop_Limit
Price
Price for price type
Event Type
See event types listed below.
Sample Notification
Below is a sample order update message.
<class>com.etrade.lmq.orderstatus.common.dto.OrderStatusResponse</class>
<quantityFilled>0</quantityFilled>
<accountNumber>83531504</accountNumber>
<price>0</price>
<symbol>AAPL</symbol>
<legStatus>OPEN</legStatus>
<orderNumber>130</orderNumber>
<priceType>TRIGGER_UNSPECIFIED</priceType>
<orderAction>BUY</orderAction>
<quantity>5</quantity>
<eventType>OPEN</eventType>
<orderStatus>OPEN</orderStatus>
Complex orders
The following rules describe how complex orders are treated by the streaming service.
E*TRADE Developer Platform 29 The Streaming API
Each leg of an order is pushed as the update is returned from the market. The legs can
be pushed separately. Applications can correlate legs by using the orderNumber
included in the update.
For Buy Writes, the order status update shows both legs of the order. For partial
executions, the quantity filled is pushed for both the stock and the option.
For Spreads, the order status update shows both legs of the order. For partial
executions, the quantity filled is pushed for both legs.
Trailing stops and conditional orders
For trailing stops and conditional orders, an order status is sent if those orders are triggered and
executed. If a trailing stop is triggered, an order is sent to the market to execute (triggered
orders are market orders), and the notification alerts the user once the order is executed
(whether fully or partially).
When orders are cancelled (for example, "One-Cancels-All" orders), or when a user cancels a
conditional order, the order is cancelled within the E*TRADE system and not at the exchange.
Since the cancellation is a result of user action, no update message is sent.
Note that "Live" and "Open" are not valid statuses. Push events only occur when there is an
execution (full or partial), cancellation, or rejection from the exchange.
Using Comet
Our Comet web architecture uses the Bayeux protocol as described in Comet documentation.
There are significant differences between Comet 1.x and Comet 2.x. In the E*TRADE API v0,
Comet 1.x is supported.
We use the CometD implementation, and to use the service you'll need to use the CometD
libraries, available as shown here:
Resource
Link
CometD libraries for JavaScript and Java
http://cometd.org/documentation
CometD documentation for JavaScript
http://cometd.org/documentation/cometd-javascript
CometD documentation for Java
http://cometd.org/documentation/cometd-java
Comet service
The Comet service of the E*TRADE Developer Platform is accessible at this URL:
https://etwspush.etrade.com/apistream/cometd/oauth/
This service requires OAuth authorization, which is detailed in a separate section of the
Developer Platform documentation. Requests to the service must include an OAuth header -
E*TRADE Developer Platform 30 The Streaming API
i.e., the consumer key, access token, timestamp, nonce, signature method, and signature. If
the OAuth token expires during the session (e.g., at midnight US Eastern time), subsequent
HTTP requests from the application return authorization errors, not streaming updates, so
updates effectively cease with the first update after the token expires - even though the
subscription to the service is technically still in effect.
The general approach is to connect to the Comet service, subscribe to the update and error
channels, specify which accounts to listen to for activity, and use callback functions to handle
the messages that come in.
Channels
Here is a list of the channels used.
Channel
Published by
Description
/service/etws/join
client
Used for subscribing to channels, i.e., the order update
channel and the two error channels
/etws/error
service
Used for higher-level error messages
/service/etws/error
service
Used for errors specific to the subscription
/service/etws/accountlisten
client
Used for specifying which accounts to listen to for order
activity
/service/etws/accountunlisten
client
Used for specifying accounts to stop listening to
/service/etws/orderupdate
service
Used by service to transmit order status updates
Connecting requires that you publish to /service/etws/join with one of these two options:
Action
Description
join
cometd.publish("/service/etws/join", { type: 'join'});
reconnect
cometd.publish("/service/etws/join", { type: 'reconnect'});
Sample code
The following JavaScript examples demonstrate the basics of:
connecting to the service
subscribing to error messages and order status updates
listening to specific accounts for activity
unlistening to specific accounts
These samples require the CometD JavaScript library to work.
Connecting to the Service
This code establishes and re-establishes the connection to the service.
E*TRADE Developer Platform 31 The Streaming API
function _initialize()
{
_cometd = $.cometd; // Use the default Comet object
_cometUrl = "https://etwspush.etrade.com/apistream/cometd/oauth/";
_metaSubscriptions = [];
$.each(_metaSubscriptions, function(index, subscription) {
_cometd.removeListener(subscription)
});
_metaSubscriptions.push(_cometd.addListener('/meta/handshake', this,
_metaHandshake));
_metaSubscriptions.push(_cometd.addListener('/meta/connect', this, _metaConnect));
var oauthHeader = {Authorization: header};
_cometd.init({url: _cometUrl, requestHeaders: oauthHeader});
}
function _metaHandshake(message)
{
_handshook = message.successful;
_connected = false;
}
function _metaConnect(message)
{
var wasConnected = _connected;
_connected = message.successful;
if (wasConnected)
{
if (_connected)
{
// Normal operation, a long poll that reconnects
}
else
{
// Disconnected
}
}
else
{
if (_connected)
{
// Connected
baseSubscribe();
if(_firstConnection){
_cometd.publish("/service/etws/join", { type:'join'});
}else{
_cometd.publish("/service/etws/join", { type:'re-connect'});
}
_firstConnection = false;
}
else
{
// Could not connect
}
}
E*TRADE Developer Platform 32 The Streaming API
}
Handling Errors and Updates
This sample shows how callback functions are used to process messages from the error and
orderupdate channels, described in the table of channels above.
function handleError(message)
{
//Handle error
}
function handleUpdate(message)
{
//Handle order status update message
}
Subscribing to Notification Channels
This sample code subscribes to the channels for system errors, service errors, and order status
updates, using the subscribe() method from the Comet JavaScript library several times in a
batch.
function baseSubscribe(){
_cometd.startBatch();
channel = _cometd.subscribe("/etws/error", this, handleError);
channel = _cometd.subscribe("/service/etws/error", this, handleError);
channel = _cometd.subscribe("/service/etws/orderupdate", this, handleUpdate);
_cometd.endBatch();
}
Listening to Specific Accounts
Subscribing to the order-update channel is not sufficient for receiving order status updates. You
must also specify which accounts to listen to. This is done by publishing to accountlisten.
Specify a single account or a comma-separated list of accounts under the name "accounts", as
shown in these examples.
Examples
cometd.publish("/service/etws/accountlisten", {accounts:83405188});
cometd.publish("/service/etws/accountlisten", {accounts:83405188,83405557,83412346});
E*TRADE Developer Platform 33 The Streaming API
Unlistening to Specific Accounts
To stop listening to order status updates for one or more accounts, publish to
accountunlisten. Specify a single account or a comma-separated list of accounts under the
name "accounts", as shown in these examples.
Examples
cometd.publish("/service/etws/accountunlisten", {accounts:83405188});
cometd.publish("/service/etws/accountunlisten", {accounts:83405188,83405557,83412346})
Sample Response
Here is a sample order update message:
{
"class":"com.etrade.lmq.orderstatus.common.dto.OrderStatusResponse",
"quantityFilled":0,
"accountNumber":"83531504",
"price":0,
"symbol":"AAPL",
"legStatus":"OPEN",
"orderNumber":130,
"priceType":"TRIGGER_UNSPECIFIED",
"orderAction":"BUY",
"quantity":5,
"eventType":"OPEN",
"orderStatus":"OPEN"
}
E*TRADE Developer Platform 34 REST API Reference
REST API Reference
This section contains detailed reference material on each of the individual REST APIs,
organized into the following sub-sections:
Authorization
Accounts
Market
Orders
Rate Limits
Notifications
Error Handling
E*TRADE Developer Platform 35 Get Request Token
Authorization
Get Request Token
Returns
a temporary request token, initiating the OAuth process.
Description
This API returns
a temporary request token that begins the OAuth process. The request token
must accompany the user to the authorization page, where the user will grant your application
limited access to the account. The token expires after five minutes.
URL
https://etws.etrade.com/oauth/request_token
HTTP Method: GET
Request Parameters
Property
Type
Description
oauth_consumer_key
string
The value used by the consumer to identify itself to the service
provider.
oauth_timestamp
integer
The date and time of the request, in epoch time. Must be
accurate within five minutes.
oauth_nonce
string
A nonce, as described in the authorization guide - roughly, an
arbitrary or random value that cannot be used again with the
same timestamp.
oauth_signature_method
string
The signature method used by the consumer to sign the request.
The only supported value is "HMAC-SHA1".
oauth_signature
string
Signature generated with the shared secret and token secret
using the specified oauth_signature_method, as
described in OAuth documentation.
oauth_callback
string
Callback information, as described elsewhere. Must always be
set to "oob", whether using a callback or not.
Response Properties
Property
Type
Description
oauth_token
string
The consumer's request token
oauth_token_secret
string
The token secret
oauth_callback_confirmed
boolean
Returns true if a callback URL is configured for the current
consumer key, otherwise false. Callbacks are described under
the Authorize Application API.
E*TRADE Developer Platform 36 Get Request Token
Sample Request
URL
GET https://etws.etrade.com/oauth/request_token
HTTP header
Authorization: OAuth
realm="",oauth_callback="oob",oauth_signature="FjoSQaFDKEDK1FJazlY3xArNflk%3D",
oauth_nonce="LTg2ODUzOTQ5MTEzMTY3MzQwMzE%3D",oauth_signature_method="HMAC-
SHA1",oauth_consumer_key="282683cc9e4b8fc81dea6bc687d46758",oauth_timestamp="127325442
5"
Sample Response
The response data is contained in the body of the response, URL-encoded. (This encoding type
is identified in the response header, just as with XML and JSON responses.)
oauth_token=%2FiQRgQCRGPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D&oauth_token_secret=%2FrC9
scEpzcwSEMy4vE7nodSzPLqfRINnTNY4voczyFM%3D&oauth_callback_confirmed=true
Notes
The request token is only valid for 5 minutes.
E*TRADE Developer Platform 37 Authorize Application
Authorize Application
Allows the user to authorize the consumer application.
Description
Once your application has the request token, it should redirect the user to an E*TRADE
authorization page, as shown in the URL below. Include the request token and your consumer
key as parameters in the URL as shown. The page at this URL asks the user to authorize your
application. Upon approval of the authorization request, E*TRADE generates a verification
code.
By default, E*TRADE then displays this verification code in an "Authorization Complete" page,
allowing the user to manually copy the code and paste it into your application. However, the
recommended alternative is for E*TRADE to pass the verification code directly into your
application via a pre-configured callback URL.
Using a callback requires that the callback URL be associated with your consumer key in the
E*TRADE system. To request this, follow the instructions in our Authorization guide chapter
(separate from this API reference). Your callback URL can be just a simple address, or can
also include query parameters. Once the callback is configured, users who approve the
authorization request are automatically redirected to the specified URL, with the verification
code appended as a query parameter. Examples are shown in the Sample Response below.
URL
https://us.etrade.com/e/etws/authorize?key={oauth_consumer_key}&token={oauth_token}
HTTP Method: GET
Request Parameters
Property
Type
Required?
Description
oauth_consumer_key
string
required
The value used by the consumer to identify itself to the
service provider.
oauth_token
string
required
The consumer's request token.
Response Properties
Property
Type
Description
oauth_verifier
query parameter
verification code
Sample Request
https://us.etrade.com/e/etws/authorize?key=282683cc9e4b8fc81dea6bc687d46758&token=%2Fi
QRgQCRGPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D
E*TRADE Developer Platform 38 Authorize Application
Sample Response
As described above, the authorize call is not a REST API in the usual sense, and does not
return a "response" in the usual way. If the user authorizes your application on the E*TRADE
authorization site, the result is either the display of a verification code at that site or, if a callback
is used, a redirect to your callback URL.
In the callback scenario, the verification code is appended to your callback URL as an
oauth_verifier parameter. Here are two examples:
https://myapplicationsite.com/mytradingapp?oauth_verifier=WXYZ89
https://myapplicationsite.com?myapp=trading&oauth_verifier=WXYZ89
Notes
If using the default approach - letting the user copy and paste the verification code - we
recommend opening a separate browser window for the authorization, leaving your
application open in the original window. Once the user has authorized your application and
copied the verification code, the user can simply close the authorization window and return
to your application in the original window.
If using the callback approach, we recommend redirecting to the authorization page in the
current window. Once the user has authorized your application, E*TRADE redirects the
user to your callback page; the verification code is included as a URL parameter (as in the
sample response above).
E*TRADE Developer Platform 39 Get Access Token
Get Access Token
Returns an
OAuth access token.
Description
This method returns an access token, which confirms that the user has authorized the
application to access user data.
All calls to the E*TRADE API (e.g., accountlist, placeequityorder, etc.) must include this access
token along with the consumer key, timestamp, nonce, signature method, and signature. This
can be done in the query string, but is typically done in the HTTP header.
Token lifespan
By default, the access token expires at the end of the current calendar day, US Eastern time.
Once the token has expired, no requests will be processed for that token until the OAuth
process is repeated - i.e., the user must log in again and the application must secure a new
access token.
During the current day, if the application does not make any requests for two hours, the access
token is inactivated. In this inactive state, the access token is not valid for authorizing requests.
It must be reactivated using the Renew Access Token API.
URL
https://etws.etrade.com/oauth/access_token
HTTP Method: GET
Request Parameters
Property
Type
Required?
Description
oauth_consumer_key
string
required
The value used by the consumer to identify itself to
the service provider.
oauth_timestamp
integer
required
The date and time of the request, in epoch time.
Must be accurate to within five minutes.
oauth_nonce
string
required
A nonce, as described in the authorization guide -
roughly, an arbitrary or random value that cannot be
used again with the same timestamp.
oauth_signature_method
string
required
The signature method used by the consumer to sign
the request. The only supported value is "HMAC-
SHA1".
E*TRADE Developer Platform 40 Get Access Token
oauth_signature
string
required
Signature generated with the shared secret and
token secret using the specified
oauth_signature_method, as described in OAuth
documentation.
oauth_token
string
required
The consumer's request token to be exchanged for
an access token.
oauth_verifier
string
required
The code received by the user to authenticate with
the third-party application.
Response Properties
Property
Type
Description
oauth_token
string
The consumer's access token
oauth_token_secret
integer
The token secret
Sample Request
URL
GET https://etws.etrade.com/oauth/access_token
HTTP header
Authorization: OAuth
realm="",oauth_signature="FjoSQaFDKEDK1FJazlY3xArNflk%3D",oauth_nonce="LTg2ODUzOTQ5MTE
zMTY3MzQwMzE%3D",oauth_signature_method="HMAC-SHA1",oauth_consumer_key=
"282683cc9e4b8fc81dea6bc687d46758",oauth_timestamp="1273254425",oauth_verifier="Y27X25
F",oauth_token=%2FiQRgQCRGPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D
Sample Response
oauth_token=%3TiQRgQCRGPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D&oauth_token_secret=%7RrC9
scEpzcwSEMy4vE7nodSzPLqfRINnTNY4voczyFM%3D
Notes
The production access token expires by default at midnight US Eastern time.
Technically, the access token and related parameters can be passed with HTTP requests as
part of the URL, but we recommend this information be passed in the header of the request
instead.
E*TRADE Developer Platform 41 Renew Access Token
Renew Access Token
Renews the OAuth access token after two hours or more of inactivity.
Description
If the application does not make any requests for two hours, the access token is inactivated. In
this inactive state, the access token is not valid for authorizing requests. It must be reactivated
using the Renew Access Token API.
By default the access token expires at midnight US Eastern time. Once the token has expired,
no further requests will be processed until the user logs in again and the application secures a
new access token.
URL
https://etws.etrade.com/oauth/renew_access_token
HTTP Method: GET
Request Parameters
Property
Type
Required?
Description
oauth_consumer_key
string
required
The value used by the consumer to identify itself to
the service provider.
oauth_timestamp
integer
required
The date and time of the request, in epoch time.
Must be accurate within five minutes.
oauth_nonce
string
required
A nonce, as described in the authorization guide -
roughly, an arbitrary or random value that cannot be
used again with the same timestamp.
oauth_signature_method
string
required
The signature method used by the consumer to sign
the request. The only supported value is "HMAC-
SHA1".
oauth_signature
string
required
Signature generated with the shared secret and
token secret using the specified
oauth_signature_method, as
described in OAuth documentation.
oauth_token
string
required
The consumer's request token to be exchanged for
an access token.
Response Properties
Property
Type
Description
oauth_token
string
The consumer's access token.
oauth_token_secret
integer
The token secret.
E*TRADE Developer Platform 42 Renew Access Token
Sample Request
URL
GET https://etws.etrade.com/oauth/renew_access_token
HTTP header
Authorization: OAuth
realm="",oauth_signature="FjoSQaFDKEDK1FJazlY3xArNflk%3D",oauth_nonce="LTg2ODUzOTQ5MTE
zMTY3MzQwMzE%3D",oauth_signature_method="HMAC-SHA1",oauth_consumer_key=
"282683cc9e4b8fc81dea6bc687d46758",oauth_timestamp="1273254425",oauth_token=%2FiQRgQCR
GPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D
Sample Response
oauth_token=%3TiQRgQCRGPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D&oauth_token_secret=%7RrC9
scEpzcwSEMy4vE7nodSzPLqfRINnTNY4voczyFM%3D
E*TRADE Developer Platform 43 Revoke Access Token
Revoke Access Token
Revokes an OAuth access token.
Description
This method revokes an access token that was granted for the consumer key. Once the token
is revoked, it no longer grants access to E*TRADE data. We strongly recommend revoking the
access token once your application no longer needs access to the user's E*TRADE account. In
the event of a security compromise, a revoked token is useless to a malicious entity.
URL
https://etws.etrade.com/oauth/revoke_access_token
HTTP Method: GET
Request Parameters
Property
Type
Required?
Description
oauth_consumer_key
string
required
The value used by the consumer to identify itself to the
service provider.
oauth_timestamp
integer
required
The date and time of the request, in epoch time. Must
be accurate within five minutes.
oauth_nonce
string
required
A nonce, as described in the authorization guide -
roughly, an arbitrary or random value that cannot be
used again with the same timestamp.
oauth_signature_method
string
required
The signature method used by the consumer to sign
the request. The only supported value is "HMAC-
SHA1".
oauth_signature
string
required
Signature generated with the shared secret and token
secret using the specified
oauth_signature_method, as described
in OAuth documentation.
oauth_token
string
required
The consumer's access token to be revoked.
Response Properties
Property
Type
Description
oauth_token
string
The consumer's access token
oauth_token_secret
integer
The token secret
Sample Request
URL
GET https://etws.etrade.com/oauth/revoke_access_token
E*TRADE Developer Platform 44 Revoke Access Token
HTTP header
Authorization: OAuth
realm="",oauth_signature="FjoSQaFDKEDK1FJazlY3xArNflk%3D",oauth_nonce="LTg2ODUzOTQ5MTE
zMTY3MzQwMzE%3D",oauth_signature_method="HMAC-SHA1",oauth_consumer_key=
"282683cc9e4b8fc81dea6bc687d46758",oauth_timestamp="1273254425",oauth_token=%2FiQRgQCR
GPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D
Sample Response
oauth_token=%3TiQRgQCRGPo7Xdk6G8QDSEzX0Jsy6sKNcULcDavAGgU%3D&oauth_token_secret=%7RrC9
scEpzcwSEMy4vE7nodSzPLqfRINnTNY4voczyFM%3D
E*TRADE Developer Platform 45 List Accounts
Accounts
List Accounts
Retrieves
a list of the current user's E*TRADE brokerage accounts.
Description
This API returns a list of E*TRADE accounts for the current user. Only brokerage accounts are
returned - that is, accounts that can be used for trading, as opposed to credit cards, etc.
URL
https://etws.etrade.com/accounts/rest/accountlist
HTTP Method: GET
Request Parameters
No parameters.
Response Properties
Property
Type
Description
accountDesc
string
A text description of the account
accountId
integer
Numeric account ID
marginLevel
string
The account's margin level. Possible values are: CASH, MARGIN.
netAccountValue
double
The total value of the account. This includes cash plus stocks, options,
mutual funds, and bonds.
registrationType
string
The type of account. Possible values are: INDIVIDUAL, JOINT,
CORPORATE, IRA, ESTATE, TRUST.
Sample Request
GET https://etws.etrade.com/accounts/rest/accountlist
Sample response - XML
<AccountListResponse>
<Account>
<accountDesc>MyAccount-1</accountDesc>
<accountId>83405188</accountId>
<marginLevel>MARGIN</marginLevel>
<netAccountValue>9999871.82</netAccountValue>
<registrationType>INDIVIDUAL</registrationType>
</Account>
<Account>
E*TRADE Developer Platform 46 List Accounts
<accountDesc>MyAccount-3</accountDesc>
<accountId>83405553</accountId>
<marginLevel>CASH</marginLevel>
<netAccountValue>100105468.99</netAccountValue>
<registrationType>INDIVIDUAL</registrationType>
</Account>
<Account>
<accountDesc>SIMPLE IRA</accountDesc>
<accountId>83405188</accountId>
<marginLevel>CASH</marginLevel>
<netAccountValue>99794.13</netAccountValue>
<registrationType>IRA</registrationType>
</Account>
</AccountListResponse>
Sample response - JSON
{
"AccountListResponse": {
"Account": [
{
"accountDesc": "MyAccount-1",
"accountId": "83405188",
"marginLevel": "MARGIN",
"netAccountValue": "9999871.82",
"registrationType": "INDIVIDUAL"
},
{
"accountDesc": "MyAccount-3",
"accountId": "83405553",
"marginLevel": "CASH",
"netAccountValue": "100105468.99",
"registrationType": "INDIVIDUAL"
},
{
"accountDesc": "SIMPLE IRA",
"accountId": "83405188",
"marginLevel": "CASH",
"netAccountValue": "99794.13",
"registrationType": "IRA"
}
]
}
}
Sample use cases
Some possible use cases and workflows are described below.
Purpose
Workflow
Related APIs
E*TRADE Developer Platform 47 List Accounts
List accounts,
account detail
Display the type, description, and net value for
each of the user's accounts as well as a detail
display for each account.
List Accounts,
Get Account Balance,
Get Account Positions
Set the active
account for a trade
When setting up an order, allow the user to
select an account; this is critical when a user has
multiple accounts and wants to place an order in
a specific account (e.g., IRA rather than day-
trading account).
List Accounts,
Get Account Balance
Retrieve account
summary info for
order lists, order
previews, and order
validation
When listing orders, previewing an order, or
validating an order before placing it, use List
Accounts to look up the account type,
description, and balance(s).
Get Account Balance,
List Orders,
Preview Equity Order,
Preview Option Order,
Preview Equity Order Change,
Preview Option Order Change
Related APIs
Get Account Balance, Get Account Positions
E*TRADE Developer Platform 48 Get Account Balance
Get Account Balance
Retrieves
the current account balance and related details for a specified account.
Description
This API returns detailed balance information for a specified account for the current user. The
information returned includes account type, option level, and details on up to four balances -
account balance, margin account balance, day trade balance, and cash account balance.
URL
https://etws.etrade.com/accounts/rest/accountbalance/{accountId}
HTTP Method: GET
Request Parameters
Property
Type
Description
accountId
path
Numeric account ID
Sample Request
GET https://etws.etrade.com/accounts/rest/accountbalance/83405188
Response Properties
Property
Type
Description
accountId
integer
Numeric account ID
accountType
string
The account's margin level. Possible values are:
CASH, MARGIN.
optionLevel
string
The option level of the account, i.e., what
option-related actions are allowed. Possible
values are:
• LEVEL_1 - Write covered calls.
• LEVEL_2 - Write covered calls, purchases.
• LEVEL_3 - Write covered calls, purchases,
spreads, uncovered puts. (Margin or IRA
account required for spreads; margin account
required for uncovered puts.)
• LEVEL_4 - Write covered calls, purchases,
spreads, uncovered puts, uncovered
equity/index calls, and uncovered index puts.
(Margin account required.)
accountBalance
complex
Container for basic brokerage account balances
cashAvailableForWithdrawal
double
The amount of cash that is available for
withdrawal
E*TRADE Developer Platform 49 Get Account Balance
cashCall
double
If a cash call has been issued, this value is the
amount of cash or equivalent securities needed
to meet the cash call. For a definition of cash
call, refer to the E*TRADE online glossary.
fundsWithheldFromPurchasePower
double
The amount of any funds withheld from the
purchasing power, if any
fundsWithheldFromWithdrawal
double
The total of any funds that are not allowed to be
withdrawn
netAccountValue
double
The account value minus any margin debt
netCash
double
The net cash amount held in the account. A
negative balance reflects margin debt.
sweepDepositAmount
double
The amount held in the sweep deposit account
totalLongValue
double
The total value of securities that are held long in
the account
totalSecuritiesMktValue
double
The total value of the securities held in the
account
totalCash
double
The total cash amount held in the account. A
negative balance reflects margin debt.
marginAccountBalance
complex
Container for margin-related account balances.
Only appears for margin-level accounts.
fedCall
double
If funds are required to meet a Regulation T "fed
call", this value is the amount the investor must
deposit for buying on margin or selling short.
For a definition of fed call, refer to the E*TRADE
online glossary.
marginBalance
double
The net open balance in the user's margin
account
marginBalanceWithdrawal
double
The amount of the margin balance that is
available for withdrawal
marginEquity
double
The value of the account's margin positions
minus any margin debt
marginEquityPct
double
The account's equity divided by the market
value of its marginable securities
marginableSecurities
double
The value of marginable securities held in the
account
maxAvailableForWithdrawal
double
The total amount of cash plus margin equity that
is available for withdrawal from this account
minEquityCall
double
If the account's margin equity has fallen below
E*TRADE's minimum account equity
requirement, this value is the amount of
additional equity required. For a definition of
minimum equity call, refer to the E*TRADE
online glossary.
nonMarginableSecuritiesAnd Options
double
The value of securities and options that are not
marginable
totalShortValue
double
The total value of securities that are held short
in the account
E*TRADE Developer Platform 50 Get Account Balance
shortReserve
double
The amount reserved to cover the short
positions in the account
dtBalance
complex
Container for account balances related to day-
trading. Only appears for day-trading accounts.
dtCashBalance
double
The cash available for investment in a day-
trading account
dtMarginBalance
double
The margin available for investment in a day-
trading account
dtMarginableSecurities
double
The value of marginable securities held in a
day-trading account
dtNonMarginableSecuritiesAndOptions
double
The value of non-marginable securities and
options held in a day-trading account
dtStatus
string
The current status of a day-trading account.
Possible values are:
• NOT_QUALIFIED
• QUALIFIED_4X
• MARGIN_CALL_2XD
• MARGIN_CALL_1XD
• MIN_EQUITY_CALL_1XK
• QUALIFIED_RESTRICTION
• CASH_ONLY
cashAccountBalance
complex
Container for account cash balances
cashAvailableForInvestment
double
The total amount of cash available for
investment in the account
cashBalance
double
The amount of cash in the account
settledCashForInvestment
double
The amount of settled cash in the account
unSettledCashForInvestment
double
The amount of unsettled cash in the account
Sample response - XML
<AccountBalanceResponse>
<accountId>83405188</accountId>
<accountType>MARGIN</accountType>
<optionLevel>LEVEL_4</optionLevel>
<accountBalance>
<cashAvailableForWithdrawal>0.00</cashAvailableForWithdrawal>
<cashCall>0.00</cashCall>
<fundsWithheldFromPurchasePower>0.00</fundsWithheldFromPurchasePower>
<fundsWithheldFromWithdrawal>0.00</fundsWithheldFromWithdrawal>
<netAccountValue>-286.55</netAccountValue>
<netCash>-286.55</netCash>
<sweepDepositAmount>0.00</sweepDepositAmount>
<totalLongValue>0.00</totalLongValue>
<totalSecuritiesMktValue>0.00</totalSecuritiesMktValue>
<totalCash>-286.55</totalCash>
</accountBalance>
<marginAccountBalance>
<fedCall>0.00</fedCall>
<marginBalance>-286.55</marginBalance>
E*TRADE Developer Platform 51 Get Account Balance
<marginBalanceWithdrawal>-286.55</marginBalanceWithdrawal>
<marginEquity>-286.55</marginEquity>
<marginEquityPct>0.00</marginEquityPct>
<marginableSecurities>-1146.20</marginableSecurities>
<maxAvailableForWithdrawal>-286.55</maxAvailableForWithdrawal>
<minEquityCall>2286.55</minEquityCall>
<nonMarginableSecuritiesAndOptions>-286.55</nonMarginableSecuritiesAndOptions>
<totalShortValue>0.00</totalShortValue>
<shortReserve>0.00</shortReserve>
</marginAccountBalance>
</AccountBalanceResponse>
Sample response - JSON
{
"AccountBalanceResponse": {
"accountId": "83405188",
"accountType": "MARGIN",
"optionLevel": "LEVEL_4",
"accountBalance": {
"cashAvailableForWithdrawal": "0.00",
"cashCall": "0.00",
"fundsWithheldFromPurchasePower": "0.00",
"fundsWithheldFromWithdrawal": "0.00",
"netAccountValue": "-286.55",
"netCash": "-286.55",
"sweepDepositAmount": "0.00",
"totalLongValue": "0.00",
"totalSecuritiesMktValue": "0.00",
"totalCash": "-286.55"
},
"marginAccountBalance": {
"fedCall": "0.00",
"marginBalance": "-286.55",
"marginBalanceWithdrawal": "-286.55",
"marginEquity": "-286.55",
"marginEquityPct": "0.00",
"marginableSecurities": "-1146.20",
"maxAvailableForWithdrawal": "-286.55",
"minEquityCall": "2286.55",
"nonMarginableSecuritiesAndOptions": "-286.55",
"totalShortValue": "0.00",
"shortReserve": "0.00"
}
}
}
Sample use cases
Some possible use cases and workflows are described below.
Purpose
Workflow
Related APIs
E*TRADE Developer Platform 52 Get Account Balance
list of accounts,
account detail
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
balance summary
When previewing or validating an order before
placing it, use Get Account Balance to check the
account balances for sufficient funds.
Get Account Balance,
List Orders,
Preview Equity Order,
Preview Option Order,
Preview Equity Order Change,
Preview Option Order Change
Related APIs
List Accounts, Get Account Positions, Get Transaction History, Get Transaction Details
Sandbox Samples
The only parameter for this API is the account ID, which is required. The following shows a
typical request and response in the sandbox environment.
Request
GET https://etwssandbox.etrade.com/accounts/sandbox/rest/accountbalance/83405188.json
Response
{
"AccountBalanceResponse": {
"accountId": "83405188",
"accountType": "MARGIN",
"optionLevel": "LEVEL_4",
"accountBalance": {
"cashAvailableForWithdrawal": "9986621.36",
"fundsWithheldFromWithdrawal": "0.00",
"netAccountValue": "10086354.52",
"netCash": "9997973.185855",
"sweepDepositAmount": "0.00",
"totalLongValue": "88255.00",
"totalSecuritiesMktValue": "88255.00"
},
"marginAccountBalance": {
"marginBalance": "9997973.19",
"marginBalanceWithdrawal": "9986621.36",
"marginEquity": "9989687.81",
"marginableSecurities": "19978072.55",
"maxAvailableForWithdrawal": "9986621.36",
"nonMarginableSecuritiesAndOptions": "9986621.36",
"shortReserve": "126.33"
}
}
}
E*TRADE Developer Platform 53 Get Account Positions
Get Account Positions
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.
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.
E*TRADE Developer Platform 54 Get Account Positions
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=GO
OG&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
E*TRADE Developer Platform 55 Get Account Positions
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 &amp; 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>
E*TRADE Developer Platform 56 Get Account Positions
<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>
E*TRADE Developer Platform 57 Get Account Positions
<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
E*TRADE Developer Platform 58 Get Account Positions
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
Related APIs
List Accounts, Get Account Balance, Get Transaction History, Get Transaction Details
The only required parameter for this API is account number.
Sandbox Samples
Request
GET
https://etwssandbox.etrade.com/accounts/sandbox/rest/accountpositions/83405188?typeCod
e=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>
E*TRADE Developer Platform 59 Get Account Positions
<marketValue>1086.44</marketValue>
</AccountPosition>
<AccountPosition>
<costBasis>54.30</costBasis>
<description>HELMERICH &amp; 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 &amp; 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>
E*TRADE Developer Platform 60 Get Account Positions
<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 &apos;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 &apos;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 &apos;10 $37.5 Call</description>
E*TRADE Developer Platform 61 Get Account Positions
<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 &apos;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>
E*TRADE Developer Platform 62 List Alerts
List Alerts
Lists alerts for the current user.
Description
When called with HTTP GET and no parameters, this resource returns a list of alerts related to
trading and account activity. For each alert, it returns an alert ID, the date and time the alert
was issued, the subject, and a flag that shows whether the alert has ever been read.
When called with different syntax, the alerts resource is also used to read or delete an
individual alert.
Order status alerts
The items returned by this API include messages about order status (completed, cancelled,
etc.). However, to receive order status updates in a timely way, it's better to use the streaming
API, which pushes the updates to the application immediately rather than waiting to be polled.
For details, see our documentation on the Streaming API.
URL
https://etws.etrade.com/accounts/rest/alerts
HTTP Method: GET
Request Parameters
No parameters.
Sample Request
GET https://etws.etrade.com/accounts/rest/alerts
Response Properties
Property
Type
Description
Alerts
complex
Container for one or more Alert elements
Alert
complex
Container for an alert. Only appears if there is at least one alert for the user.
dateTime
long
The date and time the alert was issued, in epoch time
alertId
integer
Numeric alert ID
subject
string
Subject of the alert
readFlag
string
Indicates whether the alert has been read by the user (i.e., previously retrieved
in detailed format by calling this API with this alertId as a parameter). Possible
values are: READ, UNREAD.
symbol
string
Market symbol for the instrument related to this alert, if any, such as GOOG
E*TRADE Developer Platform 63 List Alerts
Sample response - XML
<AlertsResponse>
<Alerts>
<Alert>
<dateTime>1266519024</dateTime>
<alertId>1108</alertId>
<subject>Sell Short 1 HP Executed @ $2</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266518336</dateTime>
<alertId>1107</alertId>
<subject>Buy to cover 1 HP Executed @ $50</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
</Alerts>
</AlertsResponse>
Sample response - JSON
{
"AlertsResponse": {
"Alerts": {
"Alert": [
{
"dateTime": "1266519024",
"alertId": "1108",
"subject": "Sell Short 1 HP Executed @ $2",
"readFlag": "UNREAD"
},
{
"dateTime": "1266518336",
"alertId": "1107",
"subject": "Buy to cover 1 HP Executed @ $50",
"readFlag": "UNREAD"
}
]
}
}
}
Notes
For timely order status updates, we suggest using the Streaming API.
Sample use cases
Some possible use cases and workflows are described below.
E*TRADE Developer Platform 64 List Alerts
Purpose
Workflow
Related APIs
List active alerts
Display a list of new or recent alerts when starting
the application and by polling at regular intervals.
Allow the user to read or delete an alert by
selecting it from the list.
List Alerts,
Read Alert,
Delete Alert
Related APIs
Read Alert, Delete Alert, Streaming API
Sandbox Samples
Request
GET https://etwssandbox.etrade.com/accounts/sandbox/rest/alerts
Response
<AlertsResponse>
<Alerts>
<Alert>
<dateTime>1266519024</dateTime>
<alertId>1108</alertId>
<subject>Sell Short 1 HP Executed @ $2</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266518336</dateTime>
<alertId>1107</alertId>
<subject>Buy to cover 1 HP Executed @ $50</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266518271</dateTime>
<alertId>1106</alertId>
<subject>Buy to cover 1 HP Executed @ $50</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266517369</dateTime>
<alertId>1105</alertId>
<subject>Buy 1 ETFC Executed @ $1</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266516266</dateTime>
<alertId>1104</alertId>
<subject>Buy 4 CSCO Cancelled</subject>
E*TRADE Developer Platform 65 List Alerts
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266515972</dateTime>
<alertId>1103</alertId>
<subject>Buy 2 MSFT Cancelled</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498346</dateTime>
<alertId>1102</alertId>
<subject>Buy 1 QQQQ Executed @ $100</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498323</dateTime>
<alertId>1101</alertId>
<subject>Buy 1 MSFT Executed @ $0.1</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498302</dateTime>
<alertId>1099</alertId>
<subject>Buy 1 QQQQ Executed @ $100</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498295</dateTime>
<alertId>1100</alertId>
<subject>Buy 1 QQQQ Executed @ $88.3</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498293</dateTime>
<alertId>1098</alertId>
<subject>Buy 1 QQQQ Executed @ $0.1</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498287</dateTime>
<alertId>1096</alertId>
<subject>Sell 1 IBM Executed @ $127</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498281</dateTime>
E*TRADE Developer Platform 66 List Alerts
<alertId>1097</alertId>
<subject>Sell 1 IBM Executed @ $1</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498276</dateTime>
<alertId>1095</alertId>
<subject>Buy 2 GOOG Executed @ $0.01</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498273</dateTime>
<alertId>1094</alertId>
<subject>Sell Short 1 IBM Executed @ $1</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498268</dateTime>
<alertId>1093</alertId>
<subject>Buy to cover 1 IBM Executed @ $1</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498242</dateTime>
<alertId>1092</alertId>
<subject>Buy 2 GOOG Triggered</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266498004</dateTime>
<alertId>1091</alertId>
<subject>Buy 1 MSFT Triggered</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266490639</dateTime>
<alertId>1090</alertId>
<subject>Buy 2 MSFT Cancelled</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266490294</dateTime>
<alertId>1089</alertId>
<subject>Buy 4 IBM Cancelled</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
E*TRADE Developer Platform 67 List Alerts
<dateTime>1266490249</dateTime>
<alertId>1088</alertId>
<subject>Buy 2 IBM Cancelled</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266489623</dateTime>
<alertId>1087</alertId>
<subject>Buy 1220 IBM Cancelled</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266488490</dateTime>
<alertId>1086</alertId>
<subject>Buy 1 IBM Executed @ $134</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266486731</dateTime>
<alertId>1085</alertId>
<subject>Buy 1 HP Feb 50 Put Executed @ $5</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
<Alert>
<dateTime>1266486647</dateTime>
<alertId>1084</alertId>
<subject>Sell 1 HP Feb 50 Put Executed @ $5</subject>
<readFlag>UNREAD</readFlag>
<symbol></symbol>
</Alert>
</Alerts>
</AlertsResponse>
E*TRADE Developer Platform 68 Read Alert
Read Alert
Retrieves a specified alert.
Description
When called using HTTP GET with an alert ID, this resource retrieves the details of the
specified alert, including the date and time it was created, the subject and complete text of the
alert, and the date when it was first read, if ever.
When called with different syntax, the alerts resource is also used to list the available alerts
for the user or delete an individual alert.
URL
https://etws.etrade.com/accounts/rest/alerts
HTTP Method: GET
Request Parameters
Property
Type
Required?
Description
alertId
path
required
Numeric alert ID
Sample Request
GET https://etws.etrade.com/accounts/rest/alerts/1108
Response Properties
Property
Type
Description
createDate
long
Date and time when the alert was issued, in epoch time
alertId
integer
Numeric alert ID
msgText
string
Body of the alert
readDate
long
The date and time when the alert was first read (i.e., retrieved), in epoch time.
When retrieved for the first time, this value is 0 (zero). After that, this value is
permanently set to the time of the first retrieval.
subject
string
Subject of the alert
Sample response - XML
<AlertDetailsResponse>
<createDate>1266608946</createDate>
<alertId>1108</alertId>
<msgText>Account: xxxx-5557 Your day Trailing Stop Buy to open order for 5 IBM Feb
110 Calls was cancelled See order # 183 for details.</msgText>
<readDate>0</readDate>
E*TRADE Developer Platform 69 Read Alert
<subject>Buy 5 IBM Feb 110 Calls Cancelled</subject>
</AlertDetailsResponse>
Sample response - JSON
{
"AlertDetailsResponse": {
"createDate": "1266608946",
"alertId": "1108",
"msgText": "Account: xxxx-5557 Your day Trailing Stop Buy to open order for 5 IBM
Feb 110 Calls was cancelled See order # 183 for details.",
"readDate": "0",
"subject": "Buy 5 IBM Feb 110 Calls Cancelled"
}
}
Notes
The first retrieval of a particular alert will show 0 as the read date. On subsequent
retrievals, the read date will always be the date & time of that first retrieval.
Sample use cases
A possible use case is described below.
Purpose
Workflow
Related APIs
Display alert details
Display the details of an alert - for instance, when
the alert is selected from a list of available alerts.
List Alerts, Read Alert
Related APIs
List Alerts, Delete Alert, Streaming API
Sandbox Samples
Request
GET https://etwssandbox.etrade.com/accounts/sandbox/rest/alerts/1108
Response
<AlertDetailsResponse>
<createDate>1266608946</createDate>
<alertId>1108</alertId>
<msgText>Account: xxxx-5557 Your day Trailing Stop Buy to open order for 5 IBM Feb
110 Calls was cancelled See order # 183 for details.</msgText>
<readDate>0</readDate>
<subject>Buy 5 IBM Feb 110 Calls Cancelled</subject>
</AlertDetailsResponse>
E*TRADE Developer Platform 70 Read Alert
E*TRADE Developer Platform 71 Delete Alert
Delete Alert
Deletes a specified alert.
Description
When called using HTTP DELETE with an alert ID, this resource marks the specified alert as
deleted. This effectively removes the alert from any further access by the user.
When called with different syntax, the alerts resource is also used to list the available alerts
for the user or retrieve the details of an individual alert.
URL
https://etws.etrade.com/accounts/rest/alerts
HTTP Method: DELETE
Request Parameters
Property
Type
Required?
Description
alertId
path
required
Numeric alert ID
Sample Request
DELETE https://etws.etrade.com/accounts/rest/alerts/321
Response Properties
Property
Type
Description
result
string
Result of the operation. Possible values are: SUCCESS, FAILURE.
Sample response - XML
<deleteAlertResponse>
<result>Success</result>
<deleteAlertResponse>
Sample response - JSON
{
"json.deleteAlertResponse":{
"result":"Success"
}
}
E*TRADE Developer Platform 72 Delete Alert
Sample use cases
Some possible use cases and workflows are described below.
Purpose
Workflow
Related APIs
Delete an alert
Delete an alert - for example, when the alert is
selected on a list and the user chooses "delete"
from a menu or context menu.
List Alerts, Delete Alert
Delete multiple alerts
Use checkbox controls on an alert list to allow
batch deletion of alerts.
Delete Alert
Related APIs
List Alerts, Read Alert
Sandbox Samples
Request
DELETE https://etws.etrade.com/accounts/rest/alerts/321.json
Response
{
"json.deleteAlertResponse":{
"result":"Success"
}
}
E*TRADE Developer Platform 73 Get Transaction History
Get Transaction History
Retrieves a list of transactions for a specified account.
Description
This API returns a list of transactions (such as deposits, withdrawals, and transfers) for a single,
specified account. The request can specify start and end dates, going back as much as two
years, and the maximum number of transactions to return. Results can be filtered by:
a single transaction type (e.g., check, dividend, transfer)
a group of related transaction types - deposits, withdrawals, or trades
within a group (e.g., deposits), a list of transaction types (e.g., dividend & interest)
within the trades group:
one or all asset types - equities, options, money market, mutual funds, or bonds
within a single asset type, a single ticker symbol
Since an account history may contain a large number of transactions, the API allows you to
page through them in groups by specifying how many to return at a time (the count) and the
starting point for each successive group (the marker).
URL
https://etws.etrade.com/accounts/rest/{accountId}/transactions
HTTP Method: GET
Request Parameters
The only required parameter is the account ID. By default the API returns a maximum of 50
transactions for the specified account, going back thirty days, and all transaction types are
included.
The request parameters and transaction types are shown below, followed by example queries.
Request parameters
Parameter
Type
Required?
Description
accountId
path
required
Numeric account ID. This is the only required parameter.
group
path
optional
Major groupings of the transaction types defined in the
Transaction types table below. Possible values are:
DEPOSITS, WITHDRAWALS, TRADES.
assetType
path
conditional
Only allowed if group is TRADES. Possible values are: EQ
(equities), OPTN (options), MMF (money market funds), MF
(mutual funds), BOND (bonds). To retrieve all types, use ALL
or omit this parameter.
E*TRADE Developer Platform 74 Get Transaction History
transactionType
path
optional
Transaction type(s) to include, e.g., check, deposit, fee,
dividend, etc. A list of types is provided in the Transaction
types table below. If a group is specified, this can be a
comma-separated list of valid types for the group. Otherwise,
only one type is accepted.
tickerSymbol
path
conditional
Only allowed if group is TRADES. A single market symbol,
e.g., GOOG.
startDate
string
optional
The earliest date to include in the date range, formatted as
MMDDYYYY. History is available for two years.
endDate
string
optional
The latest date to include in the date range, formatted as
MMDDYYYY.
count
integer
optional
Number of transactions to return in the response. If not
specified, defaults to 50. Used for paging as described in the
Notes below.
marker
integer
optional
Specifies the desired starting point of the set of items to return.
Used for paging as described in the Notes below.
Transaction types
Most transaction types are members of groups: trades (T), deposits (D), and withdrawals (W),
as shown in the table below. Exceptions are corporate actions, currency exchange
transactions, and sweep deposits.
Type
Group
Description
assignment
T
A balance adjustment as the result of another party exercising an option.
For a definition of assignments, refer to the E*TRADE online glossary.
atm
D, W
Service charge from automated teller machines
check
D, W
Check deposit or withdrawal
corporate_actions
Split, merger, or acquisition
contribution
D, W
Money put into retirement fund
currency_xch
Currency exchange
debit
W
List of transactions that decrease assets
deposit
D
List of transactions that Increase assets
direct_debit
W
Decrease of assets
direct_deposit
D
Increase of assets
distribution
D, W
Money taken out of retirement fund
dividend
D
Dividend paid
exercise
T
A balance adjustment as the result of exercising an option
expiration
T
The date on which an option, right, or warrant expires and becomes
worthless if not exercised. Also, the date on which an agreement is no
longer in effect.
fee
W
Service fees
interest
D
Interest charged
pos
D, W
Point of sale debit
E*TRADE Developer Platform 75 Get Transaction History
sweep
Sweep deposit
transfer
D, W
Cash transfer (in or out)
wire
D, W
Cash wire (in or out)
Sample Requests
Below are some examples of queries to demonstrate the API syntax. The path parameters, if
used, appear in the order shown here:
https://etws.etrade.com/accounts/rest/{accountId}/transactions/{Group}/{AssetType}/{Tr
ansactionType}/{TickerSymbol}{.json}
List all deposits for the last 30 days, up to 50 transactions:
https://etws.etrade.com/accounts/rest/83405188/transactions/DEPOSITS
All deposits for the year 2011, up to 25 transactions:
https://etws.etrade.com/accounts/rest/83405188/transactions/DEPOSITS?startDate=0101201
1&endDate=12312011&count=25
The next 25 deposit transactions (URL received as part of preceding response):
https://etws.etrade.com/accounts/rest/83405188/transactions/DEPOSITS.json?startDate=01
012011&endDate=12212011&count=25&marker=345678
From the withdrawals group, just the ATM fees and service fees:
https://etws.etrade.com/accounts/rest/83405188/transactions/WITHDRAWALS/ATM,fee.json
From the trades group, all transactions for Google:
https://etws.etrade.com/accounts/rest/83405188/transactions/TRADES/OPTN/ALL/GOOG
Just the assignment and exercise transactions for Google options:
https://etws.etrade.com/accounts/rest/83405188/transactions/TRADES/OPTN/ASSIGNMENT,EXE
RCISE/GOOG
All checking deposits and withdrawals:
E*TRADE Developer Platform 76 Get Transaction History
https://etws.etrade.com/accounts/rest/83405188/transactions/TRADES/EQ/
Response Properties
Property
Type
Description
count
integer
Number of transactions returned in this response
next
string
URL to fetch the next set of transactions ("page") in this series, if
there is one. Empty if there are no more transactions to retrieve.
transaction
complex
Container for the elements of a transaction, shown next. The
number of these transaction containers is reflected in the count.
Appears if there is at least one transaction that meets the
requirements.
transactionId
long
Numeric transaction ID
transactionDate
long
Date and time in epoch time
transactionShortDesc
string
Brief description of transaction type, e.g., "Adjustment", "Interest",
"Transfer", "Wire", "Contribution", "Fee", "Option Assignment",
"Option Expiration", "Option Exercise", "Bought", "Bought To
Open", "Sold", etc.
description
string
One-line description of transaction
amount
double
Amount of transaction in dollars, or 0.00 if not applicable
details
string
URL to request the details of this transaction, as described in the
Get Transaction Details API
Sample response - XML
<transactions>
<accountId>83405188</accountId>
<count>2</count>
<next></next>
<transaction>
<transactionId>345678</transactionId>
<transactionDate>1266519026</transactionDate>
<transactionShortDesc>Bought</transactionShortDesc>
<description>10 of AAPL @ $3.00 (Order #141)</description>
<amount>-39.99</amount>
<details>
https://etws.etrade.com/accounts/sandbox/rest/83405188/transactions/345678
</details>
</transaction>
<transaction>
<transactionId>345678</transactionId>
<transactionDate>1266519024</transactionDate>
<transactionShortDesc>Sold</transactionShortDesc>
<description>1 of KO @ $100.00 (Order #142)</description>
<amount>90.00</amount>
<details>
https://etws.etrade.com/accounts/sandbox/rest/83405188/transactions/345678
</details>
</transaction>
E*TRADE Developer Platform 77 Get Transaction History
</transactions>
Sample response - JSON
{
"transactions": {
"accountId": "83405188",
"count": "2",
"transaction": [
{
"transactionId": "345678",
"transactionDate": "1266519026",
"transactionShortDesc": "Bought",
"description": "10 of AAPL @ $3.00 (Order #141)",
"amount": "-39.99",
"details":
"https://etws.etrade.com/accounts/sandbox/rest/83405188/transactions/345678"
},
{
"transactionId": "345678",
"transactionDate": "1266519024",
"transactionShortDesc": "Sold",
"description": "1 of KO @ $100.00 (Order #142)",
"amount": "90.00",
"details":
"https://etws.etrade.com/accounts/sandbox/rest/83405188/transactions/345678"
}
]
}
}
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 50), and the marker property to specify the
starting point. A request with no count and no marker retrieves the most recent 50
transactions. The next URL provided in the response retrieves the next set of
transactions in the series, using the transaction ID of the last transaction as the marker.
To page through all the items, repeat the request with the marker from each previous
response until you receive a response with a count less than the one you specified,
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, re-issuing the requests for pages that are earlier in the series), or saving
the items returned and re-displaying them from the local copy if desired.
Sample use cases
Some possible use cases and workflows are described below.
E*TRADE Developer Platform 78 Get Transaction History
Purpose
Workflow
Related APIs
Transaction history
For a selected account, display basic account info,
current balances, and a paged history of transactions
for the account. Allow the user to filter the history
with criteria such as date range, symbol, or
transaction type.
Get Transaction History,
List Accounts, Get Account
Balance
Transaction details
When the user selects a transaction from a list of
transactions, the details of the transaction are
displayed along with supporting information such as
basic account information and a description of any
securities involved.
Get Transaction History,
Get Transaction Details,
List Accounts, Look Up
Product
Related APIs
Get Transaction Details, List Accounts, Get Account Balance
Sandbox Samples
Request 1 - Basic listing of transactions
No filter except account ID. A maximum of 10 records is requested.
GET
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions?count=10
Response 1
In this response, a count of 10 items is returned, plus a next URL that can be used for
retrieving the next 10 items. Notice that, in the next URL, the marker is the transaction ID of
the last transaction received in this. You can use the provided next URL, or construct your
own custom URL by using the last transaction ID as a marker.
<transactions>
<accountId>83405188</accountId>
<count>10</count>
<next>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions?count=10&am
p;marker=345687
</next>
<transaction>
<transactionId>345678</transactionId>
<transactionDate>1266519026</transactionDate>
<transactionShortDesc>Bought</transactionShortDesc>
<description>10 of AAPL @ $3.00 (Order #141)</description>
<amount>-39.99</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345678
</details>
</transaction>
<transaction>
E*TRADE Developer Platform 79 Get Transaction History
<transactionId>345679</transactionId>
<transactionDate>1266519024</transactionDate>
<transactionShortDesc>Sold</transactionShortDesc>
<description>1 of KO @ $100.00 (Order #142)</description>
<amount>90.00</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345679
</details>
</transaction>
<transaction>
<transactionId>345680</transactionId>
<transactionDate>1266517024</transactionDate>
<transactionShortDesc>Bought To Open</transactionShortDesc>
<description>1 IBM Jan 19 &apos;13 $205 Call(IBM) @ $10.10</description>
<amount>-1012.75</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345680
</details>
</transaction>
<transaction>
<transactionId>345681</transactionId>
<transactionDate>1266519026</transactionDate>
<transactionShortDesc>Bought</transactionShortDesc>
<description>10 of AAPL bonds</description>
<amount>-39.99</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345681
</details>
</transaction>
<transaction>
<transactionId>345682</transactionId>
<transactionDate>1266519024</transactionDate>
<transactionShortDesc>Sold</transactionShortDesc>
<description>1 of KO bonds</description>
<amount>90.00</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345682
</details>
</transaction>
<transaction>
<transactionId>345683</transactionId>
<transactionDate>1266519026</transactionDate>
<transactionShortDesc>Bought</transactionShortDesc>
<description>10 of AAPL Mutual funds</description>
<amount>-39.99</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345683
</details>
</transaction>
<transaction>
<transactionId>345684</transactionId>
<transactionDate>1266519024</transactionDate>
<transactionShortDesc>Sold</transactionShortDesc>
<description>1 of KO Mutual funds</description>
E*TRADE Developer Platform 80 Get Transaction History
<amount>90.00</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345684
</details>
</transaction>
<transaction>
<transactionId>345685</transactionId>
<transactionDate>1266519026</transactionDate>
<transactionShortDesc>Bought</transactionShortDesc>
<description>10 of AAPL money market funds</description>
<amount>-39.99</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345685
</details>
</transaction>
<transaction>
<transactionId>345686</transactionId>
<transactionDate>1266519024</transactionDate>
<transactionShortDesc>Sold</transactionShortDesc>
<description>1 of KO money market funds</description>
<amount>90.00</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345686
</details>
</transaction>
<transaction>
<transactionId>345687</transactionId>
<transactionDate>1266517024</transactionDate>
<transactionShortDesc>Option Expiration</transactionShortDesc>
<description>1 IBM Expiration</description>
<amount>0</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345687
</details>
</transaction>
</transactions>
Request 2 - Deposits for single date
GET
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/DEPOSITS?st
artDate=02182010&endDate=02182010
Response 2
In this response, the count is 10 and the next element is empty. Based on this, we infer that
there were 10 deposits on this date.
<transactions>
<accountId>83405188</accountId>
<count>10</count>
E*TRADE Developer Platform 81 Get Transaction History
<next></next>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Check</transactionShortDesc>
<description>Deposited check $100</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Contribution</transactionShortDesc>
<description>Deposited $100 contribution</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Direct Deposit</transactionShortDesc>
<description>Deposited $100 direct deposit</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Deposit</transactionShortDesc>
<description>Deposited $100 deposit</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Distribution</transactionShortDesc>
<description>Deposited $100 Distribution</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Dividend</transactionShortDesc>
E*TRADE Developer Platform 82 Get Transaction History
<description>Deposited $100 Dividend</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Pos</transactionShortDesc>
<description>Deposited $100 pos</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Interest</transactionShortDesc>
<description>Deposited $100 Interest</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Transfer</transactionShortDesc>
<description>TEST</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
<transaction>
<transactionId>123456</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Wire</transactionShortDesc>
<description>Deposited $100 Wire</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456
</details>
</transaction>
</transactions>
E*TRADE Developer Platform 83 Get Transaction History
Request 3 - Selected transaction types from a single group
GET
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/WITHDRAWALS
/CHECK,CONTRIBUTION,DIRECT_DEBIT,DISTRIBUTINO,FEE,POS,TRANSFER,WIRE
Response 3
<transactions>
<accountId>83405188</accountId>
<count>8</count>
<next></next>
<transaction>
<transactionId>234567</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Check</transactionShortDesc>
<description>Withdrew $100 Check</description>
<amount>-100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
<transaction>
<transactionId>234567</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Contribution</transactionShortDesc>
<description>Withdrew $100 contribution</description>
<amount>-100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
<transaction>
<transactionId>234567</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Withdrawal direct debit</transactionShortDesc>
<description>Withdrew $100 direct debit</description>
<amount>100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
<transaction>
<transactionId>234567</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Distribution</transactionShortDesc>
<description>Withdrew $100 distribution</description>
<amount>-100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
<transaction>
<transactionId>234567</transactionId>
E*TRADE Developer Platform 84 Get Transaction History
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Fee</transactionShortDesc>
<description>Subscription: Pro Dec 11</description>
<amount>-54.81</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
<transaction>
<transactionId>234567</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Pos</transactionShortDesc>
<description>Withdrew $100 pos</description>
<amount>-100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
<transaction>
<transactionId>234567</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Transfer</transactionShortDesc>
<description>TRANSFER TO XXXX0940-1 REFID:140230935;</description>
<amount>-100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
<transaction>
<transactionId>234567</transactionId>
<transactionDate>1266518024</transactionDate>
<transactionShortDesc>Wire</transactionShortDesc>
<description>Withdrew $100 wire</description>
<amount>-100</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567
</details>
</transaction>
</transactions>
Request 4 - All trades for one asset type and security
This example requests a JSON response by adding ".json" at the end of the path.
GET
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/TRADES/EQ/A
APL.json
Response 4
{
E*TRADE Developer Platform 85 Get Transaction History
"transactions": {
"accountId": "83405188",
"count": "1",
"transaction": {
"transactionId": "345678",
"transactionDate": "1266519026",
"transactionShortDesc": "Bought",
"description": "10 of AAPL @ $3.00 (Order #141)",
"amount": "-39.99",
"details": "
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345678
"
}
}
}
Request 5 - All trades for all asset types for one security
GET
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/TRADES/ALL/
GOOG
Response 5
<transactions>
<accountId>83405188</accountId>
<count>1</count>
<next></next>
<transaction>
<transactionId>345678</transactionId>
<transactionDate>1266517024</transactionDate>
<transactionShortDesc>Bought To Open</transactionShortDesc>
<description>1 IBM Jan 19 &apos;13 $205 Call(IBM) @ $10.10</description>
<amount>-1012.75</amount>
<details>
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345678
</details>
</transaction>
</transactions>
Request 6 - Checking account deposits and withdrawals
Lists checking transactions for this account - both deposits and withdrawals. This example
requests a JSON response by adding ".json" at the end of the path.
GET
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/CHECK.json?
startDate=01012011&endDate=12312011
E*TRADE Developer Platform 86 Get Transaction History
Response 6
{
"transactions": {
"accountId": "83405188",
"count": "2",
"transaction": [
{
"transactionId": "123456",
"transactionDate": "1266518024",
"transactionShortDesc": "Check",
"description": "Deposited check $100",
"amount": "100",
"details":
"https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/123456"
},
{
"transactionId": "234567",
"transactionDate": "1266518024",
"transactionShortDesc": "Check",
"description": "Withdrew $100 Check",
"amount": "-100",
"details":
"https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/234567"
}
]
}
}
E*TRADE Developer Platform 87 Get Transaction Details
Get Transaction Details
Retrieves the details of a transaction.
Description
This API returns the details of a transaction, based on two required inputs - account ID and
transaction ID. Both of these inputs are typically obtained by using the Get Transaction History
API.
The same account types and transaction types are supported in both APIs. The details that are
returned depend upon the type of transaction, e.g., a stock trade has a displaySymbol but a
check transaction does not.
URL
https://etws.etrade.com/accounts/rest/{accountId}/transactions/{transactionId}
HTTP Method: GET
Request Parameters
Parameter
Type
Required?
Description
accountId
path
required
Numeric account ID
transactionId
path
required
Numeric transaction ID, usually acquired by using the Get
Transaction History API.
Sample Request
https://etws.etrade.com/accounts/rest/{accountId}/transactions/345678
Response Properties
Property
Type
Description
transactionDate
long
Date of the specified transaction
transactionType
string
Type of transaction (deposit, dividend, etc.). Possible values are
listed in the Transaction types table below.
userDescription
string
User-defined description
transactionDescription
string
Transaction description
quantity
decimal
Item count (e.g., share count)
amount
decimal
Total cost of transaction, including commission if any
commission
decimal
Commission amount
price
decimal
Price per item if applicable (e.g., price per share)
productID
complex
Container for identity of the product
symbol
string
Security symbol in internal E*TRADE database format
E*TRADE Developer Platform 88 Get Transaction Details
typeCode
string
The type of security. Possible values are: EQ (equity), INDX (index),
MF (mutual fund), FI (fixed income).
category
string
User-defined category
displaySymbol
string
Product symbol in client-facing display format , e.g., "GOOG" or
"GOOG Dec 17 2012 $600.50 CALL"
underlyingProductId
complex
Container for identity of the underlier (if applicable)
symbol
string
Market symbol of the underlier, e.g., GOOG
typeCode
string
The type of security for the underlier. Possible values are: EQ
(equity), INDX (index), MF (mutual fund), FI (fixed income).
settlementDate
long
Settlement date in epoch time
settlementCurrency
string
Settlement currency
paymentCurrency
string
Payment currency
accountOrderNo
long
Order number
Transaction types
Most transaction types are members of groups: trades (T), deposits (D), and withdrawals (W),
as shown in the table below. Exceptions are corporate actions, currency exchange
transactions, and sweep deposits. (This is the same table shown under Get Transaction
History.)
Type
Group
Description
assignment
T
A balance adjustment as the result of another party exercising an option.
For a definition of assignments, refer to the E*TRADE online glossary.
atm
D, W
Service charge from automated teller machines
check
D, W
Check deposit or withdrawal
corporate_actions
Split, merger, or acquisition
contribution
D, W
Money put into retirement fund
currency_xch
Currency exchange
debit
W
List of transactions that decrease assets
deposit
D
List of transactions that Increase assets
direct_debit
W
Decrease of assets
direct_deposit
D
Increase of assets
distribution
D, W
Money taken out of retirement fund
dividend
D
Dividend paid
exercise
T
A balance adjustment as the result of exercising an option
expiration
T
The date on which an option, right, or warrant expires and becomes
worthless if not exercised. Also, the date on which an agreement is no
longer in effect.
fee
W
Service fees
interest
D
Interest charged
pos
D, W
Point of sale debit
E*TRADE Developer Platform 89 Get Transaction Details
sweep
Sweep deposit
transfer
D, W
Cash transfer (in or out)
wire
D, W
Cash wire (in or out)
Sample response - XML
<transactionDetails>
<transactionDate>1266518024</transactionDate>
<transactionType>bought</transactionType>
<userDescription>reimbursement</userDescription>
<transactionDescription>Bought 10 AAPL @200</transactionDescription>
<quantity>10</quantity>
<amount>2010.00</amount>
<price>200.00</price>
<commission>10.00</commission>
<productId>
<symbol>AAPL</symbol>
<typeCode>EQ</typeCode>
</productId>
<underlyingProductId/>
<displaySymbol>AAPL</displaySymbol>
<accountOrderNo>10</accountOrderNo>
<settlementCurrency>USD</settlementCurrency>
<paymentCurrency>USD</paymentCurrency>
<category></category>
<settlementDate>1322456400</settlementDate>
</transactionDetails>
Sample response - JSON
{
"json.transactionDetails":{
"transactionDate":1266518024,
"transactionType":"bought",
"userDescription":"reimbursement",
"transactionDescription":"Bought 10 AAPL @200",
"quantity":10,
"amount":"2010.00",
"price":"200.00",
"commission":"10.00",
"productId":{
"symbol":"AAPL",
"typeCode":"EQ"
},
"underlyingProductId":"",
"displaySymbol":"AAPL",
"accountOrderNo":10,
"settlementCurrency":"USD",
"paymentCurrency":"USD",
"category":"",
"settlementDate":1322456400
E*TRADE Developer Platform 90 Get Transaction Details
}
}
Sample use cases
Some possible use cases and workflows are described below.
Purpose
Workflow
Related APIs
Transaction detail
display
User selects a transaction from a list of transactions
that meet specified criteria (e.g., account, date range,
symbol, transaction type). The details of the
transaction are displayed along with supporting
information such as basic account information and a
description of any securities involved.
Get Transaction History,
Get Transaction Details,
List Accounts, Look Up
Product
Related APIs
Get Transaction History, List Accounts, Get Account Balance
Sandbox Samples
Request
https://etwssandbox.etrade.com/accounts/sandbox/rest/83405188/transactions/345678
Response
<transactionDetails>
<transactionDate>1266518024</transactionDate>
<transactionType>bought</transactionType>
<userDescription>reimbursement</userDescription>
<transactionDescription>Bought 10 AAPL @200</transactionDescription>
<quantity>10</quantity>
<amount>2010.00</amount>
<price>200.00</price>
<commission>10.00</commission>
<productId>
<symbol>AAPL</symbol>
<typeCode>EQ</typeCode>
</productId>
<underlyingProductId/>
<displaySymbol>AAPL</displaySymbol>
<accountOrderNo>10</accountOrderNo>
<settlementCurrency>USD</settlementCurrency>
<paymentCurrency>USD</paymentCurrency>
<category></category>
<settlementDate>1322456400</settlementDate>
</transactionDetails>
E*TRADE Developer Platform 91 Look Up Product
Market
Look Up Product
Looks up an exchange and symbol based on company name and security type.
Description
This API returns a list of securities of a specified type (e.g., equity stock) based on a full or
partial match of any part of the company name. For instance, a search for "jones" returns a list
of securities associated with "Jones Soda Co", "Stella Jones Inc", and many others. The list
contains the company name, the exchange that lists the security, the security type, and the
symbol, for as many matches as are found.
The result may include some unexpected matches, because the search includes more than just
the display version of the company name. For instance, searching on "etrade" returns securities
for "E TRADE" - notice the space in the name.
This API is for searching on the company name, not a security symbol. It's commonly used to
look up a symbol based on the company name, e.g., "What is the symbol for Google stock?".
To look up company information based on a symbol, or to find detailed information on a
security, use the quote API.
URL
https://etws.etrade.com/market/rest/productlookup
HTTP Method: GET
Request Parameters
Parameter
Type
Required?
Description
company
string
required
Full or partial name of the company. Note that the system extensively
abbreviates common words such as "company", "industries", and
"systems", and generally skips punctuation (periods, commas,
apostrophes, etc.) .
type
enum
required
The type of security. Possible values are: EQ (equity) or MF (mutual
fund).
Response Properties
Property
Type
Description
companyName
string
The name of the company
exchange
string
The exchange that lists the company
securityType
string
The type of security. Possible values are EQ (equity) and MF (mutual
fund).
E*TRADE Developer Platform 92 Look Up Product
symbol
string
The market symbol for this security
Sample Request
GET https://etws.etrade.com/market/rest/productlookup?company=cisco&type=EQ
Sample response - XML
<productLookupResponse>
<productList>
<companyName>CISCO SYS INC COM</companyName>
<exchange>NASDAQ NM</exchange>
<securityType>EQ</securityType>
<symbol>CSCO</symbol>
</productList>
<productList>
<companyName>FRANCISCO INDS INC COM</companyName>
<exchange>OTC</exchange>
<securityType>EQ</securityType>
<symbol>FRAN</symbol>
</productList>
<productList>
<companyName>SAN FRANCISCO CO</companyName>
<exchange>OTC</exchange>
<securityType>EQ</securityType>
<symbol>SFHC</symbol>
</productList>
</productLookupResponse>
Sample response - JSON
{
"productLookupResponse":{
"productList":[
{
"companyName":"CISCO SYS INC COM",
"exchange":"NASDAQ NM",
"securityType":"EQ",
"symbol":"CSCO"
},
{
"companyName":"FRANCISCO INDS INC COM",
"exchange":"OTC",
"securityType":"EQ",
"symbol":"FRAN"
},
{
"companyName":"SAN FRANCISCO CO",
"exchange":"OTC",
"securityType":"EQ",
"symbol":"SFHC"
}
E*TRADE Developer Platform 93 Look Up Product
]
}
}
Sample use cases
Some possible use-cases and workflows are described below.
Purpose
Workflow
Related APIs
Look Up
Product
Based on user input, display a list of matching company
names, security types, and market symbols. User can
select a desired symbol to retrieve, for instance, a current
market value, fundamental display, and streaming updates.
Look Up Product, Get
Quote, Streaming API
Related APIs
Get Quote, Get Option Chains
Sandbox Samples
The following shows a typical request and response in the sandbox environment.
Request
GET
https://etwssandbox.etrade.com/market/sandbox/rest/productlookup?company=fi&type=EQ
Response
<ProductLookupResponse>
<Product>
<companyName>E TRADE FINANCIAL CORP COM</companyName>
<exchange>NASDAQ NM</exchange>
<securityType>EQ</securityType>
<symbol>ETFC</symbol>
</Product>
<Product>
<companyName>FT UT 1888DFIETFCM</companyName>
<exchange>OTCBB</exchange>
<securityType>EQ</securityType>
<symbol>FDFXNX</symbol>
</Product>
</ProductLookupResponse>
E*TRADE Developer Platform 94 Get Quote
Get Quote
Returns detailed market information for securities.
Description
This API returns detailed quote information for one or more specified securities. An optional flag
specifies one of five pre-configured field sets to return: fundamentals, intraday activity, options,
a 52-week display, or all available details (the default). Developers can select the response that
most closely fits their needs to minimize data size, processing time, and network traffic.
Version v0 of the E*TRADE API supports real-time market data (as opposed to delayed data,
available in some other contexts). Users who have not yet signed the real-time market data
agreement on the E*TRADE website receive an error message when trying to access market
data with this API.
URL
https://etws.etrade.com/market/rest/quote/{symbol, symbol...}
HTTP Method: GET
Request Parameters
Parameter
Type
Required?
Description
symbol
path
required
One or more (comma-separated) symbols for equities or options, up to
a maximum of 25. Symbols for equities are simple, e.g., GOOG.
Symbols for options are more complex, consisting of six elements
separated by colons, in this format:
underlier:year:month:day:optionType:strikePrice.
detailFlag
enum
optional
Optional parameter specifying which details to return in the response.
The field set for each possible value is listed in separate tables below.
The possible values are:
• FUNDAMENTAL - Instrument fundamentals and latest price
• INTRADAY - Performance for the current or most recent trading day
• OPTIONS - Information on a given option offering
• WEEK52 - 52-week high and low (highest high and lowest low)
• ALL (default) - All of the above information and more
Response Properties (detailFlag = "ALL")
Property
Type
Description
adjNonAdjFlag
boolean
Indicates whether an option has been adjusted due to a corporate action
(e.g. a dividend or stock split). Possible values are TRUE, FALSE.
annualDividend
double
Cash amount paid per share over the past year
ask
double
The current ask price for a security
E*TRADE Developer Platform 95 Get Quote
askExchange
string
Code for the exchange reporting the ask price. Exchange codes are
listed in a separate table below.
askSize
long
Number of shares or contracts offered by a broker/dealer at the ask price
askTime
string
Time of the ask, e.g., "15:15:43 EDT 03-15-2011"
beta
double
A measure of a stock's volatility relative to the primary market index
bid
double
Current bid price for a security
bidExchange
string
Code for the exchange reporting the bid price. Exchange codes are listed
in a separate table below.
bidSize
long
Number of shares or contracts offered at the bid price
bidTime
string
Time of the bid, e.g., "15:15:43 EDT 03-15-2011"
chgClose
double
Dollar change of the last price from the previous close
chgClosePrcn
double
Percentage change of the last price from the previous close
companyName
string
Name of the company or mutual fund. (Shows up to 40 characters.)
daysToExpiration
long
Number of days before the option expires
dirLast
string
Direction of movement, i.e., whether the current price is higher or lower
than the price of the most recent trade
dividend
double
Cash amount per share of the latest dividend
eps
double
Earnings per share on a rolling basis. (Stocks only.)
estEarnings
double
Projected earnings per share for the next fiscal year. (Stocks only.)
exDivDate
string
Date on which shareholders were entitled to receive the latest dividend, in
epoch time.
exchgLastTrade
string
Code for the exchange of the last trade. Exchange codes are listed in a
separate table below.
fsi
string
Financial Status Indicator - indicates whether a Nasdaqlisted issuer has
failed to submit its regulatory filings on a
timely basis, failed to meet continuing listing standards, and/or filed for
bankruptcy. Codes are:
• D - Deficient
• E - Delinquent
• Q - Bankrupt
• N - Normal
• G - Deficient and Bankrupt
• H - Deficient and Delinquent
• J - Delinquent and Bankrupt
• K - Deficient, Delinquent, and Bankrupt
high
double
Highest price at which a security has traded during the current day
high52
double
Highest price at which a security has traded during the past year (52
weeks). For options, this value is the lifetime high.
highAsk
double
Highest ask price for the current trading day
highBid
double
Highest bid price for the current trading day
lastTrade
double
Price of the most recent trade in a security
low
double
Lowest price at which a security has traded during the current day
low52
double
Lowest price at which a security has traded during the past year (52
weeks). For options, this value is the lifetime low.
E*TRADE Developer Platform 96 Get Quote
lowAsk
double
Lowest ask price for the current trading day
lowBid
double
Lowest bid price for the current trading day
numTrades
long
Number of transactions that involve buying a security from another entity
open
double
Price of a security at the current day's market open
openInterest
long
Total number of options or futures contracts that are not closed or
delivered on a particular day
optionStyle
string
Specifies how the contract treats the expiration date. Possible values are
"European" (options can be exercised only on the expiration date) or
"American" (options can be exercised any time before it expires).
optionUnderlier
string
Symbol for the underlier. (Options only.)
prevClose
double
Official price at the close of the previous trading day
prevDayVolume
long
Final volume from the previous market session
primaryExchange
string
Exchange code of the primary listing exchange for this instrument.
(Exchange codes are listed in a separate table below.)
symbolDesc
string
Description of the security - e.g., the company name or option description.
todayClosed
double
Price at the close of the regular trading session for the current day.
totalVolume
long
Total number of shares or contracts exchanging hands.
upc
long
Uniform Practice Code - identifies specific FINRA advisories detailing
unusual circumstances (e.g., extremely large dividends, when-issued
settlement dates, and worthless securities).
volume10Day
long
Ten-day average trading volume for the security
dateTime
string
Time of this quote, e.g., "15:15:43 EDT 03-15-2011"
product
complex
Container for product information
symbol
string
Market trading symbol for the stock
type
string
Type of security. Possible values are: EQ and OPTN.
exchange
string
Exchange that lists this company. (Exchange codes are listed in a
separate table below.)
Response Properties (detailFlag = "FUNDAMENTAL")
Property
Type
Description
beta
double
A measure of a stock's volatility relative to the primary market index
eps
double
Earnings per share on a rolling basis. (Applies to stocks only.)
estEarnings
double
Projected earnings per share for the next fiscal year. (Applies to stocks only.)
high52
double
The highest price at which a security has traded during the past year (52
weeks). For options, this value is the lifetime high.
lastTrade
double
The price of the most recent trade in a security
low52
double
The lowest price at which a security has traded during the past year (52
weeks). For options, this value is the lifetime low.
symbolDesc
string
A description of the security, such as company name or option description
volume10Day
long
Ten-day average trading volume for the security
dateTime
long
The time of this quote, e.g., "15:15:43 EDT 03-15-2011"
product
complex
Container for symbol information
E*TRADE Developer Platform 97 Get Quote
symbol
string
The market trading symbol for the stock
type
string
The type of security. Possible values are: EQ and OPTN.
exchange
string
The exchange that lists this company. (Exchange codes are listed in a
separate table below.)
Response Properties (detailFlag = "INTRADAY")
Property
Type
Description
ask
double
The current ask price for a security
bid
double
The current bid price for a security
chgClose
double
The dollar change of the last price from the previous close
chgClosePrcn
double
The percentage change of the last price from the previous close
high
double
The highest price at which a security has traded during the current day
lastTrade
double
The price of the most recent trade in a security
low
double
The lowest price at which a security has traded during the current day
totalVolume
long
Total number of shares or contracts exchanging hands
dateTime
long
The time of this quote, e.g., "15:15:43 EDT 03-15-2011"
product
complex
Container for symbol information
symbol
string
The market trading symbol for the stock
type
string
The type of security. Possible values are: EQ and OPTN.
exchange
string
The exchange that lists this company. (Exchange codes are listed in a
separate table below.)
Response Properties (detailFlag = "OPTIONS")
Property
Type
Description
ask
double
The current ask price for a security
askSize
long
The number of shares or contracts offered by a broker/dealer at the ask
price
bid
double
The current bid price for a security
bidSize
long
The number of shares or contracts offered at the bid price
daysToExpiration
long
Number of days before the option expires
lastTrade
double
The price of the most recent trade in a security
openInterest
long
The total number of options or futures contracts that are not closed or
delivered on a particular day
dateTime
string
The time of this quote, e.g., "15:15:43 EDT 03-15-2011"
product
complex
Container for symbol information
symbol
string
The market trading symbol for the stock
type
string
The type of security. Possible values are: EQ and OPTN.
exchange
string
The exchange that lists this company. (Exchange codes are listed in a
separate table below.)
E*TRADE Developer Platform 98 Get Quote
Response Properties (detailFlag = "WEEK_52")
Property
Type
Description
annualDividend
double
The cash dividend paid per share over the past year
high
double
The highest price at which a security has traded during the current day
lastTrade
double
The price of the most recent trade in a security
low
double
The lowest price at which a security has traded during the current day
prevClose
double
The official price at the close on the previous trading day
symbolDesc
string
A description of the security - e.g., company name or option description
totalVolume
long
Total number of shares or contracts exchanging hands
dateTime
long
The time of this quote, e.g., "15:15:43 EDT 03-15-2011"
product
complex
Container for symbol information
symbol
string
The market trading symbol for the stock in the quote
type
string
The type of security. Possible values are: EQ and OPTN.
exchange
string
The exchange that lists this company. (Exchange codes are listed in a
separate table below.)
Sample Request
GET https://etrade.com/market/rest/quote/GOOG?detailFlag=ALL
Sample response - XML (detailFlag = "ALL")
<quoteResponse>
<quoteData>
<all>
<adjNonAdjFlag>false</adjNonAdjFlag>
<annualDividend>0</annualDividend>
<ask>603.94</ask>
<askExchange>Q</askExchange>
<askSize>100</askSize>
<askTime>14:35:42 EST 01-04-2011</askTime>
<bid>603.75</bid>
<bidExchange>P</bidExchange>
<bidSize>100</bidSize>
<bidTime>14:35:42 EST 01-04-2011</bidTime>
<chgClose>-0.4900000000000091</chgClose>
<chgClosePrcn>-0.08</chgClosePrcn>
<companyName>GOOGLE INC</companyName>
<daysToExpiration>0</daysToExpiration>
<dirLast>U</dirLast>
<dividend>0</dividend>
<eps>24.63</eps>
<estEarnings>33.642</estEarnings>
<exDivDate></exDivDate>
<exchgLastTrade></exchgLastTrade>
<fsi>N</fsi>
<high>606.18</high>
<high52>630.85</high52>
E*TRADE Developer Platform 99 Get Quote
<highAsk>640</highAsk>
<highBid>606.79</highBid>
<lastTrade>603.86</lastTrade>
<low>600.12</low>
<low52>433.63</low52>
<lowAsk>600.12</lowAsk>
<lowBid>449.47</lowBid>
<numTrades>10590</numTrades>
<open>606.4</open>
<openInterest>0</openInterest>
<optionStyle></optionStyle>
<optionUnderlier></optionUnderlier>
<prevClose>604.35</prevClose>
<prevDayVolume>2366286</prevDayVolume>
<primaryExchange>Q </primaryExchange>
<symbolDesc>GOOGLE INC</symbolDesc>
<todayClose>0</todayClose>
<totalVolume>1412611</totalVolume>
<upc>0</upc>
<volume10Day>1436450</volume10Day>
</all>
<dateTime>14:35:30 EST 01-04-2011</dateTime>
<product>
<symbol>GOOG</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</quoteData>
</quoteResponse>
Sample response - JSON (detailFlag = "ALL")
{
"quoteResponse":{
"quoteData":{
"all":{
"adjNonAdjFlag":false,
"annualDividend":0,
"ask":603.94,
"askExchange":"Q",
"askSize":100,
"askTime":"14:35:42 EST 01-04-2011",
"bid":603.75,
"bidExchange":"P",
"bidSize":100,
"bidTime":"14:35:42 EST 01-04-2011",
"chgClose":-0.4900000000000091,
"chgClosePrcn":-0.08,
"companyName":"GOOGLE INC",
"daysToExpiration":0,
"dirLast":"U",
"dividend":0,
"eps":24.63,
E*TRADE Developer Platform 100 Get Quote
"estEarnings":33.642,
"exDivDate":"",
"exchgLastTrade":"",
"fsi":"N",
"high":606.18,
"high52":630.85,
"highAsk":640,
"highBid":606.79,
"lastTrade":603.86,
"low":600.12,
"low52":433.63,
"lowAsk":600.12,
"lowBid":449.47,
"numTrades":10590,
"open":606.4,
"openInterest":0,
"optionStyle":"",
"optionUnderlier":"",
"prevClose":604.35,
"prevDayVolume":2366286,
"primaryExchange":"Q ",
"symbolDesc":"GOOGLE INC",
"todayClose":0,
"totalVolume":1412611,
"upc":0,
"volume10Day":1436450
},
"dateTime":"14:35:30 EST 01-04-2011",
"product":{
"symbol":"GOOG",
"type":"EQ",
"exchange":"Q"
}
}
}
}
Sample response - XML (detailFlag = "FUNDAMENTAL")
<QuoteResponse>
<QuoteData>
<dateTime>15:15:43 EDT 03-15-2011</dateTime>
<fundamental>
<companyName>GOOGLE INC</companyName>
<eps>24.63</eps>
<estEarnings>34.524</estEarnings>
<high52>642.96</high52>
<lastTrade>570.92</lastTrade>
<low52>433.63</low52>
<symbolDesc>GOOGLE INC</symbolDesc>
<volume10Day>2718247</volume10Day>
</fundamental>
<product>
<symbol>GOOG</symbol>
E*TRADE Developer Platform 101 Get Quote
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
<QuoteData>
<dateTime>12:15:58 EST 02-24-2010</dateTime>
<fundamental>
<companyName>MICROSOFT CORP</companyName>
<eps>1.81</eps>
<estEarnings>1.811</estEarnings>
<high52>31.5</high52>
<lastTrade>28.71</lastTrade>
<low52>14.87</low52>
<symbolDesc>MICROSOFT CORP</symbolDesc>
<volume10Day>56676460</volume10Day>
</fundamental>
<product>
<symbol>MSFT</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
</QuoteResponse>
Sample response - JSON (detailFlag = "FUNDAMENTAL")
{
"QuoteResponse": {
"QuoteData": [
{
"dateTime": "15:15:43 EDT 03-15-2011",
"fundamental": {
"companyName": "GOOGLE INC",
"eps": "24.63",
"estEarnings": "34.524",
"high52": "642.96",
"lastTrade": "570.92",
"low52": "433.63",
"symbolDesc": "GOOGLE INC",
"volume10Day": "2718247"
},
"product": {
"symbol": "GOOG",
"type": "EQ",
"exchange": "Q"
}
},
{
"dateTime": "12:15:58 EST 02-24-2010",
"fundamental": {
"companyName": "MICROSOFT CORP",
"eps": "1.81",
"estEarnings": "1.811",
"high52": "31.5",
E*TRADE Developer Platform 102 Get Quote
"lastTrade": "28.71",
"low52": "14.87",
"symbolDesc": "MICROSOFT CORP",
"volume10Day": "56676460"
},
"product": {
"symbol": "MSFT",
"type": "EQ",
"exchange": "Q"
}
}
]
}
}
Sample response - XML (detailFlag = "INTRADAY")
<quoteResponse>
<quoteData>
<dateTime>14:52:03 EST 01-04-2011</dateTime>
<intraday>
<ask>602.56</ask>
<bid>602.45</bid>
<chgClose>-1.8999999999999773</chgClose>
<chgClosePrcn>-0.31</chgClosePrcn>
<companyName>GOOGLE INC</companyName>
<high>606.18</high>
<lastTrade>602.45</lastTrade>
<low>600.12</low>
<totalVolume>1465065</totalVolume>
</intraday>
<product>
<symbol>GOOG</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</quoteData>
</quoteResponse>
Sample response - JSON (detailFlag = "INTRADAY")
{
"quoteResponse":{
"quoteData":{
"dateTime":"14:52:03 EST 01-04-2011",
"intraday":{
"ask":602.56,
"bid":602.45,
"chgClose":-1.8999999999999773,
"chgClosePrcn":-0.31,
"companyName":"GOOGLE INC",
"high":606.18,
"lastTrade":602.45,
E*TRADE Developer Platform 103 Get Quote
"low":600.12,
"totalVolume":1465065
},
"product":{
"symbol":"GOOG",
"type":"EQ",
"exchange":"Q"
}
}
}
}
Sample response - XML (detailFlag = "OPTIONS")
<quoteResponse>
<quoteData>
<dateTime>14:52:52 EST 01-04-2011</dateTime>
<option>
<ask>602.73</ask>
<askSize>100</askSize>
<bid>602.57</bid>
<bidSize>300</bidSize>
<companyName>GOOGLE INC</companyName>
<daysToExpiration>0</daysToExpiration>
<lastTrade>602.7299</lastTrade>
<openInterest>0</openInterest>
</option>
<product>
<symbol>GOOG</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</quoteData>
</quoteResponse>
Sample response - JSON (detailFlag = "OPTIONS")
{
"quoteResponse":{
"quoteData":{
"dateTime":"14:52:52 EST 01-04-2011",
"option":{
"ask":602.73,
"askSize":100,
"bid":602.57,
"bidSize":300,
"companyName":"GOOGLE INC",
"daysToExpiration":0,
"lastTrade":602.7299,
"openInterest":0
},
"product":{
"symbol":"GOOG",
E*TRADE Developer Platform 104 Get Quote
"type":"EQ",
"exchange":"Q"
}
}
}
}
Sample response - XML (detailFlag = "WEEK_52")
<quoteResponse>
<quoteData>
<dateTime>14:54:41 EST 01-04-2011</dateTime>
<product>
<symbol>GOOG</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
<week52>
<annualDividend>0</annualDividend>
<companyName>GOOGLE INC</companyName>
<high52>630.85</high52>
<lastTrade>602.6</lastTrade>
<low52>433.63</low52>
<perf12Months>97</perf12Months>
<prevClose>604.35</prevClose>
<symbolDesc>GOOGLE INC</symbolDesc>
<totalVolume>1469699</totalVolume>
</week52>
</quoteData>
</quoteResponse>
Sample response - JSON (detailFlag = "WEEK_52")
{
"quoteResponse":{
"quoteData":{
"dateTime":"14:54:41 EST 01-04-2011",
"product":{
"symbol":"GOOG",
"type":"EQ",
"exchange":"Q"
},
"week52":{
"annualDividend":0,
"companyName":"GOOGLE INC",
"high52":630.85,
"lastTrade":602.6,
"low52":433.63,
"perf12Months":97,
"prevClose":604.35,
"symbolDesc":"GOOGLE INC",
"totalVolume":1469699
}
E*TRADE Developer Platform 105 Get Quote
}
}
}
Exchange Codes
Code
Exchange
A
American Stock Exchange
G
Amex Emerging Company Marketplace
AP
Archipelago
Z
BATS
M
Chicago (Midwest) Stock Exchange
CO
Chicago Board Options Exchange
C
Cincinnati Stock Exchange
GP
GovPX Bonds
I
International Securities Exchange (Options)
IS
Island
XT
Market XT
V
Nasdaq Bulletin Board, Trades Only
F
NASDAQ Mutual Fund & Money Market Fund
Q
Nasdaq National Market System (NMS)
B
NASDAQ OMX BX
U
Nasdaq OTC Bulletin Board (Pink Sheet Stocks)
S
Nasdaq Small Cap
T
Nasdaq Trades in Listed Stocks
N
New York Stock Exchange
R
New York Stock Exchange Trade Reporting Facility (TRF)
P
Pacific Stock Exchange
P
Pacific Stock Exchange, Tier I
PT
Pacific Stock Exchange, Tier II
X
Philadelphia Stock Exchange
RD
Red Book
Notes
This API takes an instrument symbol as input. In some use cases it will be necessary to
use the Look Up Product API to find the symbol based on a company name provided by
the user.
The API allows up to 25 symbols to be specified per request. Such a request counts as
a single request, not multiple requests, so it does not exceed the rate limit.
The E*TRADE API v0 supports real-time market data (as opposed to delayed data,
available in some other contexts). Users who have not yet signed the real-time market
E*TRADE Developer Platform 106 Get Quote
data agreement on the E*TRADE website receive an error message when trying to
access market data with this API.
Sample use cases
Some possible use-cases and workflows are described below.
Purpose
Workflow
Related APIs
Symbol lookup
Use the Get Quote API to look up basic information such as
company name or product description for a product. This is
used in multiple places within an application, e.g., when
hovering over a symbol.
Get Quote
Product display
with updating
quote
Display a list of stocks for a given company name, and allow
a user to select a stock and specify a type of quote display
(e.g., fundamentals). Show the quote along with a box that
shows dynamically-updating price data.
Look Up Product, Get
Quote, Streaming API
Related APIs
Look Up Product, Get Option Chains, Get Option Expire Dates
Sandbox Samples
Below are example sandbox requests and responses for the following common operations:
1. Request all information (the default) for a single security
2. Request all information for multiple securities
3. Request fundamentals for a single security
4. Request intraday for multiple securities
5. Request options for a single security
6. Request 52-week data for a single security
Request 1 - All (single)
GET https://etwssandbox.etrade.com/market/sandbox/rest/quote/AAPL
Response 1
<QuoteResponse>
<QuoteData>
<all>
<adjNonAdjFlag>false</adjNonAdjFlag>
<annualDividend>0.0</annualDividend>
<ask>0.0</ask>
E*TRADE Developer Platform 107 Get Quote
<askExchange>K</askExchange>
<askSize>0</askSize>
<askTime>00:00:00 EDT 03-15-2011</askTime>
<bid>0.0</bid>
<bidExchange>K</bidExchange>
<bidSize>0</bidSize>
<bidTime>00:00:00 EDT 03-15-2011</bidTime>
<chgClose>0.3100000000000023</chgClose>
<chgClosePrcn>0.09</chgClosePrcn>
<companyName>APPLE INC</companyName>
<daysToExpiration>0</daysToExpiration>
<dirLast>D</dirLast>
<dividend>0.0</dividend>
<eps>15.15</eps>
<estEarnings>23.021</estEarnings>
<exDivDate></exDivDate>
<exchgLastTrade>Pacific</exchgLastTrade>
<fsi>N</fsi>
<high>0.0</high>
<high52>364.9</high52>
<highAsk>0.0</highAsk>
<highBid>0.0</highBid>
<lastTrade>353.87</lastTrade>
<low>0.0</low>
<low52>199.25</low52>
<lowAsk>0.0</lowAsk>
<lowBid>0.0</lowBid>
<numTrades>0</numTrades>
<open>0.0</open>
<openInterest>0</openInterest>
<optionStyle></optionStyle>
<optionUnderlier></optionUnderlier>
<prevClose>353.56</prevClose>
<prevDayVolume>15587670</prevDayVolume>
<primaryExchange>Q</primaryExchange>
<symbolDesc>APPLE INC</symbolDesc>
<todayClose>353.87</todayClose>
<totalVolume>0</totalVolume>
<upc>0</upc>
<volume10Day>17085828</volume10Day>
</all>
<dateTime>15:15:54 EDT 03-15-2011</dateTime>
<product>
<symbol>AAPL</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
</QuoteResponse>
E*TRADE Developer Platform 108 Get Quote
Request 2 - All (multiple)
GET https://etwssandbox.etrade.com/market/sandbox/rest/quote/GOOG,AAPL,MSFT
Response 2
<QuoteResponse>
<QuoteData>
<all>
<adjNonAdjFlag>false</adjNonAdjFlag>
<annualDividend>0.0</annualDividend>
<ask>0.0</ask>
<askExchange>Y</askExchange>
<askSize>0</askSize>
<askTime>00:00:00 EDT 03-15-2011</askTime>
<bid>0.0</bid>
<bidExchange>Q</bidExchange>
<bidSize>0</bidSize>
<bidTime>00:00:00 EDT 03-15-2011</bidTime>
<chgClose>0.92999999999995</chgClose>
<chgClosePrcn>0.16</chgClosePrcn>
<companyName>GOOGLE INC</companyName>
<daysToExpiration>0</daysToExpiration>
<dirLast>D</dirLast>
<dividend>0.0</dividend>
<eps>24.63</eps>
<estEarnings>34.524</estEarnings>
<exDivDate></exDivDate>
<exchgLastTrade>NASDAQ</exchgLastTrade>
<fsi>N</fsi>
<high>0.0</high>
<high52>642.96</high52>
<highAsk>0.0</highAsk>
<highBid>0.0</highBid>
<lastTrade>570.92</lastTrade>
<low>0.0</low>
<low52>433.63</low52>
<lowAsk>0.0</lowAsk>
<lowBid>0.0</lowBid>
<numTrades>0</numTrades>
<open>0.0</open>
<openInterest>0</openInterest>
<optionStyle></optionStyle>
<optionUnderlier></optionUnderlier>
<prevClose>569.99</prevClose>
<prevDayVolume>2813969</prevDayVolume>
<primaryExchange>Q</primaryExchange>
<symbolDesc>GOOGLE INC</symbolDesc>
<todayClose>570.92</todayClose>
<totalVolume>0</totalVolume>
<upc>0</upc>
<volume10Day>2718247</volume10Day>
</all>
<dateTime>15:15:43 EDT 03-15-2011</dateTime>
E*TRADE Developer Platform 109 Get Quote
<product>
<symbol>GOOG</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
<QuoteData>
<all>
<adjNonAdjFlag>false</adjNonAdjFlag>
<annualDividend>0.0</annualDividend>
<ask>0.0</ask>
<askExchange>K</askExchange>
<askSize>0</askSize>
<askTime>00:00:00 EDT 03-15-2011</askTime>
<bid>0.0</bid>
<bidExchange>K</bidExchange>
<bidSize>0</bidSize>
<bidTime>00:00:00 EDT 03-15-2011</bidTime>
<chgClose>0.3100000000000023</chgClose>
<chgClosePrcn>0.09</chgClosePrcn>
<companyName>APPLE INC</companyName>
<daysToExpiration>0</daysToExpiration>
<dirLast>D</dirLast>
<dividend>0.0</dividend>
<eps>15.15</eps>
<estEarnings>23.021</estEarnings>
<exDivDate></exDivDate>
<exchgLastTrade>Pacific</exchgLastTrade>
<fsi>N</fsi>
<high>0.0</high>
<high52>364.9</high52>
<highAsk>0.0</highAsk>
<highBid>0.0</highBid>
<lastTrade>353.87</lastTrade>
<low>0.0</low>
<low52>199.25</low52>
<lowAsk>0.0</lowAsk>
<lowBid>0.0</lowBid>
<numTrades>0</numTrades>
<open>0.0</open>
<openInterest>0</openInterest>
<optionStyle></optionStyle>
<optionUnderlier></optionUnderlier>
<prevClose>353.56</prevClose>
<prevDayVolume>15587670</prevDayVolume>
<primaryExchange>Q</primaryExchange>
<symbolDesc>APPLE INC</symbolDesc>
<todayClose>353.87</todayClose>
<totalVolume>0</totalVolume>
<upc>0</upc>
<volume10Day>17085828</volume10Day>
</all>
<dateTime>15:15:54 EDT 03-15-2011</dateTime>
<product>
<symbol>AAPL</symbol>
E*TRADE Developer Platform 110 Get Quote
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
<QuoteData>
<all>
<adjNonAdjFlag>false</adjNonAdjFlag>
<annualDividend>0.52</annualDividend>
<ask>28.71</ask>
<askExchange>NASDAQ National Market Sys (NMS)</askExchange>
<askSize>15600</askSize>
<askTime>12:14:22 EST 02-24-2010</askTime>
<bid>28.7</bid>
<bidExchange></bidExchange>
<bidSize>15600</bidSize>
<bidTime>12:14:22 EST 02-24-2010</bidTime>
<chgClose>-0.3400000000000001</chgClose>
<chgClosePrcn>-15.11</chgClosePrcn>
<companyName>MICROSOFT CORP</companyName>
<daysToExpiration>0</daysToExpiration>
<dirLast>U</dirLast>
<dividend>0.13</dividend>
<eps>1.81</eps>
<estEarnings>1.811</estEarnings>
<exDivDate>11/17/2009</exDivDate>
<exchgLastTrade>Pacific</exchgLastTrade>
<fsi>N</fsi>
<high>28.77</high>
<high52>31.5</high52>
<highAsk>28.77</highAsk>
<highBid>28.76</highBid>
<lastTrade>28.705</lastTrade>
<low>28.38</low>
<low52>14.87</low52>
<lowAsk>28.39</lowAsk>
<lowBid>28.0</lowBid>
<numTrades>61376</numTrades>
<open>28.52</open>
<openInterest>0</openInterest>
<optionStyle></optionStyle>
<optionUnderlier></optionUnderlier>
<prevClose>28.73</prevClose>
<prevDayVolume>75648887</prevDayVolume>
<primaryExchange>Q</primaryExchange>
<symbolDesc>MICROSOFT CORP</symbolDesc>
<todayClose>0.0</todayClose>
<totalVolume>22403011</totalVolume>
<upc>0</upc>
<volume10Day>56676460</volume10Day>
</all>
<dateTime>12:14:22 EST 02-24-2010</dateTime>
<product>
<symbol>MSFT</symbol>
<type>EQ</type>
<exchange>Q</exchange>
E*TRADE Developer Platform 111 Get Quote
</product>
</QuoteData>
</QuoteResponse>
Request 3 - Fundamentals (single)
GET
https://etwssandbox.etrade.com/market/sandbox/rest/quote/MSFT?detailFlag=FUNDAMENTAL
Response 3
<QuoteResponse>
<QuoteData>
<dateTime>12:15:58 EST 02-24-2010</dateTime>
<fundamental>
<companyName>MICROSOFT CORP</companyName>
<eps>1.81</eps>
<estEarnings>1.811</estEarnings>
<high52>31.5</high52>
<lastTrade>28.71</lastTrade>
<low52>14.87</low52>
<symbolDesc>MICROSOFT CORP</symbolDesc>
<volume10Day>56676460</volume10Day>
</fundamental>
<product>
<symbol>MSFT</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
</QuoteResponse>
Request 4 - Intraday (multiple)
GET
https://etwssandbox.etrade.com/market/sandbox/rest/quote/GOOG,AAPL,MSFT?detailFlag=INT
RADAY
Response 4
<QuoteResponse>
<QuoteData>
<dateTime>15:15:43 EDT 03-15-2011</dateTime>
<intraday>
<ask>0.0</ask>
<bid>0.0</bid>
<chgClose>0.92999999999995</chgClose>
<chgClosePrcn>0.16</chgClosePrcn>
E*TRADE Developer Platform 112 Get Quote
<companyName>GOOGLE INC</companyName>
<high>0.0</high>
<lastTrade>570.92</lastTrade>
<low>0.0</low>
<totalVolume>0</totalVolume>
</intraday>
<product>
<symbol>GOOG</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
<QuoteData>
<dateTime>15:15:54 EDT 03-15-2011</dateTime>
<intraday>
<ask>0.0</ask>
<bid>0.0</bid>
<chgClose>0.3100000000000023</chgClose>
<chgClosePrcn>0.09</chgClosePrcn>
<companyName>APPLE INC</companyName>
<high>0.0</high>
<lastTrade>353.87</lastTrade>
<low>0.0</low>
<totalVolume>0</totalVolume>
</intraday>
<product>
<symbol>AAPL</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
<QuoteData>
<dateTime>12:19:32 EST 02-24-2010</dateTime>
<intraday>
<ask>28.74</ask>
<bid>28.73</bid>
<chgClose>0.00999999999999801</chgClose>
<chgClosePrcn>0.03</chgClosePrcn>
<companyName>MICROSOFT CORP</companyName>
<high>28.77</high>
<lastTrade>28.74</lastTrade>
<low>28.38</low>
<totalVolume>22756597</totalVolume>
</intraday>
<product>
<symbol>MSFT</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
</QuoteResponse>
E*TRADE Developer Platform 113 Get Quote
Request 5 - Options (single)
GET https://etwssandbox.etrade.com/market/sandbox/rest/quote/MSFT?detailFlag=OPTIONS
Response 5
<QuoteResponse>
<QuoteData>
<dateTime>12:18:18 EST 02-24-2010</dateTime>
<option>
<ask>28.72</ask>
<askSize>11200</askSize>
<bid>28.71</bid>
<bidSize>19100</bidSize>
<companyName>MICROSOFT CORP</companyName>
<daysToExpiration>0</daysToExpiration>
<lastTrade>28.72</lastTrade>
<openInterest>0</openInterest>
</option>
<product>
<symbol>MSFT</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
</QuoteData>
</QuoteResponse>
Request 6 - 52-week (single)
GET https://etwssandbox.etrade.com/market/sandbox/rest/quote/MSFT?detailFlag=WEEK_52
Response 6
<QuoteResponse>
<QuoteData>
<dateTime>12:17:30 EST 02-24-2010</dateTime>
<product>
<symbol>MSFT</symbol>
<type>EQ</type>
<exchange>Q</exchange>
</product>
<week52>
<annualDividend>0.52</annualDividend>
<companyName>MICROSOFT CORP</companyName>
<high52>31.5</high52>
<lastTrade>28.705</lastTrade>
<low52>14.87</low52>
<perf12Months>0.0</perf12Months>
<prevClose>28.73</prevClose>
<symbolDesc>MICROSOFT CORP</symbolDesc>
<totalVolume>22434786</totalVolume>
E*TRADE Developer Platform 114 Get Quote
</week52>
</QuoteData>
</QuoteResponse>
E*TRADE Developer Platform 115 Get Option Chains
Get Option Chains
Returns a list of option chains associated with a specific underlier.
Description
This API returns a list of option chains for a specific underlying instrument. The request must
specify an instrument, the month the option expires, and whether you are interested in calls,
puts, or both. Values returned include the option pair count and information about each option
pair, including the type, call count, symbol, product, date, and strike price.
URL
https://etws.etrade.com/market/rest/optionchains
HTTP Method: GET
Request Parameters
Parameter
Type
Description
chainType
enum
The type of option chain. Possible values are: CALL, PUT, or
CALLPUT (i.e., both calls and puts).
expirationMonth
integer
The month the option will expire
expirationYear
integer
The year the option will expire
underlier
string
The market symbol for the underlying security
skipAdjusted
boolean
Specifies whether to show (TRUE) or not show (FALSE)
adjusted options, i.e., options that have undergone a change
resulting in a modification of the option contract. Default
value is TRUE.
Response Properties
Property
Type
Description
optionPairCount
integer
The number of option pairs returned
optionPairs
complex
Container for an option pair. There will be one of these for each
option pair in the response.
callCount (or
putCount)
integer
The number of call or put objects in this container
pairType
string
Determines whether the response will contain calls, puts, or both.
Possible values are: CALLONLY, PUTONLY, or CALLPUT.
call (or put)
complex
Container for a call or put. There are typically more than one of
these in a response - check callCount or putCount for the
count.
rootSymbol
string
The underlier for the option as originally contracted, e.g., GOOG.
For adjusted options, this root symbol may not match the current
symbol.
E*TRADE Developer Platform 116 Get Option Chains
expireDate
complex
Container for information on the expiration date
day
integer
Expiration day as a day of the month
month
integer
Expiration month as number
year
integer
Four-digit expiration year
expiryType
string
Expiry type of the option. Possible values are: QUARTERLY,
MONTHLY, or WEEKLY.
product
complex
A container for information on the product specified in this option
exchangeCode
string
The primary exchange where the option is traded
symbol
string
The market symbol for the option, formatted as the stock symbol,
expiration date, price, "Put" or "Call", and expiry type - "w"
(weekly), "q" (quarterly), or neither (monthly). For example,
"GOOG Jan 07 '11 $660 Call w".
typeCode
string
Value is always OPTN. Supported for legacy purposes.
strikePrice
double
The agreed strike price for the option, as stated in the contract
callCount (or
putCount)
integer
The number of call or put objects in this response
symbol
string
The market symbol for the instrument, e.g., GOOG
Sample Request
GET
https://etws.etrade.com/market/rest/optionchains?expirationMonth=04&expirationYear=201
1&chainType=PUT&skipAdjusted=true&underlier=GOOG
Sample response - XML
<OptionChainResponse>
<optionPairCount>2</optionPairCount>
<optionPairs>
<call>
<rootSymbol>GOOG</rootSymbol>
<expireDate>
<day>7</day>
<month>1</month>
<year>2011</year>
<expiryType>WEEKLY</expiryType>
</expireDate>
<product>
<exchangeCode>CINC</exchangeCode>
<symbol>GOOG Jan 07 '11 $540 Call w</symbol>
<typeCode>OPTN</typeCode>
</product>
<strikePrice>540.000000</strikePrice>
</call>
<callCount>1</callCount>
<pairType>CALLPUT</pairType>
<put>
<rootSymbol>GOOG</rootSymbol>
<expireDate>
E*TRADE Developer Platform 117 Get Option Chains
<day>7</day>
<month>1</month>
<year>2011</year>
<expiryType>WEEKLY</expiryType>
</expireDate>
<product>
<exchangeCode>CINC</exchangeCode>
<symbol>GOOG Jan 07 '11 $540 Put w</symbol>
<typeCode>OPTN</typeCode>
</product>
<strikePrice>540.000000</strikePrice>
</put>
<putCount>1</putCount>
</optionPairs>
<optionPairs>
<call>
<rootSymbol>GOOG</rootSymbol>
<expireDate>
<day>7</day>
<month>1</month>
<year>2011</year>
<expiryType>WEEKLY</expiryType>
</expireDate>
<product>
<exchangeCode>CINC</exchangeCode>
<symbol>GOOG Jan 07 '11 $660 Call w</symbol>
<typeCode>OPTN</typeCode>
</product>
<strikePrice>660.000000</strikePrice>
</call>
<callCount>1</callCount>
<pairType>CALLPUT</pairType>
<put>
<rootSymbol>GOOG</rootSymbol>
<expireDate>
<day>7</day>
<month>1</month>
<year>2011</year>
<expiryType>WEEKLY</expiryType>
</expireDate>
<product>
<exchangeCode>CINC</exchangeCode>
<symbol>GOOG Jan 07 '11 $660 Put w</symbol>
<typeCode>OPTN</typeCode>
</product>
<strikePrice>660.000000</strikePrice>
</put>
<putCount>1</putCount>
</optionPairs>
<symbol>goog</symbol>
</OptionChainResponse>
E*TRADE Developer Platform 118 Get Option Chains
Sample response - JSON
{
"OptionChainResponse": {
"optionPairCount": "2",
"optionPairs": [
{
"call": {
"rootSymbol": "GOOG",
"expireDate": {
"day": "7",
"month": "1",
"year": "2011",
"expiryType": "WEEKLY"
},
"product": {
"exchangeCode": "CINC",
"symbol": "GOOG Jan 07 '11 $540 Call w",
"typeCode": "OPTN"
},
"strikePrice": "540.000000"
},
"callCount": "1",
"pairType": "CALLPUT",
"put": {
"rootSymbol": "GOOG",
"expireDate": {
"day": "7",
"month": "1",
"year": "2011",
"expiryType": "WEEKLY"
},
"product": {
"exchangeCode": "CINC",
"symbol": "GOOG Jan 07 '11 $540 Put w",
"typeCode": "OPTN"
},
"strikePrice": "540.000000"
},
"putCount": "1"
},
{
"call": {
"rootSymbol": "GOOG",
"expireDate": {
"day": "7",
"month": "1",
"year": "2011",
"expiryType": "WEEKLY"
},
"product": {
"exchangeCode": "CINC",
"symbol": "GOOG Jan 07 '11 $660 Call w",
"typeCode": "OPTN"
},
E*TRADE Developer Platform 119 Get Option Chains
"strikePrice": "660.000000"
},
"callCount": "1",
"pairType": "CALLPUT",
"put": {
"rootSymbol": "GOOG",
"expireDate": {
"day": "7",
"month": "1",
"year": "2011",
"expiryType": "WEEKLY"
},
"product": {
"exchangeCode": "CINC",
"symbol": "GOOG Jan 07 '11 $660 Put w",
"typeCode": "OPTN"
},
"strikePrice": "660.000000"
},
"putCount": "1"
}
],
"symbol": "goog"
}
}
Sample use cases
Some possible use-cases and workflows are described below.
Purpose
Workflow
Related APIs
Options display
Create a table of options for a desired security by
requesting option data (with Get Option Chains),
grouping it by dates (from Get Option Expire Dates),
sorting each group, and displaying the result. May
enhance display by using streaming quote updates for
the symbol.
Get Option Chains, Get
Option Expire Dates, Get
Quote, Streaming API
Related APIs
Get Option Expire Dates, Get Quote
Sandbox Samples
The following shows a typical request and response in the sandbox environment.
Request
GET
https://etwssandbox.etrade.com/market/sandbox/rest/optionchains?chainType=PUT&expirati
onMonth=1&expirationYear=2013&underlier=GOOG
E*TRADE Developer Platform 120 Get Option Chains
Response
<OptionChainResponse>
<optionPairCount>2</optionPairCount>
<optionPairs>
<callCount>0</callCount>
<pairType>PUTONLY</pairType>
<put>
<rootSymbol>GOU</rootSymbol>
<expireDate>
<day>20</day>
<month>3</month>
<year>2010</year>
<expiryType>MONTHLY</expiryType>
</expireDate>
<product>
<exchangeCode>CINC</exchangeCode>
<symbol>GOU Mar 20 &apos;10 $240 Put</symbol>
<typeCode>OPTN</typeCode>
</product>
<strikePrice>240.000000</strikePrice>
</put>
<putCount>1</putCount>
</optionPairs>
<optionPairs>
<callCount>0</callCount>
<pairType>PUTONLY</pairType>
<put>
<rootSymbol>GOU</rootSymbol>
<expireDate>
<day>20</day>
<month>3</month>
<year>2010</year>
<expiryType>MONTHLY</expiryType>
</expireDate>
<product>
<exchangeCode>CINC</exchangeCode>
<symbol>GOU Mar 20 &apos;10 $250 Put</symbol>
<typeCode>OPTN</typeCode>
</product>
<strikePrice>250.000000</strikePrice>
</put>
<putCount>1</putCount>
</optionPairs>
<symbol>GOOG</symbol>
</OptionChainResponse>
E*TRADE Developer Platform 121 Get Option Expire Dates
Get Option Expire Dates
R
eturns a list of expiration dates for options that have the specified underlier.
Description
Returns a list of dates suitable for structuring an option table display. The dates are used to
group option data (returned by the optionchains method) for a specified underlier, creating a
table display.
URL
https://etws.etrade.com/market/rest/optionexpiredate
HTTP Method: GET
Request Parameters
Parameter
Type
Required?
Description
underlier
string
required
The symbol for the underlying instrument for this option
Response Properties
Property
Type
Description
ExpirationDate
complex
Container for information on a single expiration date. There will be one of
these for each date in the response.
day
integer
The day (1-31) the option will expire
month
integer
The month (1-12) the option will expire
year
integer
The 4-digit year the option will expire
expiryType
string
Expiry type of the option. Possible values are: QUARTERLY, MONTHLY, or
WEEKLY.
Sample Request
GET https://etws.etrade.com/market/rest/optionexpiredate?underlier=ABC
Sample response - XML
<OptionExpireDateGetResponse>
<ExpirationDate>
<day>22</day>
<month>1</month>
<year>2011</year>
<expiryType>MONTHLY</expiryType>
</ExpirationDate>
<ExpirationDate>
<day>19</day>
<month>2</month>
E*TRADE Developer Platform 122 Get Option Expire Dates
<year>2011</year>
<expiryType>MONTHLY</expiryType>
</ExpirationDate>
</OptionExpireDateGetResponse>
Sample response - JSON
{
"OptionExpireDateGetResponse": {
"ExpirationDate": [
{
"day": "22",
"month": "1",
"year": "2011",
"expiryType": "MONTHLY"
},
{
"day": "19",
"month": "2",
"year": "2011",
"expiryType": "MONTHLY"
}
]
}
}
Notes
To create an option chain display, group the option chain data by dates, which are
supplied by the Get Option Expire Dates API.
Sample use cases
Purpose
Workflow
Related APIs
Options display
Create a table of options for a desired security by requesting
option data (with Get Option Chains), grouping it by dates (from
Get Option Expire Dates), sorting each group, and displaying
the result. May enhance display by using streaming quote
updates for the symbol.
Get Option
Chains, Get
Option Expire
Dates, Get Quote,
Streaming API
Related APIs
Get Option Chains, Get Quote
Sandbox Samples
The following shows a typical request and response in the sandbox environment.
E*TRADE Developer Platform 123 Get Option Expire Dates
Request
GET
https://etwssandbox.etrade.com/market/sandbox/rest/optionexpiredate.json?underlier=IBM
Response
{
"optionExpireDateGetResponse":{
"expireDates":[
{
"day":22,
"month":1,
"year":2011,
"expiryType":"MONTHLY"
},
{
"day":19,
"month":2,
"year":2011,
"expiryType":"MONTHLY"
},
{
"day":19,
"month":3,
"year":2011,
"expiryType":"MONTHLY"
},
{
"day":18,
"month":6,
"year":2011,
"expiryType":"MONTHLY"
},
{
"day":21,
"month":1,
"year":2012,
"expiryType":"MONTHLY"
},
{
"day":19,
"month":1,
"year":2013,
"expiryType":"MONTHLY"
}
]
}
}
E*TRADE Developer Platform 124 List Orders
Orders
List Orders
Retur