crypto_trader/docs/api/source/market_data.rst

Market Data API
===============

REST API endpoints for market data and pricing information.

Market Data Endpoints
---------------------

OHLCV Data
~~~~~~~~~~

**GET** ``/api/market-data/ohlcv/{symbol}``

Get OHLCV (Open, High, Low, Close, Volume) candlestick data for a symbol.

**Parameters:**

- ``symbol`` (path, required): Trading pair symbol (e.g., "BTC/USD")
- ``timeframe`` (query, optional): Timeframe for candles (default: "1h")
  - Valid values: "1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"
- ``limit`` (query, optional): Number of candles to return (default: 100, max: 1000)
- ``exchange`` (query, optional): Exchange name (deprecated, uses pricing service)

**Response:**

.. code-block:: json

   [
     {
       "time": 1609459200,
       "open": 50000.0,
       "high": 51000.0,
       "low": 49000.0,
       "close": 50000.0,
       "volume": 1000.0
     }
   ]

**Example:**

.. code-block:: bash

   curl http://localhost:8000/api/market-data/ohlcv/BTC%2FUSD?timeframe=1h&limit=100

Ticker Data
~~~~~~~~~~~

**GET** ``/api/market-data/ticker/{symbol}``

Get current ticker data for a symbol, including price, volume, and provider information.

**Parameters:**

- ``symbol`` (path, required): Trading pair symbol (e.g., "BTC/USD")

**Response:**

.. code-block:: json

   {
     "symbol": "BTC/USD",
     "bid": 50000.0,
     "ask": 50001.0,
     "last": 50000.5,
     "high": 51000.0,
     "low": 49000.0,
     "volume": 1000000.0,
     "timestamp": 1609459200000,
     "provider": "CCXT-Kraken"
   }

**Example:**

.. code-block:: bash

   curl http://localhost:8000/api/market-data/ticker/BTC%2FUSD

Provider Health
~~~~~~~~~~~~~~~

**GET** ``/api/market-data/providers/health``

Get health status for pricing providers.

**Parameters:**

- ``provider`` (query, optional): Specific provider name to get health for

**Response:**

.. code-block:: json

   {
     "active_provider": "CCXT-Kraken",
     "health": {
       "CCXT-Kraken": {
         "status": "healthy",
         "last_check": "2025-01-01T12:00:00Z",
         "last_success": "2025-01-01T12:00:00Z",
         "success_count": 100,
         "failure_count": 2,
         "avg_response_time": 0.123,
         "consecutive_failures": 0,
         "circuit_breaker_open": false
       }
     }
   }

**Example:**

.. code-block:: bash

   curl http://localhost:8000/api/market-data/providers/health?provider=CCXT-Kraken

Provider Status
~~~~~~~~~~~~~~~

**GET** ``/api/market-data/providers/status``

Get detailed status for all pricing providers, including cache statistics.

**Response:**

.. code-block:: json

   {
     "active_provider": "CCXT-Kraken",
     "providers": {
       "CCXT-Kraken": {
         "status": "healthy",
         "last_check": "2025-01-01T12:00:00Z",
         "success_count": 100,
         "failure_count": 2,
         "avg_response_time": 0.123
       },
       "CoinGecko": {
         "status": "unknown",
         "success_count": 0,
         "failure_count": 0
       }
     },
     "cache": {
       "size": 50,
       "max_size": 1000,
       "hits": 1000,
       "misses": 200,
       "hit_rate": 83.33,
       "evictions": 0,
       "avg_age_seconds": 30.5
     }
   }

**Example:**

.. code-block:: bash

   curl http://localhost:8000/api/market-data/providers/status

Provider Configuration
~~~~~~~~~~~~~~~~~~~~~~

**GET** ``/api/market-data/providers/config``

Get current provider configuration.

**Response:**

.. code-block:: json

   {
     "primary": [
       {
         "name": "kraken",
         "enabled": true,
         "priority": 1
       },
       {
         "name": "coinbase",
         "enabled": true,
         "priority": 2
       }
     ],
     "fallback": {
       "name": "coingecko",
       "enabled": true,
       "api_key": ""
     },
     "caching": {
       "ticker_ttl": 2,
       "ohlcv_ttl": 60,
       "max_cache_size": 1000
     },
     "websocket": {
       "enabled": true,
       "reconnect_interval": 5,
       "ping_interval": 30
     }
   }

**Example:**

.. code-block:: bash

   curl http://localhost:8000/api/market-data/providers/config

Update Provider Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**PUT** ``/api/market-data/providers/config``

Update provider configuration.

**Request Body:**

.. code-block:: json

   {
     "primary": [
       {
         "name": "kraken",
         "enabled": true,
         "priority": 1
       }
     ],
     "caching": {
       "ticker_ttl": 5,
       "ohlcv_ttl": 120
     }
   }

**Response:**

.. code-block:: json

   {
     "message": "Configuration updated successfully",
     "config": {
       "primary": [...],
       "fallback": {...},
       "caching": {...},
       "websocket": {...}
     }
   }

**Example:**

.. code-block:: bash

   curl -X PUT http://localhost:8000/api/market-data/providers/config \
     -H "Content-Type: application/json" \
     -d '{"caching": {"ticker_ttl": 5}}'

WebSocket Updates
-----------------

The WebSocket endpoint at ``/ws`` broadcasts real-time price updates.

**Connection:**

.. code-block:: javascript

   const ws = new WebSocket('ws://localhost:8000/ws');
   ws.onopen = () => {
     // Subscribe to symbol updates
     ws.send(JSON.stringify({
       type: 'subscribe',
       symbol: 'BTC/USD'
     }));
   };
   
   ws.onmessage = (event) => {
     const message = JSON.parse(event.data);
     if (message.type === 'price_update') {
       console.log('Price update:', message);
     }
   };

**Message Types:**

- ``subscribe``: Subscribe to price updates for a symbol
- ``unsubscribe``: Unsubscribe from price updates
- ``price_update``: Price update broadcast (contains exchange, symbol, price, timestamp)
- ``provider_status_update``: Provider status change notification

**Price Update Message:**

.. code-block:: json

   {
     "type": "price_update",
     "exchange": "pricing",
     "symbol": "BTC/USD",
     "price": "50000.50",
     "timestamp": "2025-01-01T12:00:00Z"
   }

Error Responses
---------------

All endpoints may return standard HTTP error codes:

- ``400 Bad Request``: Invalid request parameters
- ``404 Not Found``: Symbol or provider not found
- ``500 Internal Server Error``: Server error

Error response format:

.. code-block:: json

   {
     "detail": "Error message describing what went wrong"
   }