VALR Authentication: API Key Security and Best Practices (2026)

Authentication overview

VALR's API authentication framework is designed to provide secure and verifiable access to user accounts and trading functionalities. It primarily relies on a combination of API keys and cryptographic signatures to ensure that all requests originate from an authorized source and have not been tampered with in transit. This approach aligns with common industry practices for securing financial transaction APIs, where data integrity and sender authenticity are critical. The system requires developers to generate unique API keys and secrets, then use these credentials to construct a signed request for each API call.

The authentication process typically involves generating a unique signature for each request using a secret key, a timestamp, and the request payload. This signature is then included in the request headers along with the public API key. VALR's servers validate this signature upon receipt, ensuring that only authenticated and authorized requests are processed. This method is applicable across both VALR's REST API for traditional request-response interactions and its WebSocket API for real-time data streaming and trading, ensuring consistent security across all programmatic interfaces. More information on the specific parameters for signing requests is available in the VALR API documentation on authentication.

Supported authentication methods

VALR employs a robust API key and HMAC-SHA512 signing mechanism for all programmatic access. This method is a standard for securing sensitive API interactions, especially in financial contexts where non-repudiation and data integrity are paramount. HMAC (Hash-based Message Authentication Code) ensures that a message has not been altered and was sent by the legitimate sender possessing the secret key, as described in RFC 2104.

API Key with HMAC-SHA512 Signing

This is the exclusive authentication method for VALR's public and private APIs. It involves three core components:

1. API Key (Public Key): A unique identifier for your application, included in the request header. This key identifies the caller.
2. API Secret (Private Key): A confidential key used to generate the request signature. This key must be kept secure and never transmitted directly.
3. HMAC-SHA512 Signature: A cryptographic hash generated using your API Secret, the request method, URL path, query parameters, request body, and a timestamp. This signature proves the authenticity and integrity of the request.

When to use:

• All private API endpoints (e.g., placing orders, checking balances, managing accounts).
• Public API endpoints that require rate limit increases or specific account context.
• WebSocket API connections for authenticated streams (e.g., private order book, account updates).

The table below summarizes the primary authentication method:

Getting your credentials

To interact with the VALR API, you must first generate an API key and secret from your VALR account. This process is performed through the VALR web interface and involves a few steps to ensure secure credential generation and management.

1. Log in to your VALR Account: Navigate to the VALR website and log in with your credentials.
2. Access API Settings: Once logged in, go to the 'API Keys' section, typically found under your profile or security settings. The exact navigation may vary slightly but is generally accessible from the main account dashboard.
3. Generate New API Key: Click on the option to 'Create New API Key' or similar. You will be prompted to provide a label for your key, which helps in identifying its purpose later.
4. Set Permissions: Critically, you must configure the permissions for your new API key. VALR allows granular control over what an API key can do (e.g., read account information, place orders, withdraw funds). It is a best practice to grant only the minimum necessary permissions for the application the key will be used with. For instance, if your application only needs to read market data, do not enable trading or withdrawal permissions.
5. Record API Key and Secret: Upon creation, VALR will display your API Key and API Secret. The API Secret is shown only once and will not be retrievable again. You must copy both values immediately and store them in a secure location. If you lose your API Secret, you will need to revoke the key and generate a new one.
6. IP Whitelisting (Optional but Recommended): For enhanced security, VALR offers IP whitelisting. If your application will always originate from a static IP address, you can specify this IP or a range of IPs. This restricts API access to only those whitelisted addresses, preventing unauthorized access even if your API key is compromised.

Refer to the VALR documentation on generating API keys for the most current and detailed instructions, including any specific security prompts or multi-factor authentication requirements during key generation.

Authenticated request example

Authenticating a request to the VALR API involves generating an HMAC-SHA512 signature using your API Secret and incorporating it into the request headers. The following Python example demonstrates how to create an authenticated GET request to retrieve account balances.

import hmac
import hashlib
import time
import requests
import json

# Your VALR API credentials
API_KEY = "YOUR_VALR_API_KEY"
API_SECRET = "YOUR_VALR_API_SECRET".encode('utf-8') # Ensure secret is bytes

# API base URL
BASE_URL = "https://api.valr.com"

# Request details
METHOD = "GET"
PATH = "/v1/account/balances"
QUERY_PARAMS = ""
BODY = "{}" # Empty JSON body for GET requests

# Generate timestamp (milliseconds since epoch)
TIMESTAMP = str(int(time.time() * 1000))

# Construct the payload for signing
# The order of parameters in the payload string is critical
# Timestamp, HTTP Method, Path, Query Parameters, JSON Body
# Note: Query parameters should be the raw string, not URL-encoded.
# If there are query parameters, they should be appended after '?' to the PATH.
# Example: PATH = "/v1/marketdata/orderbook/BTCZAR?limit=10"
#          QUERY_PARAMS = "limit=10"

# For simplicity here, assuming no query params for /v1/account/balances
STRING_TO_SIGN = TIMESTAMP + METHOD + PATH + QUERY_PARAMS + BODY

# Create the HMAC SHA512 signature
hmac_signature = hmac.new(API_SECRET, STRING_TO_SIGN.encode('utf-8'), hashlib.sha512)
SIGNATURE = hmac_signature.hexdigest()

# Prepare headers
HEADERS = {
    "X-VALR-API-KEY": API_KEY,
    "X-VALR-SIGNATURE": SIGNATURE,
    "X-VALR-TIMESTAMP": TIMESTAMP,
    "Content-Type": "application/json"
}

# Make the request
response = requests.request(METHOD, BASE_URL + PATH, headers=HEADERS, data=BODY)

# Print response
print(f"Status Code: {response.status_code}")
print(f"Response Body: {json.dumps(response.json(), indent=2)}")

This example demonstrates the core components: a timestamp, the HTTP method, the request path, any query parameters, and the request body are concatenated into a string. This string is then signed using HMAC-SHA512 with your API secret. The resulting signature, along with your API key and timestamp, is sent in the request headers. Developers using VALR's official SDKs (Python, Node.js, Java) will find the signing process abstracted, simplifying integration.

Security best practices

Maintaining the security of your API credentials is paramount when interacting with financial platforms like VALR. Adhering to these best practices can significantly reduce the risk of unauthorized access and potential financial loss:

1. Secure Storage of API Secrets: Never hardcode API secrets directly into your application code. Store them in environment variables, secure configuration files, or a dedicated secret management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). Your API secret should never be committed to version control systems like Git.
2. Least Privilege Principle: When generating API keys in your VALR account, grant only the minimum necessary permissions required for your application's functionality. For instance, if your application only reads market data, do not enable trading or withdrawal permissions. This limits the damage if a key is compromised.
3. IP Whitelisting: If your application operates from a fixed set of IP addresses, always enable IP whitelisting for your API keys. This ensures that even if your API key and secret are stolen, they cannot be used from an unauthorized IP address.
4. Regular Key Rotation: Periodically rotate your API keys. This means generating a new key, updating your applications to use the new key, and then revoking the old key. The frequency depends on your security policy, but quarterly or semi-annually is a common practice.
5. Monitor API Usage: Regularly review your API usage logs and account activity for any unusual patterns or unauthorized access attempts. VALR typically provides tools or logs within your account settings to help monitor API activity.
6. Error Handling and Logging: Implement robust error handling in your applications. Avoid logging sensitive information like API keys or secrets directly in application logs, especially in production environments. Log only necessary information for debugging and monitoring.
7. Secure Development Practices: Follow general secure coding guidelines. Sanitize all inputs, validate outputs, and protect against common web vulnerabilities such as SQL injection, cross-site scripting (XSS), and cross-site request forgery (CSRF), especially if your API integration involves a web front-end.
8. Use Official SDKs: Whenever possible, use the official VALR SDKs (Python, Node.js, Java) as they typically abstract away the complexities of signature generation and incorporate best practices for secure API interaction. This reduces the chance of implementation errors that could lead to vulnerabilities.
9. Time Synchronization: Ensure that the system clock of the server running your API integration is accurately synchronized. Discrepancies between your system time and VALR's servers can lead to signature validation failures due to timestamp mismatches.

By implementing these practices, developers can create more secure and reliable applications that interact with the VALR API, protecting both their own and their users' assets.