rckrdmrd
789d1ab46b
Some checks failed
CI Pipeline / changes (push) Has been cancelled
CI Pipeline / core (push) Has been cancelled
CI Pipeline / trading-backend (push) Has been cancelled
CI Pipeline / trading-data-service (push) Has been cancelled
CI Pipeline / trading-frontend (push) Has been cancelled
CI Pipeline / erp-core (push) Has been cancelled
CI Pipeline / erp-mecanicas (push) Has been cancelled
CI Pipeline / gamilit-backend (push) Has been cancelled
CI Pipeline / gamilit-frontend (push) Has been cancelled
635 lines
12 KiB
Markdown
635 lines
12 KiB
Markdown
# OrbiQuant IA - Service Integration Contracts
|
|
|
|
## Overview
|
|
|
|
Este documento define los contratos de API entre los servicios de la plataforma OrbiQuant IA 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": "OrbiQuant 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)
|
|
```typescript
|
|
// 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)
|
|
```typescript
|
|
// 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:
|
|
```json
|
|
{
|
|
"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
|
|
```javascript
|
|
// Events received
|
|
{ type: "ticker", data: { symbol, price, timestamp } }
|
|
{ type: "candle", data: { symbol, ohlcv, timeframe } }
|
|
{ type: "orderbook", data: { symbol, bids, asks } }
|
|
```
|
|
|
|
### ML Engine WebSocket
|
|
```javascript
|
|
// 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*
|