backend/docs/API.md

# 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 |