REST API Authentication Guide for Wallet as a Service (WaaS) Web3 APIs

Making API Requests

All private REST API requests must include the following headers:

• OK-ACCESS-KEY: Your API key (string)
• OK-ACCESS-SIGN: Base64-encoded HMAC SHA256 signature (see signature section)
• OK-ACCESS-TIMESTAMP: Request timestamp in UTC (e.g., 2020-12-08T09:08:57.715Z)
• OK-ACCESS-PASSPHRASE: The passphrase you set when creating the API key

Additional headers required for WaaS endpoints:

• OK-ACCESS-PROJECT: Your project ID (found in project details)

Request Requirements:

• Content type must be application/json
• All requests must contain valid JSON

Signature Generation

The OK-ACCESS-SIGN header is generated by:

1. Creating a pre-hash string: timestamp + method + requestPath + body
2. Signing it with your Secret Key using HMAC SHA256
3. Encoding the result in Base64

Components:

• timestamp: ISO format (same as OK-ACCESS-TIMESTAMP)
• method: Uppercase HTTP method (GET/POST)
• requestPath: API endpoint path (e.g., /api/v5/account/balance)
• body: Request body string (omitted for GET requests)

Example:

sign = Base64.encode(HMAC_SHA256(timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC', SecretKey))

Postman Implementation Guide

👉 Learn how to optimize your API testing workflow

Setting Up Postman Requests

1. Adding Parameters (for GET requests):

   • Navigate to the "Params" tab
   • Add key-value pairs for query parameters

2. Configuring Headers:

   • Required headers:

     • OK-ACCESS-KEY
     • OK-ACCESS-PASSPHRASE
     • OK-ACCESS-PROJECT (for WaaS endpoints)

3. Request Body (for POST requests):

   • Select "raw" and "JSON" format
   • Enter JSON-formatted request body

4. Pre-request Scripts:

   • JavaScript code to generate:

     • Signature (OK-ACCESS-SIGN)
     • Timestamp (OK-ACCESS-TIMESTAMP)

JavaScript Code Examples

Here's how to implement API calls in JavaScript:

// GET Request Example
async function getAccountBalance() {
  const timestamp = new Date().toISOString();
  const method = 'GET';
  const requestPath = '/api/v5/account/balance?ccy=BTC';
  
  const preHash = timestamp + method + requestPath;
  const sign = generateSignature(preHash, secretKey);
  
  // ... request implementation
}

// POST Request Example
async function createOrder() {
  const timestamp = new Date().toISOString();
  const method = 'POST';
  const requestPath = '/api/v5/trade/order';
  const body = JSON.stringify({
    instId: "BTC-USDT",
    lever: "5",
    mgnMode: "isolated"
  });
  
  const preHash = timestamp + method + requestPath + body;
  const sign = generateSignature(preHash, secretKey);
  
  // ... request implementation
}

FAQ Section

👉 Discover more about secure API integrations

Frequently Asked Questions

Q: How do I generate API keys?
A: Navigate to Developer Portal > API Management and follow the key generation guide.

Q: Why is my signature invalid?
A: Double-check: 1) Timestamp format 2) Uppercase method 3) Correct request path 4) Body stringification.

Q: What's the difference between WaaS and regular endpoints?
A: WaaS endpoints require the additional OK-ACCESS-PROJECT header for project-specific requests.

Q: How often should I rotate my API keys?
A: We recommend rotating keys every 90 days for optimal security.

Q: Can I use the same API key for multiple projects?
A: No, each project requires its own API key with proper permissions.

Best Practices

1. Security Recommendations:

   • Store keys securely (never in client-side code)
   • Implement IP whitelisting
   • Set appropriate permission scopes

2. Performance Tips:

   • Cache frequent responses when possible
   • Implement request throttling
   • Batch requests when appropriate

3. Error Handling:

   • Implement proper HTTP status code checks
   • Include retry logic for transient failures
   • Monitor API usage and limits