Barchart Market Data Solutions » Streaming API » Protocol

Streaming Protocol (JERQ Middleware Protocol)

The JERQ Middleware server is used as a gateway to receive ddf data.

Java

Introduction

Overview

Protocol

Specifications for JERQ Middleware Server

The JERQ Middleware server is used as a gateway to receive ddf data. The Middleware Server performs the following functions:

Authenticate and Authorize Users
Relay ddf data

There are two general types of requests that JERQ handles:

Requests for a symbol or a list of symbols. This is generally used by client applications servicing the needs of a individual, e.g. a quoteboard, chart, etc. In this mode, JERQ filters the ddf broadcast feed for the symbols requested. Further, since this method is meant for individual clients, and because the list of symbols is finite, JERQ provides a refresh message at the start of the transmission that updates all relevant data fields.
Requests for an exchange, or a list of exchanges. This is used by redistributors and others who need the full data feed. This type of request also mimics the push data method.

Streaming Protocol

There is an authentication and startup protocol that your system must use in order to log into the quote stream. The important aspects of the authentication protocol are outlined here. You can always test this system using a telnet application.

All messages are terminated with a line feed ( ). On some systems (such as UNIX), the implies a carriage return, whereas on Microsoft systems (DOS, Windows), the line feed does not imply a carriage return. Check your programming language for specifics.

When you connect to the JERQ server, it will send an informational message. This header will be terminated with three (3) consecutive "+" characters (Ascii 43 (0x2B)).

All further informational messages will start with a "+".

Special Note: This protocol dictates that you ignore all messages that you do not understand. Do not try to process messages with invalid codes. This allows for revisions to the protocol with backwards compatibility.

Step 1: Determine the Server

Before you connect to the ddfplus server, you need to know which server to connect to. There is a single, hard-coded url you should use for this:

http://www.ddfplus.com/getusersettings.php?username=<username>&password=<password>

The document returned looks something like this:

<usersettings>
<login username="[username]" status="ok" credentials="ok">
<service id="[service]" maxsymbols="250"/>
<exchanges ids="MD,AMEX,CBOT,CBOTM,CFE,CME,GBLX,IMM,IOM,COMEX,CXMI,COMX,DME,DOWC,FOREX,ICE,ICEUS,ICEFI,INDEX,INDEX-DOW,INDEX-CFE,INDEX-SP,KCBT,MGEX,NTDS,OTCBB,FUND,NYMEX,NYMI,NYSE,INDEX-DOW,INDEX-CFE,WPG,MOBI,NliF "/>
</login>
<servers>
<server type="stream" primary="qs02.aws.ddfplus.com" secondary="qs01.aws.ddfplus.com" recovery="qs02.aws.ddfplus.com"/>
<server type="historical" primary="http://datasrv.ddfplus.com/isv/data.htx" maxrecords="14000"/>
<server type="historicalv2" primary="http://ds01.ddfplus.com/historical/" secondary="http://ds01.ddfplus.com/historical/"/>
<server type="extras" primary="http://extras.ddfplus.com"/>
<server type="news" primary="news.barchart.com:6397"/>
</servers>
</usersettings>

This document tells you which services, exchanges, and permissions the user has set, as well as which servers to connect to. The only server that you are interested in for this part of your application is the streaming server. So, enumerate the servers, type="stream", and the primary server. This has been highlighted in the document. This is the server that you should connect to.

Step 2: Connecting and Logging in

When you establish a connection to a jerq server (you can try this from a DOS or UNIX shell window by typing in: telnet <ddfplus server> 7500), you will see the following welcome message:

Welcome to the Jerq Server
Connected to Streaming Quotes (using JERQP)
+++

The command to login is LOGIN <username>:<password>. So if your username is "tom" and your password is "collins", you login with LOGIN tom:collins. Remember that all JERQ commands end with a cr/lf.

To logoff, issue the command LOGOFF

Step 3: Requesting data

Right after logging in, set the version of the protocol to 4 with the command: VERSION 4

The data request for symbols is essentially a comma separated list of symbols, with requesters at the end of each one. The format is: symbol=[list of commands]

The command options are:

s - request a snapshot/refresh quote
S - request quote stream
b - request a refresh of the book (market depth)
B - request a stream of the book

So, to start up quote stream for IBM, with initial refresh, you would use IBM=Ss. If you also want the book data for ESH1, the full command is: GO IBM=Ss,ESH1=SsBb

If you want to stop the ESH1 book stream at this point, and keep the IBM quote stream and the ESH1 quote stream, issue the command: STOP ESH1=B

The initial refresh of data returns a quasi-xml result set, similar to the xml query/response set, except that you only get the <QUOTE ......> ...... </QUOTE> part of the text.

Since version 4 streams both delayed and realtime data, the only way to tell which symbol is which, is by the mode="char" parameter. The parameters are:

R - Realtime
S - Realtime Snapshot
I - Intraday Delayed
D - End of Day

The quote stream messages are regular ddfplus messages. Please consult the ddfplus Feed Specs for more information.

If you have an institutional data account, to subscribe to all symbols on an exchange you can send the following command:

STR L <code>;

Where <code> is the exchange code. Note that the trailing semicolon is required.