Token Analysis

Overview

Comprehensive social intelligence report for a cryptocurrency token, combining sentiment, alpha, and engagement metrics with sentiment-to-price correlation analysis. It can return a single aggregate summary for a lookback window or a time-series broken into fixed-width buckets, depending on the requested granularity.

Business Value

• Real-time Market Intelligence: Access curated insights from 38K high-quality DeFi tweets to identify emerging trends and sentiment shifts
• Multi-dimensional Scoring: Comprehensive analysis across sentiment, alpha potential, legitimacy, technical accuracy, and engagement metrics
• Investment Signal Detection: Identify potential alpha opportunities through AI-scored social media analysis from credible sources
• Risk Assessment: Evaluate content legitimacy and technical accuracy to filter out noise and misinformation
• Social Trading Insights: Track engagement metrics and content previews to understand market discourse and community sentiment

Endpoint Details

URL:

https://api.cambrian.org/deep42/social-data/token-analysis

Method: GET Authentication: Required via X-API-KEY header

Query Parameters

Parameter	Type	Required	Default	Description
token_symbol	string	No	SOL	Token symbol to analyze (e.g. BTC, ETH, SOL). Defaults to SOL when omitted; in that case the response includes tokenSymbolDefaulted=true.
days_back	integer	No	7	Number of days of history to analyze. Values are clamped to the range 1 to 730 (out-of-range values are silently clamped to the nearest bound, not rejected). Non-integer values return a 400.
granularity	string	No	total	Aggregation granularity. Use total for a single aggregate object, or a fixed bucket width expressed as <N>h (hours) or <N>d (days) for a time series, e.g. 1h, 4h, 6h, 1d, 7d, 30d. Bucket widths from 1h to 365d are supported. Time-series buckets are returned most-recent first, up to 1000.

Response Field Descriptions

Fields below apply to the default granularity=total aggregate response.

Response Field	Type	Description
tokenSymbol	string	Token symbol analyzed
totalTweets	integer	Total high-quality tweets in the analysis period
uniqueAuthors	integer	Number of unique authors discussing this token
avgSentiment	number	Average sentiment score. Range 0-10. 0 = very bearish, 5 = neutral, 10 = very bullish
avgAlpha	number	Average alpha (novelty/actionability) score. Range 0-10. Higher = more novel and actionable insights
sentimentVolatility	number	Standard deviation of sentiment scores. Range 0-5. <1 = strong consensus, >2 = highly divided opinions
totalLikes	integer	Total likes across all tweets
totalRetweets	integer	Total retweets across all tweets
totalReplies	integer	Total replies across all tweets
totalViews	integer	Total views across all tweets
totalEngagement	integer	Total engagement (likes + retweets + replies)
engagementRate	number	Engagement as a percentage of views: (likes + retweets + replies) / views * 100. Typically 0-100; values above ~5 indicate above-average engagement
avgLikesPerTweet	number	Average likes per tweet
avgRetweetsPerTweet	number	Average retweets per tweet
veryBullishTweets	integer	Count of tweets with sentiment >= 8
bullishTweets	integer	Count of tweets with sentiment 6-7.9
neutralTweets	integer	Count of tweets with sentiment 4-5.9
bearishTweets	integer	Count of tweets with sentiment < 4
veryBullishPct	number	Percentage of very bullish tweets. Range 0-100
bullishPct	number	Percentage of bullish tweets. Range 0-100
neutralPct	number	Percentage of neutral tweets. Range 0-100
bearishPct	number	Percentage of bearish tweets. Range 0-100
firstTweet	string	Timestamp of earliest tweet in the period
latestTweet	string	Timestamp of most recent tweet in the period
activeDays	integer	Number of days with at least one tweet
analysisPeriodDays	integer	Total days covered by the analysis
priceCorrelationBullishAccuracy24h	number	Percentage of bullish signals followed by a price increase after 24 hours. Null when price history at this horizon is insufficient.
priceCorrelationBullishAccuracy7d	number	% of bullish signals where price increased after 7 days
priceCorrelationBullishAccuracy30d	number	% of bullish signals where price increased after 30 days
priceCorrelationBearishAccuracy24h	number	% of bearish signals where price decreased after 24 hours
priceCorrelationBearishAccuracy7d	number	% of bearish signals where price decreased after 7 days
priceCorrelationBearishAccuracy30d	number	% of bearish signals where price decreased after 30 days
priceCorrelationBullishAvgReturn24h	number	Average % return 24 hours after bullish signal
priceCorrelationBullishAvgReturn7d	number	Average % return 7 days after bullish signal
priceCorrelationBullishAvgReturn30d	number	Average % return 30 days after bullish signal
priceCorrelationBearishAvgReturn24h	number	Average % return 24 hours after bearish signal
priceCorrelationBearishAvgReturn7d	number	Average % return 7 days after bearish signal
priceCorrelationBearishAvgReturn30d	number	Average % return 30 days after bearish signal
priceCorrelationBullishSignals	integer	Total bullish sentiment signals tracked over the trailing 90-day correlation window; not directly comparable to totalTweets, which counts tweets in the requested period
priceCorrelationBearishSignals	integer	Total bearish sentiment signals tracked over the trailing 90-day correlation window; not directly comparable to totalTweets, which counts tweets in the requested period
priceCorrelationEnrichedSignals	integer	Signals with completed price data
priceCorrelationPendingSignals	integer	Signals awaiting price data
priceCorrelationFirstSignalDate	string	Earliest signal date (YYYY-MM-DD)
priceCorrelationLastSignalDate	string	Latest signal date (YYYY-MM-DD)
tokenSymbolDefaulted	boolean	True when token_symbol was omitted and the analysis defaulted to SOL

Examples

Default Token Analysis (no parameters)

Calling the endpoint with no query parameters defaults token_symbol to SOL, days_back to 7, and granularity to total, and it returns a single aggregate social intelligence report.

curl -X GET "https://api.cambrian.org/deep42/social-data/token-analysis" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "tokenSymbol": "SOL",
  "totalTweets": 176,
  "uniqueAuthors": 133,
  "avgSentiment": 7.62,
  "avgAlpha": 7.24,
  "sentimentVolatility": 1.87,
  "totalLikes": 9064,
  "totalRetweets": 962,
  "totalReplies": 2025,
  "totalViews": 1097735,
  "totalEngagement": 12051,
  "engagementRate": 1.1,
  "avgLikesPerTweet": 51.5,
  "avgRetweetsPerTweet": 5.5,
  "veryBullishTweets": 123,
  "bullishTweets": 41,
  "neutralTweets": 2,
  "bearishTweets": 10,
  "veryBullishPct": 69.9,
  "bullishPct": 23.3,
  "neutralPct": 1.1,
  "bearishPct": 5.7,
  "firstTweet": "2026-08-27T10:23:07+00:00",
  "latestTweet": "2026-09-03T12:17:45+00:00",
  "activeDays": 8,
  "analysisPeriodDays": 7,
  "priceCorrelationBullishAccuracy24h": 55.4,
  "priceCorrelationBullishAccuracy7d": 63.4,
  "priceCorrelationBullishAccuracy30d": 70.2,
  "priceCorrelationBearishAccuracy24h": 42.9,
  "priceCorrelationBearishAccuracy7d": 35.6,
  "priceCorrelationBearishAccuracy30d": 32.4,
  "priceCorrelationBullishAvgReturn24h": 0.73,
  "priceCorrelationBullishAvgReturn7d": 4.31,
  "priceCorrelationBullishAvgReturn30d": 9.11,
  "priceCorrelationBearishAvgReturn24h": 0.76,
  "priceCorrelationBearishAvgReturn7d": 4.27,
  "priceCorrelationBearishAvgReturn30d": 8.98,
  "priceCorrelationBullishSignals": 11731,
  "priceCorrelationBearishSignals": 1714,
  "priceCorrelationEnrichedSignals": 10044,
  "priceCorrelationPendingSignals": 3401,
  "priceCorrelationFirstSignalDate": "2026-06-05",
  "priceCorrelationLastSignalDate": "2026-09-03",
  "tokenSymbolDefaulted": true
}

tokenSymbolDefaulted: true confirms token_symbol was omitted and the report defaulted to SOL. Over the trailing 7-day window, SOL shows strongly bullish sentiment (avgSentiment 7.62, 69.9% very bullish tweets) with moderate sentiment-to-price predictive accuracy that improves at longer horizons (55.4% at 24h up to 70.2% at 30d for bullish signals).

x402 Payment Option

This endpoint supports pay-per-use access via the x402 payment protocol (v2): pay $0.05 USDC per request using blockchain micropayments. No API key required.

Quick Start (TypeScript)

npm install @x402/fetch @x402/evm viem

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment(
  "https://x402.cambrian.org/deep42/social-data/token-analysis"
);
const data = await response.json();

Quick Start (Python)

pip install "x402[httpx]"

import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

async def main():
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    async with x402HttpxClient(client) as http:
        response = await http.get("https://x402.cambrian.org/deep42/social-data/token-analysis")
        print(response.json())

asyncio.run(main())

Payment Flow

1. Send a normal request to the endpoint (no API key needed)
2. Server returns 402 Payment Required with payment details
3. The x402 SDK automatically signs a payment authorization with your wallet
4. The SDK resubmits the request with the signed payment
5. Server verifies payment and returns the API response

The x402 SDK handles steps 2 through 5 automatically.

Network: Base (chain ID 8453) | Currency: USDC | Price: $0.05 per request

---

API Versioning

This endpoint supports multiple API versions. Use the Accept header to request a specific version.

Available Versions

Version	State	Default	Accept Header
1.0.0	Current	Yes	application/vnd.cambrian.deep42.social-data.token-analysis.v1+json
2.0.0	Current	No	application/vnd.cambrian.deep42.social-data.token-analysis.v2+json

How to Request a Specific Version

curl -X GET "https://api.cambrian.org/deep42/social-data/token-analysis" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/vnd.cambrian.deep42.social-data.token-analysis.v1+json"

Version Lifecycle

• Current: Actively maintained and recommended for new integrations
• Deprecated: Still functional but scheduled for removal (check deprecated_at)
• Sunset: No longer available (returns 410 Gone)

Note: If no Accept header is specified, the default version (1.0.0) applies.

---

Related Endpoints

• /deep42/social-data/alpha-tweet-detection - Feed of tweets scored for sentiment, alpha, legitimacy, and technical accuracy, with AI-generated reasoning
• /deep42/social-data/sentiment-shifts - Identifies tokens with significant sentiment changes between two periods that could signal market movements
• /deep42/social-data/trending-momentum - Identifies tokens with rapidly increasing social signals and momentum indicators
• /deep42/social-data/influencer-credibility - Returns cryptocurrency influencers ranked by historical directional-price accuracy of their calls