Cambrian Detect major sentiment shifts in crypto tokens API

By Cambrian Network deep42

GET /api/v1/deep42/social-data/sentiment-shifts

Sentiment Shifts

Overview

The Sentiment Shifts endpoint identifies tokens with significant sentiment changes that could signal market movements and trading opportunities. It compares average AI-assigned sentiment scores (0-10 per tweet) between a current period and a previous period of equal length, and it returns only tokens with sufficient tweet volume in both periods so the comparison stays statistically relevant.

Business Value

  • Early Market Signal Detection: Catch sentiment shifts before they translate to price movements, giving traders a potential timing advantage
  • Risk Management: Identify tokens experiencing bearish sentiment shifts that may warrant position adjustments or increased monitoring
  • Portfolio Opportunity Discovery: Find tokens with improving sentiment that could represent new investment opportunities
  • Data-Driven Decision Making: Replace gut feelings about market sentiment with quantified, statistical analysis of social media conversations
  • Statistical Validation: Only includes tokens with sufficient tweet volume in both periods for statistically relevant sentiment comparisons

Endpoint Details

URL:

https://api.cambrian.org/deep42/social-data/sentiment-shifts

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

Query Parameters

Parameter Type Required Default Description
comparison_period string No 3d Period to compare against. One of 24h, 3d, 7d
limit integer No 20 Number of tokens to return (maximum 50)

Response Field Descriptions

Response Field Type Description
tokenSymbol string Cryptocurrency token symbol (e.g., BTC, ETH, SOL)
sentimentShift number Change in average sentiment between current and previous period. Calculated as currentSentiment - previousSentiment. Range: -10 to +10. Positive = bullish shift, negative = bearish shift. >2 = notable, >5 = major shift
currentSentiment number Average AI-assigned sentiment score across all tweets about this token in the current period (last 24 hours). Range 0-10. Each tweet is independently scored: 0 = very bearish, 5 = neutral, 10 = very bullish. Minimum 3 tweets required
previousSentiment number Average AI-assigned sentiment score across all tweets in the previous period (from comparison_period ago to 24h ago). Range 0-10. Minimum 2 tweets required
currentPeriodTweets integer Number of tweets about this token in the current period (last 24 hours). Higher counts indicate more active discussion and more reliable sentiment averages
previousPeriodTweets integer Number of tweets about this token in the previous period. Used as denominator for volumeChange calculation
currentPeriodAuthors integer Number of distinct authors discussing this token in the current period. Higher counts indicate broader market attention rather than a single voice driving sentiment
bullishRatio number Percentage of current-period tweets with bullish sentiment (score >=6). Range 0-100. >60 = bullish majority, <40 = bearish majority. Calculated from tweets scoring >=6 (bullish) vs <4 (bearish), excluding neutral 4-5
volumeChange number Ratio of current period tweet count to previous period. 1.0 = unchanged, 2.0 = doubled, 0.5 = halved. >1.5 = significant increase in discussion volume
qualityScore number Sum of average sentiment + average alpha for current period tweets. Range 0-20. Indicates both directional conviction and content quality. >10 = above-average, >15 = high quality
volatility number Standard deviation of sentiment scores within the current period. Range 0-5. <1 = strong consensus among authors, >2 = highly divided opinions
confidenceScore number Confidence in the detected shift. Calculated as log(tweet_count + 1) * abs(sentiment_shift). Accounts for both sample size and shift magnitude. Higher = more reliable signal. >3 = moderate confidence, >5 = high confidence
signalMagnitude number Shift magnitude normalized by volatility. Calculated as abs(sentiment_shift) / max(volatility, 1). >1 = shift exceeds normal variance, >2 = shift is 2x normal variance. Higher values indicate more statistically meaningful shifts

Examples

Detecting Recent Major Sentiment Shifts

This example retrieves the top tokens with significant sentiment shifts using the default 3-day comparison period. Results are limited to 3 items for this example.

curl -X GET "https://api.cambrian.org/deep42/social-data/sentiment-shifts?limit=3" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

[
  {
    "tokenSymbol": "AVICI",
    "sentimentShift": 3.07,
    "currentSentiment": 6.67,
    "previousSentiment": 3.6,
    "currentPeriodTweets": 3,
    "previousPeriodTweets": 10,
    "currentPeriodAuthors": 3,
    "bullishRatio": 100,
    "volumeChange": 0.3,
    "qualityScore": 6.67,
    "volatility": 1.15,
    "confidenceScore": 4.25,
    "signalMagnitude": 2.66
  },
  {
    "tokenSymbol": "WMTX",
    "sentimentShift": 2.85,
    "currentSentiment": 7.18,
    "previousSentiment": 4.33,
    "currentPeriodTweets": 11,
    "previousPeriodTweets": 3,
    "currentPeriodAuthors": 10,
    "bullishRatio": 100,
    "volumeChange": 3.67,
    "qualityScore": 10.36,
    "volatility": 1.25,
    "confidenceScore": 7.08,
    "signalMagnitude": 2.28
  },
  {
    "tokenSymbol": "RAVE",
    "sentimentShift": -2.58,
    "currentSentiment": 4.67,
    "previousSentiment": 7.25,
    "currentPeriodTweets": 6,
    "previousPeriodTweets": 4,
    "currentPeriodAuthors": 5,
    "bullishRatio": 60,
    "volumeChange": 1.5,
    "qualityScore": 7.5,
    "volatility": 3.01,
    "confidenceScore": 5.03,
    "signalMagnitude": 0.86
  }
]

AVICI shows the strongest bullish shift (+3.07) despite a drop in tweet volume. WMTX combines a large positive shift (+2.85) with tripled tweet volume and the highest confidence score (7.08), which points to a well-supported bullish signal. RAVE shows a bearish reversal (-2.58), with lower confidence and a smaller, less consistent move.

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/sentiment-shifts"
);
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/sentiment-shifts")
        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 No application/vnd.cambrian.deep42.social-data.sentiment-shifts.v1+json
2.0.0 Current Yes application/vnd.cambrian.deep42.social-data.sentiment-shifts.v2+json

How to Request a Specific Version

curl -X GET "https://api.cambrian.org/deep42/social-data/sentiment-shifts" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/vnd.cambrian.deep42.social-data.sentiment-shifts.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 detected as having high alpha potential for cryptocurrency investments, scored across sentiment, alpha, legitimacy, and technical accuracy
  • /deep42/social-data/influencer-credibility - Direct array of cryptocurrency influencers with recent activity and historical directional-price metrics
  • /deep42/social-data/token-analysis - Comprehensive social intelligence report for a cryptocurrency token with sentiment analysis
  • /deep42/social-data/trending-momentum - Identifies tokens with rapidly increasing social signals and momentum indicators