SSE Endpoints

Complete API reference for Vedicquant Server-Sent Events endpoints.

Base URL

Environment URLs

• Production: https://sse.vedicquant.com

Authentication

All endpoints require authentication via API key:

Header Authentication (Recommended):

X-API-Key: your-api-key

Query Parameter Authentication:

GET /api/signals/stream?api_key=your-api-key

Free Week Keys

For testing and development:

Pattern: free-week-[anything]
Examples: free-week-demo, free-week-test123, free-week-mybot

Endpoints

GET /

Server status and information endpoint.

Response:

{
  "message": "vedicquant.com realtime signals SSE",
  "status": "active",
  "free_week": true,
  "connected_clients": 15,
  "version": "1.0.0",
  "uptime": "2h 34m 12s"
}

Example:

curl https://sse.vedicquant.com/

---

GET /api/signals/stream

Main SSE endpoint for receiving real-time trading signals.

Headers:

• X-API-Key (required): Authentication key
• Accept: text/event-stream
• Cache-Control: no-cache

Query Parameters:

• api_key (optional): Alternative authentication method

Response Format: Server-Sent Events stream with multiple event types.

Event Types:

connection Event

Sent immediately upon successful connection.

event: connection
data: {
  "type": "connected",
  "client_id": "client_a1b2c3d4",
  "timestamp": "2024-01-25T10:15:30Z",
  "message": "Connected to crypto signals stream"
}

signal Event

Trading signal data - the main event type.

event: signal
data: {
  "event_type": "new_signal",
  "id": 123,
  "symbol": "BTC",
  "signal_type": "BUY",
  "signal_strength": "strong",
  "price_at_signal": 95000.50,
  "target_price": 96900.00,
  "stop_loss_price": 92625.00,
  "close_price": null,
  "status": "active",
  "result": "hold",
  "phase_id": 5,
  "phase_start": "2024-01-25T10:00:00Z",
  "phase_end": "2024-01-25T11:30:00Z",
  "phase_name": "Amrita - Best",
  "profit_loss_percentage": 0,
  "profit_loss_amount": null,
  "issued_at": "2024-01-25T10:15:30Z",
  "closed_at": null,
  "timestamp": "2024-01-25T10:15:30Z"
}

heartbeat Event

Keep-alive message sent every 30 seconds.

event: heartbeat
data: {
  "type": "heartbeat",
  "timestamp": "2024-01-25T10:45:30Z"
}

Usage Examples:

JavaScript

const eventSource = new EventSource(
  'https://sse.vedicquant.com/api/signals/stream?api_key=free-week-demo'
);

eventSource.addEventListener('connection', (event) => {
  const data = JSON.parse(event.data);
  console.log('Connected:', data.message);
});

eventSource.addEventListener('signal', (event) => {
  const signal = JSON.parse(event.data);
  console.log('New signal:', signal);
});

eventSource.addEventListener('heartbeat', (event) => {
  console.log('Heartbeat received');
});

Python

import requests
import json

headers = {'X-API-Key': 'free-week-demo'}
response = requests.get(
    'https://sse.vedicquant.com/api/signals/stream',
    headers=headers,
    stream=True
)

for line in response.iter_lines():
    if line.startswith(b'event: '):
        event_type = line[7:].decode()
    elif line.startswith(b'data: '):
        data = json.loads(line[6:].decode())
        print(f"Event: {event_type}, Data: {data}")

cURL

curl -H "X-API-Key: free-week-demo" \
     -H "Accept: text/event-stream" \
     "https://sse.vedicquant.com/api/signals/stream"

Error Responses:

// 401 Unauthorized
{
  "detail": "API key required"
}

// 401 Invalid Key
{
  "detail": "Invalid API key"
}

// 429 Rate Limited
{
  "detail": "Rate limit exceeded"
}

---

POST /internal/new-signal

Internal endpoint for submitting new signals (used by crypto tracker).

Internal Use Only

This endpoint is for internal system use only. External access may be restricted.

Headers:

• Content-Type: application/json

Request Body:

{
  "symbol": "BTC",
  "signal_type": "BUY",
  "signal_strength": "strong",
  "price_at_signal": 95000.50,
  "target_price": 96900.00,
  "stop_loss_price": 92625.00,
  "phase_name": "Amrita - Best",
  "phase_start": "2024-01-25T10:00:00Z",
  "phase_end": "2024-01-25T11:30:00Z"
}

Response:

{
  "message": "Signal received",
  "clients": 15,
  "signal_id": 123
}

---

POST /internal/price-update

Internal endpoint for price updates.

Internal Use Only

This endpoint is for internal system use only.

Request Body:

{
  "symbol": "BTC",
  "price": 95250.75,
  "timestamp": "2024-01-25T10:16:00Z"
}

---

POST /api/free-week/signup

Free week access signup (development/testing).

Request Body:

{
  "email": "developer@example.com"
}

Response:

{
  "message": "Free week access granted",
  "api_key": "free-week-dev-a1b2c3d4",
  "expires_at": "2024-02-01T00:00:00Z"
}

Response Headers

All SSE responses include:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: X-API-Key, Accept

Connection Management

Automatic Reconnection

Browsers automatically reconnect when SSE connections drop. For custom clients:

import time

def connect_with_retry(max_retries=5):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, stream=True)
            if response.status_code == 200:
                return response
        except Exception as e:
            wait_time = 2 ** attempt  # Exponential backoff
            print(f"Retry {attempt + 1} in {wait_time}s: {e}")
            time.sleep(wait_time)
    
    raise Exception("Max retries exceeded")

Heartbeat Monitoring

Monitor heartbeat events to detect connection issues:

let lastHeartbeat = Date.now();

eventSource.addEventListener('heartbeat', () => {
  lastHeartbeat = Date.now();
});

// Check for stale connection every 60 seconds
setInterval(() => {
  const timeSinceHeartbeat = Date.now() - lastHeartbeat;
  if (timeSinceHeartbeat > 60000) {
    console.warn('Connection may be stale');
    // Reconnect logic here
  }
}, 60000);

Rate Limits

• Connections: 10 concurrent per API key
• Reconnections: 60 per hour per IP
• Free week: No strict limits (fair use)

Error Handling

Handle various error scenarios:

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  
  // Check connection state
  if (eventSource.readyState === EventSource.CLOSED) {
    console.log('Connection closed, will not reconnect');
  } else if (eventSource.readyState === EventSource.CONNECTING) {
    console.log('Reconnecting...');
  }
};

// Network error handling
eventSource.addEventListener('error', (event) => {
  if (event.target.readyState === EventSource.CLOSED) {
    // Manual reconnection logic
    setTimeout(() => {
      initializeSSE();
    }, 5000);
  }
});

WebSocket Alternative

For environments where SSE isn't suitable, we also provide WebSocket endpoints:

// WebSocket endpoint (alternative)
const ws = new WebSocket('wss://sse.vedicquant.com/ws/signals?api_key=free-week-demo');

ws.onmessage = (event) => {
  const signal = JSON.parse(event.data);
  console.log('Signal via WebSocket:', signal);
};

SSE vs WebSocket

• SSE: Simpler, auto-reconnects, HTTP-based, one-way
• WebSocket: Two-way communication, lower overhead, more complex
• Recommendation: Use SSE unless you need bidirectional communication

Testing Tools

Browser DevTools

1. Open browser DevTools (F12)
2. Go to Network tab
3. Connect to SSE endpoint
4. Monitor real-time events

SSE Testing Tools

• Postman: Supports SSE testing
• curl: Command-line testing
• Browser Extensions: SSE client extensions
• Custom Tools: Build testing dashboards

Example Test Script

#!/bin/bash
# test_sse.sh - Quick SSE connection test

echo "🧪 Testing Vedicquant SSE Connection..."

API_KEY="free-week-test"
URL="https://sse.vedicquant.com/api/signals/stream"

echo "🔑 API Key: $API_KEY"
echo "📡 URL: $URL"
echo "🚀 Connecting..."

curl -N -H "X-API-Key: $API_KEY" \
     -H "Accept: text/event-stream" \
     "$URL"

Ready to integrate real-time cosmic signals? 🌙✨