Adrian Flores Cortes c5e33555be docs: Move service integration to transversal location

Moved docs/api-contracts/SERVICE-INTEGRATION.md to
docs/90-transversal/integraciones/INT-SERVICES-INTEGRATION.md

Part of ST3.2 Documentation Reorganization.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-26 18:58:33 -06:00

12 KiB

Raw Blame History

id	title	type	project	version	updated_date
SERVICE-INTEGRATION	Trading Platform - Service Integration Contracts	Documentation	trading-platform	1.0.0	2026-01-04

Trading Platform - Service Integration Contracts

Overview

Este documento define los contratos de API entre los servicios de la plataforma Trading Platform para uso personal con enfoque en ML.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Frontend     │────▶│     Backend     │────▶│   ML Engine     │
│   (React/Vite)  │     │   (Express.js)  │     │    (FastAPI)    │
│   Port: 5173    │     │   Port: 8000    │     │   Port: 8002    │
└─────────────────┘     └────────┬────────┘     └────────┬────────┘
                                 │                       │
                                 │                       │
                        ┌────────▼────────┐     ┌────────▼────────┐
                        │   LLM Agent     │     │  Data Service   │
                        │    (FastAPI)    │     │    (FastAPI)    │
                        │   Port: 8003    │     │   Port: 8001    │
                        └─────────────────┘     └─────────────────┘

Service Ports

Service	Port	Description
Backend	8000	Main API Gateway (Express.js)
Data Service	8001	Market data from Massive.com/Polygon
ML Engine	8002	ML predictions and signals
LLM Agent	8003	AI copilot and auto-trading
Frontend	5173	React application (dev)
Ollama	11434	Local LLM inference
PostgreSQL	5432	Main database
Redis	6379	Cache and sessions

Data Service API (Port 8001)

Base URL: http://localhost:8001

Health Check

GET /health
Response: { status: "healthy", providers: [...], uptime: 123 }

Get OHLCV Data

GET /api/ohlcv
Query Parameters:
  - symbol: string (required) - e.g., "XAUUSD"
  - timeframe: string (required) - "1m", "5m", "15m", "1h", "4h", "1d"
  - start: ISO datetime (optional)
  - end: ISO datetime (optional)
  - limit: number (optional, default: 1000)

Response:
{
  "bars": [
    {
      "timestamp": "2025-12-08T12:00:00Z",
      "open": 2350.50,
      "high": 2355.00,
      "low": 2348.00,
      "close": 2352.75,
      "volume": 15000
    }
  ],
  "symbol": "XAUUSD",
  "timeframe": "15m",
  "count": 100
}

Get Snapshot

GET /api/snapshot/{symbol}
Response:
{
  "symbol": "XAUUSD",
  "bid": 2350.25,
  "ask": 2350.75,
  "last_price": 2350.50,
  "timestamp": "2025-12-08T12:00:00Z",
  "daily_change": 5.50,
  "daily_change_pct": 0.23
}

Get Symbols

GET /api/symbols
Response:
{
  "symbols": ["XAUUSD", "EURUSD", "GBPUSD", "BTCUSD", "ETHUSD"]
}

Sync Data

POST /api/sync/{symbol}
Body:
{
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-12-08T00:00:00Z"
}
Response:
{
  "status": "completed",
  "rows_synced": 50000
}

WebSocket Stream

WS /ws/stream
Subscribe message:
{
  "action": "subscribe",
  "channels": ["ticker", "candles"],
  "symbols": ["XAUUSD", "BTCUSD"]
}

ML Engine API (Port 8002)

Base URL: http://localhost:8002

Health Check

GET /health
Response:
{
  "status": "healthy",
  "version": "0.1.0",
  "models_loaded": true,
  "timestamp": "2025-12-08T12:00:00Z"
}

Get Active Signals (NEW - Primary endpoint for dashboard)

GET /api/signals/active
Query Parameters:
  - symbols: string (optional) - Comma-separated, e.g., "XAUUSD,EURUSD"
  - timeframe: string (optional, default: "15m")
  - rr_config: string (optional, default: "rr_2_1")

Response:
{
  "signals": [
    {
      "signal_id": "SIG-A1B2C3D4",
      "symbol": "XAUUSD",
      "direction": "long",
      "entry_price": 2350.50,
      "stop_loss": 2345.50,
      "take_profit": 2360.50,
      "risk_reward_ratio": 2.0,
      "prob_tp_first": 0.62,
      "confidence_score": 0.72,
      "amd_phase": "accumulation",
      "volatility_regime": "medium",
      "range_prediction": {
        "horizon": "15m",
        "delta_high": 12.5,
        "delta_low": 8.3,
        "confidence_high": 0.72,
        "confidence_low": 0.68
      },
      "timestamp": "2025-12-08T12:00:00Z",
      "valid_until": "2025-12-08T12:15:00Z"
    }
  ],
  "generated_at": "2025-12-08T12:00:00Z",
  "symbols_processed": ["XAUUSD", "EURUSD"],
  "errors": []
}

Generate Single Signal

POST /generate/signal
Body:
{
  "symbol": "XAUUSD",
  "timeframe": "15m"
}
Query: ?rr_config=rr_2_1

Response: SignalResponse (same as above, single object)

Detect AMD Phase

POST /api/amd/{symbol}
Query Parameters:
  - timeframe: string (default: "15m")
  - lookback_periods: number (default: 100)

Response:
{
  "phase": "accumulation",
  "confidence": 0.72,
  "start_time": "2025-12-08T11:00:00Z",
  "characteristics": {
    "range_compression": 0.65,
    "volume_ratio": 0.8
  },
  "signals": ["range_compression", "low_volume"],
  "strength": 0.68,
  "trading_bias": {
    "direction": "long",
    "position_size": 0.7
  }
}

Predict Range

POST /predict/range
Body:
{
  "symbol": "XAUUSD",
  "timeframe": "15m"
}

Response:
[
  {
    "horizon": "15m",
    "delta_high": 12.5,
    "delta_low": 8.3,
    "confidence_high": 0.72,
    "confidence_low": 0.68
  }
]

WebSocket Signals

WS /ws/signals
Receive real-time signals as they are generated

LLM Agent API (Port 8003)

Base URL: http://localhost:8003

Health Check

GET /api/v1/health
Response:
{
  "status": "healthy",
  "llm_provider": "ollama",
  "model": "llama3:8b",
  "gpu_available": true
}

Chat

POST /api/v1/chat
Body:
{
  "message": "What's the current outlook for XAUUSD?",
  "user_id": "user123",
  "conversation_id": "conv456",
  "stream": true
}

Response (SSE stream or JSON):
{
  "response": "Based on current analysis...",
  "tool_calls": [...],
  "conversation_id": "conv456"
}

Auto-Trade Configuration (NEW)

POST /api/v1/auto-trade/config
Body:
{
  "enabled": true,
  "symbols": ["XAUUSD", "BTCUSD"],
  "max_risk_per_trade": 0.02,
  "max_daily_trades": 5,
  "min_confidence": 0.6,
  "paper_trading": true,
  "require_confirmation": false
}

Response:
{
  "status": "configured",
  "config": { ... }
}

Get Auto-Trade Status

GET /api/v1/auto-trade/status
Response:
{
  "enabled": true,
  "mode": "paper",
  "trades_today": 3,
  "last_decision": {
    "symbol": "XAUUSD",
    "action": "BUY",
    "timestamp": "2025-12-08T12:00:00Z",
    "reasoning": "..."
  }
}

Get Trade Decisions History

GET /api/v1/auto-trade/decisions
Query: ?limit=50&symbol=XAUUSD

Response:
{
  "decisions": [
    {
      "id": "dec123",
      "symbol": "XAUUSD",
      "action": "BUY",
      "confidence": 0.72,
      "reasoning": "AMD phase is accumulation...",
      "ml_signal": { ... },
      "executed": true,
      "result": "pending",
      "timestamp": "2025-12-08T12:00:00Z"
    }
  ]
}

MT4 Integration (NEW)

Connect to MT4

POST /api/v1/auto-trade/mt4/connect
Body:
{
  "account_id": "your-metaapi-account-id",
  "token": "optional-metaapi-token"
}

Response:
{
  "success": true,
  "connected": true,
  "account": {
    "login": "12345678",
    "server": "Broker-Demo",
    "balance": 10000.0,
    "currency": "USD",
    "leverage": 100
  }
}

Get MT4 Status

GET /api/v1/auto-trade/mt4/status

Response:
{
  "connected": true,
  "account": {
    "id": "acc123",
    "login": "12345678",
    "server": "Broker-Demo",
    "platform": "mt4",
    "balance": 10000.0,
    "equity": 10150.0,
    "margin": 500.0,
    "free_margin": 9650.0,
    "profit": 150.0,
    "currency": "USD",
    "leverage": 100
  }
}

Get Open Positions

GET /api/v1/auto-trade/mt4/positions

Response:
{
  "success": true,
  "positions": [
    {
      "id": "pos123",
      "symbol": "EURUSD",
      "type": "BUY",
      "volume": 0.1,
      "open_price": 1.1000,
      "current_price": 1.1050,
      "stop_loss": 1.0950,
      "take_profit": 1.1100,
      "profit": 50.0,
      "swap": -0.5,
      "open_time": "2025-12-08T10:00:00Z"
    }
  ]
}

Close Position

POST /api/v1/auto-trade/mt4/positions/close
Body:
{
  "position_id": "pos123",
  "volume": null  // null = close all
}

Response:
{
  "success": true,
  "position_id": "pos123"
}

Disconnect from MT4

POST /api/v1/auto-trade/mt4/disconnect

Response:
{
  "success": true,
  "connected": false
}

Data Service MT4 API (Port 8001)

Base URL: http://localhost:8001/api/mt4

Connect to MT4 Account

POST /api/mt4/connect
Body:
{
  "account_id": "metaapi-account-id",
  "token": "optional-metaapi-token"
}

Response:
{
  "connected": true,
  "account_id": "acc123",
  "login": "12345678",
  "server": "Broker-Demo",
  "platform": "mt4",
  "balance": 10000.0,
  "currency": "USD"
}

Get Real-Time Tick

GET /api/mt4/tick/{symbol}

Response:
{
  "symbol": "EURUSD",
  "bid": 1.0998,
  "ask": 1.1002,
  "spread": 0.0004,
  "timestamp": "2025-12-08T12:00:00Z"
}

Get Historical Candles

GET /api/mt4/candles/{symbol}?timeframe=1h&limit=100

Response:
[
  {
    "time": "2025-12-08T11:00:00Z",
    "open": 1.0990,
    "high": 1.1010,
    "low": 1.0985,
    "close": 1.1000,
    "volume": 1250
  }
]

Open Trade

POST /api/mt4/trade
Body:
{
  "symbol": "EURUSD",
  "action": "BUY",  // BUY, SELL, BUY_LIMIT, SELL_LIMIT, BUY_STOP, SELL_STOP
  "volume": 0.1,
  "price": null,    // null for market orders
  "stop_loss": 1.0950,
  "take_profit": 1.1100,
  "comment": "Trading Platform AI"
}

Response:
{
  "success": true,
  "order_id": "ord123",
  "position_id": "pos456"
}

Close Position

POST /api/mt4/positions/{position_id}/close?volume=0.05

Response:
{
  "success": true,
  "position_id": "pos456"
}

Backend API (Port 8000)

Base URL: http://localhost:8000

Proxy to ML Engine

GET /api/ml/signals/active -> ML Engine /api/signals/active
POST /api/ml/amd/{symbol} -> ML Engine /api/amd/{symbol}

Proxy to LLM Agent

POST /api/chat -> LLM Agent /api/v1/chat
GET /api/auto-trade/status -> LLM Agent /api/v1/auto-trade/status

Portfolio Management

GET /api/portfolio
POST /api/portfolio/positions
GET /api/portfolio/history

Frontend API Consumption

Services Configuration (Frontend)

// src/config/services.ts
export const SERVICES = {
  BACKEND: import.meta.env.VITE_BACKEND_URL || 'http://localhost:8000',
  ML_ENGINE: import.meta.env.VITE_ML_ENGINE_URL || 'http://localhost:8002',
  DATA_SERVICE: import.meta.env.VITE_DATA_SERVICE_URL || 'http://localhost:8001',
  LLM_AGENT: import.meta.env.VITE_LLM_AGENT_URL || 'http://localhost:8003',
};

API Hooks (React Query)

// Example: useActiveSignals hook
export function useActiveSignals(symbols?: string[]) {
  return useQuery({
    queryKey: ['signals', 'active', symbols],
    queryFn: () => fetch(`${SERVICES.ML_ENGINE}/api/signals/active?symbols=${symbols?.join(',')}`),
    refetchInterval: 60000, // Refresh every minute
  });
}

Error Responses

All services use consistent error format:

{
  "error": "Error type",
  "detail": "Detailed error message",
  "timestamp": "2025-12-08T12:00:00Z"
}

HTTP Status Codes:

200: Success
400: Bad Request (invalid parameters)
401: Unauthorized
404: Not Found
500: Internal Server Error
503: Service Unavailable (models not loaded, etc.)

WebSocket Events

Data Service WebSocket

// Events received
{ type: "ticker", data: { symbol, price, timestamp } }
{ type: "candle", data: { symbol, ohlcv, timeframe } }
{ type: "orderbook", data: { symbol, bids, asks } }

ML Engine WebSocket

// Events received
{ type: "signal", data: SignalResponse }
{ type: "amd_change", data: { symbol, old_phase, new_phase } }

Document Version: 1.0.0 Last Updated: 2025-12-08

12 KiB Raw Blame History

Trading Platform - Service Integration Contracts

Overview

Architecture

Service Ports

Data Service API (Port 8001)

Health Check

Get OHLCV Data

Get Snapshot

Get Symbols

Sync Data

WebSocket Stream

ML Engine API (Port 8002)

Health Check

Get Active Signals (NEW - Primary endpoint for dashboard)

Generate Single Signal

Detect AMD Phase

Predict Range

WebSocket Signals

LLM Agent API (Port 8003)

Health Check

Chat

Auto-Trade Configuration (NEW)

Get Auto-Trade Status

Get Trade Decisions History

MT4 Integration (NEW)

Connect to MT4

Get MT4 Status

Get Open Positions

Close Position

Disconnect from MT4

Data Service MT4 API (Port 8001)

Connect to MT4 Account

Get Real-Time Tick

Get Historical Candles

Open Trade

Close Position

Backend API (Port 8000)

Proxy to ML Engine

Proxy to LLM Agent

Portfolio Management

Frontend API Consumption

Services Configuration (Frontend)

API Hooks (React Query)

Error Responses

WebSocket Events

Data Service WebSocket

ML Engine WebSocket

12 KiB

Raw Blame History