Abstract
There are two ways into Whisky Invest Direct: the website for people and an XML API for trading robots. The XML API is not a core service, but it makes writing a trading robot much simpler.
This page describes the XML API and gives a robot writer enough to get started. It is not a full guide and says nothing about trading strategy.
Audience
This page is for programmers who know CGI, XML and HTTP requests and responses.
Disclaimer
The XML API is supplied as is, with no warranty or support. Whisky Invest Direct uses it too, so we have an interest in it being accurate and stable, but we make no guarantee of the stability of the API or the accuracy of the information it provides.
Trading carries a risk of financial loss. Automated trading carries many more risks, including the accuracy of information, the reliability of connections and the speed of system response. By using the XML API you accept all risks involved, including but not limited to financial loss for any reason.
We may charge or suspend clients whose robots break the terms of use, for example by using excessive system resources. Please poll the system within the rate limits, which allow one call at a time per account.
Overview
The API is served at legacy.whiskyinvestdirect.com (opens the Whisky Invest Direct website). It is not available at www.whiskyinvestdirect.com (opens the Whisky Invest Direct website), so point your robot at legacy.whiskyinvestdirect.com.
The API works like the website: you submit CGI parameters and the server responds, but in XML rather than HTML. A skilled programmer should find it straightforward to trade through it. Every page needed for trading, such as the market view, has an XML equivalent. Most other pages, such as statements and account settings, do not and must be used by hand.
Security
Login is a username and password with an optional, recommended memorable information check. Anything
sensitive or valuable is sent over a secure connection. Public information, such as the market view, can be
read without signing in. Our servers track your session with a cookie (JSESSIONID), so your robot must
handle cookies as a browser does or its login will keep being forgotten.
When you first request a secure page over HTTPS, you are sent to a username and password page at:
https://legacy.whiskyinvestdirect.com/secure/login.do
Submit its j_username and j_password parameters as an HTTP POST, form-encoded in the request body, to:
POST https://legacy.whiskyinvestdirect.com/secure/j_security_check
Content-Type: application/x-www-form-urlencoded
j_username=XXX&j_password=YYY
Sending credentials in the request body, as shown, is the more secure way to log in.
On success you are either logged in or shown the memorable information check, if it is turned on.
The memorable information check has no XML equivalent. To make it easier, your robot can read a meta tag in the head of the check page:
<meta name="X-Challenge" content="0,2,5" />
Three characters must be submitted correctly. CONTENT gives their positions, counting from zero. In the
example above the robot must submit the first, third and sixth characters of the memorable information as
response[0], response[1] and response[2].
For example, if the memorable information is ABCDEFGHI, submit this, again as a POST with the characters
in the request body:
POST https://legacy.whiskyinvestdirect.com/secure/second-login.do
Content-Type: application/x-www-form-urlencoded
response[0]=A&response[1]=C&response[2]=F
You can now use secure pages.
Requests
The XML API offers 7 services:
- view the market
- view balance
- place an order
- cancel an order
- view orders
- view a single order
- get the lower and upper recommended trading threshold
View market
URL: https://legacy.whiskyinvestdirect.com/secure/api/v2/view_market_xml.do
There is also a version that needs no login:
https://legacy.whiskyinvestdirect.com/view_market_xml.do
It is cached on the server, so it is less up to date than the logged-in version. Both show a market at most nine prices deep.
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://legacy.whiskyinvestdirect.com/secure/api/v2/view_balance_xml.do
| CGI parameter | Description | Example |
|---|---|---|
simple |
Whether to return a simple balance: your positions without pending settlement information. Almost no robot needs that extra information and it adds load to our servers, so we strongly advise 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://legacy.whiskyinvestdirect.com/secure/api/v2/place_order_xml.do
| CGI parameter | Description | Example |
|---|---|---|
actionIndicator |
B to buy (spirit with currency) or S to sell (spirit for currency). |
actionIndicator=S |
considerationCurrency |
The currency to trade, USD or GBP. Must match the account currency, usually set at sign-up and shown in your account settings. |
considerationCurrency=USD |
securityId |
The security id of the spirit to trade. For a full list of spirits and their ids, make a view market request with securityId left empty. |
securityId=SPIRIT000100 |
quantity |
The quantity to trade in LPA. | quantity=50 |
limit |
The limit price of the bid or offer, with no more than two decimal places. | limit=2.13 |
typeCode |
One of TIL_CANCEL (good until cancelled), TIL_TIME (good until a time), IMMEDIATE (execute immediately) or FILL_KILL (fill or kill). |
typeCode=TIL_TIME |
clientTransRef |
Your reference. Must be unique for the account. | clientTransRef=ABC12345 |
confirmed |
For robots, always true. |
confirmed=true |
goodUntil |
Blank unless typeCode is TIL_TIME, when it must be a UTC timestamp in the format yyyy-MM-dd%20HH:mm%20UTC. |
goodUntil=2017-06-02 09:15 |
Sample request:
https://legacy.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://legacy.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 robots, always 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://legacy.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: USD, GBP or blank for both. |
considerationCurrency=USD |
status |
Filters the orders returned: OPEN (all open orders), DEALT (all orders that have dealt), OPEN_DEALT (open and dealt), CLOSED (now closed), REJECTED (rejected) or blank for all. We strongly recommend robots use only OPEN, which is optimised for them. View other orders with view single order. |
status=OPEN |
fromDate |
Optional. Returns only orders that are not open and were placed after this date. If left out, it is 30 days ago. Does not apply to open orders. Format yyyymmdd. |
fromDate=20130921 |
toDate |
Optional. Returns only orders that are not open and were placed before this date. The most fromDate and toDate can be apart is 12 months. Does not apply to open orders. Format as above. |
toDate=20130925 |
page |
The response is paginated, starting at page zero. Use this to choose 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://legacy.whiskyinvestdirect.com/secure/api/v2/view_single_order_xml.do
| CGI parameter | Description | Example |
|---|---|---|
orderId |
The order id returned by place order. | orderId=1101 |
clientTransRef |
Optional. The reference you used when placing the order. | 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>
Get the lower and upper recommended trading threshold
URL: https://legacy.whiskyinvestdirect.com/recommended_limit_margin.json?securityId=${securityId}¤cy=${currency}
| CGI parameter | Description | Example |
|---|---|---|
securityId |
The id of the spirit to view. | SPIRIT000100 |
currency |
The currency to view, GBP or USD. Should match the account currency, usually set at sign-up and shown in your account settings. |
GBP |
Returns the spirit's current valuation (mid) and the highest and lowest limit prices an order can have (bandUpper and bandLower). bandUpperPercent and bandLowerPercent give each band as a percentage of mid. A band and its percentage are left out when that limit is switched off. The response is JSON only.
Sample response:
{
"mid": 3.6,
"bandUpper": 3.96,
"bandUpperPercent": 10.0,
"bandLower": 0.72,
"bandLowerPercent": 80.0
}
Status codes
The statusCode field on order responses is one of:
| Value | Description |
|---|---|
OPEN |
The order is open. |
DONE |
The order has closed. |
EXPIRED |
The order closed by expiring. |
CANCELLED |
The order was cancelled. |
KILLED |
The order was killed because it could not be filled. |
NOFUNDS |
Rejected for insufficient funds. |
BADLIMIT |
Rejected because the limit was too high or too low. |
NOT_ACCOUNT_CURRENCY |
Rejected because it was not in the account currency. |
QUEUED |
Queued, waiting to be processed. |
SECURITY_SUSPENDED |
The whisky line is suspended from trading. |
Rate limiting
To protect the performance of the site, some actions are limited to a maximum number per minute. If you go over the limit, the action is ignored and an error is returned with HTTP status code 429. The limit resets after a minute.
| Action | Maximum per minute |
|---|---|
| View market | 120 per IP address |
| View balance | 10 |
| Place order | 10 per whisky line |
| View orders | 30 |
| View single order | 60 per whisky line |
| All XML API calls together (market data and cancels not counted) | 400 |
Each client can run one XML API call at a time (market data and cancels not included). Further calls wait up to 5 seconds for their turn with up to 30 waiting. A call is also refused when 60 calls from all clients are already waiting on the server. A call that cannot wait gets HTTP status code 429 with a Retry-After header saying how many seconds to wait before trying again.
Where we reasonably believe one person runs several accounts, we add up their rates across those accounts.
We may change these limits without notice and suspend accounts that use excessive system resources, for example accounts that are regularly rate limited.