API Keys

Sjakil edited this page Sep 22, 2017 · 4 revisions

Especially to new users, API keys can be confusing. This page is dedicated to explaining what they are and how to use them.

What are they?

A simple way of putting it would be to say that an API key is a login authorization to an account in a format which can easily and securely be used by machines. You can use APIs for all sorts of applications, but in our case it gives the gunbot access to make trades for you and allows the GUI to retrieve information like balances and trade history. All this, without needing your login information.

Key and secret

In order to ensure security, a connection to an API is usually made using a key and secret combination. Without going into further detail, this helps protects your account. It is similar to how bitcoin wallets use a public and private key. You can share your API key with other people, but you should never share your API secret. If you want to read more, you can check out: Public-key cryptography.

Nonces

A good API uses what are called nonces. These are arbitrary numbers which may only be used once. They introduce randomness to make sure that no API request can be made twice (using the same nonce). This usually results in a requirement of a higher nonce in each successive request to an API. This is the reason why you should always use different API keys for each application (i.e. gunbot and GUI). If you do not, it will probably result in an unusable API key for either application (i.e. unsolvable 422 error on poloniex). Read more on nonces here: Cryptographic nonce.

Permissions

Most APIs allow you to modify the things your API key can and cannot do. Because the API does not need your login authorization, it is important to consider which permssions to give each API key. The gunbot will require permission to read your account information as well as make trades. The GUI will only require permission to read your account information. The type of permissions you can set depend on the exchange you use. In most cases you should not allow withdrawals.

Licensing

Because an API key is connected to a single account, it can also be used to verify licenses for products like the GUI. The licensing for the gunbot and the GUI are completely separate for the time being. As stated before, it is best to use two different API keys for both applications. Also, there is no need to register the gunbot API key with me, or the GUI API key with Gunthar.

Example setup

Let's say you want to use the gunbot and the GUI together on Bittrex, these would be the steps to follow:

  1. Create two API keys (and secrets) in your exchange account
    • Remember to store your secrets somewhere safe
  2. Purchase a license for both products
  3. Register the appropriate key with both products
  4. Configure gunbot and GUI configuration
    • Configure gunbot configuration using the steps below
    • Configure GUI configuration using the steps below

Gunbot configuration

The gunbot configuration file you need to modify depends on the version of your gunbot. Please use the corresponding one.

Version 3.3.2 and below

  • If you don't use bittrex, please look for the correct setting (i.e. POLONIEX_KEY or KRAKEN_KEY).
  • Each pair has a configuration file of it's own, for example: 'bittrex-BTC_DASH-config.js'.
  • Edit every pair you want to use to reflect the code below.
  • In more recent versions it is possible to use the 'ALLPAIRS-params.js' file to set the API key for all pairs.
	"BITTREX_KEY": "aaaaabbbbbcccccdddddeeeee",
	"BITTREX_SECRET": "1111122222333334444455555",

Version 3.3.3 and above

  • There is only one configuration file, which is 'config.js'.
  • Edit it to reflect the code shown below.
	"exchanges": {
		"poloniex": {
			"key": "",
			"secret": ""
		},
		"kraken": {
			"key": "",
			"secret": ""
		},
		"bittrex": {
			"key": "aaaaabbbbbcccccdddddeeeee",
			"secret": "1111122222333334444455555"
		}
	},

GUI configuration

When you start the GUI for the first time, the initial configuration wizard will appear. You need to enter your GUI API key and secret there. After saving the configuration, the file "gui-config.json" will contain the code below. You can change it using the GUI or by hand at any time, but please restart the GUI after doing so.

Initial configuration wizard

Configuration

Editing "gui-config.json"

	"apiKeys": {
		"ui": {
			"key": "YOUR_GUI_LICENSE_KEY_SHOULD_BE_HERE"
		},
		"poloniex": {
			"key": "",
			"secret": ""
		},
		"kraken": {
			"key": "",
			"secret": ""
		},
		"bittrex": {
			"key": "fffffggggghhhhhiiiiijjjjj",
			"secret": "6666677777888889999900000"
		}
	},
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.