Introduction

This tutorial uses the E*TRADE Java SDK, and is designed for Java programmers who want to develop their own application using the E*TRADE API to leverage E*TRADE's market data offerings, order routing capabilities, and other services.

If you are not a Java developer, you may still find this tutorial helpful - the examples are simple and the code is easy to read. You may also find helpful information elsewhere in the platform documentation. The OAuth authorization process, in particular, is explained in the separate Authorization section of this documentation.

The tutorial will walk you through two procedures:

  1. Authorize your application using OAuth.
  2. Retrieve a list of your E*TRADE accounts.
Requirements
Java SDK

To proceed with this tutorial, you must first have completed the installation of the E*TRADE Java SDK, including:

  • Java 1.6 or later installed
  • 3rd-party jars installed
  • E*TRADE Java SDK libraries in your CLASSPATH
Sandbox consumer key

The application created in this tutorial will need a valid consumer key for the sandbox test environment, as described in the Introduction documentation.

Step 1: OAuth Authorization

The OAuth protocol enables a user to authorize an application to use a data service on the user's behalf. The process is explained in detail in our Authorization. Note that, in the instructions below, the "user" is generally assumed to be the developer who is reading or following the tutorial.

In OAuth, an application's access to the user account requires a temporary access token and access secret. The token must accompany every API call, along with a signature based on the secret. Your application must perform the following steps to get the access token and secret:

  1. Obtain a request token and token secret from E*TRADE, using your consumer key.
  2. Redirect the user to an E*TRADE authorization page, where the user logs in and grants access to the application. This results in a verification code, which is then typed into the application by the user or automatically passed to the application via a callback.
  3. Use the request token and verification code to get the access token and token secret.
Obtain a request token

The following Java code obtains the request token and token secret. Remember that the request token is only valid for five minutes.

import com.etrade.etws.account.Account;
import com.etrade.etws.account.AccountListResponse;
import com.etrade.etws.oauth.sdk.client.IOAuthClient;
import com.etrade.etws.oauth.sdk.client.OAuthClientImpl;
import com.etrade.etws.oauth.sdk.common.Token;
import com.etrade.etws.sdk.client.ClientRequest;

// Variables
public IOAuthClient client = null;
public ClientRequest request = null;
public Token token = null;
public String oauth_consumer_key = null; // Your consumer key
public String oauth_consumer_secret = null; // Your consumer secret
public String oauth_request_token = null; // Request token 
public String oauth_request_token_secret = null; // Request token secret
client = OAuthClientImpl.getInstance(); // Instantiate IOAUthClient
request = new ClientRequest(); // Instantiate ClientRequest
request.setEnv(Environment.SANDBOX); // Use sandbox environment

request.setConsumerKey(oauth_consumer_key); //Set consumer key
request.setConsumerSecret(oauth_consumer_secret); // Set consumer secret
token= client.getRequestToken(request); // Get request-token object
oauth_request_token  = token.getToken(); // Get token string
oauth_request_token_secret = token.getSecret(); // Get token secret
Obtain a verification code

The next section of code redirects your user to E*TRADE for authorization. Upon successful login, the E*TRADE page displays information to user about your application's request for access. If the user approves, the page displays a verification code.

import java.awt.Desktop;
import java.net.URI;

String authorizeURL = null;
authorizeURL = client.getAuthorizeUrl(request); // E*TRADE authorization URL
URI uri = new java.net.URI(authorizeURL);
Desktop desktop = Desktop.getDesktop();
desktop.browse(authorizeURL);

If Customer Service has configured a callback URL for your application, the user is then automatically routed to your callback URL, with the verification code added as a parameter on the URL. If not, the user has to manually copy the verification code and enter it into your application. More information on callbacks is provided in our Authorization documentation.

Obtain an access token

The following code shows how to exchange the request token and verification code for an access token with the verification code.

public String oauth_access_token = null; // Variable to store access token 
public String oauth_access_token_secret = null; // Variable to store access token secret
public String oauth_verify_code = "Your verification_code"; // Should contain the Verification Code received from the authorization step

request = new ClientRequest(); // Instantiate ClientRequest
request.setEnv(Environment.SANDBOX); // Use sandbox environment
// Prepare request
request.setConsumerKey(oauth_consumer_key); // Set consumer key
request.setConsumerSecret(oauth_consumer_secret); // Set consumer secret
request.setToken(oauth_request_token); // Set request token
request.setTokenSecret(oauth_request_token_secret); // Set request-token secret
request.setVerifierCode(oauth_verify_code); // Set verification code

// Get access token
token = client.getAccessToken(request); // Get access-token object
oauth_access_token = token.getToken(); // Access token string
oauth_access_token_secret = token.getSecret(); // Access token secret

Congratulations, your application has been authorized - at least, temporarily. A sandbox access token is good for 24 hours. Production access tokens are good until midnight Eastern time, or for a duration configured at your request by Customer Service.

Step 2: Retrieve a list of accounts

You have the access token, so now you can make requests on the user's account. The code below shows how to request a list of the user's accounts and display the results.

request = new ClientRequest(); // Instantiate ClientRequest
// Prepare request
request.setEnv(Environment.SANDBOX);
request.setConsumerKey(oauth_consumer_key);
request.setConsumerSecret(oauth_consumer_secret);
request.setToken(oauth_access_token);
request.setTokenSecret(oauth_access_token_secret);

try
{
  AccountsClient account_client = new AccountsClient(request);
  AccountListResponse response = account_client.getAccountList();
  List<Account> alist = response.getResponse();
  Iterator<Account> al = alist.iterator();
  while (al.hasNext()) {
    Account a = al.next();
    System.out.println("===================");
    System.out.println("Account: " + a.getAccountId());
    System.out.println("===================");
  }
}
catch (Exception e)
{
}
What's next?

Now that you've authorized your application and retrieved an account list, you can experiment with other E*TRADE APIs on your own. We encourage you to explore these other resources:

PLEASE READ THE IMPORTANT DISCLOSURES BELOW

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


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


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


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