Authentication

Blocky402 uses different authentication methods for testnet and mainnet environments.

Testnet (Current)

No authentication required! Testnet is open access for development and testing.

# No headers needed
curl http://localhost:3002/supported

// No authentication required
const response = await fetch('http://localhost:3002/supported');

Mainnet (Coming Soon)

Mainnet will require an API key for authentication and rate limiting.

API Key Format

API keys follow this format:

b402_<64_character_hex_string>

Example:

b402_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Using API Keys

Include your API key in the X-Api-Key header:

curl -X GET "https://api.blocky402.com/v1/supported" \
  -H "X-Api-Key: b402_1234567890abcdef..."

const response = await fetch('https://api.blocky402.com/v1/supported', {
  headers: {
    'X-Api-Key': 'b402_1234567890abcdef...'
  }
});

import requests
 
response = requests.get(
    'https://api.blocky402.com/v1/supported',
    headers={'X-Api-Key': 'b402_1234567890abcdef...'}
)

Getting API Keys

API key management will be available when mainnet launches. You’ll be able to:

• Generate new API keys
• View existing keys
• Revoke keys
• Monitor usage

Rate Limiting

Testnet

• Type: Per-IP address
• Limit: 100 requests per minute
• Burst: 10 requests
• Reset: In-memory (resets on server restart)

Mainnet (Coming Soon)

• Type: Per-API-Key
• Limit: 10 requests per second
• Daily Quota: 10,000 settlements per day per key
• Monthly Quota: 300,000 settlements per month per key

Rate Limit Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Handling Rate Limits

When rate limited, you’ll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2024-01-15T10:31:00Z"
    }
  }
}

Best Practices

1. Respect rate limits: Don’t exceed the limits
2. Implement backoff: Use exponential backoff when rate limited
3. Cache responses: Cache /supported endpoint responses
4. Batch requests: Combine multiple operations when possible

Example: Handling Rate Limits

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const resetAt = response.headers.get('X-RateLimit-Reset');
      const waitTime = Math.max(1000, (resetAt * 1000) - Date.now());
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

Security Best Practices

1. Never commit API keys: Store keys in environment variables
2. Use different keys: Use separate keys for development and production
3. Rotate keys regularly: Rotate API keys periodically
4. Monitor usage: Watch for unusual activity
5. Revoke compromised keys: Immediately revoke any compromised keys

Environment Variables

# .env file
BLOCKY402_API_KEY=b402_1234567890abcdef...
BLOCKY402_API_URL=https://api.blocky402.com/v1

// Use environment variables
const apiKey = process.env.BLOCKY402_API_KEY;
const apiUrl = process.env.BLOCKY402_API_URL || 'http://localhost:3002';
 
const response = await fetch(`${apiUrl}/supported`, {
  headers: apiKey ? { 'X-Api-Key': apiKey } : {}
});

Error Responses

Invalid API Key

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key",
    "details": {}
  }
}

HTTP Status: 401 Unauthorized

Rate Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2024-01-15T10:31:00Z"
    }
  }
}

HTTP Status: 429 Too Many Requests

Migration from Testnet to Mainnet

When migrating from testnet to mainnet:

1. Get an API key: Sign up and generate your API key
2. Update base URL: Change from http://localhost:3002 to https://api.blocky402.com/v1
3. Add authentication: Include X-Api-Key header in all requests
4. Update network IDs: Change from testnet (e.g., eip155:80002) to mainnet (e.g., eip155:137)
5. Test thoroughly: Test with small amounts first

Need Help?

• See Testnet Guide for testnet-specific information
• Check API Reference for endpoint details
• Review Code Examples for authentication examples