trading-tui - Monitor de mercados financieros desde tu terminal

trading-tui es un proyecto open source desarrollado en Python para monitorear mercados financieros, gestionar alertas de precio y consultar datos de mercado directamente desde la terminal.

Está construido con FastAPI y Textual, combinando una API REST asíncrona con una TUI orientada al teclado. Los datos de mercado utilizan adaptadores intercambiables, mientras que alertas, watchlists, configuración y notificaciones permanecen desacopladas de la interfaz y de los proveedores de datos.

El proyecto se desarrolla de forma incremental: al principio la idea es comenzar con una herramienta útil para monitoreo de mercados y evolucionar hacia gráficos, datos en streaming, notificaciones y funcionalidades de portafolio.

Ver código fuente en GitHub

¿Qué es trading-tui?

La mayoría de las herramientas de mercado asumen un navegador, una aplicación de escritorio o una aplicación móvil.

trading-tui toma otro camino:

Terminal
   │
   ▼
Textual TUI
   │
   ▼
FastAPI
   │
   ├── Datos de mercado
   │      ├── Yahoo
   │      └── Binance
   │
   └── Alertas
          ├── Condiciones
          ├── Persistencia
          └── Notificaciones

Todo funciona localmente. SQLite maneja persistencia de alertas y JSON almacena configuración de usuario.

Estado actual

En desarrollo activo

Versión actual:

0.2.0

El proyecto todavía está evolucionando. Algunas funcionalidades ya están implementadas y otras forman parte del roadmap.

Monitoreo de mercados

La TUI permite consultar mercados mediante listas predefinidas, watchlists y screeners personalizados.

Vistas disponibles:

Activos con mayor actividad
Ganadores
Perdedores
Múltiples watchlists personales
Screener personalizado
Búsqueda de símbolos
Información de símbolos
Noticias recientes
Precio, volumen, market cap y variación
Datos OHLC recientes
Estado de alertas por símbolo

El screener personalizado puede consultar el universo completo de Yahoo US Market utilizando filtros como:

sector:technology
mincap:1b
sort:percentchange

Los precios pueden ordenarse, filtrarse, buscarse y paginarse sin salir de la terminal.

Alertas

Las alertas son uno de los componentes principales de trading-tui.

Actualmente existen condiciones:

above
below
crossing

También existen condiciones basadas en variación porcentual:

rises_by
falls_by
turns_positive
turns_negative

Múltiples condiciones pueden combinarse mediante:

ALL
ANY

Las alertas también tienen dos modos de ejecución:

ONCE
EVERY_TIME

ONCE Ejecuta alerta una sola vez y posteriormente la mueve a estado TRIGGERED.

EVERY_TIME Permite ejecutar la alerta repetidamente mientras sus condiciones vuelvan a cumplirse.

Las alertas pueden tener fecha de expiración, mensajes personalizados y canales de notificación.

Ciclo de vida:

ACTIVE
   ├──► TRIGGERED
   ├──► EXPIRED
   └──► DISABLED

Las condiciones crossing mantienen información del precio anterior. Por esto, alcanzar un precio objetivo no basta: el precio debe atravesar el objetivo.

Las condiciones de variación porcentual utilizan igualmente valores anteriores para determinar la transición.

Notificaciones

El sistema de notificaciones utiliza una abstracción basada en canales extensibles.

Actualmente existe:

in_app

También existen canales preparados como puntos de extensión:

toast
sound
push
email

Estos últimos funcionan actualmente como placeholders y no representan integraciones completas.

Esta separación mantiene la lógica de notificaciones independiente de la evaluación de alertas y facilita agregar nuevos mecanismos de entrega.

Adaptadores de datos de mercado

Los datos de mercado están aislados mediante adaptadores.

Actualmente:

yahoo
binance

Yahoo es proveedor predeterminado y no requiere API key.

Yahoo proporciona:

Cotizaciones
Velas
Screeners predefinidos
Búsqueda de símbolos
Noticias

Binance proporciona:

Cotizaciones
Velas

El soporte de screener para Binance está planificado.

La arquitectura permite agregar nuevos proveedores sin acoplarlos a la TUI o a la lógica de alertas.

Arquitectura

El proyecto utiliza arquitectura modular y orientada a operaciones asíncronas.

Datos de mercado
       │
       ▼
MarketDataAdapter
       │
       ▼
FastAPI
       │
       ├────────────────┐
       ▼                ▼
Servicios mercado   AlertService
                        │
                ┌───────┴────────┐
                ▼                ▼
          Condiciones       Repository
          Strategy          SQLite
                │
                ▼
       NotificationService
                │
                ▼
       NotificationChannel

Dominio de alertas permanece independiente de almacenamiento, HTTP y UI.

Evaluación de condiciones utiliza objetos Strategy seleccionados mediante Factory.

Persistencia utiliza abstracción de Repository.

FastAPI compone dependencias durante el inicio de la aplicación.

TUI se comunica con el backend mediante un cliente HTTP en lugar de evaluar alertas directamente.

Esta separación facilita el testing y permite incorporar futuros clientes y transportes, incluyendo WebSockets.

Persistencia

Alertas utilizan SQLite mediante aiosqlite.

La base de datos funciona en modo WAL y sobrevive a los reinicios de la aplicación.

Base de datos predeterminada:

alerts.db

La ruta puede configurarse mediante:

ALERTS_DB_PATH

Configuración de usuario se almacena separadamente:

~/.config/trading-tui/settings.json

Puede sobrescribirse mediante:

TRADING_TUI_SETTINGS

Actualmente, los settings incluyen watchlists y preferencias de notificaciones.

TUI

trading-tui está diseñada alrededor de la interacción orientada al teclado.

Atajos principales:

t       top active
g       gainers
l       losers
w       watchlist
s       screener
a       alerts
p       prices
n       new alert / new watchlist
r       refresh
e       enable
d       disable
x       delete
o       settings
q       quit

Tabla de precios soporta:

1-5     sorting
f       all changes
u       upward changes
d       downward changes
/       search
[ ]     pagination
Tab     switch watchlist

Objetivo: mantener las manos en el teclado y evitar abrir otro dashboard para revisar precios.

Instalación

El proyecto utiliza uv para la gestión del entorno y dependencias de Python.

Instalación de desarrollo:

bash

uv pip install -e ".[dev]"

Crear .env:

dotenv

ADAPTER_NAME=yahoo
DEFAULT_SYMBOL=BTC-USD

Ejecutar API:

bash

uvicorn app.main:app --reload --port 8333

Ejecutar TUI:

bash

uv run python -m tui_client.app

Para uso diario, proyecto también proporciona comandos CLI:

bash

uv tool install .

Luego:

bash

trading-tui

trading-tui Puede iniciar la API automáticamente cuando sea necesario.

API también puede ejecutarse independientemente:

bash

trading-tui-api

Documentación OpenAPI:

http://127.0.0.1:8333/docs

REST API

La funcionalidad de mercado está expuesta mediante FastAPI.

Mercado

GET /market/candles
GET /market/quotes
GET /market/screeners
GET /market/screener
GET /market/search
GET /market/news

Alertas

GET    /alerts
POST   /alerts
GET    /alerts/{alert_id}
DELETE /alerts/{alert_id}

POST /alerts/{alert_id}/enable
POST /alerts/{alert_id}/disable
POST /alerts/evaluate

API no pretende ser un producto separado de TUI.

Su función es proporcionar una frontera clara entre el dominio de mercado/alertas y la interfaz terminal, dejando abierta la posibilidad de futuros clientes.

Testing

El proyecto incluye tests para backend y TUI.

Actualmente se cubren:

Condiciones de alertas
Transiciones crossing
Condiciones de variación porcentual
Ciclo de vida de alertas
Condiciones ALL / ANY
Modos ONCE / EVERY_TIME
Expiración
Repositories
Persistencia SQLite
REST endpoints
Entrega de notificaciones
User settings
Interacciones TUI

Tests utilizan Pilot API de Textual para probar flujos de UI sin depender de sleep innecesarios.

Ejecutar tests:

bash

pytest

Principios de diseño

trading-tui también funciona como experimento de arquitectura de software.

Algunos patrones utilizados deliberadamente:

Strategy para condiciones de alertas
Factory para construcción de condiciones
Observer para evaluación basada en precios
Repository para persistencia
Adapter para proveedores de mercado y canales de notificación
Dependency Injection para servicios FastAPI

El objetivo no es agregar patrones por agregar patrones.

El objetivo es mantener datos de mercado, dominio, persistencia, notificaciones, API y UI reemplazables sin convertir el proyecto en código fuertemente acoplado.

Limitaciones actuales

El proyecto todavía está en una etapa temprana.

Actualmente utiliza polling mediante REST en lugar de streaming de mercado en tiempo real.

Algunos canales de notificación son placeholders.

Gráficos e indicadores técnicos todavía no están implementados.

Portafolios todavía no están implementados.

Screeners para Binance todavía no están implementados.

Evaluación automática de alertas a partir de actualizaciones continuas de mercado también está pendiente. Actualmente la evaluación puede ejecutarse mediante API.

Estas limitaciones representan el estado actual del proyecto, no funcionalidades ocultas.

Roadmap

Las próximas etapas buscan convertir el monitor de mercado en una estación de trabajo más completa para la terminal.

Streaming

Situación actual:

REST polling
     ↓
WebSocket market feed

Existe un schema WSMsg. El próximo paso es exponer /market/ws y conectar actualizaciones de precios/velas en tiempo real con la aplicación.

Notificaciones

Integraciones previstas:

Email
Webhook
Discord
Telegram

Portafolio

Soporte previsto para:

Holdings
Valor de portafolio
Monitoreo de variaciones
Alertas específicas de portafolio

Gráficos

Previsto:

Gráficos candlestick
Indicadores técnicos
Visualización histórica

Automatización de alertas

Flujo actual:

Actualización de mercado
    ↓
POST /alerts/evaluate
    ↓
AlertService

Objetivo:

Live market feed
    ↓
AlertService.handle_price()
    ↓
Evaluación de condiciones
    ↓
NotificationService
    ↓
Canales de notificación

Esto elimina la evaluación manual del ciclo de vida de alertas.

Infraestructura

Mejoras previstas:

HTTP client compartido
Linting
Formatting
Type checking
CI
Automatización de releases
Documentación para contribuidores

¿Por qué construirlo?

trading-tui nació como experimento práctico:

¿Cómo sería una herramienta útil de monitoreo de mercados si la terminal fuera su interfaz principal?

Pero también es un ejercicio continuo de ingeniería.

Combina:

Python
Programación asíncrona
FastAPI
Textual
REST APIs
Adaptadores de datos de mercado
Diseño orientado a eventos
Patrones de diseño
SQLite
Testing
CLI packaging
Docker
Desarrollo open source

Proyecto evoluciona públicamente.

Nuevas funcionalidades, decisiones arquitectónicas, experimentos, errores y soluciones forman parte de su historia.

Estado del proyecto

En desarrollo activo

Versión actual:

0.2.0

Repositorio:

github.com/corderkrow/trading-tui

Historial de releases:

RELEASES.md

Los mercados se mueven rápido. El código debería poder seguirles el ritmo.

trading-tui es parte monitor de mercados, parte experimento CLI y parte ejercicio continuo para construir software Python mantenible.