Token Analysis

Overview

Returns a comprehensive social intelligence report for a single cryptocurrency token. The response aggregates tweet volume, engagement, and sentiment distribution over a configurable lookback window, and includes historical correlation between bullish/bearish sentiment signals and subsequent price movement at the 24-hour, 7-day, and 30-day horizons.

Business Value

• Sentiment-Price Correlation: Measures how accurately bullish and bearish social signals predicted subsequent price direction at 24h, 7d, and 30d horizons over a trailing 90-day window
• Engagement Benchmarking: Aggregates likes, retweets, replies, and views (totals and per-tweet averages) to quantify how much attention a token is generating
• Sentiment Distribution: Breaks tweets into very bullish, bullish, neutral, and bearish buckets to gauge market consensus versus division
• Flexible Time Resolution: Choose a single aggregate snapshot (total) or time-series buckets from 1 hour to 365 days to track how sentiment evolves over time
• Data Quality Safeguards: Automatically withholds analysis for tokens with insufficient tweet volume or author diversity, so thin data doesn't produce misleading conclusions

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	-	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, not rejected). Non-integer values return a 400. In v2.1 and later, the window is exactly days_back × 24 hours, in UTC.
granularity	string	No	total	Aggregation granularity. Use total for a single aggregate object, or a fixed bucket width 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

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. In v2.1 and later, days are UTC dates, so a window of N days can touch N + 1 dates.
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 Token Specified)

Demonstrates the default aggregate (granularity=total) response when token_symbol is omitted. The request defaults to SOL, and the response shows this with tokenSymbolDefaulted: true.

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": 1714,
  "uniqueAuthors": 966,
  "avgSentiment": 6.19,
  "avgAlpha": 1.55,
  "sentimentVolatility": 1.46,
  "totalLikes": 71422,
  "totalRetweets": 18669,
  "totalReplies": 29598,
  "totalViews": 4637395,
  "totalEngagement": 119689,
  "engagementRate": 2.58,
  "avgLikesPerTweet": 41.7,
  "avgRetweetsPerTweet": 10.9,
  "veryBullishTweets": 369,
  "bullishTweets": 706,
  "neutralTweets": 595,
  "bearishTweets": 44,
  "veryBullishPct": 21.5,
  "bullishPct": 41.2,
  "neutralPct": 34.7,
  "bearishPct": 2.6,
  "firstTweet": "2026-09-23T07:23:59+00:00",
  "latestTweet": "2026-09-30T12:00:03+00:00",
  "activeDays": 8,
  "analysisPeriodDays": 7,
  "priceCorrelationBullishAccuracy24h": 55.3,
  "priceCorrelationBullishAccuracy7d": 57,
  "priceCorrelationBullishAccuracy30d": 72.8,
  "priceCorrelationBearishAccuracy24h": 46.6,
  "priceCorrelationBearishAccuracy7d": 42,
  "priceCorrelationBearishAccuracy30d": 32.6,
  "priceCorrelationBullishAvgReturn24h": 0.49,
  "priceCorrelationBullishAvgReturn7d": 3.37,
  "priceCorrelationBullishAvgReturn30d": 14.91,
  "priceCorrelationBearishAvgReturn24h": 0.27,
  "priceCorrelationBearishAvgReturn7d": 2.83,
  "priceCorrelationBearishAvgReturn30d": 13.77,
  "priceCorrelationBullishSignals": 10520,
  "priceCorrelationBearishSignals": 1664,
  "priceCorrelationEnrichedSignals": 11400,
  "priceCorrelationPendingSignals": 784,
  "priceCorrelationFirstSignalDate": "2026-07-02",
  "priceCorrelationLastSignalDate": "2026-09-30",
  "tokenSymbolDefaulted": true
}

This result covers the default 7-day window for SOL: 1,714 high-quality tweets from 966 unique authors, a moderately bullish average sentiment of 6.19, and a bullish-tilted distribution (21.5% very bullish, 41.2% bullish, 34.7% neutral, 2.6% bearish). Over the trailing 90-day price-correlation window, bullish signals were right 55.3% of the time at 24h, rising to 72.8% at 30d.

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 to 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	No	application/vnd.cambrian.deep42.social-data.token-analysis.v1+json
2.0.0	Current	Yes	application/vnd.cambrian.deep42.social-data.token-analysis.v2+json
2.1.0	Current	No	application/vnd.cambrian.deep42.social-data.token-analysis.v2.1+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 (2.0.0) is returned.

---

Related Endpoints

• /deep42/social-data/alpha-tweet-detection - Feed of tweets scored for alpha potential, sentiment, legitimacy, and technical accuracy
• /deep42/social-data/influencer-credibility - Ranks cryptocurrency influencers by historical directional-price accuracy
• /deep42/social-data/sentiment-shifts - Detects tokens with significant sentiment changes between two time periods
• /deep42/social-data/trending-momentum - Identifies tokens with rapidly increasing social signals and momentum