Authentication

Institution API keys

Your business creates institution API keys in VALR Business. Creating a key needs a team member with permission to manage API keys, and confirmation by email and two-factor authentication. When you create a key you choose:

• Bundles: what the key can do (permissions & bundles).
• Sub-accounts (optional): limit the key to specific sub-accounts. Without a limit, the key can act on your primary account and any sub-account.
• IP addresses (optional): only accept requests from these addresses or ranges.
• Endpoints (optional): only allow these endpoints.

The API key and secret are shown once. Keys don't expire; revoke a key in VALR Business when you no longer need it.

Keep the secret secret

Anyone with your API secret can sign requests as your business. Never send it in a request, commit it to source control or paste it into a web page.

Signing a request

Every request is signed with HMAC-SHA512, using your API secret as the key, over this string:

timestamp + METHOD + path + body + subAccountId

Part	Value
timestamp	Current time in Unix milliseconds; the same value you send in X-VALR-TIMESTAMP
METHOD	HTTP method in upper case, e.g. POST
path	Path including the query string, e.g. /v1/account/balances?excludeZeroBalances=true
body	The exact JSON string you send, or an empty string
subAccountId	The sub-account ID you send in X-VALR-SUB-ACCOUNT-ID, or an empty string

Send these headers:

Header	Value
X-VALR-API-KEY	Your API key
X-VALR-SIGNATURE	The signature, as lower-case hex
X-VALR-TIMESTAMP	The timestamp you signed
X-VALR-SUB-ACCOUNT-ID	Optional: act on this sub-account

Sign each request just before you send it: requests with an old timestamp are rejected, and each signature can only be used once. Every endpoint's code samples sign the request for you; set VALR_API_KEY and VALR_API_SECRET in your environment and run them.

Primary account and sub-accounts

Without X-VALR-SUB-ACCOUNT-ID, a request acts on your primary account. Some endpoints, such as payments and deposit references, only work on the primary account and with a key that isn't limited to sub-accounts. Those endpoints say so, and return 401 with code -93 otherwise.

Verify your implementation

	GET example	POST example
Secret	4961b74efac86b25cce8fbe4c9811c4c7a787b7a5996660afcc2e287ad864363	same
Timestamp	1558014486185	1558017528946
Method	GET	POST
Path	/v1/account/balances	/v1/orders/market
Body	(empty)	{"customerOrderId":"ORDER-000001","pair":"BTCUSDC","side":"BUY","quoteAmount":"80000"}
Signature	9d52c181ed69460b49307b7891f04658e938b21181173844b5018b2fe783a6d4c62b8e67a03de4d099e7437ebfabe12c56233b73c6a0cc0f7ae87e05f6289928	09f536e3dfdad58443f16010a97a0a21ad27486b7b8d6d4103170d885410ed77f037f1fa628474190d4f5c08ca12c1acc850901f1c2e75c6d906ec3b32b008d0