REST API - Authentication

All REST API requests require authentication using API keys sent as Bearer tokens in the Authorization header.

Getting Your API Key

Before you can use the Hercle REST API, you must complete the onboarding process and have your KYC (Know Your Customer) approved. Once approved, you can retrieve your API key:

Sandbox Environment: Log in at https://auth.sandbox.hercle.financial/sign-in
Production Environment: Use the production authentication portal
Navigate to the Account page
Go to the API Key area
Either generate a new key or retrieve your existing one
Save your API key securely (it will only be shown once)

Warning: Your API key is valuable. Never share your API keys or commit them to version control. Store them securely and refrain from sharing them publicly or in any insecure spaces.

Authentication Method

Bearer Token

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Complete Example

curl -X GET https://publicapi.sandbox.hercle.financial/api/v1/user/balances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Base URLs

Hercle provides two environments for API integration:

Sandbox Environment

Base URL: https://publicapi.sandbox.hercle.financial

Use the sandbox environment for:

Testing your integration
Development and debugging
Learning the API without risk
No real funds involved

curl -X GET https://publicapi.sandbox.hercle.financial/api/v1/pairs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Production Environment

Base URL: https://publicapi.hercle.financial

Use the production environment for:

Live trading with real funds
Production applications
⚠️ Real financial transactions

curl -X GET https://publicapi.hercle.financial/api/v1/pairs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Request Headers

Every authenticated request must include:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Example in Different Languages

cURL

curl -X POST https://publicapi.sandbox.hercle.financial/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"priceId":"price_123","side":"buy","slippage":1.0}'

JavaScript (Fetch)

const response = await fetch(
  'https://publicapi.sandbox.hercle.financial/api/v1/orders',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      priceId: 'price_123',
      side: 'buy',
      slippage: 1.0,
    }),
  }
);

const data = await response.json();

Python (Requests)

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://publicapi.sandbox.hercle.financial/api/v1/orders',
    headers=headers,
    json={
        'priceId': 'price_123',
        'side': 'buy',
        'slippage': 1.0
    }
)

data = response.json()

Authentication Errors

401 Unauthorized

Missing or invalid API key:

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing authentication credentials"
}

Common causes:

API key not provided in the Authorization header
API key is incorrect or malformed
API key has been revoked or expired
Missing "Bearer " prefix in Authorization header

How to fix:

Ensure you're including the Authorization header: Authorization: Bearer YOUR_API_KEY
Verify your API key is correct
Check if your API key is still active in the Account page
Confirm you're using the correct environment (sandbox vs production)

403 Forbidden

Insufficient permissions:

{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions to perform this action"
}

Common causes:

Account KYC not yet approved
API key doesn't have required permissions
Account restrictions or limitations
Trying to access restricted features

How to fix:

Complete KYC verification if not already done
Check your account status and permissions
Contact support if you believe you should have access

Security Best Practices

1. Store Keys Securely

❌ Don't do this:

// Never hardcode API keys
const apiKey = 'your_actual_api_key_here';

✅ Do this instead:

// Use environment variables
const apiKey = process.env.HERCLE_API_KEY;

2. Use Environment Variables

Create a .env file (and add it to .gitignore):

# .env
HERCLE_API_KEY=your_api_key_here
HERCLE_BASE_URL=https://publicapi.sandbox.hercle.financial

3. Rotate Keys Regularly

Generate new API keys periodically
Immediately rotate if a key is compromised
Delete unused API keys from your account
Keep track of where each key is being used

4. Use HTTPS Only

All API requests must use HTTPS
Never send API keys over unencrypted connections
The Hercle API enforces HTTPS for all endpoints

5. Monitor API Usage

Regularly review your API activity:

Check for unusual patterns or unexpected requests
Monitor failed authentication attempts
Review your trading activity regularly
Set up alerts for important actions

Rate Limiting

The Hercle API implements rate limiting to ensure fair usage and system stability. Rate limits vary by endpoint type and are subject to change.

Understanding Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests error:

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests in a given time period"
}

Best Practices

Implement exponential backoff: Wait progressively longer between retries
Cache responses: Store frequently accessed data to reduce API calls
Batch operations: Group multiple operations when possible
Monitor your usage: Track your API request patterns

Handling Rate Limits

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      // Rate limited - wait before retrying
      const waitTime = Math.pow(2, i) * 1000; // Exponential backoff
      await new Promise((resolve) => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

Testing Authentication

Test your API key with a simple request to verify it's working correctly:

Sandbox Test

curl -X GET https://publicapi.sandbox.hercle.financial/api/v1/user/balances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Production Test

curl -X GET https://publicapi.hercle.financial/api/v1/user/balances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Success Response (200)

{
  "userId": "1a66db8f-4043-4035-91df-615b3a7ac073",
  "sequence": 6618,
  "assets": [
    {
      "name": "BTC",
      "available": 0.014335,
      "allocated": 0
    },
    {
      "name": "USDT",
      "available": 1000.5,
      "allocated": 0
    }
  ],
  "deleted": false
}

Error Response (401)

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing authentication credentials"
}

Common Issues

"Invalid API key" Error

Problem: API key not recognized by the system

Solutions:

Double-check you copied the entire API key
Ensure there are no extra spaces before or after the key
Verify you're using the correct environment (sandbox vs production)
Check if the API key was deleted or regenerated

"Forbidden" Error

Problem: API key is valid but lacks permissions

Solutions:

Complete KYC verification if required
Wait for account approval
Verify your account has access to the requested feature
Contact support if the issue persists

Connection Issues

Problem: Unable to connect to the API

Solutions:

Verify the base URL is correct
Check your internet connection
Ensure you're using HTTPS (not HTTP)
Try the request with cURL to rule out code issues

Next Steps

← REST API Introduction

Learn about the REST API capabilities

→ Start Building

Make your first API call

→ Error Handling

Handle API errors properly

→ Available Pairs

View tradable pairs