Authentication

Overview

The Have I Been Drained API uses User-Agent headers for authentication and rate limiting. No API keys are required for basic usage, but they’re available for higher rate limits.

User-Agent Format

Unregistered Tier (Default)

Rate Limit: 10 requests/hour No User-Agent header required, but you’ll have the lowest rate limit.

curl "https://api.haveibeendrained.org/api/v1/check?address=..."

Registered Tier

Rate Limit: 100 requests/hour Include your app information in the User-Agent:

User-Agent: MyApp/1.0.0 ([email protected])

Format:

AppName/Version ([email protected])

Example:

curl "https://api.haveibeendrained.org/api/v1/check?address=..." \
  -H "User-Agent: WalletChecker/2.1.0 ([email protected])"

Enterprise Tier

Rate Limit: 1000+ requests/hour Include your API key in the User-Agent or as a header: Option 1: User-Agent (Recommended)

User-Agent: MyApp/1.0.0 ([email protected]; API Key: hibd_...)

Option 2: X-API-Key Header

User-Agent: MyApp/1.0.0 ([email protected])
X-API-Key: hibd_...

Example:

curl "https://api.haveibeendrained.org/api/v1/check?address=..." \
  -H "User-Agent: EnterpriseApp/3.0.0 ([email protected]; API Key: hibd_abc123...)" \
  -H "X-API-Key: hibd_abc123..."

Getting an API Key

API keys are available for enterprise tier users. Contact [email protected] to request an API key.

Requirements:

Legitimate use case
Higher rate limit needs (1000+ req/hour)
Contact information for support

Process:

Email [email protected]
Describe your use case
Provide contact information
Receive API key via email

Rate Limit Headers

All responses include rate limit information:

RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 1702227600
Retry-After: 3600

Headers:

RateLimit-Limit - Maximum requests per window
RateLimit-Remaining - Requests remaining in current window
RateLimit-Reset - Unix timestamp when limit resets
Retry-After - Seconds until limit resets (when exceeded)

Rate Limit Exceeded

When rate limit is exceeded: Status Code: 429 Too Many Requests Response:

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit for this endpoint. Please try again later.",
  "retryAfter": 3600,
  "timestamp": 1702224000000
}

Handling:

Check Retry-After header for wait time
Implement exponential backoff
Consider upgrading to enterprise tier
Use cached responses when possible

Best Practices

User-Agent Formatting

✅ Good:

MyApp/1.0.0 ([email protected])
WalletChecker/2.1.0 ([email protected])

❌ Bad:

MyApp (missing version)
MyApp/1.0.0 (missing contact)

Rate Limit Management

Monitor headers - Track remaining requests
Implement caching - Cache responses when possible
Use exponential backoff - When rate limited
Request appropriate tier - Match your usage needs

Security

Never expose API keys in client-side code. Use server-side proxies for web applications.

Server-side only - Keep API keys on your backend
Environment variables - Store keys securely
Rotate keys - Change keys if compromised
Monitor usage - Watch for unusual activity

Code Examples

JavaScript/Node.js

const response = await fetch(
  'https://api.haveibeendrained.org/api/v1/check?address=...',
  {
    headers: {
      'User-Agent': 'MyApp/1.0.0 ([email protected])',
      'X-API-Key': 'hibd_...' // Optional for enterprise
    }
  }
);

const rateLimitRemaining = response.headers.get('RateLimit-Remaining');
console.log(`Remaining requests: ${rateLimitRemaining}`);

Python

import requests

headers = {
    'User-Agent': 'MyApp/1.0.0 ([email protected])',
    'X-API-Key': 'hibd_...'  # Optional for enterprise
}

response = requests.get(
    'https://api.haveibeendrained.org/api/v1/check',
    params={'address': '...'},
    headers=headers
)

rate_limit_remaining = response.headers.get('RateLimit-Remaining')
print(f"Remaining requests: {rate_limit_remaining}")

cURL

curl "https://api.haveibeendrained.org/api/v1/check?address=..." \
  -H "User-Agent: MyApp/1.0.0 ([email protected])" \
  -H "X-API-Key: hibd_..." \
  -v  # -v shows response headers

Troubleshooting

Rate limit too low

Upgrade to registered tier (add User-Agent)
Request enterprise tier API key
Implement response caching
Optimize request frequency

API key not working

Verify key format (starts with hibd_)
Check User-Agent format
Ensure key is included in header
Contact support if issues persist

Authentication errors

Verify User-Agent format
Check API key validity
Ensure headers are set correctly
Review error message details

Getting started

Integration

API Reference

Overview

User-Agent Format

Unregistered Tier (Default)

Registered Tier

Enterprise Tier

Getting an API Key

Rate Limit Headers

Rate Limit Exceeded

Best Practices

User-Agent Formatting

Rate Limit Management

Security

Code Examples

JavaScript/Node.js

Python

cURL

Troubleshooting

​Overview

​User-Agent Format

​Unregistered Tier (Default)

​Registered Tier

​Enterprise Tier

​Getting an API Key

​Rate Limit Headers

​Rate Limit Exceeded

​Best Practices

​User-Agent Formatting

​Rate Limit Management

​Security

​Code Examples

​JavaScript/Node.js

​Python

​cURL

​Troubleshooting

Overview

User-Agent Format

Unregistered Tier (Default)

Registered Tier

Enterprise Tier

Getting an API Key

Rate Limit Headers

Rate Limit Exceeded

Best Practices

User-Agent Formatting

Rate Limit Management

Security

Code Examples

JavaScript/Node.js

Python

cURL

Troubleshooting