Advanced API FAQ

Possible status values for deposit/withdrawal transactions

Using the REST API funding endpoints, clients are able to deposit/withdraw funds to/from their Kraken account, and to request the real time status of a deposit/withdrawal transaction.

Deposits/withdrawals pass through several stages between the initial request and the transaction being completed, hence the funding endpoints will return a different status value depending upon when they are called.

Note that the status values originally came from pages 16/17 of the Internet Financial Exchange Protocol (IFEX) document, but the values have been modified slightly to be more suitable for crypto transactions (not all possible status values are used, for example).

Deposits

The possible status values for deposit transactions are as follows:

•
Settled = Deposit has been received but still needs additional confirmations on the blockchain.
•
Success = Deposit has achieved the required number of confirmations on the blockchain.
•
Failure = Deposit failed (for one or more of various reasons).

The following are some examples of how the above status values would appear in responses from the DepositStatus endpoint:

Settled status:{"error":[],"result":[{"method":"Dogecoin","aclass":"currency","asset":"XXDG","refid":"QSB7IFM-Q3LT3X-NVAOKE","txid":"92c908ea2ea819d678d67130e4d20b625a8f97f3cfff45f906dde8cef41a046a","info":"D7SLwMBPqfFMCZ8EJDMoVEePpZAFFegLt8","amount":"997.00000000","fee":"0.00000000","time":1611308478,"status":"Settled"}]}

Success status:{"error":[],"result":[{"method":"Dogecoin","aclass":"currency","asset":"XXDG","refid":"QSB7IFM-Q3LT3X-NVAOKE","txid":"92c908ea2ea819d678d67130e4d20b625a8f97f3cfff45f906tdde8cef41a046a","info":"D7SLwMBPqfFMCZ8EJDMoVEePpZAFFegLt8","amount":"997.00000000","fee":"0.00000000","time":1611308478,"status":"Success"}]}

Withdrawals

The possible status values for withdrawal transactions are as follows:

•
Initial = Withdrawal request has been received and is being checked for validity (any funding restrictions on the account, etc.).
•
Pending = Withdrawal is waiting to be processed by our funding gateway.
•
Settled = Withdrawal has been sent to the blockchain (at this point the blockchain transaction ID would become available).
•
Success = Withdrawal transaction has at least 1 confirmation on the blockchain.
•
On hold = Withdrawal has been held and has to be manually checked by our funding team.
•
Failure = Withdrawal failed (for one or more of various reasons).

The following are some examples of how the above status values would appear in responses from the WithdrawStatus endpoint:

Initial status:{"error":[],"result":[{"method":"Dogecoin","aclass":"currency","asset":"XXDG","refid":"ASBCMYC-F5ETQT-34NMWT","txid":null,"info":"DGNBPsa2GhhtZGEZo79uF3WN2bTxFxmc9y","amount":"98.00000000","fee":"2.00000000","time":1612782924,"status":"Initial"}]}

Pending status:{"error":[],"result":[{"method":"Dogecoin","aclass":"currency","asset":"XXDG","refid":"ASBCMYC-F5ETQT-34NMWT","txid":null,"info":"DGNBPsa2GhhtZGEZo79uF3WN2bTxFxmc9y","amount":"98.00000000","fee":"2.00000000","time":1612782924,"status":"Pending"}]}

Settled status:{"error":[],"result":[{"method":"Dogecoin","aclass":"currency","asset":"XXDG","refid":"ASBCMYC-F5ETQT-34NMWT","txid":"064536e901f2cbfa6e279aa7a87c700b64e0ce561bf6e266788c47496f75106c","info":"DGNBPsa2GhhtZGEZo79uF3WN2bTxFxmc9y","amount":"98.00000000","fee":"2.00000000","time":1612782924,"status":"Settled"}]}

Success status:{"error":[],"result":[{"method":"Dogecoin","aclass":"currency","asset":"XXDG","refid":"ASBCMYC-F5ETQT-34NMWT","txid":"064536e901f2cbfa6e279aa7a87c700b64e0ce561bf6e266788c47496f75106c","info":"DGNBPsa2GhhtZGEZo79uF3WN2bTxFxmc9y","amount":"98.00000000","fee":"2.00000000","time":1612782924,"status":"Success"}]}

Failure status:{"error":[],"result":[{"method":"Dogecoin","aclass":"currency","asset":"XXDG","refid":"ASBCMYC-F5ETQT-34NMWT","txid":null,"info":"DGNBPsa2GhhtZGEZo79uF3WN2bTxFxmc9y","amount":"98.00000000","fee":"2.00000000","time":1612782924,"status":"Failure","status-prop":"canceled"}]}

Additional information regarding deposits/withdrawals are available via our cash funding and crypto funding support pages.

How to retrieve historical time and sales (trading history) using the REST API Trades endpoint

The REST API OHLC endpoint only provides a limited amount of historical data, specifically 720 data points of the requested interval. For example, asking for OHLC data in 1 minute intervals will return the most recent 720 minutes (12 hours) of data.

For applications that require additional OHLC or tick data, it is possible to retrieve the entire trading history of our markets (the historical time and sales) via the REST API Trades endpoint. The OHLC for any time frame and any interval can then be created from the historical time and sales data.

The Trades endpoint takes an optional parameter named since, which specifies the starting date/time of the data. The since value is a UNIX timestamp at nanosecond resolution (a standard UNIX timestamp in seconds with 9 additional digits).

For example, a call to the Trades endpoint such as https://api.kraken.com/0/public/Trades?pair=xbtusd&since=1559347200000000000 would return the historical time and sales for XBT/USD from the 1st of June 2019 at 00:00:00 UTC:

{"error":[],"result":{"XXBTZUSD":[["8552.90000","0.03190270",1559347203.7998,"s","m",""],["8552.90000","0.03155529",1559347203.8086,"s","m",""],["8552.90000","0.00510797",1559347203.9664,"s","m",""],["8552.90000","0.09047336",1559347203.9789,"s","m",""],["8552.90000","0.00328738",1559347203.9847,"s","m",""],["8552.90000","0.00492152",1559347203.9897,"s","m",""],["8552.90000","0.00201848",1559347203.9937,"s","m",""],["8552.90000","0.11422068",1559347203.9993,"s","m",""],["8552.90000","0.00425858",1559347204.071,"s","m",""],["8552.90000","0.00427679",1559347204.0762,"s","m",""],["8552.90000","0.06381401",1559347204.1662,"s","m",""]

...

["8579.50000","0.05379597",1559350785.248,"s","l",""],["8579.50000","0.94620403",1559350785.2936,"s","l",""],["8578.10000","0.45529068",1559350785.297,"s","l",""]],"last":"1559350785297011117"}}

Subsequent calls to the Trades endpoint should replace the since parameter's value with the last parameter's value from the results of the previous call such as https://api.kraken.com/0/public/Trades?pair=xbtusd&since=1559350785297011117.

Using the special since value of 0 (zero) would return the historical time and sales from the beginning of the market (starting with the very first trade).

How to place, view, and cancel orders using a user reference

A user reference is a client provided order ID that can be used in place of the actual (API provided) order ID for some order management tasks (notably cancelling orders).

User references are implemented to be as flexible as possible, and can therefore be used in a variety of different ways, including:

•
as a unique ID (where each order has a different user reference),
•
to group related orders together (such as grouping orders with different leverage levels),
•
or as a backup ID in the event that the actual order ID is not known.

A user reference must be a numeric value between 1 and 2,147,483,647 (essentially any positive 32 bit number), and could therefore be implemented as a simple counter, as a random signed 32 bit value, or even as a timestamp in seconds (although this would fail after January 19th 2038 at 3:14:07 UTC).

Placing orders with a user reference

Orders can be placed with an attached user reference by calling the AddOrder endpoint and including the userref parameter with the user reference as the value:

$ ./krakenapi AddOrder pair=xdgusd type=buy ordertype=limit price=0.1 volume=50 userref=27649653

{"error":[],"result":{"descr":{"order":"buy 50.00000000 XDGUSD @ limit 0.1000000"},"txid":["OQJSXE-F5FOM-IXHVL4"]}}

Viewing orders that have a user reference

Orders that already have a user reference attached can be viewed by calling the Open/Closed/QueryOrders endpoints and including the userref parameter with the existing user reference as the value (in this case the user reference acts as a filter, displaying only the associated orders):

$ ./krakenapi OpenOrders userref=27649653

{"error":[],"result":{"open":{"OQJSXE-F5FOM-IXHVL4":{"refid":null,"userref":27649653,"status":"open","opentm":1629618802.9812,"starttm":0,"expiretm":0,"descr":{"pair":"XDGUSD","type":"buy","ordertype":"limit","price":"0.1000000","price2":"0","leverage":"none","order":"buy 50.00000000 XDGUSD @ limit 0.1000000","close":""},"vol":"50.00000000","vol_exec":"0.00000000","cost":"0.000000000","fee":"0.000000000","price":"0.000000000","stopprice":"0.000000000","limitprice":"0.000000000","misc":"","oflags":"fciq"}}}}

$ ./krakenapi ClosedOrders userref=38695724

{"error":[],"result":{"closed":{"O7YEFN-3V4RK-FBNSNM":{"refid":null,"userref":38695724,"status":"canceled","reason":"User requested","opentm":1629619539.3593,"closetm":1629619542.2246,"starttm":0,"expiretm":0,"descr":{"pair":"XBTUSD","type":"buy","ordertype":"limit","price":"25000.0","price2":"0","leverage":"none","order":"buy 0.00010000 XBTUSD @ limit 25000.0","close":""},"vol":"0.00010000","vol_exec":"0.00000000","cost":"0.00000","fee":"0.00000","price":"0.00000","stopprice":"0.00000","limitprice":"0.00000","misc":"","oflags":"fciq"}},"count":1}}

Cancelling orders that have a user reference

Orders that already have a user reference attached can be cancelled using the user reference by calling the CancelOrder endpoint and using the user reference as the txid value (in place of the order ID value):

$ ./krakenapi CancelOrder txid=16764529

{"error":[],"result":{"count":1}}

Note that all open orders with the same user reference would be cancelled, hence it is possible to make a single CancelOrder call to cancel multiple orders simultaneously (as indicated by the count value of 3 in the following response):

$ ./krakenapi CancelOrder txid=48695624

{"error":[],"result":{"count":3}}

Why am I getting a 403 error while using the Kraken API?

Does Kraken offer an API test environment?

Futures API

For our Futures REST and WebSocket APIs (futures.kraken.com) we offer a full test environment using the API URL demo-futures.kraken.com.

REST, WebSocket and FIX Test Environments

For our spot REST/WebSocket API and FIX API, we currently offer a testing environment for qualified clients. Accessing this environment requires an onboarding process that can be started by directly contacting the API team.

Testing our API Using the Validate Testing Parameter

When placing an order via the REST API AddOrder or WebSocket API addOrder endpoints, the validate input parameter can be used to simulate the order.

Calling AddOrder/addOrder with the validate parameter set to true (validate=1, validate=true, validate=anything, etc.) will cause the order details to be checked for errors, but the API response will never include an order ID (which would always be returned for a successful order without the validate parameter).

Example AddOrder call with the validate parameter (note the missing order ID):

Plaintext

$ ./krakenapi AddOrder pair=xdgusd type=buy ordertype=market volume=5000 validate=true{"error":[],"result":{"descr":{"order":"buy 5000.00000000 XDGUSD @ market"}}}

Small real orders and/or orders with extreme prices

For a comprehensive API test using the Validate Parameter, we recommend placing very small market orders (orders for the minimum order size), or limit orders that are priced far away from the current market price (placing a limit order to sell ETH/USD at $800 when the market price is $200, for example).

Testing using live orders allows your API code to interact with our API in real world conditions, hence every aspect of the test will be accurate (how your orders affect the order book, etc.).

Contact us directly