The WhiskyInvestDirect XML API

Abstract

There are two interfaces into the WhiskyInvestDirect system: The normal GUI interface for users and an XML interface for trading robots. While the XML interface is not considered a primary WhiskyInvestDirect service, it can be used to greatly simplify the development of trading robots.

This document describes the XML interface, giving a bot writer sufficient information to get started. It is not a comprehensive guide, nor does it give any information on trading strategies.

Audience

This document is aimed at programmers. In particularly, the reader should be familiar with CGI and the HTTP request/response protocol as well as XML file formats.

Disclaimer

The XML interface is supplied as is, with no warranty or support. WhiskyInvestDirect itself uses the interface, and for this reason has a vested interest in its accuracy and stability, however WhiskyInvestDirect makes no guarantees of the stability of the interface or the accuracy of the information it provides.

Trading involves risk of financial loss. Automated trading involves many additional risks including accuracy of information, reliability of connections, speed of system response, etc. By using the XML API you accept all risks involved, including, but not limited to financial loss for any reason.

WhiskyInvestDirect reserves the right to charge or suspend clients whose robots breach the Terms of Use — e.g. by using excessive system resources. Please poll the system within sensible limits.

Overview

The WhiskyInvestDirect API operates in a similar fashion to the normal GUI site. CGI parameters are submitted and a response is sent back from the server. The key difference is that the response is XML rather than HTML. As such, it should be relatively easy for a skilled programmer to interface with the system and trade by wire. All the GUI pages which are necessary for trading (e.g. the market viewer) have XML equivalents. Most auxiliary pages not necessary for trading (e.g. statements and account settings) have no XML equivalent and must be used manually.

Security

WhiskyInvestDirect uses an enhanced login protocol comprising of a normal username & password login together with an optional (but recommended) memorable information check. Any sensitive or valuable communications will be performed over this secure connection. Publicly available information, such as viewing the market, can be accessed using an unsecured HTTP connection. Please note that our webservers use a session cookie to track your login session (JSESSIONID). Your robot must treat cookies in a similar fashion to a normal browser, or your login will be continually forgotten.

On first requesting a secure page using an HTTPS client, the user or bot is temporarily diverted to a username/password screen at:

https://www.whiskyinvestdirect.com/secure/login.do

This screen's CGI parameters j_username j_password to be submitted to:

https://www.whiskyinvestdirect.com/secure/j_security_check?j_username=XXX&j_password=YYY

On success, the user is then either logged in or will be shown the memorable information check page if this security enhancement is enabled.

There is no XML equivalent of the memorable information check page. To simplify processing of this check, the bot can inspect a META tag in the html head section of the challenge, which appears as follows:

<meta name="X-Challenge" CONTENT="0,2,5"/>

Three characters must be correctly submitted to the server. The CONTENT attribute gives the position of these characters, zero-indexed. Thus in the example above the bot must submit the first, third and sixth memorable information characters as response[0], response[1] and response[2].

For example, if the memorable information is 'ABCDEFGHI' the correct submission will be:

https://www.whiskyinvestdirect.com/secure/second_login.do?response[0]=A&response[1]=C&response[2]=F

After successfully logging in the user can now access secure pages.

XML API requests

The XML API currently provides 6 services:

• View the market
• View balance
• Place an order
• Cancel an order
• View orders
• View single order

The interface for these is described below.

View market

URL: https://www.whiskyinvestdirect.com/secure/api/v2/view_market_xml.do

There is also a non-logged in version:

https://www.whiskyinvestdirect.com/view_market_xml.do

which is cached on the server and is not as up-to-date as the logged in version. For both versions there is a maximum market width of nine.

Sample response:

<envelope>
	<message type="MARKET_DEPTH_A" version="0.1">
		<market>
			<pitches>
				<pitch distillery="CAMERONBRIDGE" categoryName="GRAIN" barrelTypeCode="HHR" bondYear="2015" bondQuarter="Q3" securityId="SPIRIT000156" considerationCurrency="GBP" soldOut="false">
					<buyPrices>
						<price actionIndicator="B" quantity="1000" limit="2.42"/>
						<price actionIndicator="B" quantity="1000" limit="2.41"/>
						<price actionIndicator="B" quantity="4000" limit="2.4"/>
					</buyPrices>
					<sellPrices>
						<price actionIndicator="S" quantity="900" limit="2.58"/>
						<price actionIndicator="S" quantity="1000" limit="2.59"/>
						<price actionIndicator="S" quantity="4000" limit="2.6"/>
					</sellPrices>
				</pitch>
			</pitches>
		</market>
	</message>
</envelope>

View balance

URL: https://www.whiskyinvestdirect.com/secure/api/v2/view_balance_xml.do

CGI Parameter	Description	Example
simple	Specify whether to return a simple balance response, including client positions but without any pending settlement information. For the vast majority of bot users this extra information is not required and places extra load on our servers, It is strongly advised to pass simple=true.	simple=true

Sample response:

<envelope>
	<message type="CLIENT_BALANCE_A" version="0.2">
		<clientBalance>
			<clientPositions>
				<clientPosition securityId="GBP" available="895004.93" total="999959.26" classNarrative="CURRENCY" totalValuation="999959.26" valuationCurrency="GBP"/>
				<clientPosition securityId="SPIRIT000100" available="12" total="12" classNarrative="SPIRIT" totalValuation="43.2" valuationCurrency="GBP"/>
				<clientPosition securityId="SPIRIT000105" available="1" total="1" classNarrative="SPIRIT" totalValuation="2.65" valuationCurrency="GBP"/>
				<clientPosition securityId="USD" available="1005000" total="1005000" classNarrative="CURRENCY" totalValuation="643602" valuationCurrency="GBP"/>
			</clientPositions>
			<pendingSettlements></pendingSettlements>
		</clientBalance>
	</message>
</envelope>

Place order

URL: https://www.whiskyinvestdirect.com/secure/api/v2/place_order_xml.do

CGI Parameter	Description	Example
actionIndicator	One of B or S for buy (spirit with currency) or sell (spirit for currency).	actionIndicator=S
considerationCurrency	The currency to trade (USD or GBP). Must match the currency of the WhiskyInvestDirect account, usually set during registration. The account currency can be checked on the logged-in Settings page.	considerationCurrency=USD
securityId	The security ID of the spirit to trade. A full list of spirits alongside their security IDs can be got by doing a view market request with the securityId parameter left empty.	securityId=SPIRIT000100
quantity	The quantity to trade in LPA.	quantity=50
limit	The limit price for the bid or offer. Must have no more than two decimal places.	limit=2.13
typeCode	One of TIL_CANCEL (Good until cancelled), TIL_TIME (Good until time), IMMEDIATE (Execute immediate) or FILL_KILL (Fill or kill).	typeCode=TIL_TIME
clientTransRef	Your reference code. Must be unique for this account.	clientTransRef=ABC12345
confirmed	For bots, this value must always be true.	confirmed=true
goodUntil	Must be blank unless the typeCode is TIL_TIME, in which case it must be a timestamp in the format 'yyyy-MM-dd%20HH:mm%20UTC'. The time should be in UTC.	goodUntil=2017-06-02 09:15

Sample request:

https://www.whiskyinvestdirect.com/secure/api/v2/place_order_xml.do?actionIndicator=B&considerationCurrency=USD&securityId=SPIRIT000100&quantity=50&limit=3.5&typeCode=TIL_CANCEL&clientTransRef=sampleRef&confirmed=true

Sample response:

<envelope>
	<message type="PLACE_ORDER_A" version="0.1">
		<order
		orderId="1201" clientTransRef="sampleRef" actionIndicator="B" securityId="SPIRIT000100"
		considerationCurrency="USD" quantity="50" quantityMatched="0" totalConsideration="0"
		totalCommission="0" limit="3.5" typeCode="TIL_CANCEL" orderTime="2017-06-15 10:57:25 UTC"
		goodUntil="" lastModified="2017-06-15 10:57:25 UTC" statusCode="BADLIMIT"
		tradeType="ORDER_BOARD_TRADE"	orderValue="175"/>
	</message>
</envelope>

Cancel order

URL: https://www.whiskyinvestdirect.com/secure/api/v2/cancel_order_xml.do

CGI Parameter	Description	Example
orderId	The order ID returned by place_order.	orderId=12345
confirmed	For bots, this value must always be true.	confirmed=true

Sample response:

<envelope>
	<message type="SINGLE_ORDER_A" version="0.1">
		<order orderId="1102" clientTransRef="12-SEP-17B3CLIENT1" actionIndicator="B" securityId="SPIRIT000100"
		considerationCurrency="GBP" quantity="3" quantityMatched="0" totalConsideration="0"
		totalCommission="0" limit="3.6" typeCode="TIL_TIME" orderTime="2017-09-12 08:38:37 UTC"
		goodUntil="2017-09-12 08:38:37 UTC" lastModified="2017-09-12 08:38:37 UTC" statusCode="EXPIRED"
		tradeType="ORDER_BOARD_TRADE" orderValue="10.8"/>
		<cancellable/>
	</message>
</envelope>

View orders

URL: https://www.whiskyinvestdirect.com/secure/api/v2/view_orders_xml.do

CGI Parameter	Description	Example
securityId	The id of the spirit to view.	securityId=SPIRIT000100
considerationCurrency	The currency to view. May be USD, GBP, or blank for both.	considerationCurrency=USD
status	Filters the list of orders returned. One of OPEN (show all open orders), DEALT (show all orders that have dealt), OPEN_DEALT (open + dealt orders), CLOSED (orders that are now closed), REJECTED (orders that were rejected) or blank for all. It is strongly recommended that bot writers use only the OPEN status, as it is specially optimized for bot use. Other orders should be viewed with the view_single_order message.	status=OPEN
fromDate	Optional parameter to filter the non open orders, only returning those placed after the given date. If not provided, will be set to 30 days ago. Date parameters do not apply to open orders. It must be a date in the format yyyymmdd.	fromDate=20130921
toDate	Optional parameter to filter the non open orders, only returning those placed before the given date. Please note: The maximum difference between fromDate and toDate is 12 months. Date parameters do not apply to open orders. Format as above.	toDate=20130925
page	The response to view orders is paginated, starting at page zero. Use this parameter to select the page.	page=0

Sample response:

<envelope>
	<message type="ORDERS_A" version="0.4" page="0" pageSize="20">
		<orders clientId="REFEREE">
			<order orderId="1195" clientTransRef="1497522277643" actionIndicator="B" securityId="SPIRIT000118"
			considerationCurrency="GBP" quantity="1233" quantityMatched="0" totalConsideration="0" totalCommission="0"
			limit="1.2" typeCode="TIL_CANCEL" orderTime="2017-06-15 10:24:38 UTC" goodUntil=""
			lastModified="2017-06-15 10:24:38UTC" statusCode="OPEN" tradeType="ORDER_BOARD_TRADE" orderValue="1479.6"/>
			<order orderId="1184" clientTransRef="1497451421189" actionIndicator="B" securityId="SPIRIT000100"
			considerationCurrency="GBP" quantity="28571" quantityMatched="12" totalConsideration="42" totalCommission="0.74"
			limit="3.5" typeCode="TIL_CANCEL" orderTime="2017-06-14 14:43:44 UTC" goodUntil=""
			lastModified="2017-06-14 14:47:24 UTC" statusCode="OPEN" tradeType="ORDER_BOARD_TRADE" orderValue="99998.5"/>
		</orders>
	</message>
</envelope>

View single order

URL: https://www.whiskyinvestdirect.com/secure/api/v2/view_single_order_xml.do

CGI Parameter	Description	Example
orderId	The order ID returned by the place_order response.	orderId=1101
clientTransRef	The transaction reference used in the place_order request (optional).	clientTransRef=ABC12345

Sample response:

<envelope>
	<message type="SINGLE_ORDER_A" version="0.1">
		<order orderId="1101" clientTransRef="08-JUN-17B2CLIENT1" actionIndicator="B" securityId="SPIRIT000100"
		considerationCurrency="GBP" quantity="2" quantityMatched="0" totalConsideration="0"
		totalCommission="0" limit="3.6" typeCode="TIL_TIME" orderTime="2017-06-08 22:46:30 UTC"
		goodUntil="2017-07-08 22:46:30 UTC" lastModified="2017-06-08 22:46:30 UTC" statusCode="OPEN" tradeType="ORDER_BOARD_TRADE"
		orderValue="7.2"/>
		<cancellable>true</cancellable>
	</message>
</envelope>

Additional notes

The statusCode field for order responses has one of the following values:

Value	Description.
OPEN	Order is open.
DONE	Order has closed.
EXPIRED	Order closed by expiring.
CANCELLED	Order was cancelled.
KILLED	Order was killed because it could not be filled.
NOFUNDS	Order was rejected due to insufficient funds.
BADLIMIT	Order was rejected due to limit too high/low.
NOT_ACCOUNT_CURRENCY	Order was rejected because it was not in the account currency.
QUEUED	Order is queued awaiting processing.
SECURITY_SUSPENDED	Spirit line is suspended from trading.