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?
This issue may be related to Cloudflare:
https://support.cloudflare.com/hc/en-us/articles/200169226-Why-am-I-getting-a-403-error-
NOTE: Kraken has the "Browser Integrity Check" enabled.
This may occur if your request contains suspicious headers. For example, your request may be missing a user agent, or use a non-standard user agent; so please check your request headers.
If you're unable to create any standard requests that our system permits, send us a full copy of the request(s) that you're attempting, including your IP address and all headers. This information would allow us to investigate further.
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.).
TLS upgrade that might affect your API connections
For security reasons, we have recently dropped support for TLS 1.0 and 1.1. If you are encountering SSL/TLS connection error messages while trying to connect to our API, it is likely due to the use of one of these deprecated standards. You will need to modify your API client to force the use of TLS 1.2/1.3 or upgrade your version of .NET to 4.6 or above, which uses TLS 1.2/1.3 as standard.
REST API authentication calculator (Google Sheet)
The following Google Sheet can be used to calculate the REST API authentication signature for any combination of input data:
- •API private (secret) key
- •API endpoint (Balance, TradeBalance, QueryOrders, etc.)
- •Nonce value (see our what is a nonce support page for more details)
- •Endpoint input parameters (asset=doge, for example)
The calculator can be used to verify that the authentication algorithm has been correctly implemented, thereby avoiding potential issues (notably unexpected invalid key errors) later in the development cycle.
Usage instructions
- 1.Open the REST API authentication calculator in Chrome (or any other recent web browser)
- 2.Make a copy of the calculator to your own Google Drive via the File -> Make a copy menu (you will need to sign in to your Google account for this step)
- 3.Edit the API key, API endpoint, nonce value, and input data fields with your own API key and request details
- 4.Compare the calculated API authentication signature to the value calculated by your own API code (the two values must match exactly)
For security reasons, we recommend using the authentication calculator with a temporary API key, and then deleting the API key from your account once your authentication signature implementation is shown to be correct.
Example
Do I need to use a client library wrapper?
The primary benefit from using our client library wrappers is that you do not need to spend the time/effort to re-invent the wheel for creating API signatures, it's already done for you.
If you only intend to make calls to public methods, then you may choose to opt out of client libraries as no authentication is needed.
The list of available wrappers you can find here.