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:
- Authorize your application using OAuth.
- Retrieve a list of your E*TRADE accounts.
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
The application created in this tutorial will need a valid consumer key for the sandbox test environment, as described
in the Introduction documentation.
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:
- Obtain a request token and token secret from E*TRADE, using your consumer key.
- 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.
- Use the request token and verification code to get the access token and token secret.
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
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.
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.
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)
{
}
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: