Rate Limits

Standard Tier

• 100 requests per minute per wallet address
• Cached responses (within 30s) do NOT count toward rate limit
• Free endpoints (/health, /, /openapi.json, /.well-known/x402.json) do NOT count

Premium Tier

• 1000 requests per minute per wallet address
• Contact sales@foursec.xyz to upgrade

Rate Limit Headers

Every response includes:

RateLimit-Policy: 500;w=60
RateLimit-Limit: 500
RateLimit-Remaining: 495
RateLimit-Reset: 60

Header	Description
RateLimit-Policy	Max requests and window (e.g., 500;w=60)
RateLimit-Limit	Max requests per window
RateLimit-Remaining	Remaining requests this window
RateLimit-Reset	Seconds until window resets

Exceeding the Limit

Returns 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retry_after": 60
}

Why 100 req/min?

Discovery tools like x402scan probe all 16 endpoints simultaneously. 100 req/min ensures all endpoints respond properly during discovery scans without hitting rate limits.

Best Practices

1. Use caching — 30s cache means identical requests are free
2. Implement retry logic with exponential backoff
3. Batch related requests — use /api/v1/prices?symbols=btc,eth for multi-symbol queries
4. Monitor headers — check RateLimit-Remaining before bursting

Retry Example

import time

def request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        response = client.get(url)
        if response.status_code != 429:
            return response.json()
        wait = 2 ** attempt
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)
    raise Exception("Max retries exceeded")