Authentication

Every request to api.coinversa.ai/api/public/v1/* requires an API key. Get one at developers.coinversa.ai. This page is about the REST API. The WebSocket uses the same key but a different protocol: a Bearer token on the upgrade (or the bearer subprotocol from a browser), refusals as HTTP 401 / 429 / 503 or close codes rather than problem details, and capacity limits rather than request quotas. Its rules live in WebSocket authentication, not here.

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. (The REST API ignores an Authorization: Bearer header entirely; that header is how the WebSocket authenticates.)

Never commit your key to a public repo, and never ship it in a page served to other people — a key in someone else’s browser is a key you have published. For a REST call from a browser, keep the key on a server you control and proxy the request. The WebSocket can be opened directly from your own browser tools with the bearer subprotocol; the same publishing rule applies. 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	10,000+	unlimited	unlimited	unlimited	from $1,999 / mo

See pricing for what each tier unlocks.

Access is checked per key; request usage is shared by account. Additional keys do not multiply your REST RPM or daily/monthly allowance. 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 has Free endpoint access and daily/monthly caps. See how tier resolution works.

Rate-limit headers

Authenticated responses include these, 429s included:

Header	Meaning
`X-RateLimit-Tier`	Tier resolved for this request (`free`, `starter`, `pro`, `enterprise`)
`X-RateLimit-Remaining`	Minimum remaining tokens across the account minute and per-route buckets
`X-RateLimit-Next`	Time until the next token is available across the checked buckets (a duration string, e.g. `12.4s`), not a full-window refill
`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)
`X-RateLimit-Scope`	Identity the limits were counted against: `account` (keyed request) or `ip`
`X-RateLimit-Reset`	Unix seconds when the next token is available
`X-RateLimit-Daily-Reset` / `X-RateLimit-Monthly-Reset`	Unix seconds when the daily / monthly allowance resets (only on tiers with that cap)
`Retry-After`	Seconds to wait before retrying (on `429` only)
`X-Billing-State` / `X-Billing-Grace-Expires`	Present only during a payment grace window: the state (`grace`) and when the window ends

Error responses

All errors are JSON problem details: title, status, a human-readable detail, a machine-matchable code (retained for compatibility) and, when available, a more specific reason (missing_api_key, invalid_api_key, insufficient_tier, invalid_parameters or account_suspended). Match on reason when present, else 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",
  "reason": "missing_api_key",
  "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. A key that is recognized but inactive gets this same Api key needed body with reason invalid_api_key.

403 Forbidden — invalid key (code FORBIDDEN)

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

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",
  "reason": "insufficient_tier",
  "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.

403 Forbidden — account suspended (code ACCOUNT_SUSPENDED)

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Account flagged for suspicious activity, check email or contact support",
  "code": "ACCOUNT_SUSPENDED",
  "reason": "account_suspended"
}

Action: check your email or contact support. Do not retry or upgrade — the hold applies to every key on the account.

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: wait the number of seconds in Retry-After (or until X-RateLimit-Reset), 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. Retry-After gives the seconds to wait, and X-RateLimit-Daily-Reset / X-RateLimit-Monthly-Reset give the reset times. Or upgrade.

502 Bad Gateway (code BAD_GATEWAY)

The upstream Hyperliquid endpoint timed out or returned an error. Retry with backoff. (The MCP server retries timeouts and short-lived 429s, not 502s.)

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 capped at 90 days on every tier — the cap is universal, not tier-based. How a route enforces it differs: routes with a documented since ceiling reject an overlong window with a 400 (since=<value> exceeds this route's <ceiling> ceiling), while the rest run against the capped window and may echo the range you asked for. Compare response timestamps against your requested range to detect truncation, and see data windows for the per-route ceilings. 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

Authenticated requests that pass the access and rate-limit checks are 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