• C#
  • Java
  • VB
  • C++
  • Python
Contact us
Simple Syntax

Basic components of a Simple Syntax RTD formula are ProgID, Server, Ticker, Topic and Connection Parameters (optional):

=RTD(ProgID, Server, Ticker, Topic, ConnectionParams...)

where

  • ProgID = "Tws.TwsRtdServerCtrl"
  • Server = "" (empty string)

Ticker

Besides ProgID and Server, the first string should represent the Ticker in Simple Syntax.

To define a contract Ticker properly, you would need to find the correct contract attributes first. The easiest way to find contract attributes is to directly look at the Contract Description page in TWS.

The syntax for Ticker should strictly follow the below squence:

Forex Contract:

"CURRENCY1.CURRENCY2/CASH"

e.g. EUR.USD Forex can be defined as "EUR.USD/CASH"

Other Contract Types:

"SYMBOL@EXCHANGE/PRIMEXCH/SECTYPE/EXPIRATION/RIGHT/STRIKE/CURRENCY"

e.g. The E-mini futures can be defined as "ES@CME//FUT/202212///USD"

Notes:

  1. Not all contract attributes are required to be specified. You can leave the field to be blank to make that field un-specified. Sequencially, if you only need to specify several contract attributes at the begining part of the Ticker string, you can leave out the rest of the string entriely as well. For example, instead of specifying "SPY@SMART//////", "SPY@SMART" would be sufficient to define the contract properly.
  2. There are several default contract attributes in the Ticker string. If you leave them un-specified, they will take the default values as following:
    • EXCHANGE = "SMART"
    • SECTYPE = "STK"
    • CURRENCY = "USD"

For example, Ticker = "SPY" is the same as "SPY@SMART//STK////USD".

See more Syntax examples.

Topic

The second (or other strings) can be Topic. Topic string defines the tick type you would like to receive in the formula cell. Topic can be specified within the Ticker string, or as a separate string.

For exmaple, the two formulas below both request the Bid Size for SPY from ARCA exchange, where the first formula includes Topic in Ticker and the second formula specifies Topic as a separate string:

=RTD("Tws.TwsRtdServerCtrl",,"SPY@ARCA BidSize")

=RTD("Tws.TwsRtdServerCtrl",,"SPY@ARCA", "BidSize")

If no Topic string is defined, the Topic will be defaulted to "Last".

For example, the below formula will request the last price for SPY from ARCA exchange:

=RTD("Tws.TwsRtdServerCtrl",,"SPY@ARCA")

Basic Tick Types

The table below shows a full list of available basic tick types that can be specified for the Topic:

Tick NameTopic StringDescription
Bid Size"BidSize"Number of contracts (or lots) offered at the bid price.
Bid Price"Bid"Highest bid price for the contract.
Ask Price"Ask"Lowest offer price for the contract.
Ask Size"AskSize"Number of contracts (or lots) offered at the ask price.
Last Price"Last"Last price at which the contract traded.
Last Size"LastSize"Number of contracts or lots traded at the last price.
High"High"High price for the day.
Low"Low"Low price for the day.
Volume"Volume"Trading volume for the day for the selected contract (Volume for US Stocks are quoted in lots. The actual number of shares in volume can be calculated by multiplying 100).
Close Price"Close"The last available closing price for the previous day. For US Equities, we use corporate action processing to get the closing price, so the close price is adjusted to reflect forward and reverse splits and cash and stock dividends.
Open Price"Open"Today's opening price. The official opening price requires a market data subscription to the native exchange of a contract.
Last Exchange"LastExch"The exchange where the Last Price is provided from.
Bid Exchange"BidExch"The exchange where the Bid Price is provided from.
Ask Exchange"AskExch"The exchange where the Ask Price is provided from.
Last Timestamp"LastTime"Time of the last trade (in UNIX time).
Halted"Halted"Indicates if a contract is halted. See Halted
Bid Implied Volatility"BidImpliedVol"Implied volatility calculated from option bid prices.
Bid Delta"BidDelta"Delta calculated from the option bid prices.
Bid Option Price"BidOptPrice"Current bid price for the option contract.
Bid PV Dividend"BidPvDividend"The present value of dividends expected on the option's underlying.
Bid Gamma"BidGamma"The option gamma value calculated from the option bid prices.
Bid Vega"BidVega"The option vega value calculated from the option bid prices.
Bid Theta"BidTheta"The option theta value calculated from the option bid prices.
Bid Price of Underlying"BidUndPrice"The current bid price of the option underlying.
Ask Implied Volatility"AskImpliedVol"Implied volatility calculated from option ask prices.
Ask Delta"AskDelta"Delta calculated from the option ask prices.
Ask Option Price"AskOptPrice"Current ask price for the option contract.
Ask PV Dividend"AskPvDividend"The present value of dividends expected on the option's underlying.
Ask Gamma"AskGamma"The option gamma value calculated from the option ask prices.
Ask Vega"AskVega"The option vega value calculated from the option ask prices.
Ask Theta"AskTheta"The option theta value calculated from the option ask prices.
Ask Price of Underlying"AskUndPrice"The current ask price of the option underlying.
Last Implied Volatility"LastImpliedVol"Implied volatility calculated from option last prices.
Last Delta"LastDelta"Delta calculated from the option last prices.
Last Option Price"LastOptPrice"Current last price for the option contract.
Last PV Dividend"LastPvDividend"The present value of dividends expected on the option's underlying.
Last Gamma"LastGamma"The option gamma value calculated from the option last prices.
Last Vega"LastVega"The option vega value calculated from the option last prices.
Last Theta"LastTheta"The option theta value calculated from the option last prices.
Last Price of Underlying"LastUndPrice"The current last price of the option underlying.
Model Implied Volatility"ModelImpliedVol"Implied volatility calculated from option model prices.
Model Delta"ModelDelta"Delta calculated from the option model prices.
Model Option Price"ModelOptPrice"Current model price for the option contract.
Model PV Dividend"ModelPvDividend"The present value of dividends expected on the option's underlying.
Model Gamma"ModelGamma"The option gamma value calculated from the option model prices.
Model Vega"ModelVega"The option vega value calculated from the option model prices.
Model Theta"ModelTheta"The option theta value calculated from the option model prices.
Model Price of Underlying"ModelUndPrice"The current model price of the option underlying.

Note: If you do not have the corresponding Market Data Subscription, '0' will be displayed if you request for live tick types above. Please refer to Delayed Tick Types if you are interested.

API version 9.73.05 or higher is required to request option greeks data.

Generic Tick Types

A selection of Generic Tick Types are also supported in TWS RTD Server API. To request for any Generic Tick Type, you just need to specify the name of the generic tick type as the Topic string in the RTD formula.

For example, the below formula will request the 52-Week High price for SPY@SMART:

=RTD("Tws.TwsRtdServerCtrl",,"SPY@ARCA", "Week52Hi")

See table below for a full list of currently supported Generic Tick Types:

Generic Tick Type NameTopic StringDescriptionGeneric Tick Required
Auction Volume"AuctionVolume"The number of shares that would trade if no new orders were received and the auction were held now.225
Auction Imbalance"AuctionImbalance"The number of unmatched shares for the next auction; returns how many more shares are on one side of the auction than the other. 225
Auction Price"AuctionPrice"The price at which the auction would occur if no new orders were received and the auction were held now. The indicative price for the auction.225
Regulatory Imbalance"RegulatoryImbalance"The imbalance that is used to determine which at-the-open or at-the-close orders can be entered following the publishing of the regulatory imbalance.225
PL Price"PlPrice"The PL Price, also known as the Mark Price, is the current theoretical calculated value of an instrument. Since it is a calculated value, it will typically have many digits of precision.232
Creditmanager Mark Price"CreditmanMarkPrice"Not currently available.221
Creditmanager Slow Mark Price"CreditmanSlowMarkPrice"Slow Mark Price update used in system calculations (same as Mark Price update in TWS Account Window -> Portfolio).619
Call Option Volume"CallOptionVolume"Call option volume for the trading day.100
Put Option Volume"PutOptionVolume"Put option volume for the trading day.100
Call Option Open Interest"CallOptionOpenInterest"Call option open interest.101
Put Option Open Interest"PutOptionOpenInterest"Put option open interest.101
Option Historical Volatility"OptionHistoricalVol"The 30-day historical volatility (currently for stocks).104
RT Historical Volatility"RTHistoricalVol"30-day real time historical volatility (Futures only).411
Option Implied Volatility"OptionImpliedVol"A prediction of how volatile an underlying will be in the future. The IB 30-day volatility is the at-market volatility estimated for a maturity thirty calendar days forward of the current trading day, and is based on option prices from two consecutive expiration months.106
Index Future Premium"IndexFuturePremium"The number of points that the index is over the cash index (Indeses only).162
Shortable"Shortable"Describes the level of difficulty with which the contract can be sold short. See Shortable .236
Fundamental Ratios"Fundamentals"Provides the available Reuter's Fundamental Ratios. See fundamental_ratios_tags .258
Trade Count"TradeCount"Trade count for the day.293
Trade Rate"TradeRate"Trade count per minute.294
Volume Rate"VolumeRate"Volume per minute.295
Last RTH Trade"LastRthTrade"Last Regular Trading Hours traded price.318
IB Dividends"IBDividends"Contract's dividends. See IB Dividends .456
Bond Factor Multipler"BondMultiplier"Not currenctly available.460
Average Volume"AvgVolume"The average daily trading volume over 90 days (multiply this value times 100).165
High 13 Weeks"Week13Hi"Highest price for the last 13 weeks.165
Low 13 Weeks"Week13Lo"Lowest price for the last 13 weeks.165
High 26 Weeks"Week26Hi"Highest price for the last 26 weeks.165
Low 26 Weeks"Week26Lo"Lowest price for the last 26 weeks.165
High 52 Weeks"Week52Hi"Highest price for the last 52 weeks.165
Low 52 Weeks"Week52Lo"Lowest price for the last 52 weeks.165
Short-Term Volume 3 Minutes"ShortTermVolume3Min"The past three minutes volume. Interpolation may be applied.595
Short-Term Volume 5 Minutes"ShortTermVolume5Min"The past five minutes volume. Interpolation may be applied.595
Short-Term Volume 10 Minutes"ShortTermVolume10Min"The past ten minutes volume. Interpolation may be applied.595
Futures Open Interest"FuturesOpenInterest"Total number of outstanding futures contracts (TWS Build 965+ is required)588
Average Option Volume"AvgOptVolume"Average volume of the corresponding option contracts (TWS Build 970+ is required)105

By default, all Generic Tick Types are automatically requested. User just need to directly specify the Topic as the name of a generic tick type to populate the data to Excel.

In order to consume less data resource and make your market data request more efficient, you can directly specify the Generic Tick Type to be requested by defining string "genticks=id1,id2,...".

For example, to request 52-Week High price, only Generic Tick Type = 165 is required. The below formula will only request Generic Tick Type = 165:

=RTD("Tws.TwsRtdServerCtrl",,"SPY@SMART", "Week52Hi", "genticks=165")

Delayed Tick Types

When live streaming market data is not availale because of missing Market Data Subscription, delayed data will be automatically relayed back. To request delayed data via RTD, you need to specify delayed tick types for the Topic. The table below shows a full list of available delayed tick types:

Tick NameTopic StringDescription
Delayed Bid Size"DelayedBidSize"Number of contracts (or lots) offered at the bid price.
Delayed Bid Price"DelayedBid"Highest bid price for the contract.
Delayed Ask Price"DelayedAsk"Lowest offer price for the contract.
Delayed Ask Size"DelayedAskSize"Number of contracts (or lots) offered at the ask price.
Delayed Last Price"DelayedLast"Last price at which the contract traded.
Delayed Last Size"DelayedLastSize"Number of contracts or lots traded at the last price.
Delayed High"DelayedHigh"High price for the day.
Delayed Low"DelayedLow"Low price for the day.
Delayed Volume"DelayedVolume"Trading volume for the day for the selected contract (Volume for US Stocks are quoted in lots. The actual number of shares in volume can be calculated by multiplying 100).
Delayed Close Price"DelayedClose"The last available closing price for the previous day. For US Equities, we use corporate action processing to get the closing price, so the close price is adjusted to reflect forward and reverse splits and cash and stock dividends.
Delayed Open Price"DelayedOpen"Today's opening price. The official opening price requires a market data subscription to the native exchange of a contract.
Delayed Last Timestamp"DelayedLastTimestamp"Delayed time of the last trade (in UNIX time) (TWS Build 970+ is required).

For example, the below formula will request the delayed bid price for SPY from ARCA exchange:

=RTD("Tws.TwsRtdServerCtrl",,"SPY@ARCA", "DelayedBid")

Note: Delayed tick types are 15-minute delayed. Requesting for live tick types without market data subscription will result in error message "Requested market data is not subscribed. Displaying delayed market data..."

See more Syntax examples.

Connection Parameters

Since the TWS RTD Server API directly refers to the C# API Client, so it connects to TWS (or IB Gateway) the same as C# via the socket. The Host IP Address, Socket Port and Client ID are required parameters for initiating a socket connection.

  • The Host IP Address is the IP address where your TWS is running on. For a local connection, local IP 127.0.0.1 can be used.
  • The Socket Port is the port for socket connection. You can setup the host port in TWS API Settings, and you need to have your API connect to the same port as you setup in TWS.
  • The Client ID is an identification for each API connection. TWS can maintain up to 32 API Clients connecting at the same time, and the Client ID is used to distinguish each connection. This was originally designed so that API users can have multiple API programs (i.e. clients) running at the same using different strategies to trade separately. Since the TWS RTD Server API is only provided for relaying real-time data, there is no need to use multiple client IDs.

The above three parameters are defaulted to the following values if not directly specified by the user:

  • Host = "127.0.0.1" (i.e. the "localhost")
  • Port = "7496"
  • ClientID = Integer.MaxValue - 1

Simple Syntax supports several pre-defined Connection Parameters that can be specified as a separate string (i.e. String2, String3...) in the RTD formula:

  • "paper": use port=7497 for connection instead (7497 is the default port for paper TWS essions)
  • "gw": use port=4001 for connection instead (4001 is the default port for live IB Gateway sessions)
  • "gwpaper": use port=4002 for connection instead (4002 is the default port for paper IB Gateway sessions)

For example, to request High price for SPY@SMART while connecting to a TWS logged with a paper account via port 7497:

=RTD("Tws.TwsRtdServerCtrl",,"SPY@ARCA", "High", "paper")

Additional Info

See also: