Authentication

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.

Tier	Rate / min	Per day	Per month	Keys	Price
Free	30	1,000	unlimited	1	$0
Starter	120	2,000	50,000	3	$29 / mo
Pro	600	20,000	500,000	10	$199 / mo
Enterprise	custom	custom	custom	unlimited	custom quote

See pricing for what each tier unlocks.

Each key is checked on its own. A key serves the tier it was provisioned at, capped by your account’s active entitlement — a Free key calling alongside an unused Pro key on the same account still gets Free limits. See how tier resolution works.

Rate-limit headers

Every successful response includes:

Header	Meaning
`X-RateLimit-Tier`	Tier resolved for this request (`free`, `starter`, `pro`, `enterprise`)
`X-RateLimit-Remaining`	Requests remaining in the current per-minute window
`X-RateLimit-Next`	Time until the window refills (a duration string, e.g. `12.4s`)
`X-RateLimit-Route`	Remaining allowance on the per-route limit, where one applies
`X-RateLimit-Daily`	Requests remaining today (only on tiers with a daily cap)
`X-RateLimit-Monthly`	Requests remaining this billing month (only on tiers with a monthly cap)

Error responses

All errors are JSON problem details: title, status, a human-readable detail, and a machine-matchable code. Match on code — the detail wording can change. There is no 401 in this API: every auth failure is a 403.

403 Forbidden — missing key (code TIER_GATE)

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Api key needed for this request",
  "code": "TIER_GATE",
  "current_tier": "none",
  "required_tier": "free",
  "upgrade_url": "https://coinversa.ai/developers#pricing"
}

Action: include the X-API-Key header. required_tier names the minimum tier for the endpoint — even free endpoints need a key.

403 Forbidden — invalid key (code FORBIDDEN)

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Invalid API key",
  "code": "FORBIDDEN"
}

Action: check the key isn’t revoked or rotated in the portal.

403 Forbidden — insufficient tier (code TIER_GATE)

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Tool not available for current tier, must be pro or higher",
  "code": "TIER_GATE",
  "current_tier": "starter",
  "required_tier": "pro",
  "upgrade_url": "https://coinversa.ai/developers#pricing"
}

Action: upgrade at upgrade_url, or (for builder endpoints) fall back to the endpoint’s x402 pay-per-call twin. Agents: report required_tier to the human rather than retrying.

429 Too Many Requests — per-minute rate limit (code RATE_LIMITED)

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for requests (Exceeded requests per minute)",
  "code": "RATE_LIMITED"
}

Action: back off until the duration in X-RateLimit-Next elapses, or upgrade for higher RPM.

429 Too Many Requests — daily or monthly cap (code RATE_LIMITED)

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Exceeded daily and/or monthly request allowance update plan or wait for next reset",
  "code": "RATE_LIMITED"
}

Action: the daily window resets at 00:00 UTC; the monthly bucket at your billing period boundary. Or upgrade.

502 Bad Gateway (code BAD_GATEWAY)

The upstream Hyperliquid endpoint timed out or returned an error. The MCP server retries automatically; direct callers should retry with backoff.

No key at all? Every GET endpoint has a keyless x402 pay-per-call twin — payment is negotiated per request via the x402 protocol instead of a subscription. The builder analytics endpoints are the documented x402 surface today.

Historical-window caps

Caller-controlled history windows (since, hours/days params, explicit startTime/endTime ranges) are clamped to 90 days on every tier — the cap is universal, not tier-based. The clamp is silent: no error is returned, the query just runs against the capped window, and the response may echo the window you asked for. Compare response timestamps against your requested range to detect truncation. Risk endpoints (/live/risk/liquidations/*, etc.) are additionally clamped to data starting 2026-01-01 (the day we began collecting L1 liquidation events). Longer windows are available on Enterprise as custom exports and negotiated data delivery, not as an API parameter. See Data windows for per-endpoint window semantics.

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).

Getting started

MCP

Concepts

Sending the key

Tiers

Rate-limit headers

Error responses

Historical-window caps

Usage logging

​Sending the key

​Tiers

​Rate-limit headers

​Error responses

​Historical-window caps

​Usage logging

Sending the key

Tiers

Rate-limit headers

Error responses

Historical-window caps

Usage logging