Skip to content

DSTA API Documentation

Comprehensive REST API documentation for the Dr.Strange Trading Analysis (DSTA) platform.

Table of Contents

Overview

The DSTA API provides programmatic access to: - Real-time and historical market data - Portfolio statistics and analytics - Backtesting engine - Data quality monitoring - Health checks and system status

API Version: v1
Format: JSON
Protocol: REST over HTTPS

Base URL

Production:  https://api.dsta.io/v1
Development: http://localhost:8000/api/v1

Authentication

API Key Authentication

All API requests must include an API key in the header:

GET /api/v1/market/candlesticks HTTP/1.1
Host: api.dsta.io
X-API-Key: your_api_key_here

Getting an API Key

  1. Log in to the DSTA dashboard
  2. Navigate to Settings > API Keys
  3. Click "Generate New Key"
  4. Copy and store securely

JWT Authentication (For WebSocket)

WebSocket connections use JWT tokens:

const ws = new WebSocket('wss://api.dsta.io/ws/market?token=<jwt_token>');

Rate Limiting

Standard Tier: - 100 requests per minute - 1,000 requests per hour - 10,000 requests per day

Premium Tier: - 1,000 requests per minute - 10,000 requests per hour - Unlimited daily requests

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Handling

Standard Error Response

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Symbol 'INVALID' is not supported",
    "details": {
      "param": "symbol",
      "value": "INVALID",
      "supported_symbols": ["BTCUSDT", "ETHUSDT"]
    },
    "timestamp": "2024-01-27T10:30:00Z",
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Status Code Description
200 Success
201 Created
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid/missing API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error
503 Service Unavailable - Maintenance mode

Endpoints

Health & Monitoring

Health Check

GET /health/

Check the status of all system components.

Parameters: None

Response: 

{
  "status": "healthy",
  "timestamp": "2024-01-27T10:30:00Z",
  "components": {
    "database": {
      "status": "healthy",
      "latency_ms": 12
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 3
    },
    "binance_api": {
      "status": "healthy",
      "latency_ms": 45
    }
  },
  "uptime_seconds": 86400
}

Status Values: - healthy: All systems operational - degraded: Some non-critical issues - unhealthy: Critical system failure

Market Data

Get Candlesticks

GET /market/candlesticks/

Retrieve OHLCV candlestick data for a trading pair.

Parameters:

Parameter Type Required Description
exchange string Yes Exchange name (e.g., 'binance', 'gateio')
trading_pair string Yes Trading pair (e.g., 'BTCUSDT')
interval string Yes Candle interval ('1m', '5m', '15m', '1h', '4h', '1d')
from datetime Yes Start datetime (ISO 8601)
to datetime Yes End datetime (ISO 8601)
limit integer No Maximum records (default: 500, max: 1000)

Example Request: 

GET /market/candlesticks/?exchange=binance&trading_pair=BTCUSDT&interval=1h&from=2024-01-01T00:00:00Z&to=2024-01-02T00:00:00Z
X-API-Key: your_api_key

Example Response: 

{
  "exchange": "binance",
  "trading_pair": "BTCUSDT",
  "interval": "1h",
  "count": 24,
  "data": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "open": "42500.50",
      "high": "42750.00",
      "low": "42350.25",
      "close": "42680.75",
      "volume": "1250.5",
      "quote_volume": "53281250.00",
      "trades": 15420
    },
    {
      "timestamp": "2024-01-01T01:00:00Z",
      "open": "42680.75",
      "high": "42890.00",
      "low": "42650.00",
      "close": "42800.50",
      "volume": "1380.25",
      "quote_volume": "59072350.00",
      "trades": 16850
    }
  ]
}

Get Current Price

GET /market/price/

Get the current price for a trading pair.

Parameters: - exchange (string, required): Exchange name - trading_pair (string, required): Trading pair

Response: 

{
  "exchange": "binance",
  "trading_pair": "BTCUSDT",
  "price": "42850.50",
  "timestamp": "2024-01-27T10:30:15Z"
}

Statistics

Total Balance

GET /stats/total-balance/

Get aggregated balance across all connected exchanges.

Parameters: None

Response: 

{
  "total_usd": "125430.50",
  "last_updated": "2024-01-27T10:30:00Z",
  "exchanges": {
    "binance": {
      "total_usd": "75250.25",
      "assets": [
        {
          "symbol": "BTC",
          "amount": "1.5",
          "usd_value": "64275.75"
        },
        {
          "symbol": "ETH",
          "amount": "25.0",
          "usd_value": "57500.00"
        },
        {
          "symbol": "USDT",
          "amount": "10974.50",
          "usd_value": "10974.50"
        }
      ]
    },
    "gateio": {
      "total_usd": "50180.25",
      "assets": [...]
    }
  }
}

Greed and Fear Index

GET /stats/greed-and-fear-index/

Get Bitcoin Greed and Fear Index.

Parameters: - limit (integer, optional): Number of historical data points (default: 1, max: 30)

Response: 

{
  "current": {
    "value": 65,
    "classification": "Greed",
    "timestamp": "2024-01-27T00:00:00Z"
  },
  "history": [
    {
      "value": 62,
      "classification": "Greed",
      "timestamp": "2024-01-26T00:00:00Z"
    }
  ]
}

Classification Scale: - 0-24: Extreme Fear - 25-44: Fear - 45-54: Neutral - 55-74: Greed - 75-100: Extreme Greed

Data Quality

Data Quality Dashboard

GET /data-quality/

Get comprehensive data quality metrics.

Parameters: - symbols (string, optional): Comma-separated list of symbols

Response: 

{
  "overall_score": 95.5,
  "timestamp": "2024-01-27T10:30:00Z",
  "metrics": {
    "completeness": {
      "score": 98.5,
      "expected_records": 10000,
      "actual_records": 9850,
      "missing_records": 150
    },
    "freshness": {
      "score": 100.0,
      "latest_timestamp": "2024-01-27T10:29:00Z",
      "lag_seconds": 60
    },
    "quality": {
      "score": 92.0,
      "total_records": 9850,
      "invalid_records": 78,
      "anomalies": 12
    }
  },
  "symbols": {
    "BTCUSDT": {
      "completeness": 99.2,
      "freshness": 100.0,
      "quality": 95.5
    },
    "ETHUSDT": {
      "completeness": 97.8,
      "freshness": 100.0,
      "quality": 88.5
    }
  }
}

Data Completeness

GET /data-quality/completeness/

Check data completeness for specific time ranges.

Parameters: - symbol (string, required): Trading pair symbol - interval (string, required): Time interval - from (datetime, required): Start datetime - to (datetime, required): End datetime

Response: 

{
  "symbol": "BTCUSDT",
  "interval": "1h",
  "time_range": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-07T00:00:00Z"
  },
  "expected_records": 168,
  "actual_records": 165,
  "completeness_pct": 98.2,
  "gaps": [
    {
      "start": "2024-01-03T15:00:00Z",
      "end": "2024-01-03T17:00:00Z",
      "missing_count": 3
    }
  ]
}

Data Freshness

GET /data-quality/freshness/

Check how recent the data is.

Parameters: - symbols (string, optional): Comma-separated symbols

Response: 

{
  "timestamp": "2024-01-27T10:30:00Z",
  "symbols": {
    "BTCUSDT": {
      "latest_timestamp": "2024-01-27T10:29:00Z",
      "lag_seconds": 60,
      "status": "fresh"
    },
    "ETHUSDT": {
      "latest_timestamp": "2024-01-27T10:29:00Z",
      "lag_seconds": 60,
      "status": "fresh"
    }
  }
}

Status Values: - fresh: < 5 minutes lag - stale: 5-60 minutes lag - very_stale: > 60 minutes lag

Backtesting

Submit Backtest

POST /backtest/submit/

Submit a new backtest job.

Request Body: 

{
  "name": "SMA Crossover Strategy Test",
  "strategy": "sma_crossover",
  "symbols": ["BTCUSDT", "ETHUSDT"],
  "start_date": "2023-01-01T00:00:00Z",
  "end_date": "2023-12-31T23:59:59Z",
  "initial_capital": "100000.00",
  "parameters": {
    "short_window": 10,
    "long_window": 20
  },
  "commission": "0.001"
}

Response: 

{
  "backtest_id": 1234,
  "status": "queued",
  "created_at": "2024-01-27T10:30:00Z",
  "estimated_completion": "2024-01-27T10:35:00Z"
}

Get Backtest Status

GET /backtest/status/{backtest_id}/

Get the status of a backtest job.

Response: 

{
  "backtest_id": 1234,
  "status": "running",
  "progress_pct": 45.5,
  "created_at": "2024-01-27T10:30:00Z",
  "started_at": "2024-01-27T10:30:15Z",
  "current_date": "2023-06-15T00:00:00Z",
  "estimated_completion": "2024-01-27T10:35:00Z"
}

Status Values: - queued: Waiting to start - running: Currently executing - completed: Successfully finished - failed: Error occurred - cancelled: User cancelled

Get Backtest Results

GET /backtest/results/{backtest_id}/

Retrieve results of a completed backtest.

Response: 

{
  "backtest_id": 1234,
  "name": "SMA Crossover Strategy Test",
  "status": "completed",
  "completed_at": "2024-01-27T10:34:50Z",
  "duration_seconds": 290,
  "performance": {
    "total_return": 0.2450,
    "annualized_return": 0.2450,
    "sharpe_ratio": 1.85,
    "max_drawdown": -0.1250,
    "win_rate": 0.625,
    "profit_factor": 2.15
  },
  "statistics": {
    "total_trades": 48,
    "winning_trades": 30,
    "losing_trades": 18,
    "avg_win": "1850.50",
    "avg_loss": "-750.25",
    "largest_win": "5250.00",
    "largest_loss": "-2100.00"
  },
  "equity_curve": [
    {"date": "2023-01-01", "value": "100000.00"},
    {"date": "2023-01-02", "value": "101250.50"},
    ...
  ],
  "trades": [
    {
      "entry_date": "2023-01-15T10:30:00Z",
      "exit_date": "2023-01-20T15:45:00Z",
      "symbol": "BTCUSDT",
      "side": "LONG",
      "entry_price": "20500.00",
      "exit_price": "21750.00",
      "quantity": "1.5",
      "pnl": "1875.00",
      "pnl_pct": 0.0610
    }
  ]
}

List Backtests

GET /backtest/list/

List all backtest jobs.

Parameters: - status (string, optional): Filter by status - limit (integer, optional): Max results (default: 20) - offset (integer, optional): Pagination offset

Response: 

{
  "count": 150,
  "next": "/backtest/list/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "backtest_id": 1234,
      "name": "SMA Crossover Strategy Test",
      "status": "completed",
      "created_at": "2024-01-27T10:30:00Z",
      "total_return": 0.2450
    },
    ...
  ]
}

WebSocket API

Real-time Market Data

Endpoint: wss://api.dsta.io/ws/market

Connect

const ws = new WebSocket('wss://api.dsta.io/ws/market?token=<jwt_token>');

ws.onopen = () => {
    // Subscribe to symbol
    ws.send(JSON.stringify({
        action: 'subscribe',
        symbols: ['BTCUSDT', 'ETHUSDT'],
        channels: ['kline_1m', 'ticker']
    }));
};

Kline Updates

{
  "event": "kline",
  "symbol": "BTCUSDT",
  "timestamp": "2024-01-27T10:30:00Z",
  "data": {
    "open": "42500.50",
    "high": "42750.00",
    "low": "42350.25",
    "close": "42680.75",
    "volume": "1250.5",
    "is_closed": false
  }
}

Ticker Updates

{
  "event": "ticker",
  "symbol": "BTCUSDT",
  "timestamp": "2024-01-27T10:30:15.123Z",
  "data": {
    "last_price": "42680.75",
    "best_bid": "42680.50",
    "best_ask": "42681.00",
    "volume_24h": "125450.5",
    "price_change_24h": "1250.25",
    "price_change_pct_24h": "3.02"
  }
}

Error Codes

Code Description
INVALID_PARAMETER One or more parameters are invalid
MISSING_PARAMETER Required parameter is missing
INVALID_API_KEY API key is invalid or expired
RATE_LIMIT_EXCEEDED Too many requests
SYMBOL_NOT_SUPPORTED Trading pair is not supported
EXCHANGE_NOT_SUPPORTED Exchange is not supported
INVALID_INTERVAL Time interval is invalid
INVALID_DATE_RANGE Date range is invalid or too large
BACKTEST_NOT_FOUND Backtest ID doesn't exist
STRATEGY_NOT_FOUND Strategy name is not recognized
INSUFFICIENT_DATA Not enough data for the request
INTERNAL_ERROR Server encountered an error
SERVICE_UNAVAILABLE Service is temporarily unavailable

Examples

Python

import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://api.dsta.io/v1'

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
}

# Get candlesticks
response = requests.get(
    f'{BASE_URL}/market/candlesticks/',
    headers=headers,
    params={
        'exchange': 'binance',
        'trading_pair': 'BTCUSDT',
        'interval': '1h',
        'from': '2024-01-01T00:00:00Z',
        'to': '2024-01-02T00:00:00Z'
    }
)

data = response.json()
print(f"Received {data['count']} candles")

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.dsta.io/v1';

const headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
};

// Submit backtest
async function submitBacktest() {
    const response = await axios.post(
        `${BASE_URL}/backtest/submit/`,
        {
            name: 'Test Strategy',
            strategy: 'sma_crossover',
            symbols: ['BTCUSDT'],
            start_date: '2023-01-01T00:00:00Z',
            end_date: '2023-12-31T23:59:59Z',
            initial_capital: '100000.00',
            parameters: {
                short_window: 10,
                long_window: 20
            }
        },
        { headers }
    );

    console.log(`Backtest ID: ${response.data.backtest_id}`);
    return response.data.backtest_id;
}

cURL

# Health check
curl -X GET "https://api.dsta.io/v1/health/" \
  -H "X-API-Key: your_api_key"

# Get balance
curl -X GET "https://api.dsta.io/v1/stats/total-balance/" \
  -H "X-API-Key: your_api_key"

# Get candlesticks
curl -X GET "https://api.dsta.io/v1/market/candlesticks/?exchange=binance&trading_pair=BTCUSDT&interval=1h&from=2024-01-01T00:00:00Z&to=2024-01-02T00:00:00Z" \
  -H "X-API-Key: your_api_key"

See Also