Skip to main content

​
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:
FieldDescriptionExample
requestRequest path without domain name'/api/v4/trade-account/balance'
nonceAn incrementing number larger than previous requests'1594297865'
nonceWindowOptional boolean to enable time-based nonce validationtrue
Request-specific parametersAdditional 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:
HeaderValueDescription
Content-typeapplication/jsonSpecifies JSON format
X-TXC-APIKEYYOUR_API_KEYThe public WhiteBIT API key
X-TXC-PAYLOADbase64_encoded_payloadBase64-encoded request body
X-TXC-SIGNATUREsignatureHMAC-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 MessageCauseSolution
”Too many requests.”Nonce value is not greater than previous requestUse incrementing nonce values
”This action is unauthorized. Enable your key in API settings”Using disabled API keyEnable key in API settings or check IP restrictions
”You don’t have permission to use this endpoint.”Endpoint access is restrictedUpdate endpoint access in API key settings
”Invalid payload”Payload does not match decoded valueEnsure proper base64 encoding of request body
”Unauthorized request.”Request signed incorrectlyVerify signature creation process
”Nonce not provided.”Missing nonce in request bodyInclude nonce in all requests
”Your nonce is more than 5 seconds lesser than the current nonce”Invalid timestamp when using nonceWindowUse current timestamp in milliseconds
”Invalid nonceWindow.”nonceWindow is not a booleanEnsure nonceWindow is set to true or false
”Request not provided.”Missing request path in bodyInclude request path in all requests