API Documentation

Complete reference for the WealthLit Crypto Intelligence API. Real-time sentiment scores, social feeds, on-chain analytics, perpetual futures data, and more.

Getting Started

Base URL

https://api.wealthlit.xyz/v1

Response Format

All responses are JSON. Successful responses return 200 (or 201 for creation, 204 for deletion). Every response includes an X-Request-ID header for debugging.

Quick Test

curl https://api.wealthlit.xyz/v1/ping

Authentication

Most endpoints are public and require no authentication. Endpoints marked with require an API key or JWT token.

API Key

Pass your key in the X-API-Key header. Create keys from the dashboard.

curl -H "X-API-Key: csk_your_key_here" \
  https://api.wealthlit.xyz/v1/usage

JWT Bearer Token

Auth0-issued JWT tokens are also accepted for dashboard sessions.

curl -H "Authorization: Bearer eyJhbG..." \
  https://api.wealthlit.xyz/v1/webhooks

Rate Limits

Rate limits are applied per API key, per minute. Exceeding the limit returns 429 Too Many Requests.

Tier	Requests / min
Starter (free)	60
Pro	300
Enterprise	1,000

Errors

Errors return a JSON body with a detail field.

Code	Meaning
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid credentials
404	Not found — resource does not exist
409	Conflict — duplicate resource
422	Validation error — check parameter types
429	Rate limited — slow down
500	Server error — try again later
502	Bad gateway — API temporarily unavailable

{
  "detail": "Invalid scopes. Allowed: read"
}

MCP Integration

Connect AI agents directly to live market data via the Model Context Protocol. Our MCP server exposes 16 tools and 2 resources that give Claude, Cursor, and other MCP-compatible clients native access to sentiment scores, social feeds, prices, funding rates, whale transfers, and more. Available on the Pro plan.

Full MCP Documentation

Webhook verification

Before we deliver alerts to a URL, we verify that you control that endpoint using a challenge-response flow (same pattern as Stripe, Slack, GitHub).

How it works

You create a webhook via POST /v1/webhooks.
We send a POST to your URL with a JSON body: type: "webhook.verification", challenge (random token), and webhook_id.
Your endpoint must respond with HTTP 200 and echo the challenge in the response body (e.g. { "challenge": "<same value>" }) within 5 seconds.
If we receive that, the subscription becomes active and we start delivering alerts. If not, we return 422 and the subscription stays pending_verification or, after 3 failed attempts, failed_verification.

Example endpoint (Node.js)

// Handle verification and real alerts
app.post("/webhook", (req, res) => {
  const body = req.body;
  if (body.type === "webhook.verification") {
    return res.status(200).json({ challenge: body.challenge });
  }
  // Handle real alert payload (event, coin, etc.)
  console.log("Alert:", body);
  res.status(200).send();
});

If verification fails

You get 422 Unprocessable Entity with a message like "Endpoint did not respond to verification challenge." Fix your endpoint (correct URL, return 200 and echo challenge), then call POST /v1/webhooks/{webhook_id}/verify to retry. You have up to 3 attempts per create or retry; after that the subscription is marked failed_verification and you can try again by calling the verify endpoint (which resets the attempt count).