Authentication

All API requests require an API key passed via the x-api-key header.

API Key Format

x-api-key: cs_live_abc123...

The cs_live_ prefix indicates a production key. Keep your API key secret — do not expose it in client-side code or public repositories.

Rate Limits

Rate limits are enforced per API key on a daily basis (UTC midnight reset).

Tier	Daily Limit	Description
Free	1,000 requests/day	For exploration and prototyping
Pro	10,000 requests/day	For production applications
Enterprise	100,000 requests/day	For high-volume integrations

Rate Limit Headers

Every successful response includes rate limit information:

x-ratelimit-limit: 1000
x-ratelimit-remaining: 997
x-ratelimit-reset: 1711411200

Header	Description
x-ratelimit-limit	Your daily request limit
x-ratelimit-remaining	Requests remaining today
x-ratelimit-reset	Unix timestamp of next UTC midnight reset

When rate limited (HTTP 429), you'll also receive:

retry-after: 43200

The retry-after value is in seconds until your limit resets.

Error Codes

All errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Error Reference

Status	Code	Description	Recommended Action
400	BAD_REQUEST	Invalid request parameters	Check your query parameters
401	MISSING_API_KEY	No API key in header	Add x-api-key header to your request
401	INVALID_API_KEY	Key is invalid or revoked	Verify your key in the API Keys Dashboard
403	TIER_INSUFFICIENT	Endpoint requires a higher tier	Upgrade your plan
404	NOT_FOUND	Resource not found	Check space_id or entity_id
429	RATE_LIMIT_EXCEEDED	Daily limit exceeded	Wait for reset (see retry-after header) or upgrade
500	INTERNAL_ERROR	Server error	Retry after a few seconds

Example Error Responses

401 — Missing API Key

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via x-api-key header."
  }
}

429 — Rate Limited

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit exceeded. Upgrade to Pro for higher limits.",
    "retry_after": 43200
  }
}

403 — Tier Insufficient

{
  "error": {
    "code": "TIER_INSUFFICIENT",
    "message": "This endpoint requires API Pro. Upgrade at https://chainsights.one/account/api-keys",
    "required_tier": "pro"
  }
}

Need more requests?

View pricing plans to upgrade your API tier for higher rate limits and access to premium endpoints.