flow completo backend polymarket y socket.io implementado

backend/docs/ALERTS.md

@@ -0,0 +1,129 @@
+# ALERTS.md — Módulo de alertas
+
+Historial de alertas de precio disparadas por el job `processAlerts`. Las alertas se crean automáticamente cuando `yesPrice >= alertThreshold` en la watchlist del usuario.
+
+**Todos los endpoints requieren `Authorization: Bearer <token>`.**
+
+---
+
+## Endpoints
+
+### `GET /api/v1/alerts`
+
+Lista el historial de alertas del usuario, paginado y ordenado por `sentAt` DESC.
+
+**Query params**
+
+| Param | Tipo | Default | Descripción |
+|---|---|---|---|
+| `limit` | int (1-100) | `20` | Máximo de resultados |
+| `offset` | int | `0` | Paginación por offset |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": 4,
+      "userId": 1,
+      "marketId": "559677",
+      "type": "price_threshold",
+      "message": "<b>Price Alert</b>\nWill Hillary Clinton win the 2028 Democratic presidential nomination?\nYES: 0.8% ≥ threshold 0.1%",
+      "sentAt": "2026-05-16T09:38:00.033Z",
+      "market": {
+        "id": "559677",
+        "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?"
+      }
+    }
+  ]
+}
+```
+
+**Campos**
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `id` | int | ID de la alerta |
+| `userId` | int | Usuario que la recibió |
+| `marketId` | string | Mercado que la disparó |
+| `type` | string | Tipo de alerta (`price_threshold`) |
+| `message` | string | Mensaje enviado (formato HTML para Telegram) |
+| `sentAt` | ISO 8601 | Timestamp de envío |
+| `market.question` | string | Pregunta del mercado (para mostrar en UI) |
+
+---
+
+## Flujo de creación
+
+Las alertas **no se crean desde el frontend** — solo se leen. El flujo de creación es:
+
+1. `POST /api/v1/watchlist` con `alertThreshold` → guarda umbral en DB.
+2. Job `processAlerts` (cada minuto): evalúa `yesPrice >= alertThreshold` para cada watchlist entry con threshold definido.
+3. Si se cumple y no hay alerta reciente (< 5 min): crea `Alert` + envía Telegram + emite `price_alert` por socket.
+
+---
+
+## Socket — evento `price_alert`
+
+**Nombre del evento:** `price_alert`
+
+**Payload**
+
+```json
+{
+  "marketId": "559677",
+  "type": "price_threshold",
+  "message": "<b>Price Alert</b>\n..."
+}
+```
+
+**Uso en el frontend**
+
+```js
+socket.on('price_alert', ({ marketId, message }) => {
+  // mostrar notificación toast
+});
+```
+
+---
+
+## Integración Telegram
+
+Para recibir alertas vía Telegram:
+
+1. Crear un bot en [@BotFather](https://t.me/BotFather) y obtener el `TELEGRAM_BOT_TOKEN`.
+2. El usuario debe iniciar conversación con el bot y obtener su `chatId`.
+3. Configurar `telegramChatId` en el registro `User` (actualmente solo vía `prisma studio` o seed).
+4. Añadir `TELEGRAM_BOT_TOKEN` al `.env`.
+
+Si `TELEGRAM_BOT_TOKEN` no está configurado o el usuario no tiene `telegramChatId`, el envío se omite silenciosamente (la `Alert` se crea igualmente en DB).
+
+---
+
+## Ejemplos `curl`
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+
+# Listar alertas (últimas 10)
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:7860/api/v1/alerts?limit=10" | jq
+
+# Segunda página
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:7860/api/v1/alerts?limit=10&offset=10" | jq
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Params inválidos (limit > 100) |
+| `401` | `UNAUTHORIZED` | Sin token o token inválido |
+| `500` | `INTERNAL` | Error inesperado |

backend/docs/API.md

@@ -0,0 +1,137 @@
+# API.md — Referencia general PolySignal Backend
+
+Base URL (dev): `http://localhost:7860`  
+Base URL (prod, HF Spaces): misma URL que el frontend (mismo origen).
+
+---
+
+## Arranque rápido
+
+```bash
+cd backend/
+npm install
+npm run db:migrate        # solo primera vez
+npm run db:seed           # crea usuarios de prueba
+npm run dev               # http://localhost:7860
+```
+
+Usuarios de prueba: `admin@polysignal.test / Admin123!` y `user@polysignal.test / User123!`
+
+---
+
+## Autenticación
+
+El API usa JWT Bearer. Para obtener un token:
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+```
+
+Enviarlo en cada request protegido:
+
+```
+Authorization: Bearer <token>
+```
+
+---
+
+## Endpoints
+
+### Públicos (sin auth)
+
+| Método | Ruta | Descripción | Doc |
+|---|---|---|---|
+| `GET` | `/api/v1/health` | Sanity check | [AUTH.md](AUTH.md) |
+| `POST` | `/api/v1/auth/login` | Login → JWT | [AUTH.md](AUTH.md) |
+| `GET` | `/api/v1/markets` | Lista mercados paginada | [MARKETS.md](MARKETS.md) |
+| `GET` | `/api/v1/markets/:id` | Detalle de mercado | [MARKETS.md](MARKETS.md) |
+| `GET` | `/api/v1/markets/:id/signal` | Señal AI del mercado | [SIGNALS.md](SIGNALS.md) |
+
+### Protegidos (requieren `Authorization: Bearer <token>`)
+
+| Método | Ruta | Descripción | Doc |
+|---|---|---|---|
+| `GET` | `/api/v1/auth/me` | Perfil del usuario | [AUTH.md](AUTH.md) |
+| `POST` | `/api/v1/positions` | Abrir posición | [POSITIONS.md](POSITIONS.md) |
+| `GET` | `/api/v1/positions` | Listar posiciones | [POSITIONS.md](POSITIONS.md) |
+| `DELETE` | `/api/v1/positions/:id` | Cerrar posición | [POSITIONS.md](POSITIONS.md) |
+| `POST` | `/api/v1/watchlist` | Añadir a watchlist | [WATCHLIST.md](WATCHLIST.md) |
+| `GET` | `/api/v1/watchlist` | Listar watchlist | [WATCHLIST.md](WATCHLIST.md) |
+| `DELETE` | `/api/v1/watchlist/:marketId` | Eliminar de watchlist | [WATCHLIST.md](WATCHLIST.md) |
+| `GET` | `/api/v1/alerts` | Historial de alertas | [ALERTS.md](ALERTS.md) |
+
+---
+
+## Contrato de respuesta
+
+Todas las respuestas siguen el mismo envelope:
+
+```json
+// éxito
+{ "ok": true, "data": <payload>, "meta": { ...opcional } }
+
+// error
+{ "ok": false, "error": { "code": "ERROR_CODE", "message": "...", "details": [...] } }
+```
+
+Códigos HTTP: `200` lectura · `201` creación · `204` borrado · `400` validación · `401` no autenticado · `404` no encontrado · `409` conflicto · `429` rate limit · `500` server error.
+
+---
+
+## Rate limiting
+
+- **Global:** 200 req / 15 min / IP
+- **`POST /auth/login`:** 5 intentos / 15 min / IP
+
+Headers de respuesta: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.
+
+---
+
+## WebSocket (Socket.io)
+
+Conectar al mismo host que el backend:
+
+```js
+import { io } from 'socket.io-client';
+const socket = io('http://localhost:7860');
+```
+
+| Evento | Frecuencia | Descripción | Doc |
+|---|---|---|---|
+| `market_update` | cada 30s | Precio actualizado de un mercado | [MARKETS.md](MARKETS.md) |
+| `ai_signal` | cada 5 min | Nueva señal AI generada | [SIGNALS.md](SIGNALS.md) |
+| `price_alert` | cuando se dispara | Alerta de precio threshold | [ALERTS.md](ALERTS.md) |
+
+---
+
+## Importar en Insomnia / Postman
+
+Ver [`insomnia-collection.json`](insomnia-collection.json) — export v4 listo para importar en Insomnia.
+
+Pasos:
+1. Abrir Insomnia → Import → File
+2. Seleccionar `backend/docs/insomnia-collection.json`
+3. Configurar variable de entorno `base_url = http://localhost:7860`
+4. Ejecutar `POST /auth/login` y copiar el token a la variable `token`
+
+---
+
+## Variables de entorno completas
+
+Ver [`backend/.env.example`](../.env.example) para la plantilla completa.
+
+| Variable | Obligatoria | Descripción |
+|---|---|---|
+| `PORT` | Sí | Puerto del servidor (7860 para HF Spaces) |
+| `DATABASE_URL` | Sí | Path SQLite: `file:./polysignal.db` |
+| `JWT_SECRET` | Sí | Mínimo 32 chars |
+| `JWT_EXPIRES_IN` | No | Default `1h` |
+| `BCRYPT_ROUNDS` | No | Default `10` |
+| `CORS_ORIGIN` | No | Default `http://localhost:5173` |
+| `LOG_LEVEL` | No | Default `info` |
+| `HF_TOKEN` | No | HuggingFace (señales AI reales) |
+| `OPENROUTER_API_KEY` | No | Fallback LLM |
+| `FINNHUB_API_KEY` | No | Noticias para señales |
+| `TELEGRAM_BOT_TOKEN` | No | Alertas Telegram |

backend/docs/MARKETS.md

@@ -0,0 +1,193 @@
+# MARKETS.md — Módulo de mercados
+
+Referencia para el frontend: contrato HTTP, mapping de datos de Polymarket, evento socket y errores.
+
+---
+
+## Variables de entorno requeridas
+
+```
+DATABASE_URL=file:./backend/prisma/polysignal.db
+PORT=7860
+```
+
+No se necesita clave de API para Polymarket Gamma (pública).
+
+---
+
+## Endpoints
+
+### `GET /api/v1/markets`
+
+Lista paginada de mercados activos sincronizados desde Polymarket. **No requiere autenticación.**
+
+**Query params**
+
+| Param | Tipo | Default | Descripción |
+|---|---|---|---|
+| `limit` | int (1-100) | `20` | Máximo de resultados |
+| `offset` | int | `0` | Paginación por offset |
+| `category` | string | — | Filtro: `politics` \| `crypto` \| `economics` \| `sports` |
+| `status` | string | `active` | Filtro: `active` \| `closed` \| `resolved` |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": "559677",
+      "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+      "category": null,
+      "countryCode": null,
+      "yesPrice": 0.0075,
+      "noPrice": 0.9925,
+      "volumeEur": 38608906.44,
+      "liquidityEur": 2301398.64,
+      "status": "active",
+      "closesAt": "2028-11-07T00:00:00.000Z",
+      "lastSynced": "2026-05-16T09:38:30.204Z"
+    }
+  ],
+  "meta": {
+    "total": 100,
+    "limit": 1,
+    "offset": 0
+  }
+}
+```
+
+> `category` y `countryCode` pueden ser `null` si Polymarket no los proporciona.
+
+---
+
+### `GET /api/v1/markets/:id`
+
+Detalle de un mercado por su ID de Polymarket. **No requiere autenticación.**
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `id` | string | ID numérico de Polymarket (ej. `559677`) |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "559677",
+    "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+    "category": null,
+    "countryCode": null,
+    "yesPrice": 0.0075,
+    "noPrice": 0.9925,
+    "volumeEur": 38608906.44,
+    "liquidityEur": 2301398.64,
+    "status": "active",
+    "closesAt": "2028-11-07T00:00:00.000Z",
+    "lastSynced": "2026-05-16T09:38:30.204Z"
+  }
+}
+```
+
+**Respuesta `404`**
+
+```json
+{
+  "ok": false,
+  "error": { "code": "NOT_FOUND", "message": "Market not found" }
+}
+```
+
+---
+
+### `GET /api/v1/markets/:id/signal`
+
+Señal AI más reciente para un mercado. Ver [SIGNALS.md](SIGNALS.md) para el contrato completo.
+
+---
+
+## Mapping Polymarket Gamma API → `Market`
+
+URL de origen: `https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=100`
+
+| Campo Gamma API | Campo `Market` | Transformación |
+|---|---|---|
+| `id` | `id` | String (ID numérico de Polymarket) |
+| `question` | `question` | Directo |
+| `category` | `category` | Minúsculas; `null` si Gamma no lo envía |
+| — | `countryCode` | `null` por defecto (no proporcionado por Gamma) |
+| `outcomePrices[0]` | `yesPrice` | `parseFloat`; rango 0.0–1.0 |
+| `outcomePrices[1]` | `noPrice` | `parseFloat`; rango 0.0–1.0 |
+| `volume` | `volumeEur` | `parseFloat(volume) * 0.93` (USD→EUR tasa fija) |
+| `liquidity` | `liquidityEur` | Igual que `volumeEur` |
+| `active` + `closed` + `archived` | `status` | `active=true → "active"`, `closed=true → "closed"`, `archived=true → "resolved"` |
+| `endDateIso` | `closesAt` | `new Date(endDateIso)` |
+| — | `lastSynced` | `new Date()` en el momento del upsert |
+
+La sincronización usa `prisma.market.upsert({ where: { id }, ... })` para evitar duplicados.
+
+---
+
+## Socket — evento `market_update`
+
+Emitido por `src/socket/broadcaster.js` cada 30 s (tras `syncMarkets`).
+
+**Nombre del evento:** `market_update`
+
+**Payload**
+
+```json
+{
+  "marketId": "0x1a2b...",
+  "yesPrice": 0.63,
+  "noPrice": 0.37,
+  "volumeEur": 125000.00
+}
+```
+
+**Uso en el frontend (Socket.io client)**
+
+```js
+import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:7860');
+socket.on('market_update', ({ marketId, yesPrice, noPrice }) => {
+  // actualizar estado local del mercado
+});
+```
+
+En producción (HF Spaces) el frontend y backend comparten origen → usar `io()` sin URL.
+
+---
+
+## Ejemplos `curl`
+
+```bash
+# Listar mercados (primeros 5)
+curl "http://localhost:7860/api/v1/markets?limit=5"
+
+# Filtrar por estado
+curl "http://localhost:7860/api/v1/markets?status=active&limit=10"
+
+# Detalle de un mercado
+curl "http://localhost:7860/api/v1/markets/559677"
+
+# Señal AI del mercado
+curl "http://localhost:7860/api/v1/markets/559677/signal"
+```
+
+---
+
+## Códigos de error relevantes
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Parámetro inválido (ej. `limit` > 100) |
+| `404` | `NOT_FOUND` | ID de mercado no existe en DB |
+| `500` | `INTERNAL` | Error inesperado del servidor |
+
+Los endpoints de markets **no requieren autenticación** — son datos públicos.

backend/docs/POSITIONS.md

@@ -0,0 +1,196 @@
+# POSITIONS.md — Módulo de posiciones
+
+Simulador de capital virtual. Las posiciones no generan órdenes reales en Polymarket — son un tracking local de apuestas simuladas en euros.
+
+**Todos los endpoints requieren `Authorization: Bearer <token>`.**
+
+---
+
+## Endpoints
+
+### `POST /api/v1/positions`
+
+Abre una posición nueva en un mercado activo.
+
+**Body**
+
+```json
+{
+  "marketId": "559677",
+  "outcome": "YES",
+  "amountEur": 100
+}
+```
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `marketId` | string | ID del mercado (debe existir y estar `active`) |
+| `outcome` | `"YES"` \| `"NO"` | Lado de la apuesta |
+| `amountEur` | float > 0 | Importe a invertir en euros |
+
+**Respuesta `201`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 1,
+    "userId": 1,
+    "marketId": "559677",
+    "outcome": "YES",
+    "amountEur": 100,
+    "entryPrice": 0.0075,
+    "currentPrice": 0.0075,
+    "pnl": 0,
+    "kellyFraction": 0.25,
+    "status": "open",
+    "openedAt": "2026-05-16T09:14:55.750Z",
+    "closedAt": null,
+    "market": {
+      "id": "559677",
+      "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+      "yesPrice": 0.0075,
+      "noPrice": 0.9925,
+      "status": "active"
+    }
+  }
+}
+```
+
+**Campos de respuesta relevantes**
+
+| Campo | Descripción |
+|---|---|
+| `entryPrice` | Precio en el momento de abrir (`yesPrice` o `noPrice` según `outcome`) |
+| `currentPrice` | Precio actual (actualizado por `updatePositionsPnL` cada 30s) |
+| `pnl` | Profit & Loss en EUR (negativo = pérdida) |
+| `kellyFraction` | Fracción de Kelly calculada (capada al 0.25) |
+| `status` | `"open"` \| `"closed"` |
+
+---
+
+### `GET /api/v1/positions`
+
+Lista todas las posiciones del usuario autenticado (abiertas y cerradas).
+
+**Query params**
+
+| Param | Tipo | Default | Descripción |
+|---|---|---|---|
+| `limit` | int (1-100) | `20` | Máximo de resultados |
+| `offset` | int | `0` | Paginación por offset |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": 1,
+      "userId": 1,
+      "marketId": "559677",
+      "outcome": "YES",
+      "amountEur": 100,
+      "entryPrice": 0.0075,
+      "currentPrice": 0.0075,
+      "pnl": 0,
+      "kellyFraction": 0.25,
+      "status": "closed",
+      "openedAt": "2026-05-16T09:14:55.750Z",
+      "closedAt": "2026-05-16T09:15:04.155Z",
+      "market": {
+        "id": "559677",
+        "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+        "yesPrice": 0.0075,
+        "noPrice": 0.9925,
+        "status": "active"
+      }
+    }
+  ]
+}
+```
+
+---
+
+### `DELETE /api/v1/positions/:id`
+
+Cierra una posición abierta. Calcula el P&L final con el precio actual.
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `id` | int | ID de la posición |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 1,
+    "status": "closed",
+    "closedAt": "2026-05-16T09:15:04.155Z",
+    "pnl": -99.25
+  }
+}
+```
+
+**Errores**
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `404` | `NOT_FOUND` | Posición no existe o no pertenece al usuario |
+| `409` | `CONFLICT` | La posición ya está cerrada |
+
+---
+
+## Criterio de Kelly
+
+`kellyFraction = (pWin - pLoss) / pWin` capado al 25% y nunca negativo.
+
+- `pWin` = precio del outcome elegido (`yesPrice` o `noPrice`)
+- `pLoss` = `1 - pWin`
+
+El resultado es informativo — el usuario decide cuánto invertir.
+
+---
+
+## Socket — actualización de P&L
+
+El job `updatePositionsPnL` recalcula `currentPrice` y `pnl` de todas las posiciones abiertas cada 30s. No emite evento de socket propio; el frontend puede re-fetch `GET /positions` tras recibir `market_update`.
+
+---
+
+## Ejemplos `curl`
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+
+# Abrir posición
+curl -s -X POST http://localhost:7860/api/v1/positions \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"marketId":"559677","outcome":"YES","amountEur":50}' | jq
+
+# Listar posiciones
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:7860/api/v1/positions | jq
+
+# Cerrar posición (id=1)
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" http://localhost:7860/api/v1/positions/1 | jq
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Body inválido (outcome no es YES/NO, amountEur <= 0) |
+| `401` | `UNAUTHORIZED` | Sin token o token inválido |
+| `404` | `NOT_FOUND` | Mercado o posición no existe |
+| `409` | `CONFLICT` | Mercado no activo o posición ya cerrada |
+| `500` | `INTERNAL` | Error inesperado |

backend/docs/SIGNALS.md

@@ -0,0 +1,128 @@
+# SIGNALS.md — Módulo de señales AI
+
+Referencia para el frontend: señales generadas por la pipeline FinBERT + Qwen3-8B sobre mercados de Polymarket.
+
+---
+
+## Variables de entorno (opcionales)
+
+| Variable | Descripción |
+|---|---|
+| `HF_TOKEN` | HuggingFace Pro token — FinBERT + Qwen3-8B |
+| `OPENROUTER_API_KEY` | Fallback LLM si HuggingFace está saturado |
+| `FINNHUB_API_KEY` | Noticias financieras para contexto |
+
+Sin ninguna clave, el backend usa una señal **rule-based** derivada de los precios del mercado.
+
+---
+
+## Endpoints
+
+### `GET /api/v1/markets/:id/signal`
+
+Señal AI más reciente para el mercado. **No requiere autenticación.**
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `id` | string | ID numérico de Polymarket (ej. `559677`) |
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 81,
+    "marketId": "559677",
+    "signal": "bearish",
+    "confidence": 0.9,
+    "summary": "Market strongly favors NO at 99% probability. Downside momentum dominates.",
+    "keyRisk": "Unexpected positive developments could reverse this rapidly.",
+    "newsCount": 0,
+    "modelVersion": "Qwen3-8B",
+    "generatedAt": "2026-05-16T09:35:00.110Z"
+  }
+}
+```
+
+**Campos**
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `id` | int | ID de la señal en DB |
+| `marketId` | string | ID del mercado |
+| `signal` | `"bullish"` \| `"bearish"` \| `"neutral"` | Dirección recomendada |
+| `confidence` | float (0–1) | Nivel de confianza del modelo |
+| `summary` | string | Resumen del análisis |
+| `keyRisk` | string \| null | Principal riesgo identificado |
+| `newsCount` | int | Noticias procesadas por Finnhub |
+| `modelVersion` | string | Modelo que generó la señal (`Qwen3-8B`, `OpenRouter`, `rule-based`) |
+| `generatedAt` | ISO 8601 | Timestamp de generación |
+
+**Respuesta `404`**
+
+```json
+{
+  "ok": false,
+  "error": { "code": "NOT_FOUND", "message": "No signal found for this market" }
+}
+```
+
+---
+
+## Pipeline de generación
+
+1. **Finnhub** → noticias relacionadas por keywords del `question`
+2. **FinBERT** (HuggingFace) → filtro de sentimiento; descarta noticias irrelevantes
+3. **Qwen3-8B** (HuggingFace) → genera señal JSON `{ signal, confidence, summary, keyRisk }`
+4. **OpenRouter** → fallback si HF está saturado (HTTP 503)
+5. **Rule-based** → fallback final: `yesPrice > 0.6 → bullish`, `yesPrice < 0.4 → bearish`, else `neutral`
+
+La señal se persiste en `AISignal` y se emite por socket (`ai_signal`).
+
+---
+
+## Socket — evento `ai_signal`
+
+Emitido por `src/socket/broadcaster.js` cada 5 min (tras `generateSignals`).
+
+**Nombre del evento:** `ai_signal`
+
+**Payload**
+
+```json
+{
+  "marketId": "559677",
+  "signal": "bearish",
+  "confidence": 0.9,
+  "summary": "Market strongly favors NO at 99% probability."
+}
+```
+
+**Uso en el frontend**
+
+```js
+socket.on('ai_signal', ({ marketId, signal, confidence }) => {
+  // actualizar badge de señal en la tarjeta del mercado
+});
+```
+
+---
+
+## Ejemplos `curl`
+
+```bash
+# Señal más reciente de un mercado
+curl "http://localhost:7860/api/v1/markets/559677/signal"
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `404` | `NOT_FOUND` | No hay señal generada aún para ese mercado |
+| `500` | `INTERNAL` | Error inesperado del servidor |

backend/docs/WATCHLIST.md

@@ -0,0 +1,157 @@
+# WATCHLIST.md — Módulo de watchlist
+
+Mercados favoritos del usuario con umbral de alerta opcional. Cuando `yesPrice >= alertThreshold`, el job `processAlerts` crea una `Alert` y envía notificación por Telegram.
+
+**Todos los endpoints requieren `Authorization: Bearer <token>`.**
+
+---
+
+## Endpoints
+
+### `POST /api/v1/watchlist`
+
+Añade un mercado a la watchlist del usuario.
+
+**Body**
+
+```json
+{
+  "marketId": "559677",
+  "alertThreshold": 0.75
+}
+```
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `marketId` | string | ID del mercado (debe existir en DB) |
+| `alertThreshold` | float (0–1) \| null | Precio YES que dispara la alerta; `null` para no alertar |
+
+**Respuesta `201`**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": 2,
+    "userId": 1,
+    "marketId": "559677",
+    "alertThreshold": 0.75,
+    "createdAt": "2026-05-16T09:21:41.606Z",
+    "market": {
+      "id": "559677",
+      "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+      "yesPrice": 0.0075,
+      "noPrice": 0.9925,
+      "status": "active"
+    }
+  }
+}
+```
+
+**Respuesta `409`** — mercado ya está en la watchlist del usuario:
+
+```json
+{
+  "ok": false,
+  "error": { "code": "CONFLICT", "message": "Market already in watchlist" }
+}
+```
+
+---
+
+### `GET /api/v1/watchlist`
+
+Lista todos los mercados en la watchlist del usuario con datos de mercado embebidos.
+
+**Respuesta `200`**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "id": 2,
+      "userId": 1,
+      "marketId": "559677",
+      "alertThreshold": 0.001,
+      "createdAt": "2026-05-16T09:21:41.606Z",
+      "market": {
+        "id": "559677",
+        "question": "Will Hillary Clinton win the 2028 Democratic presidential nomination?",
+        "yesPrice": 0.0075,
+        "noPrice": 0.9925,
+        "status": "active"
+      }
+    }
+  ]
+}
+```
+
+---
+
+### `DELETE /api/v1/watchlist/:marketId`
+
+Elimina un mercado de la watchlist del usuario.
+
+**Params**
+
+| Param | Tipo | Descripción |
+|---|---|---|
+| `marketId` | string | ID del mercado |
+
+**Respuesta `204`** — sin body.
+
+**Respuesta `404`**
+
+```json
+{
+  "ok": false,
+  "error": { "code": "NOT_FOUND", "message": "Watchlist entry not found" }
+}
+```
+
+---
+
+## Lógica de alertas
+
+El job `processAlerts` (cron `* * * * *`) evalúa cada entrada de watchlist con `alertThreshold` definido:
+
+- Si `market.yesPrice >= alertThreshold` → crea `Alert` + envía Telegram + emite `price_alert` por socket.
+- Deduplicación: no se crea una segunda alerta si ya existe una para el mismo mercado en los últimos 5 min.
+
+Para recibir alertas por Telegram, el usuario debe tener `telegramChatId` configurado en su perfil (campo opcional en `User`).
+
+---
+
+## Ejemplos `curl`
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:7860/api/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"admin@polysignal.test","password":"Admin123!"}' | jq -r '.data.token')
+
+# Añadir a watchlist con umbral 75%
+curl -s -X POST http://localhost:7860/api/v1/watchlist \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"marketId":"559677","alertThreshold":0.75}' | jq
+
+# Listar watchlist
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:7860/api/v1/watchlist | jq
+
+# Eliminar de watchlist
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:7860/api/v1/watchlist/559677"
+```
+
+---
+
+## Códigos de error
+
+| HTTP | Código | Cuándo |
+|---|---|---|
+| `400` | `VALIDATION_ERROR` | Body inválido (marketId vacío, threshold fuera de 0–1) |
+| `401` | `UNAUTHORIZED` | Sin token o token inválido |
+| `404` | `NOT_FOUND` | Mercado no existe en DB o entrada no encontrada al borrar |
+| `409` | `CONFLICT` | Mercado ya en watchlist |
+| `500` | `INTERNAL` | Error inesperado |

backend/docs/insomnia-collection.json

@@ -0,0 +1,206 @@
+{
+  "_type": "export",
+  "__export_format": 4,
+  "__export_date": "2026-05-16",
+  "__export_source": "polysignal-backend",
+  "resources": [
+    {
+      "_id": "env_polysignal",
+      "_type": "environment",
+      "name": "PolySignal Dev",
+      "data": {
+        "base_url": "http://localhost:7860",
+        "token": ""
+      }
+    },
+    {
+      "_id": "wrk_polysignal",
+      "_type": "workspace",
+      "name": "PolySignal Backend",
+      "description": "API REST PolySignal — mercados Polymarket + señales AI"
+    },
+    {
+      "_id": "grp_auth",
+      "_type": "request_group",
+      "name": "Auth",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_health",
+      "_type": "request",
+      "parentId": "grp_auth",
+      "name": "GET /health",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/health",
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "req_login",
+      "_type": "request",
+      "parentId": "grp_auth",
+      "name": "POST /auth/login",
+      "method": "POST",
+      "url": "{{ _.base_url }}/api/v1/auth/login",
+      "headers": [{ "name": "Content-Type", "value": "application/json" }],
+      "body": {
+        "mimeType": "application/json",
+        "text": "{\n  \"email\": \"admin@polysignal.test\",\n  \"password\": \"Admin123!\"\n}"
+      }
+    },
+    {
+      "_id": "req_me",
+      "_type": "request",
+      "parentId": "grp_auth",
+      "name": "GET /auth/me",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/auth/me",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "grp_markets",
+      "_type": "request_group",
+      "name": "Markets",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_markets_list",
+      "_type": "request",
+      "parentId": "grp_markets",
+      "name": "GET /markets",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/markets",
+      "parameters": [
+        { "name": "limit", "value": "10" },
+        { "name": "offset", "value": "0" }
+      ],
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "req_markets_by_id",
+      "_type": "request",
+      "parentId": "grp_markets",
+      "name": "GET /markets/:id",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/markets/559677",
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "req_market_signal",
+      "_type": "request",
+      "parentId": "grp_markets",
+      "name": "GET /markets/:id/signal",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/markets/559677/signal",
+      "headers": [],
+      "body": {}
+    },
+    {
+      "_id": "grp_positions",
+      "_type": "request_group",
+      "name": "Positions",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_positions_open",
+      "_type": "request",
+      "parentId": "grp_positions",
+      "name": "POST /positions (open)",
+      "method": "POST",
+      "url": "{{ _.base_url }}/api/v1/positions",
+      "headers": [
+        { "name": "Authorization", "value": "Bearer {{ _.token }}" },
+        { "name": "Content-Type", "value": "application/json" }
+      ],
+      "body": {
+        "mimeType": "application/json",
+        "text": "{\n  \"marketId\": \"559677\",\n  \"outcome\": \"YES\",\n  \"amountEur\": 100\n}"
+      }
+    },
+    {
+      "_id": "req_positions_list",
+      "_type": "request",
+      "parentId": "grp_positions",
+      "name": "GET /positions",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/positions",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "req_positions_close",
+      "_type": "request",
+      "parentId": "grp_positions",
+      "name": "DELETE /positions/:id (close)",
+      "method": "DELETE",
+      "url": "{{ _.base_url }}/api/v1/positions/1",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "grp_watchlist",
+      "_type": "request_group",
+      "name": "Watchlist",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_watchlist_add",
+      "_type": "request",
+      "parentId": "grp_watchlist",
+      "name": "POST /watchlist",
+      "method": "POST",
+      "url": "{{ _.base_url }}/api/v1/watchlist",
+      "headers": [
+        { "name": "Authorization", "value": "Bearer {{ _.token }}" },
+        { "name": "Content-Type", "value": "application/json" }
+      ],
+      "body": {
+        "mimeType": "application/json",
+        "text": "{\n  \"marketId\": \"559677\",\n  \"alertThreshold\": 0.75\n}"
+      }
+    },
+    {
+      "_id": "req_watchlist_list",
+      "_type": "request",
+      "parentId": "grp_watchlist",
+      "name": "GET /watchlist",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/watchlist",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "req_watchlist_delete",
+      "_type": "request",
+      "parentId": "grp_watchlist",
+      "name": "DELETE /watchlist/:marketId",
+      "method": "DELETE",
+      "url": "{{ _.base_url }}/api/v1/watchlist/559677",
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    },
+    {
+      "_id": "grp_alerts",
+      "_type": "request_group",
+      "name": "Alerts",
+      "parentId": "wrk_polysignal"
+    },
+    {
+      "_id": "req_alerts_list",
+      "_type": "request",
+      "parentId": "grp_alerts",
+      "name": "GET /alerts",
+      "method": "GET",
+      "url": "{{ _.base_url }}/api/v1/alerts",
+      "parameters": [
+        { "name": "limit", "value": "20" },
+        { "name": "offset", "value": "0" }
+      ],
+      "headers": [{ "name": "Authorization", "value": "Bearer {{ _.token }}" }],
+      "body": {}
+    }
+  ]
+}

backend/src/alerts/alerts.controller.js

@@ -0,0 +1,9 @@
+import { ok } from '../utils/apiResponse.js';
+import { alertsService } from './alerts.service.js';
+
+export const alertsController = {
+  async list(req, res) {
+    const alerts = await alertsService.list(req.user.id, req.query);
+    ok(res, alerts);
+  },
+};

backend/src/alerts/alerts.repository.js

@@ -0,0 +1,23 @@
+import { prisma } from '../utils/prisma.js';
+
+export const alertsRepository = {
+  create({ userId, marketId, type, message }) {
+    return prisma.alert.create({ data: { userId, marketId, type, message } });
+  },
+
+  findByUser(userId, { limit = 50, offset = 0 } = {}) {
+    return prisma.alert.findMany({
+      where: { userId },
+      orderBy: { sentAt: 'desc' },
+      take: limit,
+      skip: offset,
+      include: { market: { select: { id: true, question: true } } },
+    });
+  },
+
+  findRecent(userId, marketId, type, windowMs) {
+    return prisma.alert.findFirst({
+      where: { userId, marketId, type, sentAt: { gte: new Date(Date.now() - windowMs) } },
+    });
+  },
+};

backend/src/alerts/alerts.routes.js

@@ -0,0 +1,11 @@
+import { Router } from 'express';
+import { requireAuth } from '../middlewares/requireAuth.js';
+import { alertsController } from './alerts.controller.js';
+
+const router = Router();
+
+router.use(requireAuth);
+
+router.get('/', alertsController.list);
+
+export default router;

backend/src/alerts/alerts.service.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { alertsRepository } from './alerts.repository.js';
+import { watchlistRepository } from '../watchlist/watchlist.repository.js';
+import { sendMessage } from './telegram.client.js';
+import { emitPriceAlert } from '../socket/broadcaster.js';
+import { logger } from '../utils/logger.js';
+
+const listQuery = z.object({
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+const DEDUP_WINDOW_MS = 5 * 60 * 1000; // 5 min
+
+export const alertsService = {
+  list(userId, query) {
+    const { limit, offset } = listQuery.parse(query);
+    return alertsRepository.findByUser(userId, { limit, offset });
+  },
+
+  async processAll() {
+    const entries = await watchlistRepository.findAllWithThreshold();
+
+    for (const entry of entries) {
+      const { alertThreshold, user, market } = entry;
+      if (!market.yesPrice || market.yesPrice < alertThreshold) continue;
+
+      const recent = await alertsRepository.findRecent(user.id, market.id, 'price_threshold', DEDUP_WINDOW_MS);
+      if (recent) continue;
+
+      const pct = (market.yesPrice * 100).toFixed(1);
+      const threshold = (alertThreshold * 100).toFixed(1);
+      const message =
+        `<b>Price Alert</b>\n${market.question}\nYES: ${pct}% ≥ threshold ${threshold}%`;
+
+      await alertsRepository.create({ userId: user.id, marketId: market.id, type: 'price_threshold', message });
+      await sendMessage(user.telegramChatId, message);
+      emitPriceAlert({ marketId: market.id, type: 'price_threshold', message });
+      logger.info({ marketId: market.id, userId: user.id }, 'price alert sent');
+    }
+  },
+};

backend/src/alerts/telegram.client.js

@@ -0,0 +1,16 @@
+import { httpPost } from '../utils/httpClient.js';
+import { config } from '../config.js';
+import { logger } from '../utils/logger.js';
+
+export async function sendMessage(chatId, text) {
+  if (!config.TELEGRAM_BOT_TOKEN || !chatId) return;
+  try {
+    await httpPost(
+      `https://api.telegram.org/bot${config.TELEGRAM_BOT_TOKEN}/sendMessage`,
+      { chat_id: chatId, text, parse_mode: 'HTML' },
+      { retries: 1, timeout: 8_000 },
+    );
+  } catch (err) {
+    logger.warn({ err: err.message, chatId }, 'telegram send failed');
+  }
+}

backend/src/app.js

@@ -1,9 +1,15 @@
 import express from 'express';
 import cors from 'cors';
 import helmet from 'helmet';
+import rateLimit from 'express-rate-limit';
 import { config } from './config.js';
 import { ok } from './utils/apiResponse.js';
 import authRoutes from './auth/auth.routes.js';
+import marketsRoutes from './markets/markets.routes.js';
+import signalsRoutes from './signals/signals.routes.js';
+import positionsRoutes from './positions/positions.routes.js';
+import watchlistRoutes from './watchlist/watchlist.routes.js';
+import alertsRoutes from './alerts/alerts.routes.js';
 import { notFound } from './middlewares/notFound.js';
 import { errorHandler } from './middlewares/errorHandler.js';
 
@@ -11,10 +17,24 @@ const app = express();
 
 app.use(helmet());
 app.use(cors({ origin: config.CORS_ORIGIN, credentials: true }));
+app.use(
+  rateLimit({
+    windowMs: 15 * 60 * 1000,
+    max: 200,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { ok: false, error: { code: 'TOO_MANY_REQUESTS', message: 'Rate limit exceeded' } },
+  }),
+);
 app.use(express.json({ limit: '1mb' }));
 
 app.get('/api/v1/health', (_req, res) => ok(res, { status: 'up' }));
 app.use('/api/v1/auth', authRoutes);
+app.use('/api/v1/markets', marketsRoutes);
+app.use('/api/v1/markets', signalsRoutes);
+app.use('/api/v1/positions', positionsRoutes);
+app.use('/api/v1/watchlist', watchlistRoutes);
+app.use('/api/v1/alerts', alertsRoutes);
 
 app.use(notFound);
 app.use(errorHandler);

backend/src/config.js

@@ -10,6 +10,10 @@ const schema = z.object({
   BCRYPT_ROUNDS: z.coerce.number().int().min(4).max(15).default(10),
   CORS_ORIGIN: z.string().default('http://localhost:5173'),
   LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
+  HF_TOKEN: z.string().optional(),
+  OPENROUTER_API_KEY: z.string().optional(),
+  FINNHUB_API_KEY: z.string().optional(),
+  TELEGRAM_BOT_TOKEN: z.string().optional(),
 });
 
 const parsed = schema.safeParse(process.env);

backend/src/index.js

@@ -1,15 +1,24 @@
 import http from 'node:http';
+import { Server as IOServer } from 'socket.io';
 import app from './app.js';
 import { config } from './config.js';
 import { logger } from './utils/logger.js';
 import { prisma } from './utils/prisma.js';
+import { attachBroadcaster } from './socket/broadcaster.js';
+import { startScheduler } from './scheduler.js';
 
 const httpServer = http.createServer(app);
+const io = new IOServer(httpServer, { cors: { origin: config.CORS_ORIGIN } });
+attachBroadcaster(io);
 
 httpServer.listen(config.PORT, () => {
   logger.info({ port: config.PORT, env: config.NODE_ENV }, 'PolySignal backend up');
 });
 
+if (config.NODE_ENV !== 'test') {
+  startScheduler();
+}
+
 for (const sig of ['SIGTERM', 'SIGINT']) {
   process.on(sig, async () => {
     logger.info({ sig }, 'shutting down');

backend/src/markets/markets.controller.js

@@ -0,0 +1,15 @@
+import { ok } from '../utils/apiResponse.js';
+import { marketsService } from './markets.service.js';
+
+export const marketsController = {
+  async list(req, res) {
+    const { limit, offset, category, status } = req.query;
+    const { data, total } = await marketsService.list({ limit, offset, category, status });
+    ok(res, data, { total, limit, offset });
+  },
+
+  async getById(req, res) {
+    const market = await marketsService.getById(req.params.id);
+    ok(res, market);
+  },
+};

backend/src/markets/markets.repository.js

@@ -0,0 +1,32 @@
+import { prisma } from '../utils/prisma.js';
+
+export const marketsRepository = {
+  findMany({ limit, offset, category, status }) {
+    const where = { status };
+    if (category) where.category = category;
+    return prisma.market.findMany({
+      where,
+      orderBy: { volumeEur: 'desc' },
+      take: limit,
+      skip: offset,
+    });
+  },
+
+  count({ category, status }) {
+    const where = { status };
+    if (category) where.category = category;
+    return prisma.market.count({ where });
+  },
+
+  findById(id) {
+    return prisma.market.findUnique({ where: { id } });
+  },
+
+  upsert(market) {
+    return prisma.market.upsert({
+      where: { id: market.id },
+      update: market,
+      create: market,
+    });
+  },
+};

backend/src/markets/markets.routes.js

@@ -0,0 +1,11 @@
+import { Router } from 'express';
+import { validate } from '../middlewares/validate.js';
+import { marketsController } from './markets.controller.js';
+import { listQuery, idParam } from './markets.validators.js';
+
+const router = Router();
+
+router.get('/', validate(listQuery, 'query'), marketsController.list);
+router.get('/:id', validate(idParam, 'params'), marketsController.getById);
+
+export default router;

backend/src/markets/markets.service.js

@@ -0,0 +1,18 @@
+import { HttpError } from '../utils/apiResponse.js';
+import { marketsRepository } from './markets.repository.js';
+
+export const marketsService = {
+  async list(query) {
+    const [data, total] = await Promise.all([
+      marketsRepository.findMany(query),
+      marketsRepository.count(query),
+    ]);
+    return { data, total };
+  },
+
+  async getById(id) {
+    const market = await marketsRepository.findById(id);
+    if (!market) throw new HttpError(404, 'NOT_FOUND', 'Market not found');
+    return market;
+  },
+};

backend/src/markets/markets.validators.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const listQuery = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+  category: z.enum(['politics', 'crypto', 'economics', 'sports']).optional(),
+  status: z.enum(['active', 'closed', 'resolved']).default('active'),
+});
+
+export const idParam = z.object({
+  id: z.string().min(1),
+});

backend/src/markets/polymarket.client.js

@@ -0,0 +1,45 @@
+import { httpGet } from '../utils/httpClient.js';
+
+const GAMMA_URL = 'https://gamma-api.polymarket.com/markets';
+const USD_TO_EUR = 0.93;
+
+function mapStatus({ active, closed, archived }) {
+  if (archived) return 'resolved';
+  if (closed) return 'closed';
+  return 'active';
+}
+
+function parsePrices(outcomePrices) {
+  try {
+    const arr = JSON.parse(outcomePrices);
+    return {
+      yesPrice: arr[0] != null ? parseFloat(arr[0]) : null,
+      noPrice: arr[1] != null ? parseFloat(arr[1]) : null,
+    };
+  } catch {
+    return { yesPrice: null, noPrice: null };
+  }
+}
+
+export function mapMarket(raw) {
+  const { yesPrice, noPrice } = parsePrices(raw.outcomePrices);
+  return {
+    id: String(raw.id),
+    question: raw.question,
+    category: null,
+    countryCode: null,
+    yesPrice,
+    noPrice,
+    volumeEur: raw.volume != null ? parseFloat(raw.volume) * USD_TO_EUR : null,
+    liquidityEur: raw.liquidity != null ? parseFloat(raw.liquidity) * USD_TO_EUR : null,
+    status: mapStatus(raw),
+    closesAt: raw.endDate ? new Date(raw.endDate) : null,
+    lastSynced: new Date(),
+  };
+}
+
+export async function fetchActiveMarkets(limit = 100) {
+  const url = `${GAMMA_URL}?active=true&closed=false&limit=${limit}`;
+  const raw = await httpGet(url);
+  return raw.map(mapMarket);
+}

backend/src/middlewares/validate.js

@@ -7,6 +7,11 @@ export const validate = (schema, source = 'body') => (req, _res, next) => {
       new HttpError(400, 'VALIDATION_ERROR', 'Invalid request', result.error.flatten().fieldErrors),
     );
   }
-  req[source] = result.data;
+  // req.query is a getter in Express 5 — override it with a data property
+  if (source === 'query') {
+    Object.defineProperty(req, 'query', { value: result.data, writable: true, configurable: true });
+  } else {
+    req[source] = result.data;
+  }
   next();
 };

backend/src/positions/kelly.js

@@ -0,0 +1,12 @@
+/**
+ * Kelly criterion capped at 25%.
+ * k = (odds * pWin - pLose) / odds
+ * odds = (1 / price) - 1
+ */
+export function kellyFraction(price, pWin) {
+  if (!price || price <= 0 || price >= 1 || !pWin) return 0;
+  const pLose = 1 - pWin;
+  const odds = 1 / price - 1;
+  const k = (odds * pWin - pLose) / odds;
+  return Math.min(Math.max(k, 0), 0.25);
+}

backend/src/positions/positions.controller.js

@@ -0,0 +1,19 @@
+import { ok, created, noContent } from '../utils/apiResponse.js';
+import { positionsService } from './positions.service.js';
+
+export const positionsController = {
+  async open(req, res) {
+    const position = await positionsService.open(req.user.id, req.body);
+    created(res, position);
+  },
+
+  async list(req, res) {
+    const positions = await positionsService.list(req.user.id, req.query.status);
+    ok(res, positions);
+  },
+
+  async close(req, res) {
+    const position = await positionsService.close(req.params.id, req.user.id);
+    ok(res, position);
+  },
+};

backend/src/positions/positions.repository.js

@@ -0,0 +1,30 @@
+import { prisma } from '../utils/prisma.js';
+
+export const positionsRepository = {
+  create(data) {
+    return prisma.position.create({ data });
+  },
+
+  findByUser(userId, status) {
+    return prisma.position.findMany({
+      where: { userId, ...(status ? { status } : {}) },
+      include: { market: { select: { id: true, question: true, yesPrice: true, noPrice: true, status: true } } },
+      orderBy: { openedAt: 'desc' },
+    });
+  },
+
+  findByIdAndUser(id, userId) {
+    return prisma.position.findFirst({ where: { id, userId } });
+  },
+
+  findAllOpen() {
+    return prisma.position.findMany({
+      where: { status: 'open' },
+      include: { market: { select: { yesPrice: true, noPrice: true } } },
+    });
+  },
+
+  update(id, data) {
+    return prisma.position.update({ where: { id }, data });
+  },
+};

backend/src/positions/positions.routes.js

@@ -0,0 +1,15 @@
+import { Router } from 'express';
+import { validate } from '../middlewares/validate.js';
+import { requireAuth } from '../middlewares/requireAuth.js';
+import { positionsController } from './positions.controller.js';
+import { openBody, idParam, listQuery } from './positions.validators.js';
+
+const router = Router();
+
+router.use(requireAuth);
+
+router.post('/', validate(openBody), positionsController.open);
+router.get('/', validate(listQuery, 'query'), positionsController.list);
+router.delete('/:id', validate(idParam, 'params'), positionsController.close);
+
+export default router;

backend/src/positions/positions.service.js

@@ -0,0 +1,76 @@
+import { HttpError } from '../utils/apiResponse.js';
+import { positionsRepository } from './positions.repository.js';
+import { marketsRepository } from '../markets/markets.repository.js';
+import { signalsRepository } from '../signals/signals.repository.js';
+import { kellyFraction } from './kelly.js';
+
+function currentPriceForOutcome(market, outcome) {
+  return outcome === 'YES' ? market.yesPrice : market.noPrice;
+}
+
+function calcPnl(amountEur, entryPrice, currentPrice) {
+  if (!currentPrice || !entryPrice) return 0;
+  return amountEur * (currentPrice / entryPrice - 1);
+}
+
+export const positionsService = {
+  async open(userId, { marketId, outcome, amountEur }) {
+    const market = await marketsRepository.findById(marketId);
+    if (!market) throw new HttpError(404, 'NOT_FOUND', 'Market not found');
+    if (market.status !== 'active') throw new HttpError(409, 'MARKET_CLOSED', 'Market is not active');
+
+    const entryPrice = currentPriceForOutcome(market, outcome);
+    if (!entryPrice) throw new HttpError(409, 'NO_PRICE', 'Market price unavailable');
+
+    const latestSignal = await signalsRepository.findLatestByMarket(marketId);
+    const confidence = latestSignal?.confidence ?? 0.5;
+    const fraction = kellyFraction(entryPrice, confidence);
+
+    return positionsRepository.create({
+      userId,
+      marketId,
+      outcome,
+      amountEur,
+      entryPrice,
+      currentPrice: entryPrice,
+      pnl: 0,
+      kellyFraction: fraction,
+      status: 'open',
+    });
+  },
+
+  list(userId, status) {
+    return positionsRepository.findByUser(userId, status);
+  },
+
+  async close(id, userId) {
+    const position = await positionsRepository.findByIdAndUser(id, userId);
+    if (!position) throw new HttpError(404, 'NOT_FOUND', 'Position not found');
+    if (position.status === 'closed') throw new HttpError(409, 'ALREADY_CLOSED', 'Position already closed');
+
+    const market = await marketsRepository.findById(position.marketId);
+    const currentPrice = market ? currentPriceForOutcome(market, position.outcome) : position.entryPrice;
+    const finalPnl = calcPnl(position.amountEur, position.entryPrice, currentPrice);
+
+    return positionsRepository.update(id, {
+      status: 'closed',
+      currentPrice,
+      pnl: finalPnl,
+      closedAt: new Date(),
+    });
+  },
+
+  async updateAllPnL() {
+    const open = await positionsRepository.findAllOpen();
+    await Promise.all(
+      open.map((pos) => {
+        const currentPrice = currentPriceForOutcome(pos.market, pos.outcome);
+        if (!currentPrice) return Promise.resolve();
+        return positionsRepository.update(pos.id, {
+          currentPrice,
+          pnl: calcPnl(pos.amountEur, pos.entryPrice, currentPrice),
+        });
+      }),
+    );
+  },
+};

backend/src/positions/positions.validators.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+export const openBody = z.object({
+  marketId: z.string().min(1),
+  outcome: z.enum(['YES', 'NO']),
+  amountEur: z.number().positive().max(100_000),
+});
+
+export const idParam = z.object({
+  id: z.coerce.number().int().positive(),
+});
+
+export const listQuery = z.object({
+  status: z.enum(['open', 'closed']).optional(),
+});

backend/src/routes/alerts.js

@@ -1,9 +0,0 @@
-/**
- * Rutas REST para alertas y notificaciones.
- *
- * Endpoints:
- *   GET /api/v1/alerts — historial de alertas enviadas (price_threshold, signal_change)
- *
- * Las alertas se generan automáticamente por el scheduler cada 60 segundos
- * y se envían vía Telegram Bot API.
- */

backend/src/routes/markets.js

@@ -1,9 +0,0 @@
-/**
- * Rutas REST para mercados de predicción.
- *
- * Endpoints:
- *   GET /api/v1/markets          — lista mercados activos (filtrables por category, country, limit)
- *   GET /api/v1/markets/:id      — detalle de un mercado + última señal IA
- *
- * Delega la obtención de datos al servicio services/polymarket.js.
- */

backend/src/routes/positions.js

@@ -1,10 +0,0 @@
-/**
- * Rutas REST para el simulador de posiciones con capital virtual.
- *
- * Endpoints:
- *   POST   /api/v1/positions       — abrir posición simulada (calcula fracción de Kelly)
- *   GET    /api/v1/positions       — listar posiciones del usuario con P&L actualizado
- *   DELETE /api/v1/positions/:id   — cerrar posición y calcular resultado final
- *
- * Usa userId=1 fijo para la demo.
- */

backend/src/routes/signals.js

@@ -1,9 +0,0 @@
-/**
- * Rutas REST para señales de inteligencia artificial.
- *
- * Endpoints:
- *   GET /api/v1/markets/:id/signal — devuelve la señal IA más reciente del mercado.
- *
- * Las señales incluyen: signal (bullish|bearish|neutral), confidence (0-1),
- * summary, keyRisk y timestamp.
- */

backend/src/routes/watchlist.js

@@ -1,10 +0,0 @@
-/**
- * Rutas REST para la watchlist (mercados favoritos).
- *
- * Endpoints:
- *   POST   /api/v1/watchlist        — añadir mercado a favoritos
- *   DELETE /api/v1/watchlist/:marketId — eliminar mercado de favoritos
- *   GET    /api/v1/watchlist        — listar favoritos con precios en vivo
- *
- * El usuario demo (userId=1) puede gestionar su lista personal.
- */

backend/src/scheduler.js

@@ -1,9 +1,61 @@
-/**
- * Scheduler de tareas periódicas usando node-cron.
- *
- * Define y ejecuta los 4 jobs principales:
- * 1. syncMarkets       — cada 30s, sincroniza precios desde Polymarket Gamma API.
- * 2. generateSignals   — cada 5 min, genera señales IA para el top 20 mercados.
- * 3. updatePositionsPnL— cada 30s, recalcula P&L de posiciones abiertas.
- * 4. processAlerts     — cada 60s, revisa watchlist y envía alertas Telegram.
- */
+import { schedule } from 'node-cron';
+import { fetchActiveMarkets } from './markets/polymarket.client.js';
+import { marketsRepository } from './markets/markets.repository.js';
+import { signalsService } from './signals/signals.service.js';
+import { positionsService } from './positions/positions.service.js';
+import { alertsService } from './alerts/alerts.service.js';
+import { emitMarketUpdate } from './socket/broadcaster.js';
+import { logger } from './utils/logger.js';
+
+async function syncMarkets() {
+  try {
+    const markets = await fetchActiveMarkets(100);
+    await Promise.all(markets.map((m) => marketsRepository.upsert(m)));
+    for (const m of markets) {
+      emitMarketUpdate({ marketId: m.id, yesPrice: m.yesPrice, noPrice: m.noPrice, volumeEur: m.volumeEur });
+    }
+    logger.info({ count: markets.length }, 'markets synced');
+  } catch (err) {
+    logger.error({ err: err.message }, 'syncMarkets failed');
+  }
+}
+
+async function generateSignals() {
+  try {
+    const markets = await marketsRepository.findMany({ limit: 20, offset: 0, status: 'active' });
+    for (const market of markets) {
+      try {
+        await signalsService.generateForMarket(market);
+      } catch (err) {
+        logger.error({ err: err.message, marketId: market.id }, 'signal generation failed for market');
+      }
+    }
+  } catch (err) {
+    logger.error({ err: err.message }, 'generateSignals failed');
+  }
+}
+
+async function updatePositionsPnL() {
+  try {
+    await positionsService.updateAllPnL();
+  } catch (err) {
+    logger.error({ err: err.message }, 'updatePositionsPnL failed');
+  }
+}
+
+async function processAlerts() {
+  try {
+    await alertsService.processAll();
+  } catch (err) {
+    logger.error({ err: err.message }, 'processAlerts failed');
+  }
+}
+
+export function startScheduler() {
+  syncMarkets();
+  schedule('*/30 * * * * *', syncMarkets);
+  schedule('*/5 * * * *', generateSignals);
+  schedule('*/30 * * * * *', updatePositionsPnL);
+  schedule('* * * * *', processAlerts);
+  logger.info('scheduler started');
+}

backend/src/services/aiPipeline.js

@@ -1,12 +0,0 @@
-/**
- * Pipeline de inteligencia artificial para generación de señales.
- *
- * Flujo de dos fases:
- *   1. ModernFinBERT (HF Inference API) → filtra noticias con label=neutral o score<0.65
- *   2. Qwen3-8B (HF Inference API)      → analiza mercado + noticias filtradas y genera:
- *        { signal, confidence, summary, keyRisk }
- *
- * Fallback: si HF está saturado, usa OpenRouter con deepseek/deepseek-v4-flash.
- *
- * Persiste el resultado en la tabla AISignal y emite evento 'ai_signal' por Socket.io.
- */

backend/src/services/finnhub.js

@@ -1,11 +0,0 @@
-/**
- * Servicio de integración con Finnhub REST API.
- *
- * Responsabilidades:
- *   - Obtener titulares de noticias financieras relevantes.
- *   - Proporcionar noticias crudas al pipeline de IA para análisis de sentimiento.
- *
- * Restricciones:
- *   - Free tier: máximo 60 llamadas/minuto.
- *   - Solo se invoca durante la generación de señales (cada 5 min), no en cada sync de precios.
- */

backend/src/services/kelly.js

@@ -1,15 +0,0 @@
-/**
- * Servicio de cálculo del Criterio de Kelly.
- *
- * Fórmula:
- *   k = (odds * pWin - pLose) / odds
- *   odds = (1 / yesPrice) - 1
- *   pLose = 1 - pWin
- *
- * Donde:
- *   - pWin      = confidence de la señal IA (0.0 a 1.0)
- *   - yesPrice  = precio actual del outcome YES en Polymarket
- *
- * El resultado se capa en 25% (máximo) y nunca es negativo.
- * Se almacena en Position.kellyFraction al abrir una posición.
- */

backend/src/services/polymarket.js

@@ -1,11 +0,0 @@
-/**
- * Servicio de integración con Polymarket Gamma API.
- *
- * Responsabilidades:
- *   - Fetch de mercados activos desde https://gamma-api.polymarket.com
- *   - Parseo y normalización de campos: id, question, outcomePrices, volume, liquidity, category, endDate
- *   - Persistencia en la tabla Market vía Prisma
- *   - Asignación de countryCode por geo-inferencia (delegado al pipeline de IA)
- *
- * No usa autenticación. No usa CLOB API.
- */

backend/src/services/telegramBot.js

@@ -1,12 +0,0 @@
-/**
- * Servicio de envío de alertas por Telegram Bot API.
- *
- * Implementación sin librerías externas: llamada HTTP directa a:
- *   POST https://api.telegram.org/bot<TOKEN>/sendMessage
- *
- * Tipos de alerta soportados:
- *   - price_threshold: un precio de watchlist cruzó el umbral definido.
- *   - signal_change: la señal IA de un mercado cambió de estado.
- *
- * El chat_id se obtiene del campo telegramChatId del usuario demo.
- */

backend/src/signals/aiPipeline.js

@@ -0,0 +1,176 @@
+import { httpPost } from '../utils/httpClient.js';
+import { config } from '../config.js';
+import { logger } from '../utils/logger.js';
+import { fetchFinancialNews, filterNewsByRelevance } from './finnhub.client.js';
+
+const HF_API = 'https://api-inference.huggingface.co/models';
+const FINBERT_MODEL = 'ProsusAI/finbert';
+const QWEN_MODEL = 'Qwen/Qwen3-8B';
+const OPENROUTER_API = 'https://openrouter.ai/api/v1/chat/completions';
+const OPENROUTER_MODEL = 'deepseek/deepseek-chat-v3-0324:free';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function hfHeaders() {
+  return { Authorization: `Bearer ${config.HF_TOKEN}` };
+}
+
+function extractJson(text) {
+  try { return JSON.parse(text); } catch {}
+  // strip <think>...</think> blocks (Qwen3 thinking mode)
+  const stripped = text.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+  try { return JSON.parse(stripped); } catch {}
+  const block = stripped.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (block) { try { return JSON.parse(block[1].trim()); } catch {} }
+  const inline = stripped.match(/\{[\s\S]*?\}/);
+  if (inline) { try { return JSON.parse(inline[0]); } catch {} }
+  return null;
+}
+
+function buildPrompt(market, headlines) {
+  const newsSection = headlines.length
+    ? `Relevant news:\n${headlines.map((h) => `- ${h.headline}`).join('\n')}`
+    : 'No relevant news available.';
+  return [
+    `You are a prediction market analyst. Analyze the following market and respond ONLY with valid JSON.`,
+    ``,
+    `Market: "${market.question}"`,
+    `YES price: ${market.yesPrice ?? 'N/A'} | NO price: ${market.noPrice ?? 'N/A'}`,
+    newsSection,
+    ``,
+    `Return ONLY this JSON structure, no markdown, no explanation:`,
+    `{"signal":"bullish"|"bearish"|"neutral","confidence":<0.0-1.0>,"summary":"<2 sentences>","keyRisk":"<1 sentence>"}`,
+  ].join('\n');
+}
+
+// ── FinBERT filtering ─────────────────────────────────────────────────────────
+
+async function filterWithFinBERT(articles) {
+  if (!articles.length) return articles;
+  const inputs = articles.map((a) => a.headline);
+  const results = await httpPost(
+    `${HF_API}/${FINBERT_MODEL}`,
+    { inputs },
+    { headers: hfHeaders(), retries: 1 },
+  );
+  // keep headlines classified as positive or negative with score >= 0.65
+  return articles.filter((_, i) => {
+    const top = results[i]?.[0];
+    return top && top.label !== 'neutral' && top.score >= 0.65;
+  });
+}
+
+// ── LLM generation ────────────────────────────────────────────────────────────
+
+async function callChatCompletion(url, model, messages, authHeader) {
+  const data = await httpPost(
+    url,
+    { model, messages, max_tokens: 300, temperature: 0.3 },
+    { headers: { Authorization: authHeader }, retries: 1, timeout: 30_000 },
+  );
+  return data?.choices?.[0]?.message?.content ?? null;
+}
+
+async function generateWithQwen3(market, headlines) {
+  const content = await callChatCompletion(
+    `${HF_API}/${QWEN_MODEL}/v1/chat/completions`,
+    QWEN_MODEL,
+    [{ role: 'user', content: buildPrompt(market, headlines) }],
+    `Bearer ${config.HF_TOKEN}`,
+  );
+  return content ? extractJson(content) : null;
+}
+
+async function generateWithOpenRouter(market, headlines) {
+  const content = await callChatCompletion(
+    OPENROUTER_API,
+    OPENROUTER_MODEL,
+    [{ role: 'user', content: buildPrompt(market, headlines) }],
+    `Bearer ${config.OPENROUTER_API_KEY}`,
+  );
+  return content ? extractJson(content) : null;
+}
+
+// ── rule-based fallback ───────────────────────────────────────────────────────
+
+function ruleBasedSignal(market) {
+  const p = market.yesPrice ?? 0.5;
+  if (p >= 0.65)
+    return {
+      signal: 'bullish',
+      confidence: Math.min(p, 0.9),
+      summary: `Market strongly favors YES at ${(p * 100).toFixed(0)}% probability. Momentum is positive.`,
+      keyRisk: 'Sentiment shift could rapidly reprice the market.',
+    };
+  if (p <= 0.35)
+    return {
+      signal: 'bearish',
+      confidence: Math.min(1 - p, 0.9),
+      summary: `Market strongly favors NO at ${((1 - p) * 100).toFixed(0)}% probability. Downside momentum dominates.`,
+      keyRisk: 'Unexpected positive developments could reverse this rapidly.',
+    };
+  return {
+    signal: 'neutral',
+    confidence: 0.5,
+    summary: 'Market is closely contested with no clear directional signal. Both outcomes remain plausible.',
+    keyRisk: 'High uncertainty in both directions; position sizing should be conservative.',
+  };
+}
+
+function validateSignal(result) {
+  if (!result) return false;
+  const validSignals = ['bullish', 'bearish', 'neutral'];
+  return (
+    validSignals.includes(result.signal) &&
+    typeof result.confidence === 'number' &&
+    result.confidence >= 0 &&
+    result.confidence <= 1 &&
+    typeof result.summary === 'string' &&
+    typeof result.keyRisk === 'string'
+  );
+}
+
+// ── public API ────────────────────────────────────────────────────────────────
+
+export async function run(market) {
+  // Step 1: fetch and filter news
+  let headlines = [];
+  try {
+    const allNews = await fetchFinancialNews(30);
+    const relevant = filterNewsByRelevance(allNews, market.question);
+    if (config.HF_TOKEN && relevant.length) {
+      headlines = await filterWithFinBERT(relevant);
+    } else {
+      headlines = relevant.slice(0, 10);
+    }
+  } catch (err) {
+    logger.warn({ err: err.message, marketId: market.id }, 'news fetch failed, continuing without news');
+  }
+
+  // Step 2: LLM signal generation with fallback chain
+  let result = null;
+
+  if (config.HF_TOKEN) {
+    try {
+      result = await generateWithQwen3(market, headlines);
+      if (!validateSignal(result)) result = null;
+    } catch (err) {
+      logger.warn({ err: err.message, marketId: market.id }, 'Qwen3 failed, trying OpenRouter');
+    }
+  }
+
+  if (!result && config.OPENROUTER_API_KEY) {
+    try {
+      result = await generateWithOpenRouter(market, headlines);
+      if (!validateSignal(result)) result = null;
+    } catch (err) {
+      logger.warn({ err: err.message, marketId: market.id }, 'OpenRouter failed, using rule-based');
+    }
+  }
+
+  if (!result) {
+    result = ruleBasedSignal(market);
+  }
+
+  return { ...result, newsCount: headlines.length };
+}

backend/src/signals/finnhub.client.js

@@ -0,0 +1,24 @@
+import { httpGet } from '../utils/httpClient.js';
+import { config } from '../config.js';
+
+export async function fetchFinancialNews(count = 30) {
+  if (!config.FINNHUB_API_KEY) return [];
+  const url = `https://finnhub.io/api/v1/news?category=general&token=${config.FINNHUB_API_KEY}`;
+  const articles = await httpGet(url);
+  return articles.slice(0, count).map((a) => ({
+    headline: a.headline ?? '',
+    summary: a.summary ?? '',
+  }));
+}
+
+export function filterNewsByRelevance(articles, question) {
+  const keywords = question
+    .toLowerCase()
+    .split(/\W+/)
+    .filter((w) => w.length > 4);
+  if (keywords.length === 0) return articles;
+  return articles.filter((a) => {
+    const text = `${a.headline} ${a.summary}`.toLowerCase();
+    return keywords.some((kw) => text.includes(kw));
+  });
+}

backend/src/signals/signals.controller.js

@@ -0,0 +1,9 @@
+import { ok } from '../utils/apiResponse.js';
+import { signalsService } from './signals.service.js';
+
+export const signalsController = {
+  async getLatest(req, res) {
+    const signal = await signalsService.getLatest(req.params.marketId);
+    ok(res, signal);
+  },
+};

backend/src/signals/signals.repository.js

@@ -0,0 +1,16 @@
+import { prisma } from '../utils/prisma.js';
+
+export const signalsRepository = {
+  create({ marketId, signal, confidence, summary, keyRisk, newsCount, modelVersion }) {
+    return prisma.aISignal.create({
+      data: { marketId, signal, confidence, summary, keyRisk, newsCount, modelVersion },
+    });
+  },
+
+  findLatestByMarket(marketId) {
+    return prisma.aISignal.findFirst({
+      where: { marketId },
+      orderBy: { generatedAt: 'desc' },
+    });
+  },
+};

backend/src/signals/signals.routes.js

@@ -0,0 +1,9 @@
+import { Router } from 'express';
+import { signalsController } from './signals.controller.js';
+
+const router = Router();
+
+// mounted at /api/v1/markets → full path: GET /api/v1/markets/:marketId/signal
+router.get('/:marketId/signal', signalsController.getLatest);
+
+export default router;

backend/src/signals/signals.service.js

@@ -0,0 +1,25 @@
+import { HttpError } from '../utils/apiResponse.js';
+import { signalsRepository } from './signals.repository.js';
+import { marketsRepository } from '../markets/markets.repository.js';
+import * as aiPipeline from './aiPipeline.js';
+import { emitAiSignal } from '../socket/broadcaster.js';
+import { logger } from '../utils/logger.js';
+
+export const signalsService = {
+  async getLatest(marketId) {
+    const market = await marketsRepository.findById(marketId);
+    if (!market) throw new HttpError(404, 'NOT_FOUND', 'Market not found');
+    const signal = await signalsRepository.findLatestByMarket(marketId);
+    if (!signal) throw new HttpError(404, 'NOT_FOUND', 'No signal available for this market yet');
+    return signal;
+  },
+
+  async generateForMarket(market) {
+    const modelVersion = 'Qwen3-8B';
+    const result = await aiPipeline.run(market);
+    const saved = await signalsRepository.create({ marketId: market.id, modelVersion, ...result });
+    emitAiSignal({ marketId: market.id, signal: saved.signal, confidence: saved.confidence, summary: saved.summary });
+    logger.info({ marketId: market.id, signal: saved.signal }, 'signal generated');
+    return saved;
+  },
+};

backend/src/socket/broadcaster.js

@@ -1,10 +1,17 @@
-/**
- * Módulo de difusión de eventos en tiempo real vía Socket.io.
- *
- * Emite desde el servidor hacia todos los clientes conectados:
- *   - 'market_update' → precios actualizados de mercados (cada 30s)
- *   - 'ai_signal'     → nueva señal IA generada (cada 5 min)
- *   - 'price_alert'   → alerta de umbral activada (cada 60s)
- *
- * Se importa y usa en index.js (servidor) y en scheduler.js (jobs).
- */
+let _io = null;
+
+export function attachBroadcaster(io) {
+  _io = io;
+}
+
+export function emitMarketUpdate(payload) {
+  _io?.emit('market_update', payload);
+}
+
+export function emitAiSignal(payload) {
+  _io?.emit('ai_signal', payload);
+}
+
+export function emitPriceAlert(payload) {
+  _io?.emit('price_alert', payload);
+}

backend/src/utils/httpClient.js

@@ -0,0 +1,73 @@
+import { logger } from './logger.js';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_RETRIES = 3;
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+
+function backoff(attempt) {
+  return Math.min(1_000 * 2 ** attempt, 30_000);
+}
+
+async function request(url, init = {}, { timeout = DEFAULT_TIMEOUT_MS, retries = DEFAULT_RETRIES } = {}) {
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const res = await fetch(url, {
+        ...init,
+        headers: { 'User-Agent': 'PolySignal/1.0', ...init.headers },
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (RETRYABLE_STATUSES.has(res.status) && attempt < retries) {
+        const wait = backoff(attempt);
+        logger.warn({ url, status: res.status, attempt, wait }, 'retrying request');
+        await new Promise((r) => setTimeout(r, wait));
+        continue;
+      }
+
+      const text = await res.text();
+      const data = text ? JSON.parse(text) : null;
+
+      if (!res.ok) {
+        const err = Object.assign(new Error(`HTTP ${res.status} — ${url}`), {
+          status: res.status,
+          body: data,
+        });
+        throw err;
+      }
+
+      return data;
+    } catch (err) {
+      clearTimeout(timeoutId);
+
+      if (err.name === 'AbortError') {
+        throw Object.assign(new Error(`Timeout after ${timeout}ms — ${url}`), { code: 'TIMEOUT' });
+      }
+
+      // network error (no HTTP status) → retry
+      if (!err.status && attempt < retries) {
+        const wait = backoff(attempt);
+        logger.warn({ url, err: err.message, attempt, wait }, 'network error, retrying');
+        await new Promise((r) => setTimeout(r, wait));
+        continue;
+      }
+
+      logger.error({ url, err: err.message }, 'request failed');
+      throw err;
+    }
+  }
+}
+
+export const httpGet = (url, { headers, ...opts } = {}) =>
+  request(url, { method: 'GET', headers }, opts);
+
+export const httpPost = (url, body, { headers, ...opts } = {}) =>
+  request(
+    url,
+    { method: 'POST', headers: { 'Content-Type': 'application/json', ...headers }, body: JSON.stringify(body) },
+    opts,
+  );

backend/src/watchlist/watchlist.controller.js

@@ -0,0 +1,19 @@
+import { ok, created, noContent } from '../utils/apiResponse.js';
+import { watchlistService } from './watchlist.service.js';
+
+export const watchlistController = {
+  async add(req, res) {
+    const entry = await watchlistService.add(req.user.id, req.body);
+    created(res, entry);
+  },
+
+  async remove(req, res) {
+    await watchlistService.remove(req.user.id, req.params.marketId);
+    noContent(res);
+  },
+
+  async list(req, res) {
+    const entries = await watchlistService.list(req.user.id);
+    ok(res, entries);
+  },
+};

backend/src/watchlist/watchlist.repository.js

@@ -0,0 +1,31 @@
+import { prisma } from '../utils/prisma.js';
+
+export const watchlistRepository = {
+  create({ userId, marketId, alertThreshold }) {
+    return prisma.watchlist.create({ data: { userId, marketId, alertThreshold } });
+  },
+
+  findByUser(userId) {
+    return prisma.watchlist.findMany({
+      where: { userId },
+      include: {
+        market: { select: { id: true, question: true, yesPrice: true, noPrice: true, status: true } },
+      },
+      orderBy: { createdAt: 'desc' },
+    });
+  },
+
+  deleteByUserAndMarket(userId, marketId) {
+    return prisma.watchlist.deleteMany({ where: { userId, marketId } });
+  },
+
+  findAllWithThreshold() {
+    return prisma.watchlist.findMany({
+      where: { alertThreshold: { not: null } },
+      include: {
+        user: { select: { id: true, telegramChatId: true } },
+        market: { select: { id: true, question: true, yesPrice: true } },
+      },
+    });
+  },
+};

backend/src/watchlist/watchlist.routes.js

@@ -0,0 +1,15 @@
+import { Router } from 'express';
+import { validate } from '../middlewares/validate.js';
+import { requireAuth } from '../middlewares/requireAuth.js';
+import { watchlistController } from './watchlist.controller.js';
+import { addBody, marketIdParam } from './watchlist.validators.js';
+
+const router = Router();
+
+router.use(requireAuth);
+
+router.post('/', validate(addBody), watchlistController.add);
+router.get('/', watchlistController.list);
+router.delete('/:marketId', validate(marketIdParam, 'params'), watchlistController.remove);
+
+export default router;