Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every request to api.coinversa.ai/api/public/v1/* requires an API key. Get one at developers.coinversa.ai.

​
Sending the key

Pass your key in the X-API-Key header on every request: 
curl https://api.coinversa.ai/api/public/v1/pulse/stats \
  -H "X-API-Key: cvsa_..."
That’s it — no OAuth, no bearer prefix, no signing.
Never embed your key in client-side code or commit it to a public repo. Use a server-side proxy if you need to call Pulse from a browser, or use a separate key per environment so you can rotate without disrupting other clients.

​
Tiers

Your key’s tier is set by your active subscription. Free is the default; paid tiers are managed in the billing portal.
TierRate / minPer dayPer monthKeysPrice
Free301,000unlimited1$0
Starter1202,00050,0003$29 / mo
Pro60020,000500,00010$199 / mo
Enterprisecustomcustomcustom∞custom quote
See pricing for what each tier unlocks.
Multiple keys share your account’s best tier. If you have three keys and one is on Pro, all three get Pro limits. The check looks at every active key on your account and uses the highest entitled tier.

​
Rate-limit headers

Every successful response includes:
HeaderMeaning
X-RateLimit-TierTier resolved for this request (free, starter, pro, enterprise)
X-RateLimit-LimitRequests per minute allowed
X-RateLimit-RemainingRequests remaining in the current minute window
X-RateLimit-ResetSeconds until the per-minute window resets
X-RateLimit-Daily-RemainingRequests remaining in the current 24h window (paid tiers)
X-RateLimit-Monthly-LimitTotal requests/month for your tier
X-RateLimit-Monthly-RemainingRequests remaining this calendar month
X-RateLimit-Monthly-ResetSeconds until the next month starts
Some endpoints (e.g. /pulse/leaderboard, /pulse/hidden-gems) have additional per-route limits — those are returned as X-Route-RateLimit-*.

​
Error responses

All errors return JSON with success: false and a human-readable error. Specific status codes: 
{
  "success": false,
  "error": "API key required for this endpoint.",
  "message": "Hey — you need an API key to use this endpoint. Get a free one at https://developers.coinversa.ai",
  "signup_url": "https://developers.coinversa.ai"
}
Action: include X-API-Key header.
{ "success": false, "error": "Invalid or inactive API key." }
Action: check the key isn’t revoked or rotated in the portal.
{
  "success": false,
  "error": "This endpoint requires Pro tier.",
  "current_tier": "starter",
  "required_tier": "pro",
  "upgrade_url": "https://api.coinversa.ai/api/billing/checkout/redirect?tier=pro&key_id=..."
}
Action: visit upgrade_url to start a Stripe checkout for the required tier.
{
  "success": false,
  "error": "Rate limit exceeded (30/min for free). Try again shortly.",
  "retryAfterSeconds": 47
}
Action: back off until retryAfterSeconds elapses, or upgrade for higher RPM.
{
  "success": false,
  "error": "Daily request cap reached (1000/day for free). Upgrade for higher limits.",
  "upgrade_url": "https://api.coinversa.ai/api/billing/checkout/redirect?tier=starter&key_id=..."
}
Action: the daily window resets at 00:00 UTC; monthly on the 1st of the next month. Or upgrade.
The upstream Hyperliquid endpoint timed out or returned an error. The MCP server retries automatically; direct callers should retry with backoff.

​
Historical-window caps

Endpoints that read historical data cap how far back you can query, by tier:
TierMax window
Free / Starter30 days
Pro90 days
Enterprise365 days
If you request a longer since or startTime/endTime range, the response is 400 with a hint pointing at upgrade options. Risk endpoints (/live/risk/liquidations/*, etc.) are additionally clamped to data starting 2026-01-01 (the day we began collecting L1 liquidation events).

​
Usage logging

Every authenticated request is logged with the response time and status code so you can audit usage in Usage in the portal. Logs include endpoint, method, IP, and user-agent — but never the key itself (only the SHA-256 hash).