trading-platform/docs/API.md

---
id: "API"
title: "API Documentation Overview"
type: "Documentation"
project: "trading-platform"
version: "2.0.0"
updated_date: "2026-01-26"
---

# API Documentation Overview

> **📘 For complete API specification, see:** [swagger.yml](../apps/backend/swagger.yml)
> **📄 For routing documentation, see:** [ENDPOINT-ROUTING.md](../apps/backend/ENDPOINT-ROUTING.md)

This document provides a high-level overview of the Trading Platform API. For detailed endpoint specifications, request/response schemas, and interactive API testing, refer to the OpenAPI specification in `swagger.yml`.

---

## Quick Reference

### Base URLs

| Environment | URL |
|-------------|-----|
| Development | `http://localhost:3080/api/v1` |
| Production | `https://api.trading.com/api/v1` (future) |

### Service Ports

| Service | Port | Description |
|---------|------|-------------|
| Backend API | 3080 | Main REST API + Swagger UI |
| Frontend | 3000 | React SPA |
| WebSocket | 3082 | Real-time data (Socket.io) |
| ML Engine | 3083 | ML predictions (FastAPI) |
| Data Service | 3084 | Market data aggregation |
| LLM Agent | 3085 | Trading copilot (FastAPI) |
| Trading Agents | 3086 | Automated trading (FastAPI) |
| Ollama WebUI | 3087 | LLM model management |

---

## Authentication

All protected endpoints require JWT authentication.

### Request Header

```http
Authorization: Bearer <jwt_access_token>
```

### Supported Methods

| Method | Description |
|--------|-------------|
| **Email/Password** | Traditional login with email and password |
| **OAuth 2.0** | Google, Facebook, Apple, GitHub |
| **2FA (TOTP)** | Two-factor authentication optional |

### Auth Endpoints

- `POST /auth/register` - Create new account
- `POST /auth/login` - Login with credentials
- `POST /auth/logout` - End session
- `POST /auth/refresh` - Refresh access token
- `GET /auth/me` - Get current user

**See:** [swagger.yml](../apps/backend/swagger.yml) for complete auth specification

---

## API Modules

The API is organized into the following modules:

| Module | Base Route | Description |
|--------|------------|-------------|
| **Auth** | `/api/v1/auth` | Authentication, sessions, 2FA |
| **Users** | `/api/v1/users` | User profiles and management |
| **Education** | `/api/v1/education` | Courses, lessons, certificates |
| **Trading** | `/api/v1/trading` | Bots, signals, positions |
| **Investment** | `/api/v1/investment` | PAMM accounts, distributions |
| **Portfolio** | `/api/v1/portfolio` | Portfolio management |
| **Payments** | `/api/v1/payments` | Stripe integration, subscriptions |
| **ML** | `/api/v1/ml` | ML predictions and signals |
| **Agents** | `/api/v1/agents` | Trading agent management |
| **Notifications** | `/api/v1/notifications` | User notifications |
| **Admin** | `/api/v1/admin` | Administrative functions |

**Total Endpoints:** 34+ documented in [swagger.yml](../apps/backend/swagger.yml)

---

## Response Format

### Success Response

```json
{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Success message (optional)"
}
```

### Error Response

```json
{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "field": "fieldName"
  }
}
```

### Common HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request (validation error) |
| 401 | Unauthorized (missing/invalid token) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not Found |
| 429 | Rate Limit Exceeded |
| 500 | Internal Server Error |

---

## Pagination

List endpoints support pagination via query parameters:

```http
GET /api/v1/module/resource?page=1&limit=20&sortBy=createdAt&sortOrder=desc
```

**Response metadata:**
```json
{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

---

## Rate Limiting

| Endpoint Type | Limit |
|---------------|-------|
| General | 100 requests/minute per IP |
| Auth | 5 requests/minute |
| Trading | 60 requests/minute |
| ML | 30 requests/minute |

**Response headers:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1670832000
```

---

## WebSocket (Real-Time)

**Connection:** `http://localhost:3082`

```javascript
import io from 'socket.io-client';

const socket = io('http://localhost:3082', {
  auth: { token: 'your-jwt-token' }
});

// Subscribe to price updates
socket.emit('subscribe', { symbols: ['BTCUSDT', 'ETHUSDT'] });

// Listen for updates
socket.on('price_update', (data) => {
  console.log(data); // { symbol, price, timestamp }
});
```

**Events:** `price_update`, `trade`, `orderbook_update`, `signal`, `agent_trade`, `notification`

---

## CORS Configuration

CORS enabled for:
- `http://localhost:3000` (development frontend)
- `https://app.trading.com` (production - future)

---

## Health Check

```http
GET /api/v1/health
```

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2026-01-26T10:00:00Z",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "mlEngine": "healthy"
  }
}
```

---

## API Versioning

- Current version: **v1**
- Version is in URL: `/api/v1/...`
- Breaking changes will increment version number
- Old versions maintained for 6 months after deprecation

---

## Additional Resources

| Resource | Location |
|----------|----------|
| **OpenAPI Specification** | [swagger.yml](../apps/backend/swagger.yml) |
| **Endpoint Routing** | [ENDPOINT-ROUTING.md](../apps/backend/ENDPOINT-ROUTING.md) |
| **Database Schema** | [apps/database/ddl/](../apps/database/ddl/) |
| **Security Guide** | [SECURITY.md](./90-transversal/security/SECURITY.md) |
| **Architecture** | [01-arquitectura/](./01-arquitectura/) |

---

## Swagger UI (Interactive Documentation)

**Local:** http://localhost:3080/api-docs

The Swagger UI provides:
- ✅ Interactive API testing
- ✅ Request/response examples
- ✅ Schema validation
- ✅ Authentication testing
- ✅ "Try it out" functionality

---

**Last Updated:** 2026-01-26 (ST3.2 - Documentation Purge)