For information on changes for our US clients, please visit our Support Center article.

What is a nonce?

Introduction

A nonce is a number that uniquely identifies each call to the REST API private endpoints. A nonce is required for all authenticated calls to the Spot REST API, including the account management endpoints (such as Balance, QueryOrders, QueryLedgers, etc.), the funding/earn endpoints (DepositAddresses, DepositStatus, etc.), and the trading endpoints (AddOrderCancelOrder, etc.).
For Futures REST authentication, a nonce value is not required.

Implementation

A nonce is implemented as a counter that must be unique and must increase with each call to the API. For example, assuming a starting nonce value of 0, subsequent valid nonce values would be 1, 2, 3, 4, and so on.
While a simple counter such as the above would provide a valid nonce, a more effective method of generating valid nonce values is to use a UNIX timestamp in milliseconds (the number of milliseconds since the 1st of January 1970 at 00:00:00 UTC). Using a millisecond or higher resolution timestamp for the nonce guarantees that all of the requirements of a valid nonce are met (uniqueness and always increasing), and provides sufficient values for traders making rapid successive API calls (market makers, high frequency trading bots, etc.).

Example code

The following are some examples of how to generate valid millisecond resolution nonce values in different programming languages:
Python
api_nonce = str(int(time.time()*1000))
JavaScript
var api_nonce = Date.now().toString()
PHP
$api_nonce = explode(' ', microtime());
$api_nonce = $api_nonce[1].substr($api_nonce[0], 2, 3);

API keys and nonces

Each API key has its own separate nonce, and the nonce value is persistent, which means the most recently used nonce will remain unchanged even if an API key is not used for some time.
Note that it is not possible to reset the nonce for a specific API key. In the event that a nonce value becomes invalid (such as accidentally using a UNIX timestamp far into the future), the solution would be to delete the affected API key and generate a new API key, which would automatically have a new starting nonce value of 0 (zero).