trading-platform/docs/API.md

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

API Documentation Overview

📘 For complete API specification, see: swagger.yml 📄 For routing documentation, see: 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

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 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

---

Response Format

Success Response

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

Error Response

{
  "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:

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

Response metadata:

{
  "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

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

GET /api/v1/health

Response:

{
  "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
Endpoint Routing	ENDPOINT-ROUTING.md
Database Schema	apps/database/ddl/
Security Guide	SECURITY.md
Architecture	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)