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}&currency=${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.