Cambrian Detect major sentiment shifts in crypto tokens API

By Cambrian Network deep42

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

Sentiment Shifts

Overview

Identifies tokens with significant sentiment changes that could signal market movements and trading opportunities. It compares the average AI-assigned sentiment score (0-10 per tweet) for each token between the current period (the last 24 hours) and a previous period set by comparison_period. In v2.1 and later, the two periods are of equal length: the last comparison_period and the comparison_period before it, in rolling UTC hours. Only tokens with sufficient tweet volume in both periods are included for statistical relevance.

Business Value

  • Early signal detection: Surfaces tokens with sharp bullish or bearish sentiment swings before they show up in price action.
  • Volume-aware filtering: Requires minimum tweet counts in both periods, which reduces noise from low-activity tokens.
  • Confidence scoring: Combines shift magnitude with sample size and volatility so traders can prioritize the most reliable signals.
  • Flexible time windows: Supports 24h, 3d, and 7d comparison periods to match different trading horizons.
  • Author breadth tracking: Distinguishes broad market attention from single-voice-driven sentiment shifts.

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 window. Allowed values: 24h, 3d, 7d. In v2.1 and later, the current period is the last comparison_period and the previous period is the equal-length comparison_period immediately before it, in rolling UTC hours (e.g. 3d = last 72 hours vs. the prior 72 hours). Before v3, any other value is treated as 3d; in v3 and later, any other value returns 400.
limit integer No 20 Number of tokens to return. Maximum 300.

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 (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 tweets in the current period. Range 0-10 (0 = very bearish, 5 = neutral, 10 = very bullish). Minimum 3 tweets required. In v2.1 and later, the current period is the last comparison_period.
previousSentiment number Average AI-assigned sentiment score across tweets in the previous period. Range 0-10. Minimum 2 tweets required. In v2.1 and later, the previous period is the equal-length comparison_period before the current period, and an average of 0 is returned as 0 (rather than 5).
currentPeriodTweets integer Number of tweets about this token in the current period. Higher counts indicate more reliable sentiment averages. In v2.1 and later, the current period is the last comparison_period.
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). 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. >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

Detecting major sentiment shifts

Fetches the top 3 tokens with the most significant sentiment shifts using the default 3-day comparison window.

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": "REAL",
    "sentimentShift": 4.33,
    "currentSentiment": 7.33,
    "previousSentiment": 3,
    "currentPeriodTweets": 3,
    "previousPeriodTweets": 2,
    "currentPeriodAuthors": 3,
    "bullishRatio": 100,
    "volumeChange": 1.5,
    "qualityScore": 8.33,
    "volatility": 1.53,
    "confidenceScore": 6.01,
    "signalMagnitude": 2.84
  },
  {
    "tokenSymbol": "ZENT",
    "sentimentShift": -4,
    "currentSentiment": 4,
    "previousSentiment": 8,
    "currentPeriodTweets": 4,
    "previousPeriodTweets": 2,
    "currentPeriodAuthors": 3,
    "bullishRatio": 0,
    "volumeChange": 2,
    "qualityScore": 4,
    "volatility": 2,
    "confidenceScore": 6.44,
    "signalMagnitude": 2
  },
  {
    "tokenSymbol": "WTH",
    "sentimentShift": 3,
    "currentSentiment": 7,
    "previousSentiment": 4,
    "currentPeriodTweets": 6,
    "previousPeriodTweets": 2,
    "currentPeriodAuthors": 5,
    "bullishRatio": 100,
    "volumeChange": 3,
    "qualityScore": 9.17,
    "volatility": 1.26,
    "confidenceScore": 5.84,
    "signalMagnitude": 2.37
  }
]

The limit=3 parameter limits the results to 3 items. REAL shows the strongest bullish shift (+4.33), ZENT the strongest bearish shift (-4), and WTH a moderate bullish shift (+3), each with its own confidence and signal-magnitude score.

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 No application/vnd.cambrian.deep42.social-data.sentiment-shifts.v2+json
2.1.0 Current Yes application/vnd.cambrian.deep42.social-data.sentiment-shifts.v2.1+json
3.0.0 Current No application/vnd.cambrian.deep42.social-data.sentiment-shifts.v3+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 API returns the default version (2.1.0).


Related Endpoints

  • /deep42/social-data/alpha-tweet-detection - Feed of tweets scored for sentiment, alpha, legitimacy, and technical accuracy, with AI-generated reasoning per score.
  • /deep42/social-data/influencer-credibility - Cryptocurrency influencers ranked by historical directional-price accuracy and recent activity.
  • /deep42/social-data/token-analysis - Comprehensive social intelligence report for a single cryptocurrency token.
  • /deep42/social-data/trending-momentum - Identifies tokens with rapidly increasing social signals and momentum indicators.