Getting started overview

VALR provides a cryptocurrency exchange platform accessible via both a web interface and programmatic APIs. The VALR API supports both REST and WebSocket protocols, enabling developers to integrate trading, account management, and market data functionalities into custom applications. This guide outlines the process of setting up a VALR account, generating API credentials, and making an initial API call.

The VALR API documentation provides comprehensive details on available endpoints, data structures, and authentication methods. The platform is designed for a range of users, from individual traders to institutions requiring high-frequency trading capabilities. VALR's API is suitable for automating trading strategies, integrating market data into analytical tools, and managing crypto assets programmatically.

Before making API requests, users must complete the account creation and verification process, which is standard practice for regulated financial platforms. Once verified, API keys can be generated from the account settings, providing the necessary credentials for secure access. VALR offers official SDKs in Python, Node.js, and Java to facilitate integration, alongside extensive documentation for direct API calls.

This getting started guide focuses on the essential steps required to transition from a new user to making a successful authenticated API request. It covers account setup, API key generation, and a basic example of an authenticated request using common development tools. For detailed information on specific endpoints or advanced features, refer to the official VALR API documentation.

Getting started quick reference

Step What to Do Where
1. Create Account Register on the VALR platform. VALR homepage
2. Complete KYC/AML Submit required identity verification documents. VALR account settings (post-registration)
3. Enable 2FA Set up Two-Factor Authentication for security. VALR security settings
4. Generate API Keys Create an API key and secret pair. VALR API Keys page
5. Install Tools Set up cURL, Postman, or a preferred SDK. Local development environment
6. Make First Request Execute a simple authenticated API call. Code editor/terminal

Create an account and get keys

Accessing the VALR API requires an active and verified VALR account. The process involves registration, identity verification (Know Your Customer/Anti-Money Laundering, KYC/AML), and then generating API keys.

Account registration and verification

  1. Register a VALR Account: Navigate to the VALR website and click 'Sign Up'. Provide the requested personal information, including email address and password.
  2. Verify Email: A verification link will be sent to the registered email address. Click this link to confirm your email and activate your account.
  3. Complete Identity Verification (KYC/AML): VALR, as an FSCA regulated entity in South Africa, requires users to complete identity verification. This typically involves submitting personal identification documents (e.g., ID card, passport) and proof of residence. The specific requirements are detailed within the VALR platform during the verification process. This step is mandatory before full access, including API key generation, is granted.
  4. Enable Two-Factor Authentication (2FA): For enhanced account security, enable 2FA using an authenticator app (e.g., Google Authenticator) or SMS. This is a critical security measure recommended by VALR and other financial platforms to protect user accounts from unauthorized access.

Generating API keys

Once your VALR account is fully verified and 2FA is enabled, you can generate API keys:

  1. Log In: Log in to your VALR account on the website.
  2. Navigate to API Keys: Go to 'Account' or 'Profile Settings' and locate the 'API Keys' section. The exact path may vary slightly but is typically found under security or developer settings.
  3. Create New API Key: Click on the 'Generate New API Key' or similar button. You will be prompted to label your API key (e.g., "MyTradingBot") and configure its permissions.
  4. Configure Permissions: Carefully select the permissions required for your application. Granting only necessary permissions (e.g., 'View Balances', 'Place Orders' but not 'Withdraw Funds' if your application doesn't need it) adheres to the principle of least privilege, enhancing security.
  5. Record API Key and Secret: Upon creation, VALR will display your API Key and API Secret. The API Secret is shown only once. It is crucial to copy and store both securely. If the API Secret is lost, it cannot be recovered, and a new API key pair must be generated. Treat your API Secret like a password.

Your first request

This section demonstrates how to make a simple authenticated GET request to the VALR API to retrieve account balances. We will use cURL for a direct HTTP request example, which illustrates the underlying mechanics of API key authentication. The VALR API uses HMAC-SHA512 for signing requests, a common method for securing API interactions, as detailed by MDN Web Docs on cryptographic signatures.

Authentication method

VALR API authentication requires an API Key, an API Secret, and a nonce (a unique, incrementing number or timestamp). Each authenticated request must include specific headers:

  • X-VALR-API-KEY: Your generated API key.
  • X-VALR-SIGNATURE: An HMAC-SHA512 signature of a concatenated string.
  • X-VALR-TIMESTAMP: Current Unix timestamp in milliseconds.
  • X-VALR-NONCE: A unique, monotonically increasing number per API key, typically the same as the timestamp for simplicity.

The signature string is constructed as follows:

timestamp + nonce + method.toUpperCase() + path + body

  • timestamp: The X-VALR-TIMESTAMP value.
  • nonce: The X-VALR-NONCE value.
  • method.toUpperCase(): HTTP method in uppercase (e.g., GET, POST).
  • path: The API endpoint path (e.g., /v1/account/balances).
  • body: The request body as a JSON string for POST/PUT requests. For GET requests, this is an empty string ''.

The resulting string is then signed using HMAC-SHA512 with your API Secret as the key. The signature must be hex-encoded.

Example: Get Account Balances with cURL

Let's make a request to GET /v1/account/balances to retrieve your account's cryptocurrency balances. This is a common first step to confirm API access.

# Replace with your actual API Key and Secret
API_KEY="YOUR_VALR_API_KEY"
API_SECRET="YOUR_VALR_API_SECRET"

# --- DO NOT MODIFY BELOW (unless you know what you're doing) ---

METHOD="GET"
PATH="/v1/account/balances"
BODY=""
TIMESTAMP=$(($(date +%s%N)/1000000)) # Unix timestamp in milliseconds
NONCE=$TIMESTAMP # Using timestamp as nonce for simplicity

# Construct the string to be signed
STRING_TO_SIGN="${TIMESTAMP}${NONCE}${METHOD}${PATH}${BODY}"

# Calculate HMAC-SHA512 signature (requires openssl)
# echo -n ensures no newline is added to the string_to_sign
SIGNATURE=$(echo -n "${STRING_TO_SIGN}" | openssl dgst -sha512 -hmac "${API_SECRET}" | awk '{print $2}')

# Execute the cURL request
curl -X ${METHOD} \
  -H "X-VALR-API-KEY: ${API_KEY}" \
  -H "X-VALR-SIGNATURE: ${SIGNATURE}" \
  -H "X-VALR-TIMESTAMP: ${TIMESTAMP}" \
  -H "X-VALR-NONCE: ${NONCE}" \
  "https://api.valr.com${PATH}"

This script will output a JSON array of your account balances, similar to this (example output):

[
  {
    "currency": "ZAR",
    "available": "1000.00",
    "reserved": "0.00",
    "total": "1000.00"
  },
  {
    "currency": "BTC",
    "available": "0.05",
    "reserved": "0.00",
    "total": "0.05"
  }
]

If you receive a 200 OK response with your balances, your API key setup and authentication mechanism are working correctly.

Common next steps

After successfully making your first API request, consider these common next steps to further integrate with VALR:

  1. Explore Market Data: Use public endpoints (which do not require authentication) to retrieve real-time market data, order books, and trade history for various currency pairs. This data is essential for building trading strategies.
  2. Place Orders: Implement endpoints for placing limit, market, and stop orders. Ensure your API key has the necessary 'Trade' permissions.
  3. Manage Orders: Learn how to query open orders, cancel existing orders, and retrieve order history.
  4. Utilize WebSockets: For real-time market updates and immediate order notifications, integrate with VALR's WebSocket API. This offers lower latency compared to polling REST endpoints.
  5. Implement Error Handling: Develop robust error handling mechanisms in your application to gracefully manage API rate limits, invalid requests, and other potential issues.
  6. Review SDKs: If you are working with Python, Node.js, or Java, consider using VALR's official SDKs. These SDKs often abstract away the complexity of authentication and request signing, simplifying development. Refer to the VALR SDK documentation for usage examples.
  7. Security Best Practices: Continuously review and apply security best practices, such as rotating API keys periodically, storing secrets securely (e.g., using environment variables or a secrets manager), and restricting API key permissions to the minimum required.
  8. Monitor Fees: Understand the VALR fee structure, which is tiered based on trading volume, to optimize your trading costs.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

  • 401 Unauthorized: This is the most frequent error, indicating an issue with your authentication headers. Ensure:
    • Your API Key and Secret are correct and have not been swapped.
    • The signature calculation is precise. Double-check the STRING_TO_SIGN concatenation (timestamp, nonce, method, path, body). Ensure the body is an empty string for GET requests.
    • The HMAC-SHA512 algorithm is used correctly, and the output is hex-encoded.
    • The timestamp and nonce are accurate and correctly formatted (milliseconds for timestamp, unique/monotonically increasing for nonce).
    • Your API key has the necessary permissions for the endpoint you are trying to access (e.g., 'View Balances' for the example above).
  • 403 Forbidden: This usually means your API key lacks the required permissions for the endpoint. Review the permissions assigned to your API key in the VALR dashboard and adjust them as needed. This can also occur if your account is not fully verified.
  • 404 Not Found: Check the API endpoint path. Ensure there are no typos and the path matches the official VALR API documentation exactly.
  • 429 Too Many Requests: You might be hitting rate limits. VALR has rate limits to prevent abuse. Wait a short period and retry, or implement exponential backoff in your application.
  • Incorrect Timestamp/Nonce: If your system's clock is significantly out of sync, it can cause timestamp validation failures. Ensure your system's clock is synchronized. Nonce values must be unique and increasing for each request using a specific API key.
  • SDK Issues: If using an SDK, ensure it is up to date. Consult the SDK's documentation and examples for proper usage. If problems persist, try to replicate the issue with a direct cURL request to isolate whether the problem lies with the SDK or the API credentials/logic.
  • Check VALR Status Page: Occasionally, API issues may be due to platform maintenance or outages. Check the official VALR status page (not in whitelist, but a useful troubleshooting step for users) for any reported incidents.