Sentiment Shifts

Overview

Detects major sentiment shifts in crypto tokens by comparing average AI-assigned sentiment scores (0-10 per tweet) between a current period and a previous period of equal length. Only tokens with sufficient tweet volume in both periods are included for statistical relevance.

Business Value

• Early Signal Detection: Surfaces tokens with rapid sentiment reversals that often precede price movements.
• Statistical Confidence: Filters out noise by requiring minimum tweet counts, and adds confidence and signal magnitude scores.
• Bullish/Bearish Classification: The bullishRatio and sentimentShift fields make it easy to separate bullish shifts from bearish ones.
• Volume-Aware Analysis: Pairs sentiment change with volumeChange and currentPeriodAuthors to distinguish broad market attention from isolated voices.
• Configurable Lookback: The comparison_period parameter lets consumers tune the detection window to 24h, 3d, or 7d.

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	Length of the comparison. Allowed values: 24h, 3d, 7d. The current period is the last comparison_period; the previous period is the equal-length comparison_period immediately before it, in rolling UTC hours (e.g. 3d compares the last 72 hours to the 72 hours before them).
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. Range 0-10 (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. Range 0-10. Minimum 2 tweets required. An average of 0 is returned as 0.
currentPeriodTweets	integer	Number of tweets about this token in the current period. 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 the denominator for volumeChange.
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), excluding neutral 4-5 and bearish (<4). Range 0-100. >60 = bullish majority, <40 = bearish majority.
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. >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. >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.

Examples

Top sentiment shifts, limited results

Retrieves the tokens with the most significant sentiment shifts, limited to the top 3 results.

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": "IAG",
    "sentimentShift": 4.47,
    "currentSentiment": 5.8,
    "previousSentiment": 1.33,
    "currentPeriodTweets": 5,
    "previousPeriodTweets": 3,
    "currentPeriodAuthors": 4,
    "bullishRatio": 80,
    "volumeChange": 1.67,
    "qualityScore": 6,
    "volatility": 2.28,
    "confidenceScore": 8,
    "signalMagnitude": 1.96
  },
  {
    "tokenSymbol": "ZCAT",
    "sentimentShift": 2.75,
    "currentSentiment": 7,
    "previousSentiment": 4.25,
    "currentPeriodTweets": 3,
    "previousPeriodTweets": 8,
    "currentPeriodAuthors": 2,
    "bullishRatio": 100,
    "volumeChange": 0.38,
    "qualityScore": 9,
    "volatility": 2.65,
    "confidenceScore": 3.81,
    "signalMagnitude": 1.04
  },
  {
    "tokenSymbol": "CHZ",
    "sentimentShift": 2.75,
    "currentSentiment": 6,
    "previousSentiment": 3.25,
    "currentPeriodTweets": 5,
    "previousPeriodTweets": 4,
    "currentPeriodAuthors": 5,
    "bullishRatio": 100,
    "volumeChange": 1.25,
    "qualityScore": 9.4,
    "volatility": 1,
    "confidenceScore": 4.93,
    "signalMagnitude": 2.75
  }
]

This example limits results to 3 items. IAG shows the largest bullish sentiment shift (+4.47), moving from a bearish previous period (1.33) to a moderately bullish current period (5.8) with an 80% bullish tweet ratio. ZCAT and CHZ both show a +2.75 shift, but CHZ has a lower volatility (1) and a higher signal magnitude (2.75), which means its move is more statistically consistent than ZCAT's (volatility 2.65, signal magnitude 1.04).

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
2.1.0	Current	No	application/vnd.cambrian.deep42.social-data.sentiment-shifts.v2.1+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.