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}}