trading_gnn/docs/API.md

# API Reference

Base URL: `http://localhost:8000`

---

## Dashboard

### `GET /api/dashboard/metrics`

Returns current system metrics.

**Response:**
```json
{
  "memory": {
    "allocated_gb": 4.2,
    "max_allocated_gb": 5.1,
    "total_gb": 32.0,
    "limit_gb": 28.8,
    "usage_percent": 13.1,
    "free_gb": 24.6
  },
  "account": {
    "cash": 100000.00,
    "total_value": 100000.00,
    "positions_count": 0,
    "positions": {}
  },
  "model": {
    "status": "loaded",
    "device": "cuda",
    "amd_gpu": true,
    "mixed_precision": true,
    "precision": "bf16",
    "hidden_channels": 128,
    "num_heads": 16,
    "batch_size": 128,
    "learning_rate": 0.0005
  },
  "system": {
    "project_name": "StockGNN_R9700",
    "version": "1.0.0",
    "training_active": false,
    "trading_active": false
  }
}
```

### `GET /api/dashboard/logs?limit=100`

Returns recent log entries.

**Response:**
```json
{
  "logs": [
    "[2024-01-15 09:30:00] Trading started",
    "[2024-01-15 09:30:02] Model loaded from models/stock_gnn_r9700.pt"
  ],
  "total": 2
}
```

### `POST /api/dashboard/logs/clear`

Clears stored logs.

**Response:**
```json
{"status": "cleared"}
```

---

## Trading

### `GET /api/trading/status`

**Response:**
```json
{
  "active": false,
  "cash": 100000.00,
  "total_value": 100000.00,
  "positions": {},
  "orders_count": 0
}
```

### `POST /api/trading/start`

Starts live trading.

**Response:**
```json
{"status": "started"}
```

### `POST /api/trading/stop`

Stops live trading.

**Response:**
```json
{"status": "stopped"}
```

### `GET /api/trading/orders`

Lists all orders.

**Response:**
```json
[
  {
    "order_id": "abc-123",
    "ticker": "AAPL",
    "action": "buy",
    "quantity": 100,
    "price": 150.0,
    "timestamp": "2024-01-15 09:30:00",
    "type": "market",
    "status": "filled"
  }
]
```

### `POST /api/trading/order`

Submits a manual order.

**Request Body:**
```json
{
  "ticker": "AAPL",
  "action": "buy",
  "quantity": 100,
  "price": 150.0,
  "timestamp": "2024-01-15 09:30:00",
  "type": "market"
}
```

**Response:**
```json
{"status": "submitted", "order_id": "abc-123"}
```

### `POST /api/trading/cancel/{order_id}`

Cancels an order.

**Response:**
```json
{"status": "cancelled"}
```

### `POST /api/trading/positions/close/{ticker}`

Closes a position.

**Response:**
```json
{"status": "submitted", "order_id": "def-456"}
```

### `POST /api/trading/positions/close-all`

Closes all positions.

**Response:**
```json
{
  "status": "submitted",
  "results": [
    {"ticker": "AAPL", "order_id": "ghi-789"}
  ]
}
```

---

## Models

### `GET /api/models/status`

**Response:**
```json
{
  "status": "loaded",
  "training_active": false,
  "device": "cuda",
  "amd_gpu": true,
  "mixed_precision": true,
  "precision": "bf16",
  "model_name": "stock_gnn_r9700",
  "hidden_channels": 128,
  "num_heads": 16,
  "dropout": 0.3,
  "learning_rate": 0.0005,
  "batch_size": 128,
  "epochs": 200,
  "sequence_length": 60
}
```

### `POST /api/models/train`

Starts training.

**Response:**
```json
{"status": "started"}
```

### `POST /api/models/train/stop`

Stops training.

**Response:**
```json
{"status": "stopped"}
```

### `POST /api/models/save`

Saves model weights.

**Response:**
```json
{"status": "saved"}
```

### `POST /api/models/load`

Loads model weights.

**Response:**
```json
{"status": "loaded"}
```

### `POST /api/models/benchmark`

Runs performance benchmark.

**Response:**
```json
{
  "status": "complete",
  "inference_time_ms": 2.341,
  "training_time_ms": 8.567,
  "inference_throughput": 427.0,
  "training_throughput": 116.7,
  "memory_allocated_gb": 4.5,
  "device": "cuda"
}
```

---

## Data

### `GET /api/data/tickers`

**Response:**
```json
{
  "initial": ["AAPL", "MSFT", "GOOGL", ...],
  "index": "^GSPC",
  "count": 30
}
```

### `GET /api/data/pipeline/status`

**Response:**
```json
{
  "status": "ready",
  "tickers_loaded": 30,
  "db_path": "data/processed/stock_data.db"
}
```

### `POST /api/data/update`

Triggers a full data update.

**Response:**
```json
{"status": "started"}
```

### `GET /api/data/features/{ticker}`

**Response:**
```json
{
  "ticker": "AAPL",
  "timestamp": "2024-01-15 09:30:00",
  "features": {
    "AAPL": {
      "ticker": "AAPL",
      "timestamp": "2024-01-15 09:30:00",
      "return": 0.0,
      "volatility": 0.2,
      ...
    }
  }
}
```

### `GET /api/data/price/{ticker}`

**Response:**
```json
{
  "ticker": "AAPL",
  "date": "2024-01-15 00:00:00",
  "open": 150.0,
  "high": 152.0,
  "low": 149.0,
  "close": 151.0,
  "adj_close": 151.0,
  "volume": 50000000
}
```

### `GET /api/data/prices/{ticker}?limit=30`

**Response:**
```json
[
  {
    "date": "2024-01-15",
    "open": 150.0,
    "high": 152.0,
    "low": 149.0,
    "close": 151.0,
    "volume": 50000000
  }
]
```

### `GET /api/data/corporate-actions/{ticker}`

**Response:**
```json
{
  "ticker": "AAPL",
  "actions": {
    "splits": {"2020-08-31": 4.0},
    "dividends": {"2024-01-10": 0.24}
  }
}
```

---

## WebSocket

### Connection

```javascript
const ws = new WebSocket('ws://localhost:8000/ws');
```

### Server → Client Messages

**Type: `metrics`**
```json
{
  "type": "metrics",
  "timestamp": "2024-01-15T09:30:00.000000",
  "memory": {
    "allocated_gb": 4.2,
    "total_gb": 32.0,
    "usage_percent": 13.1
  },
  "account": {
    "cash": 100000.00,
    "total_value": 100000.00,
    "positions": 0
  },
  "model": {
    "status": "loaded",
    "device": "cuda",
    "mixed_precision": true,
    "precision": "bf16"
  }
}
```

### Client → Server Messages

**Ping:**
```json
{"action": "ping"}
```

**Subscribe:**
```json
{"action": "subscribe", "channel": "all"}
```