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

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "crypto-sentiment": {
      "url": "https://mcp.wealthlit.xyz/mcp"
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "crypto-sentiment": {
      "url": "https://mcp.wealthlit.xyz/mcp"
    }
  }
}

Available Tools

Tool	Description
`get_social_score`	Composite sentiment score (0-100) for a coin or top 10
`get_sentiment`	Recent sentiment-scored headlines and posts
`get_sentiment_history`	Sentiment trend over time (bucketed)
`get_sentiment_batch`	Compare sentiment across multiple coins
`get_social_feed`	Social posts from Telegram, Discord, Farcaster and YouTube
`get_price`	Spot prices and 24h change for one or more coins
`get_fear_greed`	Crypto Fear & Greed Index
`get_whale_transfers`	Recent large on-chain transfers
`get_funding_rates`	Perpetual futures funding rates by venue
`get_funding_history`	Historical funding rates
`get_liquidations`	Recent liquidation events
`get_liquidation_summary`	Aggregated long vs short liquidation volumes
`get_liquidation_clusters`	Liquidations grouped by price level
`get_macro`	DXY, S&P 500, VIX values and daily changes
`get_macro_correlation`	BTC correlation with macro indicators
`list_coins`	All tracked cryptocurrencies with metadata

Resources

URI	Description
`crypto://coins`	All tracked cryptocurrencies
`crypto://scores/overview`	Top 10 sentiment scores

Authentication

The MCP server uses Auth0 for authentication. When you connect from Claude Desktop or Cursor, you will be prompted to sign in with the same credentials you use for the dashboard. Your requests are rate-limited based on your subscription tier.

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