Private HTTP API Authentication

Authenticate with WhiteBIT private HTTP API endpoints using API keys and HMAC-SHA512 signatures.

Overview

The Authentication guide explains how to authenticate with WhiteBIT’s private HTTP API endpoints, which require authentication for security purposes.

Getting Started

Setting Up API Keys

1. Navigate to WhiteBIT API Settings

2. Select the appropriate configuration tab for API keys

   Different API keys provide access to different API endpoints

3. Generate a new API key

4. Recommended Security Measures:

   • Enable IP restrictions (specify up to 50 trusted IPs)
   • Enable Endpoint access restrictions (select only necessary endpoints)

Authentication Requirements

All authenticated requests must:

1. Use the POST HTTP method
2. Include specific body data
3. Contain required headers

Body Data Format

The request body must be a JSON object containing:

Field	Description	Example
request	Request path without domain name	'/api/v4/trade-account/balance'
nonce	An incrementing number larger than previous requests	'1594297865'
nonceWindow	Optional boolean to enable time-based nonce validation	true
Request-specific parameters	Additional parameters required by the endpoint	"ticker": "BTC"

Example Request Body:

{
    "request": "/api/v4/trade-account/balance",
    "nonce": 1594297865,
    "nonceWindow": true,
    "ticker": "BTC"
}

About Nonce Values

• Use the Unix timestamp in milliseconds for nonce values
• Ensure each nonce is larger than previous requests
• When nonceWindow is enabled:
  • Provide Unix timestamp in milliseconds as the nonce
  • Timestamp must be within ±5 seconds of server time
  • Each nonce must be unique to prevent double processing
  • Useful for high-frequency trading systems with concurrent requests

Required Headers

Every authenticated request requires these headers:

Header	Value	Description
Content-type	application/json	Specifies JSON format
X-TXC-APIKEY	YOUR_API_KEY	The public WhiteBIT API key
X-TXC-PAYLOAD	base64_encoded_payload	Base64-encoded request body
X-TXC-SIGNATURE	signature	HMAC-SHA512 signature (hex encoded)

Create the signature using: hex(HMAC_SHA512(payload, key=api_secret))

Implementation Examples

WhiteBIT provides the API Quick Start Helper library with examples in multiple languages:

• Python
• PHP
• NodeJS
• Go
• JavaScript
• Kotlin
• DotNet
• Ruby
• C++
• Rust

Common Errors

Error Message	Cause	Solution
{“code”:2,”errors”:{},”message”:”Payload not provided.”}	X-TXC-PAYLOAD header missing or empty	Include the base64-encoded request body as X-TXC-PAYLOAD
“Too many requests.”	Nonce value is not greater than previous request	Use incrementing nonce values
”This action is unauthorized. Enable your key in API settings”	Using disabled API key	Enable key in API settings or check IP restrictions
”You don’t have permission to use this endpoint.”	Endpoint access is restricted	Update endpoint access in API key settings
”Invalid payload”	Payload does not match decoded value	Ensure proper base64 encoding of request body
”Unauthorized request.”	Request signed incorrectly	Verify signature creation process
”Nonce not provided.”	Missing nonce in request body	Include nonce in all requests
”Your nonce is more than 5 seconds lesser than the current nonce”	Invalid timestamp when using nonceWindow	Use current timestamp in milliseconds
”Invalid nonceWindow.”	nonceWindow is not a boolean	Ensure nonceWindow is set to true or false
”Request not provided.”	Missing request path in body	Include request path in all requests

For rate limits and REST error format, see Rate limits and error codes.

Testing in the API playground

Related resources

• API Reference Overview — Base URL, rate limits, and error format
• Market Data overview — Public endpoints (no authentication)
• Spot Trading overview — Private trading endpoints