trading-platform-backend-v2/ENDPOINT-ROUTING.md

API Endpoint Routing Documentation

Project: Trading Platform Backend Version: 1.0.0 Last Updated: 2026-01-26

Overview

This document describes the API endpoint routing structure for the Trading Platform backend. All endpoints follow RESTful conventions and are organized by module.

Base URL Structure

http://localhost:3080/api/v1

• Base Path: /api
• API Version: /v1
• Module Routes: /{module-name}

Module Organization

The API is organized into the following modules:

Module	Base Route	Description
Auth	/api/v1/auth	Authentication and authorization
Users	/api/v1/users	User management and profiles
Education	/api/v1/education	Educational courses and content
Trading	/api/v1/trading	Trading bots, signals, and positions
Investment	/api/v1/investment	Investment accounts and analytics
Portfolio	/api/v1/portfolio	Portfolio management
Payments	/api/v1/payments	Payment processing and subscriptions
ML	/api/v1/ml	Machine learning predictions
Agents	/api/v1/agents	Trading agent management
Notifications	/api/v1/notifications	User notifications
Admin	/api/v1/admin	Administrative functions

Authentication & Authorization Module

Base Route: /api/v1/auth

Public Endpoints (No Authentication Required)

Method	Endpoint	Description
POST	/auth/register	Register new user account
POST	/auth/login	Login with email/password
POST	/auth/oauth/:provider/url	Get OAuth authorization URL
POST	/auth/oauth/:provider/callback	OAuth callback handler
POST	/auth/forgot-password	Request password reset
POST	/auth/reset-password	Reset password with token
POST	/auth/verify-email	Verify email address

Protected Endpoints (Authentication Required)

Method	Endpoint	Description
POST	/auth/logout	Logout current session
POST	/auth/refresh	Refresh access token
GET	/auth/me	Get current user info
POST	/auth/change-password	Change user password
POST	/auth/2fa/setup	Setup 2FA
POST	/auth/2fa/enable	Enable 2FA
POST	/auth/2fa/verify	Verify 2FA code
POST	/auth/2fa/disable	Disable 2FA
GET	/auth/2fa/backup-codes	Get backup codes
GET	/auth/sessions	List user sessions
DELETE	/auth/sessions/:sessionId	Revoke session

Education Module

Base Route: /api/v1/education

Method	Endpoint	Description
GET	/education/courses	List all courses
GET	/education/courses/featured	Get featured courses
GET	/education/courses/search	Search courses
GET	/education/courses/:courseId	Get course details
GET	/education/courses/slug/:slug	Get course by slug
POST	/education/courses/:courseId/enroll	Enroll in course
GET	/education/courses/:courseId/progress	Get course progress
GET	/education/courses/:courseId/modules	List course modules
GET	/education/lessons/:lessonId	Get lesson details
POST	/education/lessons/:lessonId/complete	Mark lesson complete
GET	/education/quizzes/:quizId	Get quiz details
POST	/education/quizzes/:quizId/submit	Submit quiz answers
GET	/education/certificates	List user certificates
GET	/education/certificates/:certificateId	Get certificate
GET	/education/certificates/verify/:code	Verify certificate
GET	/education/my-courses	List enrolled courses

Trading Module

Base Route: /api/v1/trading

Method	Endpoint	Description
GET	/trading/bots	List trading bots
GET	/trading/bots/featured	Get featured bots
GET	/trading/bots/:botId	Get bot details
POST	/trading/bots/:botId/subscribe	Subscribe to bot
GET	/trading/bots/:botId/reviews	Get bot reviews
GET	/trading/signals	List trading signals
GET	/trading/signals/:signalId	Get signal details
POST	/trading/signals/:signalId/execute	Execute signal
GET	/trading/portfolio	Get trading portfolio
GET	/trading/positions	List open positions
GET	/trading/positions/:positionId	Get position details
POST	/trading/positions/:positionId/close	Close position
GET	/trading/history	Get trading history
GET	/trading/my-subscriptions	List bot subscriptions

Investment Module

Base Route: /api/v1/investment

Method	Endpoint	Description
GET	/investment/accounts	List investment accounts
POST	/investment/accounts	Create new account
GET	/investment/accounts/:accountId	Get account details
PUT	/investment/accounts/:accountId	Update account
POST	/investment/accounts/connect	Connect trading account
GET	/investment/performance	Get performance metrics
GET	/investment/analytics	Get analytics data

Portfolio Module

Base Route: /api/v1/portfolio

Method	Endpoint	Description
GET	/portfolio	List user portfolios
POST	/portfolio	Create new portfolio
GET	/portfolio/:portfolioId	Get portfolio details
PUT	/portfolio/:portfolioId	Update portfolio
DELETE	/portfolio/:portfolioId	Delete portfolio
GET	/portfolio/:portfolioId/allocations	Get allocations
POST	/portfolio/:portfolioId/allocations	Add allocation
PUT	/portfolio/:portfolioId/allocations/:id	Update allocation
GET	/portfolio/:portfolioId/performance	Get performance data
GET	/portfolio/:portfolioId/goals	List goals
POST	/portfolio/:portfolioId/goals	Create goal

Payments Module

Base Route: /api/v1/payments

Method	Endpoint	Description
GET	/payments	List user payments
POST	/payments/checkout	Create checkout session
GET	/payments/credits	Get credit balance
POST	/payments/credits/purchase	Purchase credits
GET	/payments/subscriptions	List subscriptions
GET	/payments/subscriptions/:id	Get subscription details
POST	/payments/subscriptions/:id/cancel	Cancel subscription
GET	/payments/invoices	List invoices
GET	/payments/invoices/:id	Get invoice
GET	/payments/invoices/:id/download	Download invoice PDF
GET	/payments/payment-methods	List payment methods
POST	/payments/payment-methods	Add payment method
DELETE	/payments/payment-methods/:id	Remove payment method
POST	/payments/webhooks/stripe	Stripe webhook handler

ML Module

Base Route: /api/v1/ml

Method	Endpoint	Description
GET	/ml/models	List ML models
GET	/ml/models/:modelId	Get model details
POST	/ml/predict	Request prediction
GET	/ml/predictions	List predictions
GET	/ml/predictions/:predictionId	Get prediction details
GET	/ml/signals	Get ML-generated signals

Admin Module

Base Route: /api/v1/admin

⚠️ All admin endpoints require admin role

Method	Endpoint	Description
GET	/admin/dashboard	Get admin dashboard data
GET	/admin/users	List all users
GET	/admin/users/:userId	Get user details
PUT	/admin/users/:userId	Update user
DELETE	/admin/users/:userId	Delete user
GET	/admin/courses	List all courses
PUT	/admin/courses/:courseId	Update course
DELETE	/admin/courses/:courseId	Delete course
GET	/admin/bots	List all trading bots
PUT	/admin/bots/:botId	Update bot
DELETE	/admin/bots/:botId	Delete bot
GET	/admin/transactions	List all transactions
GET	/admin/analytics	Get system analytics
GET	/admin/settings	Get system settings
PUT	/admin/settings	Update system settings

Route Files Organization

Each module has its own route file that defines the endpoints:

src/modules/
├── auth/
│   └── auth.routes.ts          # Authentication routes
├── users/
│   └── users.routes.ts         # User management routes
├── education/
│   └── education.routes.ts     # Education routes
├── trading/
│   └── trading.routes.ts       # Trading routes
├── investment/
│   └── investment.routes.ts    # Investment routes
├── portfolio/
│   └── portfolio.routes.ts     # Portfolio routes
├── payments/
│   └── payments.routes.ts      # Payment routes
├── ml/
│   └── ml.routes.ts           # ML routes
├── admin/
│   └── admin.routes.ts        # Admin routes
└── ...

Route Constants

All route paths are centralized in:

src/shared/constants/routes.constants.ts

This file exports:

• API_ROUTES - Object containing all route definitions
• HTTP_METHODS - HTTP method constants
• HTTP_STATUS - HTTP status code constants

Middleware Stack

Routes typically use the following middleware stack:

1. CORS - Cross-origin resource sharing
2. Rate Limiting - API rate limiting
3. Authentication - JWT validation (protected routes)
4. Authorization - Role-based access control
5. Validation - Request body/params validation
6. Error Handling - Centralized error handling

Error Responses

All endpoints return errors in this format:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "field": "fieldName" // Optional, for validation errors
  }
}

Success Responses

All endpoints return success in this format:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Success message" // Optional
}

Pagination

List endpoints support pagination with query parameters:

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

Response includes metadata:

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

Versioning Strategy

• Current version: v1
• API version is specified in the URL: /api/v1/...
• Breaking changes will increment the version number
• Old versions will be maintained for 6 months after deprecation

Related Documentation

• API Constants: src/shared/constants/routes.constants.ts
• Swagger/OpenAPI: Coming soon (ST2: Documentation Integration)
• Postman Collection: Coming soon
• Module READMEs: Each module's README.md file

Notes

• This routing structure was audited and documented as part of coherence fix E-COH-007 (ST1.7)
• All endpoints follow RESTful conventions
• Authentication is handled via JWT tokens in Authorization header
• CORS is enabled for frontend origins
• Rate limiting is applied per IP address and user

---

Last Audit: 2026-01-26 (ST1.7 - E-COH-007) Audited By: Claude Opus 4.5