DMBCS Kraken API 1.0
********************

DMBCS Kraken API

Copyright © 2018  DM Bespoke Computer Solutions Ltd

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

     A copy of the license is also available from the Free Software Foundation Web site at http://www.gnu.org/licenses/fdl.html.

Introduction
************

Kraken
======

Kraken is a virtual currency exchange, which also handles fiat (real) currency amounts.  Subscribers to the service have an account with associated funds attached.  The web site (www.kraken.com) provides the user with an account overview (i.e. current balance), currency-pair exchange market status (history of prices and current order book), and the means to place entries on the order book; bids for a currency which can be immediately met with orders to sell the currency are automatically transacted, with the Kraken site taking a small and variable cut of the deal, the cut decreasing with intensifying trading activity.

Kraken also provide a stateless, web-based API by which all of the above actions can be undertaken programmatically.  This is fully open, and described at www.kraken.org/help/api.  The description is almost, but not quite, enough to fully specify the interaction protocol.  Kraken also provide pointers to implementations of client-side API libraries in various languages, and reference to these must be made in order to fully understand the working of the Kraken API (the official reference implementation is written in PHP).

Client-side implementations
===========================

Kraken provide pointers to two proven client library implementations that we are immediately interested in: a C implementation and a C++ one. Unfortunately the C++ implementation only provides the thinnest veneer around TCP sockets, requiring the application programmer to have knowledge of the low-level protocol in order to be able to compose correct strings which implement the protocol, which defeats the purpose somewhat.  The C library is more comprehensive, shadowing all the functions exposed by Krakenʼs API as C functions, although they return ASCII strings holding data in JSON format which needs further processing (we actually take this approach ourself; there are plenty of good JSON libraries available, and in many cases it will be most expedient to simply send the JSON strings to a web browser and let a Javascript program there perform the required onwards analysis).

The main purpose of the DMBCS implementation is to get the best of both worlds: to have the API-completeness of the C implementation and the resource-management and detail-hiding convenience and safety promised by the above C++ implementation, so that the user does not need to understand anything of the protocol themself (This is not 100% true: when specifying currency pairs the user has to produce the correct ASCII string, e.g. ``ZUSDXXBT'' for the US Dollar/Bitcoin order book.  We have taken this decision because it would be cumbersome to encapsulate all the different currencies, which in any case tend to change from time to time, especially as new crypto-currencies become available.).

‘DMBCS’?
========

This isnʼt a vanity or promotional project with any kind of commercial restriction, it is something that was needed and is being shared so that others can benefit from the effort that has been spent on the development, and hopefully improve upon it.

It is apparent from the above that many libraries exist to interact with the Kraken facility, and we would not want to preclude the use of any of them by the installation and use of our own.  We also need a way to refer to our own implementation specifically.  So we use ‘DMBCS’ to provide our distinguishing label: this is appended to the front of the package name, and all of the C++ code comes inside a namespace with this label.  These should be considered to be five random letters: okay, they are abbreviated from DM Bespoke Computer Solutions Ltd, the original authorʼs company, but the project is released as fully free, open source software (FOSS) which falls under the GNU GPLv3 license, so you should treat it as any other component in your free, open operating system (Please donʼt tell me you actually pay money for some inferior OS beyond the eyes of humble scrutineers).

Handling JSON returns
=====================

Returns are JSON strings.

We could have developed the library to the extent that these are fully broken out into structs, but we had no immediate need for this and think that it is actually easier to just use rapidjson which effectively provides the same thing without imposing processing overhead when it is not needed; a future version of this library may come with the requisite aparatus.

For now, either send the return strings to a web browser to be handled directly by ECMAScript (JavaScript), or, if it is required to handle them locally then we find that rapidjson (https://github.com/Tencent/rapidjson) is recommendable, though there are plenty of other open-source JSON parsers out there.

Installation of the library
***************************

You will require the git code management system.  At the terminal, type git clone https://rdmp.org/dmbcs/kraken-api.git dmbcs-kraken-api, and then you will have a newly created directory called dmbcs-kraken-api which contains the full source code for the program.  Type cd dmbcs-kraken-api to enter that directory.

The libraryʼs build configuration system is GNUʼs autotools.  You will need autoconf, automake, and libtool, and pkg-config.  At the terminal, type autoreconf --install; ./configure.

You may at this point see errors relating to lack of openssl, curl, curlpp packages.  You must address these issues in your operating system and perform a successful ./configure before you can proceed with the dmbcs-kraken-api build.

The libraryʼs build is undertaken by GNU make.  You will need the make package on your system (GNU make is probably not necessary, any modern incarnation of make will most likely suffice).  Type make && sudo make install to build and install the library in your system.  Note that the sudo command will require that you have sufficient privilege on your system, and you may have to type in your system password (for a local build not requiring such privilege, in a pinch, do ./configure --prefix=install-here && make install).

That should be it.  Try making and running the example program described below (Section 3).

Use example
***********

To get a summary of the current state of the market in Bitcoin—Dollar exchanges, write the following C++ code

     #include <dmbcs-kraken-api.h>
     #include <iostream>

     int main ()
     {
         auto  K  =  DMBCS::Kraken_API  {"<your-key>", "<your-secret>"};
         std::cout << K.ticker_info ("XXBTZUSD");
         return 0;
     }

Here, <your-key> and <your-secret> are strings which you get from your Kraken account management page (do EVERYTHING in your power to make sure nobody else sees these).  Strictly speaking, they are not necessary for the above example, but do allow you to make calls on the K object which interrogate and manipulate your own funds.

If this code is stored in a file called a.cc, compile it with a line like (this should be typed all on one line, without the back-slash)

     g++ -std=c++17 $( pkg-config --cflags --libs dmbcs-kraken-api) \
        a.cc -o kraken-api

and then you will have an executable file called kraken-api.  Run this and observe the result in your terminal (you should see a string containing JSON-formatted data).

If this doesnʼt work for you, you either havenʼt installed dmbcs-kraken-api properly yet (see instructions in Section 2 above), or you need to improve your operating system, or get a better one; this is as far as we hand-hold you here.

Detailed reference
******************

An important point of note.  Any code base which includes the dmbcs-kraken-api.h header file anywhere will have the libcurlpp library automatically initialized during start-up and finalized on termination of the application.  If you are using libcurlpp for your own endeavours, you will have to take care to ensure that start-up and shut-down happen in ways which are compatible with your own code.

Note that the dmbcs-kraken-api library itself requires no explicit global initialization or finalization.

The library is not thread safe; there are severe limits to the volume and regularity of data transfer through the Kraken API, and, given the turn-around times of the accesses, access to the library should be considered a strictly serial activity for which parallelism has no purpose.  If, however, delayed blocking behaviour is unsatisfactory for your application and you need to realize asynchronous communications channels with the Exchange, running the dmbcs-kraken-api entirely in a thread separate from the main one would be appropriate.

The DMBCS::Kraken_API object
============================

The library provides one single object called DMBCS::Kraken_API. This has a single initializing constructor (Plus a natural move constructor, and nothing else: as per the parallelization discussion above, it makes no sense to be able to make copies of the Kraken_API object as the whole protocol only allows one operation at a time to be in progress.), and then has one method for each function Kraken expose in their API.  Each of these functions returns the result as a string conveying data in JSON format, which may include an error code and message.

It would be folly to describe in detail the Kraken API itself here; we content ourselves with describing our functionsʼ detailed call signatures and trusting the user to be able to find detailed notes on Krakenʼs web site, https://www.kraken.com/help/api.

Construction
------------

DMBCS::Kraken_API::Kraken_API (std::string const &key, std::string const &secret)

This is the only way to create an initial API-wrapping object.  The key and secret must be obtained from the account management page at the Kraken web site (strictly speaking, they do not need to be valid for general exchange-state inquiries, only for personal account introspection and trading).

Example use:

       auto  K  =  DMBCS::Kraken_API {"my-key", "my-secret"};

provides an object K which is subsequently used to access the Kraken exchange, as per the further examples below.

Options
-------

template <typename T>   void  DMBCS::Kraken_API::set_opt  (Option const &opt, T const &val)

Many of the Kraken API functions allow for the specification of optional filters to control the amount and nature of information returned.  These are specified in the DMBCS library through the set_opt template method. The option selection is done through constants provided in Kraken_API: choose one of

             INFO, ACLASS, ASSET, TRADES, USERREF, START, END, OFS, CLOSE_TIME,
             DO_CALCS, PAIR, FEE_INFO, OFLAGS, START_TIME, EXPIRE_TIME, VALIDATE,
             LEVERAGE, TYPE, CLOSE_TYPE, CLOSE_PRICE_1, CLOSE_PRICE_2, INTERVAL,
             SINCE, COUNT

It is up to your application to provide an appropriate value for each option — this is one of the corners where the Kraken_API does not completely encapsulate the underlying protocol.

If it is necessary to subsequently unset an option, then a method

void  DMBCS::Kraken_API::clear_opt  (Option const  &opt)

is available.

See the description of the asset_info method in Section see asset_info below for an example of how to use these functions.

Public functions: global state of the exchange
----------------------------------------------

As mentioned above, these functions donʼt strictly need the userʼs key and secret strings.  They provide non-confidential information about the state of the whole exchange, rather than the state of a userʼs account with the exchange.

server_time
...........

std::string DMBCS::Kraken_API::server_time ()

This will return the current time as understood by the Kraken service.

Example:

       std::cout  <<  K.server_time ();

prints something like

     {"error":[],"result":{"unixtime":1525292746,"rfc1123":"Wed,  2 May 18
     20:25:46 +0000"}}

on the terminal.

asset_info
..........

std::string DMBCS::Kraken_API::asset_info ()

This will return meta-information about a set of assets.  The options INFO, ACLASS and ASSET influence the return from this function.

Example:

       K.set_opt  (K.ASSET,  "XBTC");
       std::cout  <<  K.asset_info ();

will print something like

     {"error":[],"result":{"XXBT":{"aclass":"currency","altname":"XBT","decima
     ls":10,"display_decimals":5}}}

on the terminal.  Note that it has corrected the spelling from ``XBTC''!

asset_pairs
...........

std::string DMBCS::Kraken_API::asset_pairs ()

This function returns a list of pairs of asset types which may be traded for each other on the exchange, along with meta-data describing the exchange process.

The options INFO and PAIR will affect the value returned from this function.

For example,

       K.set_opt  (K.PAIR, "XXBTZUSD");
       std::cout  <<  K.asset_pairs ();

will print something like

     {"error":[],"result":{"XXBTZUSD":{"altname":"XBTUSD","aclass_base":"curre
     ncy","base":"XXBT","aclass_quote":"currency","quote":"ZUSD","lot":"unit","pa
     ir_decimals":1,"lot_decimals":8,"lot_multiplier":1,"leverage_buy":[2,3,4,5],
     "leverage_sell":[2,3,4,5],"fees":[[0,0.26],[50000,0.24],[100000,0.22],[25000
     0,0.2],[500000,0.18],[1000000,0.16],[2500000,0.14],[5000000,0.12],[10000000,
     0.1]],"fees_maker":[[0,0.16],[50000,0.14],[100000,0.12],[250000,0.1],[500000
     ,0.08],[1000000,0.06],[2500000,0.04],[5000000,0.02],[10000000,0]],"fee_volum
     e_currency":"ZUSD","margin_call":80,"margin_stop":40}}}

on the command line.

ticker_info
...........

std::string DMBCS::Kraken_API::ticker_info (std::string const &pair)

Provide up to date information about the state of the market in a trading pair.

       std::cout << K.ticker_info ("XXBTZUSD");

will produce something like

     {"error":[],"result":{"XXBTZUSD":{"a":["7616.30000","1","1.000"],"b":["7
     610.10000","3","3.000"],"c":["7616.30000","0.00840000"],"v":["941.52501200"
     ,"2032.58702329"],"p":["7638.63864","7661.37306"],"t":[3099,6798],"l":["759
     6.00000","7596.00000"],"h":["7700.00000","7728.90000"],"o":"7679.40000"}}}

on the command line.  Briefly, the components of the result are: ask, bid, close, volume, weighted-volume, trades, low, high, and open, wherein the interval-dependent quantities refer to the last 24 hours.

ohlc_data
.........

std::string DMBCS::Kraken_API::ohlc_data (std::string const &pair)

The abbreviation ``ohlc'' stands for ``open, high, low, close,'' and this function will return a history of these values for a given interval.

The pair argument should specify a trading pair, such as "XXBTZUSD" for Bitcoin—Dollar trading.

The function is affected by the INTERVAL and SINCE options.

order_book
..........

std::string DMBCS::Kraken_API::order_book (std::string const &pair)

This function returns live details of current bidding and asking prices and the volumes being offered.

The pair argument should specify a trading pair code, such as "XXBTZUSD".

The function is affected by the COUNT option.

recent_trades
.............

std::string DMBCS::Kraken_API::recent_trades (std::string const &pair)

This function returns an up to date list of all recently concluded trades.

The pair argument should indicate a trading pair, such as "XXBTZUSD".

The function is affected by the SINCE option.

spread_data
...........

std::string DMBCS::Kraken_API::spread_data (std::string const &pair)

This function returns a history of instantaneous highest bid and lowest offer values for this trading pair on the exchange.

The pair argument should indicate a trading pair, such as "XXBTZUSD".

The function is affected by the SINCE option.

Private inquiry functions
-------------------------

These functions are for inquiring into the current state of the userʼs account.

account_balance
...............

std::string account_balance ()

This function returns a list of currencies and the amount of each Kraken is holding for you on account.

trade_balance
.............

std::string trade_balance ()

This function provides a snapshot of your current trading activities, expressing your current balance in terms of potential value in a given currency.

The currency may be set with the ASSET option.  The ACLASS option is also available, and may have some use in a future version of Krakenʼs API.

open_orders
...........

std::string open_orders ()

This function provides a very detailed description of the current state of all of your open orders, including the amount of fulfilment that has been completed and the conduct of on-going actions, such as close-out.

The function is affected by the TRADES and USERREF options.

closed_orders
.............

std::string closed_orders ()

Similarly to the open_orders function above, this function provides detailed information of your closed orders.  Note that a maximum of 50 records will be returned by this function; use the OFS option in repeat calls to get information on more items.

The options which affect this function are: TRADES, USERREF, START, END, OFS and CLOSETIME.

query_orders
............

std::string query_orders (std::string const &txid)

As the above two functions, but returns data specifically about a given set of orders, identified by their transaction ID.  The txid argument is a string containing a comma-separated list of transaction IDs.

The function is affected by the TRADES and USERREF options.

trades_history
..............

std::string trades_history ()

This returns very detailed information about your trading history.  A maximum of 50 records will be returned; use the OFS option in repeat calls to get more information.

Other options which affect the outcome from this function are: TYPE, TRADES, START, and END.

trades_info
...........

std::string trades_info (std::string const &txid)

Gets detailed information, as the method above, for a very specific set of trades you have completed in the past.  The txid argument is a string containing a comma-separated list of transaction IDs.

This function is affected by the TRADES option, which causes more information to be returned (the value given to the option is irrelevant).

open_positions
..............

std::string open_positions (std::string const &txid)

Get detailed information on specific open positions, optionally with calculation of expected profit/loss given the current conditions of the exchange.  The txid argument is a string containing a comma-separated list of transaction IDs.

This function is affected by the DOCALCS option (the actual value of this option is irrelevant).

ledgers_info
............

std::string ledgers_info ()

This is the method which allows you to get the definitive history (e.g., for tax purposes), of your activities on the Kraken exchange, including exact fees which have been charged to your account.  The method will only return 50 items at a time, so you will likely need to make multiple requests with different START, END and/or OFS option settings to get the full record.

The list of options which affect this function are: ACLASS, ASSET, TYPE, START, END and OFS.

query_ledgers
.............

std::string query_ledgers (std::string const &id)

As above, but return information about a specific set of ledger entries.  The id argument is a string containing a comma-separated list of ledger item IDs.

trade_volume
............

std::string trade_volume ()

This function returns information about actual and potential costs of trading based on the userʼs recent trading volume.

The function is affected by the PAIR and FEE_INFO options.

Trading functions
-----------------

The final two functions in the Kraken API are for actively submitting order instructions to the Kraken exchange.  Use these with extreme care, especially during the development phase of your application; it is too easy to accidentally lose a lot of money!

add_order
.........

std::string  DMBCS::Kraken_API::add_order (Order_Instruction const &instruction, Order_Type const &order, std::string const &asset, std::string const &volume, ...)

This is the single method available for adding an instruction to the Kraken engine to execute a trade order on your behalf.

The available instructions are: DMBCS::Kraken_API::BUY and DMBCS::Kraken_API::SELL.

The available order types, again in the DMBCS::Kraken_API namespace but shown without for brevity, are: MARKET, LIMIT, STOP_LOSS, TAKE_PROFIT, STOP_LOSS_PROFIT, STOP_LOSS_PROFIT_LIMIT, STOP_LOSS_LIMIT, TAKE_PROFIT_LIMIT, TRAILING_STOP, TRAILING_STOP_LIMIT, STOP_LOSS_AND_LIMIT, SETTLE_POSITION.

The asset argument must indicate the asset pair to trade.  For example, to buy Bitcoin for Dollars the asset should be "XXBTZUSD".

The volume argument must be the amount of the asset you are buying or selling.

If your order type is one of LIMIT, STOP_LOSS, TAKE_PROFIT, or TRAILING_STOP, then you must supply an extra argument which gives the price at which the action takes place.  If your order type is one of STOP_LOSS_PROFIT, STOP_LOSS_PROFIT_LIMIT, STOP_LOSS_LIMIT, TAKE_PROFIT_LIMIT, TRAILING_STOP_LIMIT, STOP_LOSS_AND_LIMIT, then you must supply two extra arguments to the method: a price_1 and a price_2 which give the limits at which primary and secondary actions take place.

Note that all the ‘numerical’ arguments are in fact strings.  These are sent to the Kraken exchange as-is, and thus must be in a form that can be parsed into bona-fide numbers.  It is done this way to guarantee no loss of precision due to such things as numerical rounding or truncating a floating-point value to an integer.

Further to the somewhat complicated arrangement of compulsory arguments given above, the method is influenced by the following options: LEVERAGE, OFLAGS, START_TIME, EXPIRE_TIME, USERREF, VALIDATE, CLOSE_TYPE, CLOSE_PRICE_1, and CLOSE_PRICE_2.

Please be very careful when composing complicated esoteric options: the Kraken engine itself has been known to be somewhat fragile with its interpretation of various combinations of options.  Donʼt make any assumptions, try things out in the Kraken web interface first, and guard against spending any amount of money which means anything to you until you are absolutely sure you understand everything.

cancel_order
............

std::string DMBCS::Kraken_API::cancel_order (std::string const &txid)

Cancel the order with the given transaction ID (txid).  Of course this only works on the part of an order which has not been fulfilled by the time the instruction manages to reach, and is acted upon by, the Kraken exchange engine.

Copying This Manual
*******************

     [file fdl.texi not included]