Introduction
The aim of this document is to present and to explain the vocabulary and the grammar used by the BrokerHub API as well as the way to retrieve this information.
The goal is to be able to represent the three main elements of the platform : a quote request (Interest), a quote and a trade as well as the relationships that link those objects together.
In order to communicate between distant machines, BrokerHub has chosen to use the XML protocol. A DTD file is provided to specify the structure of the data. The first part of this document explains the DTD file. The DTD does not define any primitive data type. The primitive data types are therefore explicitly precised in this document according to the W3C Working Draft 07 April 2000 (http://www.w3.org/TR/xmlschema-2), except for the dateTime data type :
dateTime : DDD MMM DD hh:mm:ss CEST YYYY
ex : Thu Mar 29 16:46:29 CEST 2001 for Thusday the 29th of March 2001
The second part describes the connection to the BrokerHub API servers and the different ways to parse the retrieved data.
I - The document root
<!ELEMENT OTCxml (Interest*, Trade*)>
<!ATTLIST OTCxml
time CDATA #REQUIRED
warning CDATA #IMPLIED
error CDATA #IMPLIED
>
The BrokerHub api server returns some interests (with the linked quotes) and some trades depending on the request made on the server (see part II).
- time
- (dateTime) Gives the reference time and date of the BrokerHub server. It should be used to process properly the other times given in the document
- warning
- (string) gives a warning message if needed (for example, the version requested is not the last version provided by BrokerHub)
- url
- (url) Specifies the URL to be consulted to modify this interest. (Not yet used).
1 The quote request
<!ELEMENT Interest (Leg+, Bids?, Offers?, InterestDetails, User)>
<!ATTLIST Interest
id ID #REQUIRED
strategy CDATA #REQUIRED
strategyCode CDATA #REQUIRED
listed %booleanTrue;
time CDATA #REQUIRED
number CDATA #REQUIRED
changed CDATA #IMPLIED
cancelled %booleanFalse;
url CDATA #IMPLIED
>
The quote request structure depends on the strategy used. It is clear that you need more information to discribe a Condor than a single Put. But at the end a Condor is not more not less than a combination of several single options. So are all the option strategies we support.
Therefore, an option strategy is composed of a list of legs.
If this structure is quoted, it will contain "Bids" and "Offers"
The structure contains some information on the underlying stored in InterestDetails.
The User element gives information about the broker and the brokerage company that works the interest.
- id
- (string) Identifies uniquely an Interest over an unlimited period of time
- strategy
- (string) Identifies the strategy. We only support option strategies. (see list in appendix B)
- strategyCode
- (string) Identifies the strategy with a 3 letters code
- listed
- (boolean (TRUE/FALSE)) Tells if the structure is a listed lookalike (that can be physically exchanged over a regular exchange) or a custom OTC structure (that will be exchanged from backoffice to backoffice via a credit line).
- time
- (dateTime) Date and time when the interest was entered
- number
- (positiveInteger) Identifies the interests on a given day (in the order they were entered.)
- changed
- (dateTime) Date and time when the interest has been last changed
- cancelled
- (boolean (TRUE/FALSE)) Notifies if the interest is cancelled or still active.
1.1 The Trade
<!ELEMENT Trade (QuoteDetails, Price, TradeConfirmation?, DeltaDetails)>
<!ATTLIST Trade
id ID #REQUIRED
number CDATA #IMPLIED
time CDATA #REQUIRED
reference CDATA #IMPLIED
basis CDATA #IMPLIED
cancelled %booleanFalse;
>
A trade element contains information about the quote it was made on (QuoteDetails, Price),
and can contain some backoffice information (price and buy/sell detail per leg and some possible adjustments
on the delta, basis, reference, size, price ...) if it was confirmed by both counterparties.
This typically is populated wenn the trade was effectively crossed on the exchage or confirmed to the backoffice.
Since the delta is negotiable, the delta of the trade migth differ from the quote delta.
Therefore the negotiated delta is given by the DeltaDetails
- id
- (string) : id Identifies uniquely a Trade over an unlimited period of time
- number
- (positiveInteger) Identifies the Trade on a given year (in the order they were entered.)
- time
- (dateTime) : date and time of trading
- reference
- (double) : reference on which the trade was done
- basis
- (double) : if OTC index option : basis negotiated for the trade
- cancelled
- (boolean (TRUE/FALSE)) Notifies if the Trade is cancelled or valid.
2.1 The InterestDetails
<!ELEMENT InterestDetails (DeltaDetails?)>
<!ATTLIST InterestDetails
reference CDATA #IMPLIED
basis CDATA #IMPLIED
>
- reference
- (double): price of the underlying instrument that will be exchanged with the options.
- basis
- (double) : This parameter is unused the most of the time. It is only used for OTC (in %) option on index structures.
2.2 The legs
<!ELEMENT Leg (ProductInfo?, OptionInfo?, FutureInfo?)>
<!ATTLIST Leg
productId CDATA #IMPLIED
number CDATA #REQUIRED
multiplier CDATA #REQUIRED
over %booleanTrue;
>
A leg could be representing an option ("OptionInfo") or a future ("FutureInfo"). In any case the common information about the product are stored in "ProductInfo".
- productId
- (String) A product id can be provided in lieu of a ProductInfo element, in order to reduce the quantity of data sent.
- number
- (positiveInteger) implies an order within the legs. This should be used to link with any kind of data that is leg specific and not stored in the Leg element (the delta per leg for example)
- multiplier
- (positiveDouble) tells if the leg is bought (or sold) several times within the strategy. For example the butterfly has got a multiplier of two for the leg number 2 (the body) and one for the legs 1 and 3 (the wings)
- over
- (boolean (TRUE/FALSE)) over : This parameter is set only if the interest is quoted. It helps define if the leg must be bought or sold in case the strategy is bought with a positive price (true the leg must be bought, false the leg must be sold)
2.3 The Bids
<!ELEMENT Bids (Quote+)>
<!ATTLIST Bids
depth CDATA #IMPLIED
>
Contains a list of bid prices sorted from best to worst. The number of bid prices is given by the attribute depth (integer).
2.4 The Offers
<!ELEMENT Offers (Quote+)>
<!ATTLIST Offers
depth CDATA #IMPLIED
>
Contains a list of ask prices sorted from best to worst. The number of ask prices is given by the attribute depth (integer).
2.5 The TradeConfirmation
<!ELEMENT TradeConfirmation (LegConfirmation)+>
<!ATTLIST TradeConfirmation
tradeId CDATA #IMPLIED
strategy CDATA #REQUIRED
externalRef CDATA #IMPLIED
reference CDATA #REQUIRED
delta CDATA #REQUIRED
price CDATA #REQUIRED
premium CDATA #IMPLIED
basis CDATA #IMPLIED
listed %boolean;
size CDATA #REQUIRED
currency CDATA #REQUIRED
time CDATA #REQUIRED
settlement CDATA #IMPLIED
rcptName CDATA #REQUIRED
rcptAddress CDATA #REQUIRED
rcptCity CDATA #REQUIRED
rcptZipCode CDATA #REQUIRED
rcptCountry CDATA #REQUIRED
hiddenSeller %boolean;
hiddenBuyer %boolean;
sellerContact CDATA #IMPLIED
buyerContact CDATA #IMPLIED
delivery CDATA #REQUIRED
optionsDetailComment CDATA #IMPLIED
exchLookAlike %boolean;
>
The tradeConfirmation element stores the parameter values that where agreed by both counterparties. Most of the time those values will match with the values given by the QuoteDetails and the Price elements. But sometimes, the two counterparties can decide to change the delta or the reference or change from listed to OTC (OTC to listed).
The LegConfirmation elements give the detail of the confirmation per leg. As much LegConfirmations as Legs are expected.
- tradeID
- (ID) reference to the trade
-
- strategy
- (string) Identifies the strategy. We only support option strategies. (see list in appendix B)
- externalRef
- (string) trade confirmation identifier
- reference
- (double) Underlying price at which the trade was confirmed.
- delta
- (double) Delta agreed for the trade
- price
- (double) Price agreed for the trade
- premium
- (double) Price agreed for the trade when the interest is in Percent
- basis
- (double) Basis agreed for the trade (if a basis is needed : see 2.1)
- listed
- (boolean (TRUE/FALSE)) final way of exchanging the options (the interest could be listed, but the counterparties can choose to exchange it OTC. That would affect the size. The new size would be the old size times the multiplier given in 3.2).
- size
- (integer) Confirmed size of the trade.
- currency
- (string) currency in which the product is traded
- time
- (dateTime) Confirmation date and time.
- settlement
- (string) options settlement
- rcptName
- (string) name of the active user company.
- rcptAddress
- (string) address of the active trader's company.
- rcptCity
- (string) city of the active trader's company.
- rcptZipCode
- (string) zip code of the active trader's company.
- rcptCountry
- (string) country of the active trader's company.
- hiddenSeller
- (boolean) is the seller hidden to the buyer
- hiddenBuyer
- (boolean) is the buyer hidden to the seller
- sellerContact
- (string) seller contact's comment field
- buyerContact
- (string) buyer contact's comment field
- delivery
- (string) delivery type (physical/cash)
- optionsDetailComment
- (string) options detail comment
- exchLookAlike
- (boolean) is the interest exchange look alike
2.6 The User
<!ELEMENT User (Client)+>
<!ATTLIST User
type %userType;
username CDATA #REQUIRED
fullName CDATA #REQUIRED
phone CDATA #REQUIRED
fax CDATA #IMPLIED
email CDATA #REQIURED
>
The User element gives information about a user. It can be linked to many other elements. At the moment it is used to precise the broker (and brokerage house) linked to a given interest.
It comtains the element Client, giving information on the company this user belongs to.
- type
- (String) can be "BROKER" or "TRADER".
- fullName
- (String) first and last name
- username
- (String) username used to login on the system
- phone
- (String) phone number
- fax
- (String) fax number
- email
- (String) email address
3.1 The DeltaDetails
<!ELEMENT DeltaDetails (Delta)+>
<!ATTLIST DeltaDetails
total CDATA #IMPLIED
>
A DeltaDetails element gives the total delta as attribute (total (integer)) and gives the detail of delta per leg. Therefore a DeltaDetails must contain as many Delta entities as the strategy has Legs. (see Delta in 3.1)
3.2 The ProductInfo
<!ELEMENT ProductInfo EMPTY>
<!ATTLIST ProductInfo
id CDATA #REQUIRED
symbol CDATA #REQUIRED
name CDATA #REQUIRED
exchangeName CDATA #REQUIRED
sector CDATA #REQUIRED
RIC CDATA #REQUIRED
ISIN CDATA #IMPLIED
type %productType;
currency CDATA #REQUIRED
countryCode CDATA #REQUIRED
standardSize CDATA #REQUIRED
multiplier CDATA #REQUIRED
>
Gives the core (common) information on a product (option, future, equity).
- id
- (string) Identifies uniquely a product. This parameter can be used in the element leg to avoid passing a ProductInfo in the Leg.
- symbol
- (string) Exchange symbol of the product (ex : DTE for Deutsche Telekom AG options)
- name
- (string) Name of the product (ex : nokia)
- exchangeName
- (string) Name of the exchange (ex : EUREX)
- sector
- (string) Name of the sector of the underlying company. This field follows the nomenclature of the eurostock (see appendix A)
- RIC
- (string) Reuters code (ex : NOK1V.HE)
- ISIN
- (string) Isin Code
- type
- (FUTURE | INDEX | EQUITY) Type of the underlying product.
- currency
- (string) currency iso code of the product (ex : EUR, CHF, USD ...)
- countryCode
- (string) country iso code of the product (ex : FR, UK, IT ...)
- standardSize
- (integer) Listed quote requests can only be quoted with a quantity = i * standardSize (i being a positive integer).
- multiplier
- (double) amount of underlying products linked to the option contract.
3.3 The OptionInfo
<!ELEMENT OptionInfo EMPTY>
<!ATTLIST OptionInfo
call %booleanTrue;
strike CDATA #REQUIRED
maturity CDATA #REQUIRED
european %booleanTrue;
percent %booleanFalse;
>
Gives the additional information to ProductInfo for an option.
- call
- (boolean (TRUE/FALSE)) true if the option is a call option, false for a put option.
- strike
- (double) strike of the option
- maturity
- (dateTime) expiry date of the option
- european
- (boolean (TRUE/FALSE)) true if the option is of type european, false for american
- percent
- (boolean (TRUE/FALSE)) true if the option is defined in percent of the underlying (strike, bid and ask prices will be a percentage of the underlying reference defined in the InterestDetails), false otherwise (strike, bid and askprices are given in premium value)
3.4 The FutureInfo
<!ELEMENT FutureInfo EMPTY>
<!ATTLIST FutureInfo
maturity CDATA #REQUIRED
>
Gives the additional information to ProductInfo for a future.
- maturity
- (dateTime) expiry date of the future
3.5 The Quote
<!ELEMENT Quote (QuoteDetails, Price, DeltaDetails?)>
<!ATTLIST Quote
time CDATA #REQUIRED
expires CDATA #IMPLIED
basis CDATA #IMPLIED
>
- time
- (dateTime) time of creation
- expires
- (dateTime) if the quote has a time validity, this attribute tells wenn the quote expires. This date is dependent on the BrokerHub server date and time, but a reference of the actual date and time on the BrokerHub server is given in the root element of the document.
DeltaDetails indicates the delta chosen by the owner of the quote. The owner can choose to quote without delta, in which case the DeltaDetails is not populated.
- basis
- (double) the basis can be given with a given quote. The delta can be indicated as well (in the DeltaDetails element)
3.6 The LegConfirmation
<!ELEMENT LegConfirmation EMPTY>
<!ATTLIST LegConfirmation
buy %booleanTrue;
listed %booleanTrue;
number CDATA #REQUIRED
price CDATA #REQUIRED
blockTradeRef CDATA #IMPLIED
size CDATA
>
Gives the needed backoffice leg details once a trade is confirmed.
- buy
- (boolean (TRUE/FALSE)) true if the buyer of the structure needs to buy this leg, false else.
- listed
- (boolean (TRUE/FALSE)) true if this leg is Listed
- number
- (PositiveInteger) leg number corresponding to the LegConfirmation
- price
- (double) price of the leg
- blockTradeRef
- (String) if crossed on the exchange, reference given by the exchange system.
- size
- (integer) number of units
3.7 The Client
<!ELEMENT Client EMPTY>
<!ATTLIST Client
type %clientType;
name CDATA #REQUIRED
address CDATA #REQUIRED
zipCode CDATA #REQUIRED
city CDATA #REQUIRED
country CDATA #REQUIRED
vat CDATA #IMPLIED
>
Company Info.
- type
- (BROKERAGE/TRADING) type of the company
- name
- (String) name of the company
- address
- (String) address of the company
- zipCode
- (String) Zip Code of the company
- city
- (String) City of the company
- country
- (String) Country of the company
- vat
- (String) vat of the company
4.1 The Delta
<!ELEMENT Delta (#PCDATA)>
<!ATTLIST Delta
number CDATA #REQUIRED
>
Delta detail per leg (see 2.1)
- number
- (PositiveDouble) leg number corresponding to the given delta
4.2 The QuoteDetails
<!ELEMENT QuoteDetails EMPTY>
<!ATTLIST QuoteDetails
interestId CDATA #REQUIRED
confirmed %booleanTrue;
>
Enables to link a Quote to the corresponding interest and to decide if this Quote is confirmed or not by the owner of the Quote. If it is not confirmed, it can not be traded until it has been confirmed by telephon by the owner of the Quote.
- interestId
- (String) references the corresponding interest
- confirmed
- (boolean (TRUE/FALSE)) true if the quote is ferm, false if it is a phone quote (which, in case of trading should be confirmed by the owner
4.3 Price
<!ELEMENT Price (#PCDATA)>
<!ATTLIST Price
bid %boolean;
size CDATA #REQUIRED
underlyingTolerance CDATA #IMPLIED
>
Gives the price of the Quote
- bid
- (boolean (TRUE/FALSE)) true if the price is a bid, false for an offer
- size
- (integer) quantity linked to the price
- underlyingTolerance
- (positiveInteger) if defined, tolerance in percent of the underlying reference
II - Requesting and parsing data from the BrokerHub api server
1 Requesting data
The xml document can be retreived at any of the BrokerHub addresses (http://www.brokerhub.net, for production data or http://us1.brokerhub.net for test data), using the following url : [address]/api/market.jsp?[parameters].
The parameters are the following :
username : your BrokerHub username (mandatory)
password : your BrokerHub password (mandatory)
version : the version of the OTCxml feed wanted (actually 1.1). If the version is not supported any more, the field "error" is populated in the feed. If the version is supported, but not the last one, the field "warning" will be populated.(mandatory)
since : a valid date and time. If this parameter is not provided, the server will return everything from the BrokerHub markets and trades. If it is provided, the server will only return the markets and trades that came (or changed) since this time (optional).
filter : if true, then will filter the returned interests according to the user's tracker
Any combination of the optional parameters is possible. For example if since and interest are provided, the server will return every change done on the given "interest" since the "since" time.
Request Example : http://www.brokerhub.net/api/market.jsp?username=username&password=pwd&&version=1.1since=Thu+Mar+29+15:34:38+CEST+2001
2 Parsing data
There are a lot of free reliable xml parsers written in many different programming langages. We recommand using one of those.
For the programming langage java, our example uses xerces :
http://xml.apache.org/xerces-j/
Appendix A
| "31" | "Aerospace & Military Tech." |
| "41" | "Appliances & Households" |
| "42" | "Automobiles" |
| "61" | "Banking" |
| "43" | "Beverage & Tobacco" |
| "51" | "Broadcasting & Publishing" |
| "21" | "Building Materials & Comp" |
| "52" | "Business & Public Services" |
| "22" | "Chemicals" |
| "32" | "Construction & Housing" |
| "33" | "Data Processing & Reprod." |
| "34" | "Electricals & Electronics" |
| "35" | "Electronic Comp. & Services" |
| "36" | "Energy Equip & Services" |
| "11" | "Energy Sources" |
| "62" | "Financial Services" |
| "44" | "Food & Households" |
| "23" | "Forest Products & Paper" |
| "81" | "Gold Mines" |
| "45" | "Health & Personal Care" |
| "37" | "Industrial Components" |
| "63" | "Insurance" |
| "53" | "Leisure & Tourism" |
| "38" | "Machinery & Engineering" |
| "54" | "Merchandising" |
| "24" | "Metals-Non Ferrous" |
| "25" | "Metals-Steel" |
| "26" | "Misc. Materials & Comm." |
| "71" | "Multi-Industry" |
| "64" | "Real Estate" |
| "46" | "Recreation & Other Con. Goods" |
| "55" | "Telecommunications" |
| "47" | "Textiles & Apparel" |
| "56" | "Transportation-Airlines" |
| "57" | "Transportation-Road & Rail" |
| "58" | "Transportation-Shipping" |
| "12" | "Utilities-Electrical & Gas" |
| "59" | "Wholesale & Int. Trade" |
| "idx" | "Index" |
Appendix B
Table 1 (calculation of price and delta in absolut value, according to the prices and deltas of each leg) :
P[i] = price for leg i
| Strategy | Price | Strategy Code |
| Box | |P1+P4-P2-P3| | BOX |
| Calendar | |P1-P2| | CAL |
| Call/Put | |P1| | OPT |
| Christmas Tree | |P1-P2-P3| | CHR |
| Condor | |P1-P2-P3+P4| | CON |
| Conversion | |P1-P2| | COV |
| Butterfly | |P1-2*P2+P3| | FLY |
| Iron Butterfly | |P1-P2-P3+P4| | ILY |
| Ladder | |P1-P2| | LAD |
| Risk reversal | |P1-P2| | RSK |
| Ratio RR 1:n | |P1-n*P2| | RSK |
| Spread | |P1-P2| | SPR |
| Ratio Spread 1:n | |P1-n*P2| | SPRR |
| Roll | |P1+P4-P2-P3| | ROL |
| Straddle | |P1+P2| | STR |
| Straddle Swap | |P1+P2-P3-P4| | SSP |
| Strangle | |P1+P2| | SGL |
| Strangle Swap | |P1+P2-P3-P4| | SNP |
| Skinny Fly | |P1-P2-P1| | SLY |
| 
