Cómo está organizada esta documentación.

Doce módulos. Se puede leer de corrido (flechas ← →) o saltar por el panel izquierdo.

Así se ve la tira: la etapa iluminada es la que trata el slide.

FARO no adivina el precio. Le cobra peaje al mercado.

La distinción es la tesis entera del sistema: separa lo que FARO hace de lo que hace el 90% de los bots que pierden plata.

Siete principios inquebrantables.

Están en CLAUDE.md y ninguna SPEC los puede contradecir. Si el código viola uno, es un bug — no una decisión de producto.

El principio que ordena todo lo demás.

El código implementa mecanismos. La configuración define políticas. Nunca al revés.

# config.yaml — el criterio, no el código
motores:
  funding_binance:
    activo: true
    modo: "observacion"   # observacion|simulado|real
    ciclo_segundos: 300
    pares: ["BTC/USDT", "ETH/USDT", …]
    umbral_entrada_apr_pct: 12
    umbral_salida_apr_pct: 4
    persistencia_minima_ciclos: 3
    profundidad_minima_usd: 50000
    fee_taker_spot_pct: 0.1
    fee_taker_futures_pct: 0.04

riesgo:
  perdida_diaria_maxima_pct: 2    # ⇒ SAFE_MODE
  perdida_semanal_maxima_pct: 5   # ⇒ KILLED

Los seis motores, de un vistazo.

Cada uno captura una ineficiencia distinta. Se complementan: no dependen del mismo hecho del mundo.

Cuatro fases. Ninguna se saltea.

Cada fase tiene un criterio de avance explícito. No se avanza por entusiasmo; se avanza por evidencia.

Una EC2 aislada, cero puertos abiertos.

Un solo proceso Python multi-motor. La API escucha únicamente en la interfaz de WireGuard. El cockpit es estático. Nada de esto es accidental.

La anatomía de un ciclo.

Los seis motores hacen exactamente lo mismo, con distinta matemática en el paso 2. Este pipeline es la columna vertebral de FARO.

Todo scanner tiene las mismas tres capas.

Aprendido esto, leer cualquiera de los seis motores es cuestión de buscar dónde está cada capa.

# src/faro/scanners/funding_binance.py — las tres capas, en orden

# ── capa 1: el contrato con el mundo exterior (mockeable) ──
class FundingFeed(Protocol):
    async def snapshot(self, par: str) -> FundingSnapshot: ...

# ── capa 2: la matemática. pura. sin I/O. testeable en microsegundos ──
def apr_bruto_pct(funding_rate: float, interval_hours: float) -> float:
    periodos_por_anio = HORAS_ANIO / interval_hours
    return funding_rate * periodos_por_anio * 100.0

def evaluar(snapshot, cfg, apr_neto_previos) -> Evaluacion:
    """Mismas entradas ⇒ misma salida. Sin estado, sin red, sin reloj."""
    ...

# ── capa 3: el orquestador con estado ──
class FundingScanner:
    async def tick(self) -> None:
        cfg = self._config()              # relee config en cada tick (hot reload)
        for par in cfg.pares:
            snapshot = await self._fetch_resiliente(par)   # reintentos + backoff
            if snapshot is None: continue            # degradado, no inventa
            ev = evaluar(snapshot, cfg, self._historial[par])
            await self._persistir(session, par, snapshot, ev, cfg)

Regla de oro: si una decisión de negocio está adentro de la capa 3, está mal ubicada. La capa 3 solo mueve datos.

El ciclo de vida de un cambio de criterio.

Cambiar un umbral no es editar un archivo y rezar. Es un flujo con validación, versión, auditoría y rollback.

El ledger: la memoria perfecta.

Ocho tablas. Todo lo que el sistema vio, decidió, ignoró y le dijeron que haga.

La API: lectura amplia, escritura estrecha.

FastAPI, escuchando solo en 10.0.0.1:8420 — la interfaz de WireGuard. Dos scopes: lectura y admin. Todo lo que muta pasa por admin y queda auditado.

Cómo se comporta FARO cuando algo se rompe.

Principio 6: fallar cerrado. Ante la duda, el sistema hace menos, no más.

Scoring: cómo comparar peras con manzanas.

Un funding de 18% anual y un cruce de stables de 1,1% neto no se pueden comparar directamente. El scoring los lleva a la misma escala.

# core/scoring.py
def calcular_score(subscores, pesos) -> float:
    total = 0.0
    for dim in DIMENSIONES:
        sub = subscores.get(dim, NEUTRO)   # NEUTRO = 50.0
        total += sub * getattr(pesos, dim)
    return _clamp(total)                   # [0, 100]

Nueve dimensiones. El retorno pesa un cuarto.

El resto es riesgo, liquidez y realismo de ejecución. Que una oportunidad rinda mucho no alcanza — tiene que ser saleable, repetible y limpia.

Tres umbrales, tres niveles de confianza.

El score cae en un tramo y ese tramo define hasta dónde llega la autonomía del sistema.

# config.yaml
scoring:
  umbral_alerta: 70   # score mínimo para notificar
  umbral_manual: 80   # mínimo para proponer con aprobación
  umbral_auto:   90   # mínimo para auto-ejecución

# core/scoring.py — el gate solo CLASIFICA
def gate(score, cfg) -> Gate:
    if score >= cfg.umbral_auto:   return "auto"
    if score >= cfg.umbral_manual: return "manual"
    if score >= cfg.umbral_alerta: return "alerta"
    return "ninguno"

Seis estados. Uno no tiene vuelta atrás automática.

Es el principio 7. El sistema siempre sabe en qué estado está, y cada transición queda en system_state_log con su causa.

Qué te manda a SAFE_MODE, qué te manda a KILLED.

No es criterio del momento. Está escrito en disparador_automatico() y los números vienen de config. KILLED tiene prioridad sobre SAFE_MODE.

# core/fsm.py — el orden importa: primero se pregunta por KILLED
def disparador_automatico(m: MetricasRiesgo, riesgo: RiesgoConfig) -> str | None:
    if (m.config_corrupta or m.mismatch_conciliacion
        or m.perdida_semanal_pct >= riesgo.perdida_semanal_maxima_pct
        or m.perdida_mensual_pct >= riesgo.perdida_mensual_maxima_pct):
        return KILLED
    if (m.perdida_diaria_pct >= riesgo.perdida_diaria_maxima_pct
        or m.clock_drift_seg > riesgo.max_clock_drift_segundos
        or m.errores_api_consecutivos > riesgo.max_errores_api_consecutivos
        or m.depeg):
        return SAFE_MODE
    return None

En Fase 1 casi todas estas métricas valen 0 (no hay PnL ni órdenes). La lógica está presente y testeada desde el día uno, para que el día que haya capital real no haya que escribirla apurado.

RiskGuard: el que dice que no.

Stateless. Recibe una orden propuesta, la config de capital y la exposición actual. Devuelve un veredicto. Corre antes de que la orden exista.

# core/riskguard.py
def verificar(orden, cfg, exposicion) -> Veredicto:
    if orden.monto_usd > cfg.tope_por_operacion_usd:
        return Veredicto(False, "excede tope_por_operacion_usd")

    nuevo_total = exposicion.total_desplegado_usd + orden.monto_usd
    if nuevo_total > cfg.total_asignado_usd * cfg.max_desplegado_pct / 100:
        return Veredicto(False, "excede max_desplegado_pct")
    ...
    # pasó los topes duros: ¿necesita confirmación humana?
    requiere = orden.monto_usd > cfg.operacion_sin_confirmar_max_usd
    return Veredicto(True, requiere_confirmacion=requiere)

El RiskGuard prohíbe. El PortfolioManager elige.

Cuando en un mismo ciclo hay cinco oportunidades elegibles y capital para tres, alguien tiene que decidir. Determinista, sin LLM, sin sorpresas.

# core/portfolio.py — el detalle que hace la diferencia
for cand in sorted(candidatas, key=lambda c: c.score, reverse=True):
    acumulada = ExposicionActual(total, por_plataforma, por_activo, por_stablecoin)
    veredicto = verificar(cand.orden, cfg, acumulada)   # ← con lo ya aprobado
    if not veredicto.permitida: continue
    total += cand.orden.monto_usd                       # y se acumula
    aprobadas.append(cand.orden)

La disciplina de la estrategia que se muere.

Toda estrategia deja de funcionar en algún momento. La pregunta no es si pasa: es cómo distinguir un drawdown normal de un edge muerto — y decidirlo con números escritos antes, no por feeling.

"Vivo" no es lo mismo que "trabajando".

El healthcheck clásico pregunta si el proceso responde. Eso no alcanza: un motor puede estar activo: true, el proceso respondiendo 200, y el scanner haber dejado de producir observaciones hace seis horas por una excepción silenciada.

Cobrarle el alquiler a los apalancados.

Es el motor #1 del ranking: 10–30% anual en USD, delta-neutral, 100% automatizable. Todo lo demás en FARO orbita alrededor de este.

Qué mira el motor cada 300 segundos.

Cinco pares por default, contra los endpoints públicos de Binance vía ccxt. Sin API key, porque en Fase 1 no hace falta ninguna.

# la foto cruda de un par en un ciclo
@dataclass(frozen=True)
class FundingSnapshot:
    par: str                  # "BTC/USDT"
    ts: datetime
    funding_rate: float       # fracción por intervalo
                              # 0.0001 = 0.01%
    interval_hours: float     # cadencia REAL del par:
                              # 8, 4 o 1 h — no se asume
    mark_price: float         # precio del perpetuo
    index_price: float        # precio de referencia (spot)
    profundidad_usd: float    # min(spot, perp)
                              # ← la pata más fina manda

motores:
  funding_binance:
    activo: true
    modo: "observacion"
    ciclo_segundos: 300
    pares:
      - "BTC/USDT"
      - "ETH/USDT"
      - "SOL/USDT"
      - "BNB/USDT"
      - "XRP/USDT"

De 0,01% cada 8 horas a un APR neto de fees.

Tres funciones puras. Sin red, sin base, sin estado. Esta es la única parte del motor donde vive el criterio de negocio.

Ejemplo: funding_rate = 0.0001 (0,01%) con interval_hours = 8 ⇒ 1.095 períodos/año ⇒ APR bruto = 10,95%.

Entrar cuesta tres ciclos. Salir, uno solo.

La asimetría es deliberada y está documentada (ADR-009): tardar en entrar cuesta una oportunidad; tardar en salir cuesta plata.

# scanners/funding_binance.py — la función pura completa
def evaluar(snapshot, cfg, apr_neto_previos) -> Evaluacion:
    bruto = apr_bruto_pct(snapshot.funding_rate, snapshot.interval_hours)
    neto  = apr_neto_pct(snapshot.funding_rate, snapshot.interval_hours,
                         cfg.fee_taker_spot_pct, cfg.fee_taker_futures_pct,
                         cfg.horizonte_amortizacion_dias)
    prof_ok = snapshot.profundidad_usd >= cfg.profundidad_minima_usd

    serie  = [*apr_neto_previos, neto]
    consec = _ciclos_consecutivos_sobre(serie, cfg.umbral_entrada_apr_pct)

    senal = "ninguna"
    if prof_ok and consec >= cfg.persistencia_minima_ciclos:
        senal = "entrada"
    elif neto < cfg.umbral_salida_apr_pct:
        senal = "salida"
    return Evaluacion(bruto, neto, spread, profundidad, prof_ok, consec, senal)

Fijate que la profundidad no bloquea la salida: si hay que salir, se sale, aunque el libro esté fino.

Los ocho números que definen el motor.

Cambiar cualquiera de estos cambia el comportamiento del sistema sin tocar una línea de código.

La tasa en pesos contra el dólar que viene.

El motor más argentino de los seis: gana cuando la tasa en pesos le saca ventaja a la devaluación esperada. Y pierde meses de tasa en un solo salto cambiario.

Ninguna fuente sabe todo. El Normalizer las fusiona.

M2 es el motor con la ingesta más complicada: hacen falta tres APIs distintas para armar un solo instrumento evaluable.

Cinco pasos: de un precio en pesos a un retorno en dólares.

Todas las funciones reciben y devuelven porcentaje 0–100, nunca fracciones — para evitar el bug clásico de mezclar escalas.

Un bono con TIR espectacular y sin comprador no sirve.

El liquidity_score_pct combina cuatro señales en un puntaje 0–100. Si da bajo, el instrumento queda afuera del universo aunque el retorno sea el mejor de la tabla.

instruments:
  tipos_permitidos: ["LECAP", "BONCAP"]
  dtm_minimo: 1
  dtm_maximo: 365
  liquidity_score_minimo_pct: 30.0
  whitelist: []
  blacklist: []

El dólar cripto como alarma de incendio.

Cinco señales, cuatro tiers. Se toma el peor tier entre las cinco (any-of, fail-closed): una sola señal en PANIC implica PANIC global, sin importar las otras cuatro.

Que el capital ocioso no esté ocioso.

Mientras M1 espera un funding alto y M4 espera una ventana, hay plata quieta. M3 la pone a rendir 9–12% anual en USD, sin apalancamiento.

Cada instrumento tiene su propia cuenta de costos.

El APY que publica el protocolo nunca es el APY que cobrás. M3 descuenta lo que el marketing no descuenta.

Cuándo el problema no es el instrumento: es el protocolo.

Un depeg de sUSDe bloquea sUSDe. Pero si el colchón de reservas de Ethena se desploma, el problema es sistémico — y escala al sistema entero.

La pizarra miente. El cruce ejecutable, no.

Este es el motor donde la ventaja competitiva es puramente geográfica: estar en Argentina, con cuentas en ocho exchanges locales.

Una request. Toda la plaza argentina.

CriptoYa devuelve compra y venta de todas las stables en todos los exchanges argentinos en un solo request. Cada 60 segundos.

# matriz[moneda][exchange] -> Cotizacion
class Cotizacion:
    total_ask: float  # ARS que PAGÁS por 1 unidad
    total_bid: float  # ARS que RECIBÍS por 1 unidad
                      # (fees del exchange ya incluidas)

monedas:   ["USDT", "USDC", "DAI"]
exchanges: ["binancep2p", "lemoncash", "ripio",
            "buenbit", "fiwind", "letsbit",
            "belo", "satoshitango"]

Se registra la matriz completa, no solo las señales.

Esta es una decisión de diseño deliberada de M4, y es la que convierte a la Fase 1 en algo más que "esperar".

Comprar el SÍ y el NO por menos de un dólar.

La aritmética es trivial. El problema no es la matemática: es la velocidad.

El observador no busca plata. Busca evidencia.

M5 en Fase 1 tiene un único objetivo: producir el dato que permita responder GO / NO-GO con números en vez de con ganas.

# cada consulta al libro registra su round-trip
@dataclass(frozen=True)
class LibroToken:
    best_ask: float  # precio del token, 0..1
    rtt_ms:   float  # ← LA MÉTRICA QUE DECIDE TODO

El motor que no es un motor.

Wallbit no captura una ineficiencia propia: le da a los otros motores datos y capacidades que no tienen. Y pasó la auditoría de seguridad de FARO por diseño.

wallbit:
  activo: false        # hasta tener la key read-only
  ciclo_segundos: 900
  frescura_maxima_min: 30  # alerta si el rate envejece

Siete pantallas. Cada una responde una pregunta.

Astro estático, servido desde el propio núcleo en http://10.0.0.1:8420/ — la interfaz de WireGuard. Refresca cada 30 segundos contra la API.

Inicio: el chequeo de 10 segundos.

Lo primero que se mira todos los días. Si esta pantalla está verde, no hay nada que hacer.

Cómo leerla: el KPI de salud arriba de todo no dice "el proceso está vivo" — dice "los motores están produciendo observaciones". Un SILENCIOSO ahí es la alarma temprana más valiosa del sistema. renta_usd visto hace 41 minutos es normal (su ciclo es de una hora); stables_argentina hace 38 segundos también (su ciclo es de un minuto). Cada motor se mide contra su propia cadencia.

Carry: el panel del dólar.

La pantalla más densa del cockpit, porque el motor más complejo necesita mostrar dos cosas a la vez: el estado del FX y el ranking de instrumentos.

Cómo leerla: con el FX en WATCH, el umbral de retorno subió de 3,0% a 4,5% (×1,5). Por eso T15E7, con un +4,10% que en NORMAL sería señal, aparece bloqueada. Y la columna Motivo nunca está vacía: incluso el "no operar" está explicado. Eso es el principio 5 hecho interfaz.

Renta: todo se mide contra el piso.

Cómo leerla: el PT rinde nominalmente más (10,85% vs 10,74%) pero tiene menos liquidez de salida (61 vs 88) — y esa diferencia entra en el score. El T-bill no compite: es la vara. Y el panel de riesgo de protocolo es el que hay que mirar cuando algo raro pasa en cripto: si ese 0,81 se desploma por debajo de 0,20, todo FARO — no solo M3 — pasa a SAFE_MODE.

Configuración: validar antes de aplicar.

La pantalla donde se cambia el criterio del sistema. Con red de contención en cada paso.

motores:
  funding_binance:
    umbral_entrada_apr_pct: 12   # ← editás acá
    persistencia_minima_ciclos: 3

Cómo leerla: "Validar" corre pydantic sin aplicar nada — si los pesos del scoring no suman 1,0 o un umbral está fuera de rango, te lo dice ahí. "Aplicar" crea una versión nueva y el cambio surte efecto en el próximo tick de cada motor, sin reiniciar el servicio. Y todo cambio deja rastro: la tabla de auditoría responde para siempre la pregunta "¿quién bajó ese umbral y cuándo?".

Las tres que miran para atrás.

Telegram: el sistema en el bolsillo.

El cockpit es para gestionar y analizar. Telegram es para enterarse y frenar. El kill switch existe en ambos.

notificaciones:
  telegram:
    nivel_minimo: "oportunidad"
      # debug | oportunidad | operacion | critico
    resumen_diario_hora_local: "21:00"

Dónde vive, y qué hacer cuando se rompe.

Los "no" valen tanto como los "sí".

Se evaluaron 13 oportunidades. Entraron 6. Estas son las que quedaron afuera, y por qué — porque un sistema se define tanto por lo que hace como por lo que se negó a hacer.

Cómo agregar un motor nuevo.

La prueba final de que la arquitectura es buena: qué tan aburrido es extenderla.

Glosario de bolsillo.

Si te quedás con cinco cosas.

FARO · documentación técnica v1 · generada desde el repositorio · Este documento no constituye asesoramiento financiero.