Hercle

REST API Introduction

Welcome to the Hercle REST API documentation. Hercle provides RESTful endpoints for OTC trading, deposits, withdrawals, RFQ flows, address whitelisting, and comprehensive account management for institutional and retail traders.

Overview

The Hercle REST API enables you to:

  • Trade Digital Assets: Execute OTC orders with competitive pricing and instant settlement
  • Manage Funds: Handle deposits and withdrawals for both crypto and fiat currencies
  • Request for Quote (RFQ): Create and accept custom quotes with flexible expiration times
  • Address Management: Whitelist withdrawal addresses and manage deposit addresses
  • Account Operations: Monitor balances, view transaction history, and manage user data
  • Banking Integration: Manage payees, business end users, and deposit accounts
  • Lightning Network: Create invoices and process Lightning Network transactions

Base URLs

The API is available in two environments:

Production Environment

https://publicapi.hercle.financial

Use this for live trading with real funds.

Sandbox Environment

https://publicapi.sandbox.hercle.financial

Use this for testing and development without risking real funds.

Postman Collection

We provide a comprehensive Postman collection for testing and integration. The Hercle REST API Collection repository contains:

  • Full-featured Postman collection covering all endpoints
  • Environment configurations for both sandbox and production
  • Pre-configured test scripts and response validation
  • Support for both manual testing and automated workflows

Authentication

All REST API requests require authentication using API keys sent as Bearer tokens:

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

Required Headers:

  • Authorization: Bearer token with your API key
  • Content-Type: application/json

For detailed authentication instructions, see the Authentication page.

Making Your First Request

Let's start by fetching your account balances:

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

Example Response:

[
  {
    "userId": "1a66db8f-4043-4035-91df-615b3a7ac073",
    "sequence": 42,
    "assets": [
      {
        "name": "BTC",
        "available": 1.5,
        "allocated": 0.5,
        "currentExposure": 2,
        "maxExposure": 5
      },
      {
        "name": "USDT",
        "available": 10000,
        "allocated": 2000,
        "currentExposure": 12000,
        "maxExposure": 20000
      }
    ]
  }
]

API Endpoints by Category

Address Management

Manage withdrawal whitelists and deposit addresses for both crypto and fiat assets:

  • Get whitelisted addresses
  • Whitelist address
  • Remove whitelisted address
  • Get deposit addresses
  • Create deposit address

Orders

Execute OTC orders with instant settlement:

  • Place OTC order
  • Get orders (paginated)
  • Get orders by client ID

Pairs & Pricing

Query available trading pairs and get real-time pricing:

  • Get available pairs
  • Get pair size by amount
  • Get asset networks
  • Get pair price

Request for Quote (RFQ)

Create custom quotes with flexible terms:

  • Create RFQ
  • Create custom RFQ (with custom expiration)
  • Accept RFQ

User Data

Access account information and transaction history:

  • Get balances
  • Get trades by client ID
  • Get trades (paginated)
  • Get historical trades (paginated)
  • Get transactions (paginated)
  • Get historical transactions (paginated)

Withdrawals

Process withdrawals for crypto and fiat assets:

  • Create withdrawal
  • Create withdrawal with address params
  • Create instant withdrawal
  • Get withdrawals (paginated)
  • Get withdrawals by client ID

Lightning Network

Lightning Network invoice and withdrawal management:

  • Create Lightning invoice
  • Get Lightning invoices
  • Create Lightning withdrawal

Banking

Manage business end users, payees, and deposit accounts:

  • Get/Register business end users
  • Get/Create deposit accounts
  • Get/Register payees and payee addresses
  • Get/Create transfers
  • Get transaction ledger

Response Format

All API responses are returned in JSON format. Successful responses typically return the requested data directly or wrapped in a data object:

{
  "id": "xxxx",
  "status": "success",
  "data": { ... }
}

Pagination

Endpoints that return lists support pagination using the following parameters:

  • page: Page number (zero-based, e.g., 0 for first page, 1 for second page)
  • pageSize: Number of items per page (minimum 5, maximum 50)
  • startDate: ISO 8601 datetime for filtering (e.g., 2024-01-01T00:00:00Z)
  • endDate: ISO 8601 datetime for filtering (e.g., 2024-12-31T23:59:59Z)

Example:

# Get first page (50 items)
GET /api/v1/orders/2024-01-01T00:00:00Z/2024-12-31T23:59:59Z/0/50

# Get second page (50 items)
GET /api/v1/orders/2024-01-01T00:00:00Z/2024-12-31T23:59:59Z/1/50

Some endpoints use cursor-based pagination with a paginationToken:

{
  "payload": [ ... ],
  "paginationToken": "eyJwYXJ0aXRpb25LZXkiOnsiaWQiOiJldXNfZGVm..."
}

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

{
  "code": "ERROR_CODE",
  "message": "Detailed error message"
}

HTTP Status Codes

  • 200 OK - Request succeeded
  • 201 Created - Resource successfully created
  • 400 Bad Request - Invalid input or validation error
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server-side error

Common Error Codes

VALIDATION_ERROR (400)

  • Request validation failed

RATE_LIMIT_EXCEEDED (429)

  • Too many requests in a given time period

CONFLICT (400)

  • Resource already exists or conflict with existing data

GENERIC_ERROR (400)

  • General error occurred while processing request

UNAUTHORIZED (401)

  • Invalid or missing authentication credentials

FORBIDDEN (403)

  • Insufficient permissions to perform this action

NOT_FOUND (404)

  • Requested resource does not exist

For more details on error handling, see the Errors page.

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. If you exceed the rate limit, you'll receive a 429 Too Many Requests response with details about when you can retry.

Scheduled Maintenance

Regular Upgrade Window

Herclex undergoes scheduled upgrades every Wednesday from 10:00 AM to 11:00 AM GMT+1. During this window, the system may undergo maintenance and enhancements.

Urgent Upgrades

In cases where urgent upgrades are necessary outside the scheduled window, we will communicate these in advance when possible. However, the ability to provide prior notice depends on the urgency and critical nature of the upgrade.

Impact on Connectivity

During upgrade windows, if a system upgrade is in progress, temporary disconnections may occur. We recommend implementing appropriate retry logic in your applications to handle these scenarios gracefully.

System Status

You can check the current status of Hercle services and any ongoing incidents by visiting our status page.

API Versioning

The current API version is v1, indicated in the base URL path:

https://publicapi.hercle.financial/api/v1

We follow semantic versioning principles:

  • Major version changes (v1 → v2): Breaking changes that require code updates
  • Minor updates: New features and endpoints added without breaking existing functionality
  • Patch updates: Bug fixes and performance improvements

We maintain backward compatibility within major versions and provide advance notice before deprecating any endpoints.

Best Practices

Security

  • Never expose API keys: Keep them secure and never commit them to version control
  • Use environment variables: Store API keys in environment variables, not in code
  • Rotate keys regularly: Create new API keys periodically and revoke old ones
  • Use HTTPS only: All API requests must use HTTPS

Performance

  • Implement caching: Cache responses where appropriate to reduce API calls
  • Use pagination: Don't fetch all data at once; use pagination for large datasets
  • Handle rate limits: Implement exponential backoff for rate limit errors
  • Batch requests: Where possible, combine multiple operations

Error Handling

  • Always check status codes: Don't assume requests succeeded
  • Parse error messages: Use error codes and messages to handle specific scenarios
  • Implement retries: Use exponential backoff for transient errors (5xx)
  • Log errors: Keep detailed logs for debugging

Idempotency

Certain transactional endpoints support idempotency to prevent duplicate operations when retrying requests. This is particularly useful in scenarios where a network failure occurs and you're unsure whether the original request was processed.

To make an idempotent request, include a unique Client-Id header in your API call. If a request with the same Client-Id is received within 6 hours, the API will return the original response instead of processing the request again.

Header:

  • Client-Id (string) — A unique identifier for the request (e.g., a UUID). Stored for 6 hours.

Supported Endpoints:

  • Create Transfer — POST /api/v1/transfer
  • Create Withdrawal — POST /api/v1/withdrawals
  • Create Withdrawal With Address Params — POST /api/v1/withdrawals/address
  • Create Instant Withdrawal — POST /api/v1/withdrawals/instant
  • Place OTC Order — POST /api/v1/orders
  • Accept RFQ — POST /api/v1/rfq/accept

Example:

curl -X POST https://publicapi.hercle.financial/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Client-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "priceId": "xxxx",
    "side": "buy",
    "slippage": 1.0
  }'

⚠️ Sandbox only: Idempotency is currently available only in the sandbox environment.

Note: The Client-Id value must be unique per intended operation. Reusing the same Client-Id within the 6-hour window will return the cached response from the original request. After 6 hours, the Client-Id expires and can be reused.

Sandbox vs Production

Sandbox Environment

https://publicapi.sandbox.hercle.financial
  • ✓ Safe testing environment
  • ✓ No real funds at risk
  • ✓ More lenient rate limits
  • ✓ No KYC required
  • ✗ Data may be reset periodically
  • ✗ Cannot process real transactions

Production Environment

https://publicapi.hercle.financial
  • ✓ Live trading with real funds
  • ✓ Permanent data persistence
  • ✓ Full platform features
  • ✓ Production-grade reliability
  • ✗ Standard rate limits apply
  • ✗ KYC verification required

Recommendation: Always test your integration thoroughly in the sandbox environment before moving to production.

Need Help?

Next Steps

  1. Set up authentication - Get your API keys
  2. View available endpoints - Explore the API reference
  3. Download Postman collection - Start testing immediately
  4. Learn about errors - Handle errors properly

Ready to start trading? Let's dive into the Authentication guide.