Cambrian Deep social analysis for a specific token API

By Cambrian Network deep42

GET /api/v1/deep42/social-data/token-analysis

Token Analysis

Overview

Comprehensive social intelligence report for a cryptocurrency token, combining sentiment analysis, engagement metrics, and sentiment-to-price correlation. Supports both a single aggregate snapshot (granularity=total) and time-series breakdowns (e.g. hourly or daily buckets) for trend analysis.

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, 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. Supported range: 1h to 365d. Time-series buckets are returned most-recent first, up to 1000.

Response Field Descriptions

Aggregate response (granularity=total)

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
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
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
tokenSymbolDefaulted Boolean True when token_symbol was omitted and the analysis defaulted to SOL
priceCorrelationBullishAccuracy24h/7d/30d Number % of bullish signals followed by a price increase after 24h/7d/30d
priceCorrelationBearishAccuracy24h/7d/30d Number % of bearish signals followed by a price decrease after 24h/7d/30d
priceCorrelationBullishAvgReturn24h/7d/30d Number Average % return after a bullish signal at each horizon
priceCorrelationBearishAvgReturn24h/7d/30d Number Average % return after a bearish signal at each horizon
priceCorrelationBullishSignals Integer Total bullish sentiment signals tracked over the trailing 90-day correlation window
priceCorrelationBearishSignals Integer Total bearish sentiment signals tracked over the trailing 90-day correlation window
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)

Time-series response (granularity != total)

Response Field Type Description
tokenSymbol String Token symbol analyzed
granularity String Echo of the requested (normalized) granularity, e.g. 1d
analysisPeriodDays Integer Days looked back
tokenSymbolDefaulted Boolean True when token_symbol was omitted and the analysis defaulted to SOL
bucketCount Integer Number of time buckets returned in this response
maxBuckets Integer Maximum buckets returnable in a single response (row cap)
truncated Boolean True when the oldest buckets were dropped due to the row cap
timeseries[].timeBucket String Bucket start timestamp (inclusive), UTC
timeseries[].tweetsCount Integer High-quality tweets in this bucket
timeseries[].uniqueAuthors Integer Distinct authors in this bucket
timeseries[].avgSentiment Number Average sentiment score for the bucket. Range 0-10
timeseries[].avgAlpha Number Average alpha score for the bucket. Range 0-10
timeseries[].totalLikes Integer Total likes in this bucket
timeseries[].totalRetweets Integer Total retweets in this bucket
timeseries[].totalReplies Integer Total replies in this bucket
timeseries[].totalViews Integer Total views in this bucket
timeseries[].veryBullish Integer Count of tweets with sentiment >= 8
timeseries[].bullish Integer Count of tweets with sentiment 6-7.9
timeseries[].neutral Integer Count of tweets with sentiment 4-5.9
timeseries[].bearish Integer Count of tweets with sentiment < 4

Examples

1. Aggregate Social Analysis for a Major Token

Fetches a single aggregate social intelligence snapshot for BTC over the last 7 days, including sentiment breakdown, engagement metrics, and sentiment-to-price correlation.

curl -X GET "https://api.cambrian.org/deep42/social-data/token-analysis?token_symbol=BTC&days_back=7" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "tokenSymbol": "BTC",
  "totalTweets": 204,
  "uniqueAuthors": 118,
  "avgSentiment": 5.64,
  "avgAlpha": 7.09,
  "sentimentVolatility": 2.82,
  "totalLikes": 10769,
  "totalRetweets": 990,
  "totalReplies": 2252,
  "totalViews": 1321368,
  "totalEngagement": 14011,
  "engagementRate": 1.06,
  "avgLikesPerTweet": 52.8,
  "avgRetweetsPerTweet": 4.9,
  "veryBullishTweets": 84,
  "bullishTweets": 39,
  "neutralTweets": 17,
  "bearishTweets": 64,
  "veryBullishPct": 41.2,
  "bullishPct": 19.1,
  "neutralPct": 8.3,
  "bearishPct": 31.4,
  "firstTweet": "2026-07-28T07:39:27+00:00",
  "latestTweet": "2026-08-04T17:48:40+00:00",
  "activeDays": 8,
  "analysisPeriodDays": 7,
  "priceCorrelationBullishAccuracy24h": 49.8,
  "priceCorrelationBullishAccuracy7d": 36.4,
  "priceCorrelationBullishAccuracy30d": 35.3,
  "priceCorrelationBearishAccuracy24h": 51.5,
  "priceCorrelationBearishAccuracy7d": 65,
  "priceCorrelationBearishAccuracy30d": 62.9,
  "priceCorrelationBullishAvgReturn24h": -0.26,
  "priceCorrelationBullishAvgReturn7d": -1.97,
  "priceCorrelationBullishAvgReturn30d": -10.36,
  "priceCorrelationBearishAvgReturn24h": -0.37,
  "priceCorrelationBearishAvgReturn7d": -2.1,
  "priceCorrelationBearishAvgReturn30d": -9.08,
  "priceCorrelationBullishSignals": 14000,
  "priceCorrelationBearishSignals": 6843,
  "priceCorrelationEnrichedSignals": 19020,
  "priceCorrelationPendingSignals": 1823,
  "priceCorrelationFirstSignalDate": "2026-05-07",
  "priceCorrelationLastSignalDate": "2026-08-04"
}

BTC shows mixed sentiment (avgSentiment 5.64/10) with high volatility (2.82), driven by a near-even split between very bullish (41.2%) and bearish (31.4%) tweets. Note that price-correlation metrics (priceCorrelationBullish*/Bearish*) are computed over a fixed trailing 90-day window and are not directly comparable to the 7-day totalTweets figure.

2. Daily Time-Series Sentiment for a Token

Fetches daily sentiment and engagement buckets for SOL over the last 7 days, useful for tracking sentiment trends over time.

curl -X GET "https://api.cambrian.org/deep42/social-data/token-analysis?token_symbol=SOL&days_back=7&granularity=1d" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "tokenSymbol": "SOL",
  "granularity": "1d",
  "analysisPeriodDays": 7,
  "bucketCount": 8,
  "maxBuckets": 1000,
  "truncated": false,
  "timeseries": [
    {
      "timeBucket": "2026-08-04 00:00:00+00",
      "tweetsCount": 22,
      "uniqueAuthors": 19,
      "avgSentiment": 8.27,
      "avgAlpha": 7.32,
      "totalLikes": 1115,
      "totalRetweets": 95,
      "totalReplies": 339,
      "totalViews": 140462,
      "veryBullish": 19,
      "bullish": 3,
      "neutral": 0,
      "bearish": 0
    },
    {
      "timeBucket": "2026-08-03 00:00:00+00",
      "tweetsCount": 25,
      "uniqueAuthors": 19,
      "avgSentiment": 8.04,
      "avgAlpha": 7.68,
      "totalLikes": 1726,
      "totalRetweets": 193,
      "totalReplies": 252,
      "totalViews": 140049,
      "veryBullish": 19,
      "bullish": 6,
      "neutral": 0,
      "bearish": 0
    },
    {
      "timeBucket": "2026-08-02 00:00:00+00",
      "tweetsCount": 10,
      "uniqueAuthors": 10,
      "avgSentiment": 7.5,
      "avgAlpha": 7.2,
      "totalLikes": 195,
      "totalRetweets": 10,
      "totalReplies": 85,
      "totalViews": 9158,
      "veryBullish": 9,
      "bullish": 0,
      "neutral": 0,
      "bearish": 1
    },
    {
      "timeBucket": "2026-08-01 00:00:00+00",
      "tweetsCount": 4,
      "uniqueAuthors": 4,
      "avgSentiment": 8.75,
      "avgAlpha": 7,
      "totalLikes": 162,
      "totalRetweets": 25,
      "totalReplies": 63,
      "totalViews": 24726,
      "veryBullish": 4,
      "bullish": 0,
      "neutral": 0,
      "bearish": 0
    },
    {
      "timeBucket": "2026-07-31 00:00:00+00",
      "tweetsCount": 8,
      "uniqueAuthors": 7,
      "avgSentiment": 7.5,
      "avgAlpha": 7,
      "totalLikes": 577,
      "totalRetweets": 42,
      "totalReplies": 212,
      "totalViews": 47325,
      "veryBullish": 6,
      "bullish": 1,
      "neutral": 0,
      "bearish": 1
    },
    {
      "timeBucket": "2026-07-30 00:00:00+00",
      "tweetsCount": 25,
      "uniqueAuthors": 22,
      "avgSentiment": 8.32,
      "avgAlpha": 7.28,
      "totalLikes": 2234,
      "totalRetweets": 409,
      "totalReplies": 631,
      "totalViews": 194881,
      "veryBullish": 21,
      "bullish": 4,
      "neutral": 0,
      "bearish": 0
    },
    {
      "timeBucket": "2026-07-29 00:00:00+00",
      "tweetsCount": 22,
      "uniqueAuthors": 20,
      "avgSentiment": 8.23,
      "avgAlpha": 7.32,
      "totalLikes": 433,
      "totalRetweets": 43,
      "totalReplies": 216,
      "totalViews": 46045,
      "veryBullish": 20,
      "bullish": 1,
      "neutral": 0,
      "bearish": 1
    },
    {
      "timeBucket": "2026-07-28 00:00:00+00",
      "tweetsCount": 16,
      "uniqueAuthors": 12,
      "avgSentiment": 8.19,
      "avgAlpha": 7.13,
      "totalLikes": 687,
      "totalRetweets": 98,
      "totalReplies": 120,
      "totalViews": 68401,
      "veryBullish": 12,
      "bullish": 4,
      "neutral": 0,
      "bearish": 0
    }
  ]
}

SOL shows consistently strong bullish sentiment across all 8 daily buckets (avgSentiment ranging 7.5-8.75/10), with almost no bearish activity — contrasting with BTC's more divided sentiment in Example 1. truncated: false confirms all requested days fit within the 1000-bucket cap.

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")
        # Optional: add query_params for filtering
        # query_params: { limit: 100 }
        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–5 automatically.

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

Related Endpoints

  • /deep42/social-data/alpha-tweet-detection - Feed of tweets detected as having high alpha potential for cryptocurrency investments, scored on sentiment, alpha, legitimacy, and technical accuracy.
  • /deep42/social-data/influencer-credibility - Returns cryptocurrency influencers ranked by credibility score, track record, accuracy, and engagement metrics.
  • /deep42/social-data/sentiment-shifts - Identifies tokens with significant sentiment changes that could signal market movements and trading opportunities.