alert_social_shift
Detect significant spikes or drops in cryptocurrency social volume to identify sudden changes in market attention for any asset.
Instructions
Detect significant shifts (spikes or drops) in social volume (social_volume_total) for a given asset.
Parameters:
asset (str): The cryptocurrency slug (e.g., "bitcoin", "ethereum"). Required.
threshold (float): Minimum percentage change (absolute value) to trigger an alert, defaults to 50.0 (i.e., 50%).
days (int): Number of days to analyze for baseline volume, defaults to 7.
Usage:
Call this tool to check if the latest social volume has significantly spiked or dropped compared to the previous average.
Returns:
A string indicating if a shift occurred (e.g., "Bitcoin's social volume spiked by 75.0% in the last 24 hours" or "Bitcoin's social volume dropped by 60.0% in the last 24 hours").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | ||
| threshold | No | ||
| days | No |
Implementation Reference
- main.py:116-116 (registration)The @mcp.tool() decorator registers the alert_social_shift tool with the FastMCP server.
@mcp.tool() - main.py:117-150 (handler)The core handler function that implements the alert_social_shift tool logic: fetches social volume data, computes percentage change from prior average, and returns an alert message if the change exceeds the threshold.
def alert_social_shift(asset: str, threshold: float = 50.0, days: int = 7) -> str: """ Detect significant shifts (spikes or drops) in social volume (social_volume_total) for a given asset. Parameters: - asset (str): The cryptocurrency slug (e.g., "bitcoin", "ethereum"). Required. - threshold (float): Minimum percentage change (absolute value) to trigger an alert, defaults to 50.0 (i.e., 50%). - days (int): Number of days to analyze for baseline volume, defaults to 7. Usage: - Call this tool to check if the latest social volume has significantly spiked or dropped compared to the previous average. Returns: - A string indicating if a shift occurred (e.g., "Bitcoin's social volume spiked by 75.0% in the last 24 hours" or "Bitcoin's social volume dropped by 60.0% in the last 24 hours"). """ try: data = fetch_santiment_data("social_volume_total", asset, days) timeseries = data.get("data", {}).get("getMetric", {}).get("timeseriesData", []) if not timeseries or len(timeseries) < 2: return f"Unable to detect social volume shift for {asset}, insufficient data." latest_volume = int(timeseries[-1]["value"]) # Latest day's volume prev_avg_volume = sum(int(d["value"]) for d in timeseries[:-1]) / (len(timeseries) - 1) # Average of previous days change_percent = ((latest_volume - prev_avg_volume) / prev_avg_volume) * 100 abs_change = abs(change_percent) if abs_change >= threshold: direction = "spiked" if change_percent > 0 else "dropped" return f"{asset.capitalize()}'s social volume {direction} by {abs_change:.1f}% in the last 24 hours, from an average of {prev_avg_volume:,.0f} to {latest_volume:,}." return f"No significant shift detected for {asset.capitalize()}, change is {change_percent:.1f}%." except Exception as e: return f"Error detecting social volume shift for {asset}: {str(e)}" - main.py:16-42 (helper)Supporting helper function to query Santiment GraphQL API for timeseries metric data (e.g., social_volume_total), which is called by alert_social_shift.
def fetch_santiment_data(metric: str, asset: str, days: int) -> dict: now = datetime.now(UTC) to_date = now from_date = to_date - timedelta(days=days) query = f""" {{ getMetric(metric: "{metric}") {{ timeseriesData( slug: "{asset}" from: "{from_date.isoformat()}" to: "{to_date.isoformat()}" interval: "1d" ) {{ datetime value }} }} }} """ response = requests.post(SANTIMENT_API_URL, json={"query": query}, headers=HEADERS) result = response.json() if result.get("errors"): raise Exception(f"API error: {result.get('errors')}") return result