Firstrade Developer Documentation

Introduction

Registering

You need to register for a developer account on the Firstrade Developers website. Once you register, you need to build an app and have it approved by Firstrade before you can start using the live API to submit trades and manage real customer accounts.

Sandbox

To help you build and debug your application, Firstrade offers a sandbox testing environment that you can use to build, test and debug your application. You can create a set of credentials to access the sandbox environment from your developer account by clicking the create sandbox app button. In addition to a set of oauth credentials, you will also be provided with a set of customer credentials valid only for the sandbox environment that you can use during your development process.



Structure

The Firstrade API is implemented as vanilla XML over HTTPS. Each resource has a separate URL and is operated on independently of other resources using different HTTP verbs. We attempt to follow REST principles as closely as possible.

API Endpoint

All Firstrade API requests MUST use the following URL as their endpoint. API versions prior to 2.0 were not publicly released and will not function with Firstrade Developer accounts. Consumers of the Firstrade API MUST verify that the common name on the SSL certificate provided by the endpoint matches the DNS name of the endpoint and that the SSL certificate is valid. Both live and sandbox requests get sent to the same endpoint.

Endpoint

https://api.firstrade.com/rest/2.0/

Request Format

Requests are made to the Firstrade API as standard HTTP over SSL (HTTPS). Requests include one of 3 HTTP verbs (GET, POST, or DELETE) and the path of the resource on which the action should be performed. The desired response format should be appended to the resource path. Certain resources require authentication. In this case, OAuth 2.0 information should be included in the HTTP request header as described in the Authentication section.

Request Example

In this example, we make a request for the account balancese of the user specified by the OAuth 2.0 access token in the header. By appending ".xml", we indicate that the response should be delivered in XML.

GET /rest/2.0/accounts/balances.xml HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response Format

The Firstrade API supports 3 response formats: XML, JSON, and JSONP. To request different formats, append ".xml", ".json", or ."jsonp" to the end of the resource path. Please note that JSONP requires the name of the callback function be passed as the parameter "callback": ".jsonp?callback=functionName."

Response Example

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
	<account id="98800001">
		<account-balance>8301.73</account-balance>
		<total-account-value>8301.73</total-account-value>
		<total-account-change>2439.91</total-account-change>
		<short-balance>0.00</short-balance>
		<account-cash-value>0.00</account-cash-value>
		<account-margin-value>-24582.24</account-margin-value>
		<stock-buying-power>0.00</stock-buying-power>
		<option-buying-power>0.00</option-buying-power>
		<total>-18217.22</total>
		<cash-buying-power>0.00</cash-buying-power>
		<money-locked-by-pending-orders>1000.00</money-locked-by-pending-orders>
	</account>
	<account id="98800007&quorate_limitingt;>
		<account-balance>0.00</account-balance>
		<total-account-value>0.00</total-account-value>
		<total-account-change>0.00</total-account-change>
		<short-balance>0.00</short-balance>
		<account-cash-value>0.00</account-cash-value>
		<account-margin-value>0.00</account-margin-value> **
		<money-market-funds>0.00</money-market-funds>  **
		<stock-buying-power>0.00</stock-buying-power>  **
		<option-buying-power>0.00</option-buying-power>  **
		<daytrade-buying-power>0.00</daytrade-buying-power> **
		<total>0.00</total>
		<cash-buying-power>0.00</cash-buying-power>
		<money-locked-by-pending-orders>0.00</money-locked-by-pending-orders>
	</account>
</accounts>

Errors

Errors consist of an integer error and a human readable description of the error. If you wish to localization or customize error messages displayed to your users, you should use the error code as a key.

Example Error Response

<error>
	<code>1001</code>
	<message>Bad username and/or password for API Access.</message>
</error>


Security

Encryption

All requests MUST be made over SSL and the endpoint's certificate MUST be verified for authenticity.

Authentication

The Firstrade API uses OAuth 2.0 for authentication. OAuth 2.0 is a standard way for third-party apps to get authorized access to a customer's account without asking customers for sensitive usernames, pins and passwords.

The typical flow for a web app:

  1. Your app requests authorization by redirecting your user to the Firstrade Authorization endpoint: https://invest.firstrade.com/oauth/authorize
  2. We authenticate their Firstrade customer login and ask whether it's ok to give access to your app.
  3. We redirect the user back to your app with a time-limited authorization code.
  4. Your app makes a backchannel request to redeem the authorization code for an access token: POST https://invest.firstrade.com/oauth/token.
  5. We authenticate your app and issue an access token.
  6. Your app uses the token to authorize API requests on behalf of the customer.

OAuth 2.0 implementation notes

  • Read the draft spec at http://tools.ietf.org/html/draft-ietf-oauth-v2
  • We implement draft 23 and will update our implementation as the final spec converges, so be prepared for changes along the way.
  • We support the authorization code grant type and issue bearer type access tokens.
  • We issue refresh tokens. Use them to request a new access token when yours expires.
  • Access tokens will expire every few minutes.

Rate Limiting

We reserve the right to rate limit requests. If your application is being rate limited, it will receive HTTP 400 response codes. You should always check the response code and reduce your application's request rate as necessary.



API Documentation

GET /accounts

Purpose:

Obtain list of accounts.

Request:

GET /accounts HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
	<account id="98800001" alias="My Account" permissions="FULL" type="CASH,MARGIN,SHORT" ext-hours-trading-status="T"></account>
	<account id="98800007" alias="John&#39;s Account" permissions="FULL" type="CASH,MARGIN,SHORT" ext-hours-trading-status="T"></account>
	<account id="98800008" alias="Mary&#39;s Account" permissions="FULL" type="CASH,MARGIN,SHORT" ext-hours-trading-status="T"></account>
	<account id="49871955" alias="Steph&#39;s Account" permissions="FULL" type="CASH" ext-hours-trading-status="a"></account>
</accounts>
        

Errors:

  • Global errors.

GET /accounts/balances

Purpose:

Obtain balance info for accounts.

Request:

GET /accounts/balances HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
	<account id="98800001">
		<account-balance>8301.73</account-balance>
		<total-account-value>8301.73</total-account-value>
		<total-account-change>2439.91</total-account-change>
		<short-balance>0.00</short-balance>
		<account-cash-value>0.00</account-cash-value>
		<account-margin-value>-24582.24</account-margin-value>
		<stock-buying-power>0.00</stock-buying-power>
		<option-buying-power>0.00</option-buying-power>
		<total>-18217.22</total>
		<cash-buying-power>0.00</cash-buying-power>
		<money-locked-by-pending-orders>1000.00</money-locked-by-pending-orders>
	</account>
	<account id="98800007">
		<account-balance>0.00</account-balance>
		<total-account-value>0.00</total-account-value>
		<total-account-change>0.00</total-account-change>
		<short-balance>0.00</short-balance>
		<account-cash-value>0.00</account-cash-value>
		<account-margin-value>0.00</account-margin-value> **
		<money-market-funds>0.00</money-market-funds>  **
		<stock-buying-power>0.00</stock-buying-power>  **
		<option-buying-power>0.00</option-buying-power>  **
		<daytrade-buying-power>0.00</daytrade-buying-power> **
		<total>0.00</total>
		<cash-buying-power>0.00</cash-buying-power>
		<money-locked-by-pending-orders>0.00</money-locked-by-pending-orders>
	</account>
</accounts>
    
**If the customer is not approved for relevant type of trading, this element will not be sent.

Errors:

  • Global errors.

POST /accounts/:id/orders

Purpose:

Place orders.

Variables:

Stock:

  transaction    4 types BUY, SELL, SELL-SHORT, BUY-TO-COVER
  shares
  symbol
  type           4 types LIMIT, MARKET, STOP, STOP-LIMIT
  limit-price    Required only for limit orders
  stop-price     Required only for stop orders
  duration       4 types DAY, GT90, EXAM, EXPM
  instructions   (Optional)3 types AON, OPG, CLO 

Option:

  transaction    4 types BUY-OPEN, SELL-OPEN, BUY-CLOSE, SELL-CLOSE
  side           2 types CALL, PUT
  rootsymbol
  contracts    
  exp-date
  strike
  price-type     2 types LIMIT, MARKET
  limit-price    Required only for limit orders
  duration       2 types DAY, GT90
  instructions   (Optional) 1 type  AON

Request:

Stock:

 
POST /accounts/98800001/orders HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm
Content-Length: 109

price-type=LIMIT&stop-price=&duration=DAY&shares=1&symbol=msft&instructions=&transaction=BUY&limit-price=0.01

Options:

POST /accounts/98800001/orders HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm
Content-Length: 173

contracts=1&limit-price=0.01&duration=DAY&instructions=&side=CALL&rootsymbol=MSFT&strike=24.00&transaction=BUY-OPEN&exp-date=2011-12-30T00%3A00%3A00-04%3A00&price-type=LIMIT 

Response:

Stock:

<?xml version="1.0" encoding="UTF-8"?>
<order id="B00001-2237331" state="ORDER-REQUESTED-BEFORE-MARKET"/>

Options:

<?xml version="1.0" encoding="UTF-8"?>
<option-order id="B00001-2237330" state="ORDER-REQUESTED-AFTER-MARKET"/>

Error:

  • Account does not have sufficient Buying Power, or does not have the privilege to make this trade.
  • Order variables violate order rules.

GET /accounts/:id/orders

Purpose:

Get a list of orders.

Variables:

type        Three options STOCK, OPTION, MUTUAL
per-page (Optional)  Number of items to return per page. If this argument is omitted, it defaults to 8.
page (Optional)  The page of results to return. If this argument is omitted, it defaults to 1.

Request:

GET /accounts/98800001/orders?type=STOCK HTTP/1.1

Response:

	<?xml version="1.0" encoding="UTF-8"?>
	<orders type="STOCK" page="1" pages="1" per-page="8" total="2">
	  <order id="B00001-2237332" updated="2011-12-30T02:03:35-05:00" transaction="BUY" type="LIMIT" instructions="" state="ORDER-SUBMITTED">
	    <account id="98800001"/>
	    <symbol>MSFT</symbol>
	    <limit-price>0.0200</limit-price>
	    <stop-price></stop-price>
	    <shares>1</shares>
	    <filled>0</filled>
	    <estimated>
	      <price>0.0200</price>
	      <total>0.0200</total>
	    </estimated>
	    <duration type="DAY"/>
	  </order>
	  <order id="B00001-2237331" updated="2011-12-30T02:03:35-05:00" transaction="BUY" type="LIMIT" instructions="" state="ORDER-UPDATED">
	    <account id="98800001"/>
	    <symbol>MSFT</symbol>
	    <limit-price>0.0100</limit-price>
	    <stop-price></stop-price>
	    <shares>1</shares>
	    <filled>0</filled>
	    <estimated>
	      <price>0.0100</price>
	      <total>0.0100</total>
	    </estimated>
	    <duration type="DAY"/>
	  </order>
	</orders>
        

POST /accounts/:id/orders/preview

Purpose:

Preview a stock or option order.

Variables:

Stock:

  transaction    4 types BUY, SELL, SELL-SHORT, BUY-TO-COVER
  shares
  symbol
  type           4 types LIMIT, MARKET, STOP, STOP-LIMIT
  limit-price    Required only for limit orders.
  stop-price     Required only for stop orders.
  duration       4 types DAY, GT90, EXAM, EXPM
  instructions   (Optional)3 types AON, OPG, CLO

Options:

  transaction    4 types BUY-OPEN, SELL-OPEN, BUY-CLOSE, SELL-CLOSE
  side           2 types CALL, PUT
  rootsymbol
  contracts    
  exp-date
  strike
  price-type     2 types LIMIT, MARKET
  limit-price    Required only for limit orders.
  duration       2 types DAY, GT90
  instructions   (Optional) 1 type  AON

Request:

Stock:

POST /accounts/98800008/orders/preview HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm
Content-Length: 106

price-type=LIMIT&stop-price=&duration=DAY&shares=1&symbol=msft&instructions=&transaction=BUY&limit-price=1

Options:

 
POST /accounts/98800001/orders/preview HTTP/1.1
Host: api.firstrade.com
Content-Length: 173

contracts=1&limit-price=0.01&duration=DAY&instructions=&side=CALL&rootsymbol=MSFT&strike=24.00&transaction=BUY-OPEN&exp-date=2012-01-21T00%3A00%3A00-04%3A00&price-type=LIMIT 

Response:

Stock:

  <?xml version="1.0" encoding="UTF-8"?>
  <order transaction="BUY" type="LIMIT" instructions="">
    <account id="98800008" />
    <symbol>MSFT</symbol> 
    <shares>1</shares> 
    <limit-price>1.00</limit-price>
    <stop-price></stop-price>
    <estimated>
      <price>1.00</price>
      <total>1.00</total>
    </estimated>
    <duration type="DAY"> 
      <date></date> 
    </duration> 
  </order>

Options:

  <?xml version="1.0" encoding="UTF-8"?>
  <option-order transaction="BUY-OPEN" side="CALL" strike="24.00" price-type="LIMIT" instructions="">
    <account id="98800001" />
    <option-symbol>MSFT120121C00024000</option-symbol> 
    <exp-date>2012-01-21T00%3A00%3A00-04%3A00</exp-date>
    <contracts>1</contracts> 
    <limit-price>0.0100</limit-price>
    <estimated>
      <price>0.0100</price>
      <total>1.0000</total>
    </estimated>
    <duration type="DAY"> 
      <date></date> 
    </duration> 
  </option-order>

Error:

  • Account does not have sufficient Buying Power, or does not have the privilege to make this trade.
  • Order variables violate order rules.

POST /accounts/:id/orders/:orderID

Purpose:

Edit existing order.

Variables:

Stock:

  shares
  limit-price  Only required for limit orders
  stop-price   Only required for stop orders
  type           4 Types LIMIT, MARKET, STOP, STOP-LIMIT
  duration       4 Types DAY, GT90, EXAM, EXPM

Options:

  contracts
  price-type
  limit-price  Only required for limit orders
  duration       2 types DAY, GT90
  instructions   (Optional)1 type AON

Request:

Stock:

POST /accounts/98800001/orders/B00001-2237331 HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm
Content-Length: 55

shares=1&limit-price=0.02&duration=DAY&price-type=LIMIT

Options:

POST /accounts/98800001/orders/B00001-2237330 HTTP/1.1
Host: api.firstrade.com
Content-Length: 71

contracts=2&limit-price=0.03&duration=DAY&instructions=&price-type=LIMIT 

Response:

Stock:

<?xml version="1.0" encoding="UTF-8"?>
<order id="B00001-2237332" updated="2011-12-30T02:03:35-05:00" transaction="BUY" type="LIMIT" instructions="" state="ORDER-REQUESTED-BEFORE-MARKET">
	<account id="98800001" />
	<symbol>MSFT</symbol> 
	<shares>1</shares> 
	<filled>0</filled> 
	<limit-price>0.0200</limit-price>
	<stop-price></stop-price>
	<estimated>
		<price>0.0200</price>
		<total>0.0200</total>
	</estimated>
	<duration type="DAY"> 
		<date></date> 
	</duration> 
</order>

Options:

<option-order id="B00001-2237333" transaction="BUY-OPEN" side="CALL" strike="24.00" price-type="LIMIT" instructions="" updated="2011-12-30T02:04:27-05:00" state="ORDER-SUBMITTED">
	<account id="98800001" />
	<option-symbol>MSFT111230C00024000</option-symbol> 
	<exp-date>2011-12-30T00:00:00-05:00</exp-date>
	<contracts>2</contracts> 
	<limit-price>0.0300</limit-price>
	<estimated>
		<price>0.0300</price>
		<total>6.0000</total>
	</estimated>
	<duration type="DAY"> 
		<date></date> 
	</duration> 
</option-order>

Error:

  • The order was not found by the order_id variable.
  • Order has been executed or cancelled, therefore cannot be updated.

GET /accounts/:id/orders/:orderID

Purpose:

Get detailed order information.

Request:

GET /accounts/98800001/orders/B00001-2237332 HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<order id="B00001-2237332" updated="2011-12-30T02:03:35-05:00" transaction="BUY" type="LIMIT" instructions="" state="ORDER-SUBMITTED">
	<account id="98800001" />
 	<symbol>MSFT</symbol> 
	<shares>1</shares> 
	<filled>0</filled> 
	<limit-price>0.0200</limit-price>
	<stop-price></stop-price>
	<estimated>
		<price>0.0200</price>
		<total>0.0200</total>
	</estimated>
	<duration type="DAY"> 
		<date></date> 
	</duration> 
</order>

Error:

  • Cannot find order by orderID.

POST /accounts/:id/orders/:orderID/preview

Purpose:

Preview an edit order.

Variables:

Stock:

  shares
  limit-price  Only required for limit orders
  stop-price   Only required for stop orders
  type           4 types LIMIT, MARKET, STOP, STOP-LIMIT
  duration       4 types DAY, GT90, EXAM, EXPM

Options:

  contracts
  price-type
  limit-price  Only requird for limit orders.
  duration       2 types DAY, GT90
  instructions   (Optional)1 type AON

Request:

Stock:

POST /accounts/98800001/orders/B00001-2237331/preview HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm
Content-Length: 55

shares=1&limit-price=0.02&duration=DAY&price-type=LIMIT

Options:

POST /accounts/98800001/orders/B00001-2237330/preview HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm
Content-Length: 71

contracts=2&limit-price=0.03&duration=DAY&instructions=&price-type=LIMIT 

Response:

Stock:

<?xml version="1.0" encoding="UTF-8"?>
<order id = "B00001-2237331" transaction="BUY" type="LIMIT" instructions="">
	<account id="98800001" />
	<symbol>MSFT</symbol> 
	<shares>1</shares> 
	<limit-price>0.0200</limit-price>
	<stop-price></stop-price>
	<estimated>
		<price>0.0200</price>
		<total>0.0200</total>
	</estimated>
	<duration type="DAY"> 
		<date></date> 
</duration> 
</order>

Options:

<?xml version="1.0" encoding="UTF-8"?>
<option-order id="B00001-2237330" transaction="BUY-OPEN" side="CALL" strike="24.00" price-type="LIMIT" instructions="" updated="" state="">
	<account id="98800001" />
	<option-symbol>MSFT111230C00024000</option-symbol> 
	<exp-date>2011-12-30T00:00:00-05:00</exp-date>
	<contracts>2</contracts> 
	<limit-price>0.0300</limit-price>
	<estimated>
		<price>0.0300</price>
		<total>6.0000</total>
	</estimated>
	<duration type="DAY"> 
		<date></date> 
	</duration> 
</option-order>

Error:

  • The order was not found by the order_id variable.
  • Order has been executed or cancelled, therefore cannot be updated.

GET /accounts/:id/positions

Purpose:

Obtain a list of positions held.

Variables:

type Four options  STOCK,OPTION,MUTUAL,BOND
per-page (Optional)  Number of items to return per page. If this argument is omitted, it defaults to 8.
page (Optional)  The page of results to return. If this argument is omitted, it defaults to 1.

Request:

GET /accounts/98800008/positions?type=STOCK HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<positions type="STOCK" page="1" pages="1" per-page="8" total="2">
	<position id="GE" type="STOCK">
	    <symbol>GE</symbol>
	    <quantity>10.0</quantity>
	    <market-value>180.7</market-value>
	    <change>
	      <amount>2.4</amount>
	      <percent>1.346</percent>
	    </change>
	  </position>
	  <position id="SBUX" type="STOCK">
	    <symbol>SBUX</symbol>
	    <quantity>1.0</quantity>
	    <market-value>46.45</market-value>
	    <change>
	      <amount>0.67</amount>
	      <percent>1.4635</percent>
	    </change>
	</position>
</positions>

GET /customer

Purpose:

Obtain information about the currently logged in customer.

Variables:

None

Request:

GET /customer HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<customer>
	<customer-id>jack</customer-id>
	<real-time-quotes>TRUE</real-time-quotes>
</customer>

PUT /customer/logout

Purpose:

Log out the currently logged in customer. Access token & refresh tokens associated with this session will be invalidated.

Variables:

None

Request:

PUT /customer/logout HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<auth/>

GET /markets/chain/:symbol

Purpose:

Obtain options chain.

Variables:

  • exp-date(Optional)

Request:

GET /markets/chain/MSFT HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<option-chains underlying-symbol="MSFT" name="Microsoft Corporation - Common Stock">
	<exp-dates>
		<exp-date date="2011-12-30T00:00:00-05:00"></exp-date>
		<exp-date date="2012-01-21T00:00:00-05:00"></exp-date>
		<exp-date date="2012-02-18T00:00:00-05:00"></exp-date>
		<exp-date date="2012-03-17T00:00:00-05:00"></exp-date>
		<exp-date date="2012-04-21T00:00:00-05:00"></exp-date>
		<exp-date date="2012-07-21T00:00:00-05:00"></exp-date>
		<exp-date date="2012-10-20T00:00:00-05:00"></exp-date>
		<exp-date date="2013-01-19T00:00:00-05:00"></exp-date>
		<exp-date date="2014-01-18T00:00:00-05:00"></exp-date>
	</exp-dates>
	<option-chain exp-date="2011-12-30T00:00:00-05:00">
		<option option-symbol="MSFT111230C00024000" strike="24.00" side="CALL" last="0.00" change="0.00" bid="1.74" ask="1.84" volume="0" interest="0"></option>
		<option option-symbol="MSFT111230P00024000" strike="24.00" side="PUT" last="0.00" change="0.00" bid="0.00" ask="0.01" volume="0" interest="0"></option>
		<option option-symbol="MSFT111230C00025000" strike="25.00" side="CALL" last="0.92" change="-0.17" bid="0.81" ask="0.86" volume="156" interest="498"></option>
		<option option-symbol="MSFT111230P00025000" strike="25.00" side="PUT" last="0.02" change="-0.01" bid="0.01" ask="0.02" volume="151" interest="768"></option>
		<option option-symbol="MSFT111230C00026000" strike="26.00" side="CALL" last="0.06" change="-0.11" bid="0.07" ask="0.09" volume="9515" interest="9265"></option>
		<option option-symbol="MSFT111230P00026000" strike="26.00" side="PUT" last="0.26" change="0.12" bid="0.24" ask="0.27" volume="7998" interest="5092"></option>
		<option option-symbol="MSFT111230C00027000" strike="27.00" side="CALL" last="0.01" change="0.00" bid="0.01" ask="0.01" volume="80" interest="2248"></option>
		<option option-symbol="MSFT111230P00027000" strike="27.00" side="PUT" last="1.19" change="0.28" bid="1.15" ask="1.20" volume="530" interest="412"></option>
		<option option-symbol="MSFT111230C00028000" strike="28.00" side="CALL" last="0.04" change="0.00" bid="0.00" ask="0.01" volume="0" interest="50"></option>
		<option option-symbol="MSFT111230P00028000" strike="28.00" side="PUT" last="2.21" change="0.25" bid="2.15" ask="2.20" volume="3" interest="1"></option>
		<option option-symbol="MSFT111230C00029000" strike="29.00" side="CALL" last="0.00" change="0.00" bid="0.00" ask="0.04" volume="0" interest="0"></option>
		<option option-symbol="MSFT111230P00029000" strike="29.00" side="PUT" last="0.00" change="0.00" bid="3.15" ask="3.25" volume="0" interest="0"></option>
	</option-chain>
</option-chains>
    
** When request includes the optional exp-date, the system will not respond with<exp-dates></exp-dates>. When request does not include exp-date, then the values are returned in the response.

Error:

  • Invalid symbol or exp-date.

GET /markets/news

Purpose:

Obtain news article text.

Request:

GET /markets/news HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<news-list version="2.0">
	<news id="216954049">
	    <headline><![CDATA[MidnightTrader's After-Hours Trading Ranges]]></headline>
	    <date>2011-12-29T17:47:27-0500</date>
	    <url><![CDATA[http://www.firstrade.idmanagedsolutions.com/news/market_story.idms?ID_NEWS=216954049]]></url>
	    <content><![CDATA[News content.]]></content>
	  </news>
	  <news id="216950196">
	    <headline><![CDATA[Owens &amp; Minor to Present at the J.P. Morgan Healthcare Conference on January 10, 2012]]></headline>
	    <date>2011-12-29T16:15:00-0500</date>
	    <content><![CDATA[News content.]]></content>
	</news>
</news-list>

GET /markets/news/:symbol

Purpose:

Obtain the news articles for a particular stock symbol.

Request:

GET /markets/news/MSFT HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<news-list symbol="MSFT" version="2.0">
	<news id="216954992">
	    <headline><![CDATA[Most active Nasdaq-traded stocks]]></headline>
	    <date>2011-12-29T18:15:04-0500</date>
	    <url><![CDATA[http://www.firstrade.idmanagedsolutions.com/news/story.idms?ID_NEWS=216954992&SYMBOL_US=MSFT]]></url>
	    <content><![CDATA[News content.]]></content>
	  </news>
	  <news id="216953153">
	    <headline><![CDATA[After-Hours Most Actives: Nasdaq]]></headline>
	    <date>2011-12-29T17:23:35-0500</date>
	    <url><![CDATA[http://www.firstrade.idmanagedsolutions.com/news/story.idms?ID_NEWS=216953153&SYMBOL_US=MSFT]]></url>
	    <content><![CDATA[
		        <p>05:23 PM EST, 12/29/2011 (MidnightTrader) -- The most actively traded stocks in the after-hours are:</p>
	<p>NWSA, +0.4%</p>
	<p>AMR, -40%</p>
	<p>AONE, -4%</p>
	<p>MSFT, -0.08%</p>
	<p>CSCO, -0.1%</p>
	<p>http://www.midnighttrader.com<br>(C) 1999-2011 MidnightTrader, Inc. All rights reserved.</p>
		    ]]></content>
	</news>
</news-list>

Error:

  • Invalid stock symbol.

GET /markets/quotes/:symbol

Purpose:

Obtain a quote for a symbol.

Request:

GET /markets/quotes/MSFT HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
<stock symbol="MSFT" date="2011-12-29 23:23:21 +0800">
  <name>Microsoft Corporation - Common Stock</name>
  <price>25.82</price>
  <change>
    <amount>-0.22</amount>
    <percent>-0.8449</percent>
  </change>
  <bid>25.83</bid>
  <ask>25.89</ask>
  <open>26.11</open>
  <volume>1300</volume>
  <day-low>25.8</day-low>
  <day-high>26.15</day-high>
  <prev-close>26.04</prev-close>
  <year-low>23.65</year-low>
  <year-high>29.46</year-high>
  <pe>9.38909</pe>
  <beta>0.9779</beta>
  <div-per-share>n.a.</div-per-share>
  <market-cap>217202539200.0</market-cap>
  <shares-outstanding>8412182000.0</shares-outstanding>
  <short-interest>0.89</short-interest>
  <dividend-yield>n.a.</dividend-yield>
  <primary-exchange>NMS</primary-exchange>
</stock>

Error:

  • Invalid symbol.

GET /markets/stocks/:symbol

Purpose:

Search for matching symbol or company name, return 20 responses.

Request:

GET /markets/stocks/INT HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<?xml version="1.0" encoding="UTF-8"?>
	<stocks symbol="INT" version="2.0">
	  <stock symbol="INT" corp="WORLD FUEL SERVICES"/>
	  <stock symbol="INTAX" corp="RIVERSOURCE TAX-EXEMPT BOND FUND INC CL"/>
	  <stock symbol="INTC" corp="INTEL"/>
	  <stock symbol="INTE" corp="INDUSTRIAL TECH"/>
	  <stock symbol="INTG" corp="INTERGROUP"/>
	  <stock symbol="INTH" corp="INNOTECH CORP"/>
	  <stock symbol="INTIF" corp="INTIME DEPARTMENT STORE"/>
	  <stock symbol="INTIX" corp="ING INTL INDEX PORTF CL S"/>
	  <stock symbol="INTK" corp="INDUSTRIAL NANOTECH"/>
	  <stock symbol="INTLX" corp="FORESTER DISCOVERY FUND"/>
	  <stock symbol="INTO" corp="INITIO INC"/>
	  <stock symbol="INTP" corp="INTEGRATED PHARMACEUTICALS INC"/>
	  <stock symbol="INTT" corp="INTEST"/>
	  <stock symbol="INTU" corp="INTUIT"/>
	  <stock symbol="INTX" corp="INTERSECTIONS"/>
	  <stock symbol="INTZ" corp="INTRUSION"/>
	  <stock symbol="ALLX" corp="INTL ALLIANCE RES INC"/>
	  <stock symbol="CBOAX" corp="INTERMEDIATE BOND FUND of AMERICA CL 529-A SHARES"/>
	  <stock symbol="CBOBX" corp="INTERMEDIATE BOND FUND of AMERICA CL 529-B SHARES"/>
	  <stock symbol="CBOCX" corp="INTERMEDIATE BOND FUND of AMERICA CL 529-C SHARES"/>
	</stocks>

POST /watchlists

Purpose:

Create watchlist. Once created, the newly created watchlist is set as default.

Variables:

  • name

Request:

POST /watchlists HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm
Content-Length: 8

name=DDD

Response:

<watchlists>
	<lists>
		<list id="444444" name="DDD" isDefault="TRUE"/>
		<list id="111111" name="AAA" isDefault="FALSE"/>
		<list id="222222" name="BBB" isDefault="FALSE"/>
		<list id="333333" name="CCC" isDefault="FALSE"/>
	<lists>
	<watchlist id="444444" name="DDD" />
</watchlists>

POST /watchlists/symbols

Purpose:

Add symbol into default watchlist.

Variables:

    type    Three choices STOCK,OPTION,MUTUAL
    symbol
    quantity (Optional)
    cost-basis (Optional)
    commission (Optional)

Request:

POST /watchlists/symbols HTTP/1.1
Host: api.firstrade.com
Content-Length: 11

symbol=GOOG

Response:

<watchlists>
	<lists>
		<list id="222222" name="BBB" isDefault="TRUE"/>
		<list id="333333" name="CCC" isDefault="FALSE"/>
	<lists>
	<watchlist id="222222" name="BBB">
		<stocks total-value="409.20" day-gain-amount="-7.14" day-gain-percent="-1.71" overall-gain-amount="0.00" overall-gain-percent="0.00">
			<watch id="10001" symbol="IBM" quantity="2" last="191.15" change-amount="-3.41" change-percent="-1.75" day-gain-amount="-6.82" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
			<watch id="10002" symbol="C" quantity="1" last="26.90" change-amount="-0.32" change-percent="-1.18" day-gain-amount="-0.32" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
			<watch id="10005" symbol="GOOG" quantity="1" last="26.90" change-amount="-0.32" change-percent="-1.18" day-gain-amount="-0.32" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
		</stocks>
		<options total-value="168.00" day-gain-amount="-10.00" day-gain-percent="-5.62" overall-gain-amount="0.00" overall-gain-percent="0.00">
			<watch id="10003" symbol="MSFT120121C00024000" quantity="1" last="1.68" change-amount="-0.10" change-percent="-5.62" day-gain-amount="-10.00" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
			<watch id="10004" symbol="GOOG120121C00240000" quantity="0" last="315.90" change-amount="0" change-percent="0" day-gain-amount="0" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
		</options>
	</watchlist>
</watchlists>

DELETE /watchlists/symbols/:ID

Purpose:

Delete symbol from watchlist.

Request:

DELETE /watchlists/symbols/10002 HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<watchlists>
    <lists>
      <list id="222222" name="BBB" isDefault="TRUE"/>
      <list id="333333" name="CCC" isDefault="FALSE"/>
    <lists>
    <watchlist id="222222" name="BBB">
      <stocks total-value="409.20" day-gain-amount="-7.14" day-gain-percent="-1.71" overall-gain-amount="0.00" overall-gain-percent="0.00">
        <watch id="10001" symbol="IBM" quantity="2" last="191.15" change-amount="-3.41" change-percent="-1.75" day-gain-amount="-6.82" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
      </stocks>
      <options total-value="168.00" day-gain-amount="-10.00" day-gain-percent="-5.62" overall-gain-amount="0.00" overall-gain-percent="0.00">
        <watch id="10003" symbol="MSFT120121C00024000" quantity="1" last="1.68" change-amount="-0.10" change-percent="-5.62" day-gain-amount="-10.00" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
        <watch id="10004" symbol="GOOG120121C00240000" quantity="0" last="315.90" change-amount="0" change-percent="0" day-gain-amount="0" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
      </options>
    </watchlist>
</watchlists>

GET /watchlists/:id

Purpose:

Query watchlists.

Variables:

If the query does not include ListID variable, return all watchlist(listName, isDefault, id), return detailed information for default watchlist.
If the query includes ListID variable, return all watchlist(listName, isDefault, id), then return detailed information for the specified ListID set the watchlist as default.

Request:

GET /watchlists/111111 HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<watchlists>
	<lists>
		<list id="111111" name="AAA" isDefault="TRUE"/>
		<list id="222222" name="BBB" isDefault="FALSE"/>
		<list id="333333" name="CCC" isDefault="FALSE"/>
	<lists>
	<watchlist id="111111" name="AAA">
		<stocks total-value="409.20" day-gain-amount="-7.14" day-gain-percent="-1.71" overall-gain-amount="0.00" overall-gain-percent="0.00">
			<watch id="10001" symbol="IBM" quantity="2" last="191.15" change-amount="-3.41" change-percent="-1.75" day-gain-amount="-6.82" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
			<watch id="10002" symbol="C" quantity="1" last="26.90" change-amount="-0.32" change-percent="-1.18" day-gain-amount="-0.32" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
		</stocks>
		<options total-value="168.00" day-gain-amount="-10.00" day-gain-percent="-5.62" overall-gain-amount="0.00" overall-gain-percent="0.00">
			<watch id="10001" symbol="MSFT120121C00024000" quantity="1" last="1.68" change-amount="-0.10" change-percent="-5.62" day-gain-amount="-10.00" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
			<watch id="10001" symbol="GOOG120121C00240000" quantity="0" last="315.90" change-amount="0" change-percent="0" day-gain-amount="0" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
		</options>
		<mutual-fund total-value="23.56" day-gain-amount="0.44" day-gain-percent="-1.83" overall-gain-amount="0.00" overall-gain-percent="0.00">
			<watch id="10001" symbol="INTC" quantity="1" last="23.56" change-amount="-0.44" change-percent="-1.83" day-gain-amount="-0.44" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
		</mutual-fund>
	</watchlist>
</watchlists>

DELETE /watchlists/:ID

Purpose:

Delete watchlist. Then set the last accessed list as default.

Request:

DELETE /watchlists/111111 HTTP/1.1
Host: api.firstrade.com
Authorization: Bearer ei3im8cpmw5w506k5sfrs6tqm

Response:

<watchlists>
	<lists>
		<list id="222222" name="BBB" isDefault="TRUE"/>
		<list id="333333" name="CCC" isDefault="FALSE"/>
	<lists>
	<watchlist id="222222" name="BBB">
		<stocks total-value="409.20" day-gain-amount="-7.14" day-gain-percent="-1.71" overall-gain-amount="0.00" overall-gain-percent="0.00">
			<watch id="10001" symbol="IBM" quantity="2" last="191.15" change-amount="-3.41" change-percent="-1.75" day-gain-amount="-6.82" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
			<watch id="10002" symbol="C" quantity="1" last="26.90" change-amount="-0.32" change-percent="-1.18" day-gain-amount="-0.32" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
		</stocks>
		<options total-value="168.00" day-gain-amount="-10.00" day-gain-percent="-5.62" overall-gain-amount="0.00" overall-gain-percent="0.00">
			<watch id="10003" symbol="MSFT120121C00024000" quantity="1" last="1.68" change-amount="-0.10" change-percent="-5.62" day-gain-amount="-10.00" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
			<watch id="10004" symbol="GOOG120121C00240000" quantity="0" last="315.90" change-amount="0" change-percent="0" day-gain-amount="0" unit-cost="0" cost="0" gain-amount="0" gain-percent="0"/>
		</options>
	</watchlist>
</watchlists>