TradingVibe API Documentation

Introduction

TradingVibe delivers real-time crypto sentiment analysis to help traders identify market trends before they're reflected in price movements. Updated every 15 minutes for major cryptocurrencies (BTC, ETH, SOL), our API combines news analysis, social media signals, and technical indicators to give you a competitive edge.

Our sentiment analysis is powered by advanced GPT reasoning models, which processes news headlines, Reddit posts, Twitter/X content, and pricing data to provide a human-like understanding of the real-time market. The API provides a comprehensive set of metrics to help you analyze current and historical market sentiment in a single snapshot:

• Sentiment scores range from -1 (very negative) to 1 (very positive), with separate values for sentiment(the overall sentiment score), news_sentiment, and social_sentiment.
• Traditonal Fear/Greed index score from 0 to 100, converted from the sentiment score (Extreme Fear, Fear, Caution, Neutral, Positive, Optimism, Extreme Greed).
• Delta metrics (delta_1h, delta_4h, delta_24h) show sentiment changes over different timeframes, helping you identify momentum in short and medium-term trends.
• Z-score metrics (z_7d, z_30d) measure how unusual the current sentiment is relative to 7-day and 30-day periods. A high positive z-score indicates unusually positive sentiment, while a negative score shows abnormally negative sentiment.
• Content metrics show how many news articles, Reddit posts, and Twitter/X posts were analyzed in each snapshot.
• Insight: a summary provided by our AI models analyzing the overall sentiment and key factors which influenced the current score.
• Recent articles with individual sentiment scores from trusted crypto news sources included in the current analysis.

These metrics are particularly valuable for traders looking to identify sentiment shifts, anomalies, and potential trading signals before they become obvious in price action.

The API is RESTful and returns data in JSON format. All endpoints are available through HTTPS only.

No-code? Use the dashboard!

We also offer a sentiment dashboard where you can view current sentiment data and history for all coins. Perfect for traders who want to see the big picture without writing any code.

Quickstart Guide

curl -H 'Authorization: Bearer YOUR_API_KEY' https://tradingvibe.io/api/v1/sentiment/coins/btc

Request API Access

Authentication

All API requests require authentication with an API key, which can be included in one of two ways:

https://tradingvibe.io/api/v1/sentiment/coins/btc?apiKey=YOUR_API_KEY&include=articles

curl -H "Authorization: Bearer YOUR_API_KEY" https://tradingvibe.io/api/v1/sentiment/coins/btc

API URL Structure

The TradingVibe API follows RESTful principles with a resource-oriented URL structure:

Query Parameters

Use query parameters to customize your API requests:

Versioning

All API endpoints are prefixed with the version number (v1). This ensures backward compatibility as we evolve the API. Future versions may be introduced alongside the current version.

Pricing & Rate Limits

TradingVibe offers a tier‑based pricing model with a standard rate limit of 60 requests per minute for all plans. Each plan includes a monthly allocation of API requests with flexible overage options. There are no hard limits on the number of requests you can make, but you will be charged based on the overage rate for your current plan.

For non-coders, we also offer a sentiment dashboard where you can view the sentiment data for all coins. Available on all paid plans.

Endpoints

Data Model

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Here are the most common status codes you might encounter:

Error responses have the following JSON format:

{
  "error": "Error message describing what went wrong",
  "suggestion": "Suggestion for how to fix the error"
}

Common Error Examples

{
  "error": "Invalid parameter: 'from' and 'to' are not supported by the intraday endpoint. Use 'date' parameter instead, or switch to the /history endpoint for date ranges.",
  "suggestion": "Try using: /api/v1/sentiment/coins/btc/history?from=2023-09-01&to=2023-09-07"
}

{
  "error": "Invalid parameter: 'date' is not supported by the history endpoint. Use 'days', 'from', or 'to' parameters instead, or switch to the /intraday endpoint for single-day data.",
  "suggestion": "Try using: /api/v1/sentiment/coins/btc/intraday?date=2023-09-15"
}

{
  "error": "Invalid date range: Historical data is limited to 14 days maximum.",
  "suggestion": "Try using a shorter date range or use: /api/v1/sentiment/coins/btc/history?days=14"
}

{
  "error": "API key is required. Please provide your API key in the \"apiKey\" query parameter or as a Bearer token in the Authorization header.",
  "suggestion": "Add ?apiKey=YOUR_API_KEY to your request URL or include \"Authorization: Bearer YOUR_API_KEY\" in your headers."
}

{
  "error": "Invalid API key. Please check that your API key is correct and try again.",
  "suggestion": "Verify your API key is correct, or generate a new one from your dashboard at https://tradingvibe.io/dashboard."
}

{
  "error": "This API key expired on 12/15/2023.",
  "suggestion": "Generate a new API key from your dashboard at https://tradingvibe.io/dashboard or contact support to extend your current key."
}

Code Examples

Here are examples of how to use the TradingVibe API in various programming languages:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://tradingvibe.io/api/v1/sentiment/coins/btc

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://tradingvibe.io/api/v1/sentiment/coins/eth/history?days=7

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://tradingvibe.io/api/v1/sentiment/coins/eth/intraday?date=today

Webhooks

Webhooks allow you to receive real-time HTTP notifications when cryptocurrency sentiment changes meet your specified criteria. Instead of polling the API, webhooks deliver data automatically to your endpoint when conditions are triggered.

Webhooks are available on Hobby plans and above. They can be configured through your account dashboard and offer two trigger types:

Webhook Payload

When triggered, webhooks send a POST request to your specified URL with a JSON payload containing sentiment data and trigger information:

{
  "event_type": "sentiment_snapshots",
  "trigger_type": "sentiment",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "coin": "BTC",
    "interval": "15m",
    "sentiment": 0.75,
    "price": 45000,
    "price_change_24h": 2.3,
    "news_sentiment": 0.8,
    "social_sentiment": 0.7,
    "news_articles_count": 12,
    "reddit_posts_count": 24,
    "x_posts_count": 18,
    "delta_1h": 0.12,
    "delta_4h": -0.05,
    "delta_24h": 0.23,
    "z_7d": 1.2,
    "z_30d": 0.8,
    "insight": "Bitcoin sentiment remains strongly positive...",
    "threshold_met": true,
    "threshold_value": 0.5,
    "trigger_condition": "greater_than",
    "fear_greed_score": 75,
    "fear_greed_label": "Extreme Greed"
  }
}

Security

Webhooks include optional secret verification for authenticity:

Webhook Secrets

Each webhook can include an optional secret sent in the X-Webhook-Secret header. Secrets can be auto-generated (64-character cryptographically secure) or custom.

// Example webhook secret verification
app.post('/webhook', (req, res) => {
  const receivedSecret = req.headers['x-webhook-secret'];
  const expectedSecret = process.env.WEBHOOK_SECRET;
  
  if (receivedSecret !== expectedSecret) {
    return res.status(401).json({ error: 'Invalid webhook secret' });
  }
  
  // Process verified webhook payload
  const { data } = req.body;
  console.log('Sentiment update:', data.sentiment);
  
  res.status(200).json({ received: true });
});

Request Headers

Webhook requests include these headers:

• Content-Type: application/json
• User-Agent: TradingVibe-Webhook/1.0
• X-Webhook-Secret: Your webhook secret (if configured)
• X-Webhook-ID: Unique webhook identifier
• X-Webhook-Delivery: Unique delivery attempt ID

Testing and Reliability

Webhooks can be tested directly from the dashboard using the test button, which sends a sample payload to verify endpoint configuration.

Billing

Webhook deliveries count against your API request quota. This includes successful deliveries, failed delivery attempts, and manual tests from the dashboard.

Implementation Examples

Basic webhook receiver implementations:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/tradingvibe-webhook', (req, res) => {
  // Verify webhook secret
  const receivedSecret = req.headers['x-webhook-secret'];
  const expectedSecret = process.env.TRADINGVIBE_WEBHOOK_SECRET;
  
  if (receivedSecret !== expectedSecret) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  const { event_type, trigger_type, data } = req.body;
  
  // Process webhook data
  console.log(`Received ${event_type} for ${data.coin}`);
  console.log(`Sentiment: ${data.sentiment}, Price: $${data.price}`);
  console.log(`Fear/Greed: ${data.fear_greed_score}/100 (${data.fear_greed_label})`);
  
  if (trigger_type === 'sentiment' && data.threshold_met) {
    console.log('Threshold condition met!');
    // Handle sentiment threshold trigger
  }
  
  res.status(200).json({ received: true });
});

app.listen(3000);