- Frequently Asked Questions
- FAQs : Why WhiskyInvestDirect?
- FAQs : Safety
- FAQs : Storage
- FAQs : Operational
- FAQs : About Us
- FAQs : Governance
- FAQs : Robots
- How to do it
- Fund my account
- View our tariff
- Buy whisky
- Validate my account
- Submit a document
- Sell my whisky
- Withdraw funds
- Use the order panel
- Monitor my orders
- Cancelling my order
- Modify account settings
- Modify my limit price
- See my trading history
- Prove my money is safe
- Cask lists and client bank statement
- Understand my statement
- In case of death
- Close my account
- Contact WhiskyInvestDirect
- Make a complaint
- Whitelist our emails
- Become a referrer
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.
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.
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 use excessive system resources. Please poll the system within sensible limits.
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.
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:
This screen's CGI parameters j_username j_password to be submitted to:
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, response and response.
For example, if the memorable information is 'ABCDEFGHI' the correct submission will be:
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.
There is also a non-logged in version:
which is cached on the server and is not as up-to-date as the logged in version.
<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"> <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>
|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|
<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>
|actionIndicator||One of B or S for buy (spirit with currency) or sell (spirit for currency).||actionIndicator=S|
|considerationCurrency||The currency to trade. Must be USD or GBP.||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|
<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>
|orderId||The order ID returned by place_order.||orderId=12345|
|confirmed||For bots, this value must always be true.||confirmed=true|
|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|
<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
|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|
<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>
The statusCode field for order responses has one of the following values:
|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.|
|QUEUED||Order is queued awaiting processing.|