blackmistcode/polysignal_hackaton

PolySignal

Dashboard web de inteligencia de mercados de prediccion en tiempo real.

Que es

PolySignal analiza mercados de Polymarket cruzando noticias de Finnhub con modelos de IA (ModernFinBERT + Qwen3-8B) para generar senales de trading (alcista, bajista, neutral). Incluye simulador de posiciones con capital virtual, lista de seguimiento y alertas por Telegram.

No ejecuta ordenes reales. Es una herramienta de analisis e inteligencia.

Idioma: Espanol. Moneda base: Euro (€).

Stack

• Backend: Node.js 26 + Express.js 5 + Socket.io + node-cron
• ORM: Prisma 6 + SQLite
• Frontend: Vanilla JS + Vite 7 + Leaflet.js + Chart.js + Socket.io client
• IA: HuggingFace Spaces (ModernFinBERT + Qwen3-8B) + OpenRouter fallback
• Datos: Polymarket Gamma API + Finnhub REST
• Deploy: HuggingFace Spaces (Docker, puerto 7860)

Estado del proyecto

El backend es totalmente funcional:

• API REST completa con autenticacion JWT.
• Pipeline de IA con cadena de fallback (Spaces HF → API HF → OpenRouter → rule-based).
• Scheduler de tareas periodicas (sync mercados, generacion de senales, P&L, alertas).
• WebSocket en tiempo real para precios y senales.
• Base de datos SQLite con Prisma ORM

El frontend consume datos reales del backend y tiene fallback a datos mock cuando el backend no responde (modo demo sin configuracion).

Mejoras de utilidad

Para que la app sea util mas alla de la demo visual, se han incorporado los siguientes ajustes — todos orientados a que las senales tengan edge real y no sean ruido bonito:

1. Fetch diversificado por tag (anti-monotonia)

El endpoint /markets de Polymarket ignora tag_id y siempre devuelve la home feed (politica US + World Cup). El cliente usa ahora el endpoint /events que SI respeta tag_id, con un catalogo curado de ~25 tags de alto valor (crypto-prices, fed, stock-market, tech, openai, middle-east, oil-industry, europe, taiwan-election, etc.) y aplana los mercados por tag.

Resultado: ~1000 mercados activos diarios distribuidos en 6 categorias (cripto, economia, geopolitica, ciencia, politica, entretenimiento) en lugar de los ~100 dominados por una unica categoria.

2. Whitelist de mercados analizables

polymarket.client.js → isAnalyzable() flaggea como no analizables los mercados donde la IA no tiene edge plausible:

• Predicciones de palabras ("Will Trump say nuclear?")
• Views de YouTubers, recuentos de tweets
• "Before GTA VI"-style memes
• Deportes y entretenimiento

signals.service.js salta la generacion para estos mercados y el frontend pinta el badge "FUERA DE ALCANCE" en lugar de fabricar confianza falsa. Asi, cada senal visible es defendible.

3. Ground truth de cripto via CoinGecko

utils/coingecko.client.js resuelve spot prices (BTC, ETH, SOL, DOGE, ADA, XRP) y los inyecta en el prompt de la IA para mercados de precio objetivo:

GROUND TRUTH: BTC spot $103,400. Target $150,000 (+45.1% required).
Use this to judge whether the implied probability is plausible given typical volatility.

Cache TTL 60s — respeta el rate limit gratuito de CoinGecko.

4. Edge gap explicito (impliedProb vs fairProb)

Cada AISignal persiste ahora impliedProb, fairProb y edgePoints. El pipeline mapea (signal, confidence) → fairProb:

Signal	Formula
bullish + conf 0.8	fairProb = 0.5 + 0.8 × 0.5 = 0.90
bearish + conf 0.8	fairProb = 0.5 − 0.8 × 0.5 = 0.10
neutral	fairProb = 0.5

La tarjeta del mercado muestra: Mercado 65% · IA 78% · Edge +13pp — claim cuantitativo en lugar de prosa vaga.

5. Spread-aware sizing (Kelly con costes)

Polymarket expone spread, bestBid, bestAsk por mercado. positions/kelly.js → suggestSize() resta el spread del edge bruto antes de calcular el tamano de posicion:

edgeNeto = |edgePoints/100| - spread
fraction = Quarter-Kelly(price, impliedProb + edgeNeto)
amount   = bankroll * min(0.25, fraction)

Mercados con spread > 5¢ se marcan como ilíquidos y los botones de compra se desactivan. Endpoint publico: GET /api/v1/positions/suggestion/:marketId.

6. Distribucion geografica del mapa

map.js usa jitter determinista (hash del marketId → desplazamiento en bounding-box del pais) para que multiples mercados del mismo pais no se apilen sobre la capital. Mercados sin pais (cripto, indices, AI) se reparten entre 40 hubs financieros globales (NYC, Sao Paulo, Mumbai, Lagos, Moscu, Yakarta, Sydney, etc.) en vez de caer todos sobre [20,0].

Estructura

polysignal/
├── backend/                      # API REST + Servicios + Scheduler
│   ├── package.json
│   ├── prisma/
│   │   ├── schema.prisma         # Schema SQLite (User, Market, AISignal, Position, Watchlist, Alert)
│   │   ├── migrations/           # Migraciones de Prisma
│   │   └── seed.js               # Usuarios demo (admin + user)
│   └── src/
│       ├── index.js              # Entry point: HTTP server + Socket.io + scheduler
│       ├── app.js                # Express: middlewares + rutas + manejo de errores
│       ├── config.js             # Variables de entorno validadas con Zod
│       ├── scheduler.js          # Jobs periodicos (cron): sync, senales IA, PnL, alertas
│       ├── auth/                 # Autenticacion JWT + bcrypt
│       │   ├── auth.controller.js
│       │   ├── auth.service.js
│       │   ├── auth.routes.js
│       │   ├── auth.validators.js
│       │   └── jwt.js
│       ├── markets/              # Mercados de Polymarket
│       │   ├── markets.controller.js
│       │   ├── markets.service.js
│       │   ├── markets.routes.js
│       │   ├── markets.validators.js
│       │   ├── markets.repository.js
│       │   └── polymarket.client.js
│       ├── signals/              # Pipeline de IA (ModernFinBERT + Qwen3-8B)
│       │   ├── signals.controller.js
│       │   ├── signals.service.js
│       │   ├── signals.routes.js
│       │   ├── signals.repository.js
│       │   ├── aiPipeline.js     # Pipeline IA con fallback chain
│       │   └── finnhub.client.js # Noticias financieras
│       ├── positions/            # Simulador de posiciones virtuales
│       │   ├── positions.controller.js
│       │   ├── positions.service.js
│       │   ├── positions.routes.js
│       │   ├── positions.validators.js
│       │   ├── positions.repository.js
│       │   └── kelly.js          # Criterio de Kelly (sizing)
│       ├── watchlist/            # Lista de seguimiento
│       │   ├── watchlist.controller.js
│       │   ├── watchlist.service.js
│       │   ├── watchlist.routes.js
│       │   ├── watchlist.validators.js
│       │   └── watchlist.repository.js
│       ├── alerts/               # Alertas por Telegram
│       │   ├── alerts.controller.js
│       │   ├── alerts.service.js
│       │   ├── alerts.routes.js
│       │   ├── alerts.repository.js
│       │   └── telegram.client.js
│       ├── middlewares/          # Middlewares reutilizables
│       │   ├── validate.js       # Validacion Zod generica
│       │   ├── requireAuth.js    # Autenticacion JWT
│       │   ├── rateLimitLogin.js # Rate limit login
│       │   ├── errorHandler.js   # Manejo centralizado de errores
│       │   └── notFound.js       # 404
│       ├── utils/                # Utilidades compartidas
│       │   ├── apiResponse.js    # Helpers de respuesta HTTP
│       │   ├── httpClient.js     # Cliente HTTP con retry + timeout
│       │   ├── logger.js         # Pino (logs estructurados)
│       │   └── prisma.js         # Singleton PrismaClient
│       └── socket/
│           └── broadcaster.js    # Emisor de eventos Socket.io
│
├── frontend/                     # SPA Vanilla JS con Vite
│   ├── index.html                # Punto de entrada HTML
│   ├── package.json
│   ├── vite.config.js            # Proxy a backend + build config
│   └── src/
│       ├── main.js               # Entry point de Vite
│       ├── app.js                # Logica principal SPA + Socket.io
│       ├── api.js                # Cliente REST del backend
│       ├── charts.js             # Chart.js (historial + sparklines)
│       ├── map.js                # Leaflet (mapa mundial interactivo)
│       ├── simulator.js          # Simulador de posiciones virtuales
│       └── style.css             # Estilos dark terminal / fintech
│
├── spaces/                       # HuggingFace Spaces (ZeroGPU)
│   ├── modernfinbert/            # Space de ModernFinBERT
│   │   ├── app.py
│   │   ├── requirements.txt
│   │   └── README.md
│   └── qwen3-8b/                 # Space de Qwen3-8B
│       ├── app.py
│       ├── Dockerfile
│       ├── requirements.txt
│       └── README.md
│
├── package.json                  # Root con workspaces + scripts conjuntos
├── docker-compose.yml            # Orquestacion local
├── Dockerfile                    # Build para HuggingFace Spaces
├── .env.example                  # Variables de entorno de ejemplo
├── SECURITY_HEALTHCHECK.md       # Auditoria de seguridad y arquitectura
└── README.md

Requisitos

• Node.js >= 26.0.0
• npm >= 10 (workspaces)

Instalacion rapida

# 1. Instalar dependencias (root + todos los workspaces)
npm install

# 2. Configurar variables de entorno
cp .env.example .env
# Editar .env con tus claves (HF_TOKEN, HF_SPACE_*, OPENROUTER_API_KEY, etc.)

# 3. Generar base de datos y cliente Prisma
npm run db:migrate
npm run db:generate

# 4. Iniciar en desarrollo
npm run dev:all      # Backend + Frontend Vite simultaneamente

Desarrollo solo frontend

Si solo quieres visualizar el dashboard (funciona con datos mock):

cd frontend
npm install
npm run dev
# Abrir http://localhost:5173

El frontend consume datos mock localmente cuando el backend no responde, por lo que el dashboard es totalmente funcional para la demo sin configuracion adicional.

Arquitectura del Backend

El backend sigue una arquitectura Layered (Controller → Service → Repository):

Capa	Responsabilidad	Ejemplo
Controller	Recibir HTTP request, delegar a Service, responder	markets.controller.js
Service	Logica de negocio, validaciones, coordinacion	markets.service.js
Repository	Acceso a datos via Prisma ORM	markets.repository.js
Client	Integracion con APIs externas	polymarket.client.js, finnhub.client.js
Middleware	Cross-cutting concerns (auth, validacion, rate limiting)	requireAuth.js, validate.js

Pipeline de IA

Whitelist analyzable (skip predicciones-de-palabras, sports, memes)
    ↓
Noticias (Finnhub) → relevantes por mercado
    ↓
Filtrado (ModernFinBERT Space / API directa)
    ↓ (descarta neutrales, score < 0.65)
Ground truth crypto (CoinGecko spot → solo si aplica)
    ↓
Generacion de senal (Qwen3-8B Space / API directa)
    ↓
Fallback: OpenRouter (deepseek-chat)
    ↓
Fallback: Rule-based (precio del mercado)
    ↓
Calculo edge: impliedProb vs fairProb → edgePoints
    ↓
Persistencia (SQLite) + Emision Socket.io

Scheduler (node-cron)

Job	Frecuencia	Descripcion
syncMarkets	Cada 30s	Sincroniza precios + spread desde Polymarket Gamma (fetch diversificado por tag)
generateSignals	Cada 5 min	Genera senales IA para 40 mercados diversificados por categoria (solo analyzable=true)
updatePositionsPnL	Cada 30s	Recalcula P&L de posiciones abiertas
processAlerts	Cada 60s	Revisa watchlist y envia alertas Telegram

Arquitectura del Frontend

El frontend es una SPA construida con Vite 7 como bundler y dev server.

Caracteristicas visuales

• Estetica dark terminal / fintech: paleta #0a0c10, tipografias Syne + DM Mono.
• Layout ajustable: sidebar colapsable, paneles del dashboard colapsables individualmente.
• Mapa global interactivo: Leaflet con burbujas por pais (tamano = volumen, color = senal IA), jitter determinista para evitar apilamientos y 40 hubs financieros para mercados sin pais.
• Panel de senales IA: mercados con badges alcista/bajista/neutral, fila de edge cuantitativa (Mercado X% · IA Y% · Edge ±N pp) y badge "FUERA DE ALCANCE" para mercados no analizables.
• Detalle de mercado: sparklines, historial 7d, analisis IA, simulador de posiciones con sugerencia de tamano Quarter-Kelly cost-aware (servida por GET /positions/suggestion/:marketId) y deshabilitacion automatica para mercados con spread > 5¢.
• Vistas adicionales: Posiciones abiertas, Lista de seguimiento, Historial de alertas.

Flujo de desarrollo

Servicio	Comando	URL local
Backend (Express + Socket.io)	npm run dev	http://localhost:7860
Frontend (Vite + HMR)	npm run dev:frontend	http://localhost:5173
Ambos a la vez	npm run dev:all	—

Vite esta configurado con un proxy que redirige automaticamente las peticiones a /api y /socket.io hacia el backend en el puerto 7860, eliminando problemas de CORS durante el desarrollo local.

Scripts disponibles

# Levantar solo el backend
npm run dev

# Levantar solo el frontend (Vite con hot reload)
npm run dev:frontend

# Levantar backend y frontend simultaneamente
npm run dev:all

# Build de produccion del frontend (genera frontend/dist/)
npm run build:frontend

# Preview del build de produccion
npm run preview:frontend

# Base de datos
npm run db:migrate      # Crear/actualizar migraciones
npm run db:generate     # Generar cliente Prisma
npm run db:studio       # Explorar BD con Prisma Studio

Deploy en HuggingFace Spaces

1. Crear Space tipo "Docker"
2. Subir codigo (git push)
3. Configurar Secrets en la interfaz de HF con las variables de .env
4. El contenedor expone el puerto 7860 automaticamente

Docker local (opcional)

# Build y run con docker-compose
docker-compose up --build

# O solo docker build
docker build -t polysignal .
docker run -p 7860:7860 --env-file .env polysignal

Variables de entorno

# HuggingFace
HF_TOKEN=                          # API key de HuggingFace (Inference API)
HF_SPACE_MODERNFINBERT_URL=        # URL del Space (ej: usuario/modernfinbert)
HF_SPACE_QWEN_URL=                 # URL del Space (ej: usuario/qwen3-8b)

# Fallbacks y datos
OPENROUTER_API_KEY=                # Fallback LLM si HF esta saturado
FINNHUB_API_KEY=                   # Noticias financieras (finnhub.io)

# Alertas
TELEGRAM_BOT_TOKEN=                # Bot de alertas (@BotFather)

# Base de datos y auth
DATABASE_URL=file:./backend/prisma/polysignal.db
JWT_SECRET=minimo-32-caracteres    # Secreto para firmar JWT

# Servidor
PORT=7860                          # Puerto requerido por HuggingFace Spaces
NODE_ENV=production                # development | production

Equipo

Hackathon CIFO Barcelona La Violeta — 13-18 mayo 2026

Licencia

MIT