trade-doc/momentum-service-v1.md

Momentum Service V1

Ten dokument definiuje pierwszy osobny mikroserwis dla bloku Momentum z bot1.tex.

Cel

momentum-service liczy tylko skladniki momentum i zmiennosci z candles.

Zakres v1:

• mom_3s
• mom_10s
• mom_30s
• vol_30s

Poza zakresem v1:

• spread
• depth
• slippage
• gating
• scoring
• zapis decyzji tradingowej

Zasady

• Hasura jest jedynym source of truth dla danych wejsciowych.
• Fastify jest shell-em mikroserwisu i wystawia wynik przez endpointy.
• Serwis nie utrzymuje osobnego trwalego stanu prawdy.
• W v1 wynik jest wystawiany przez HTTP i trzymany tylko jako latest runtime snapshot.

Dlaczego to jest osobny serwis

momentum-service jest dobrym deployment boundary, bo caly jego processing zalezy tylko od candles i nie potrzebuje danych DLOB.

To znaczy:

• momentum i volatility sa razem w jednym serwisie
• poszczegolne horyzonty mom_3s, mom_10s, mom_30s nie sa osobnymi procesami
• granica serwisu jest wyznaczona przez wspolne wejscie i wspolny wynik runtime, a nie przez pojedynczy wzor

Wejscie

Serwis czyta z Hasury:

• bot_config po BOT_ID albo BOT_NAME
• get_drift_candles(...)

Minimalne dane z bot_config:

{
  "market_name": "SOL-PERP",
  "params": {
    "loop": {
      "decision_interval_ms": 1000,
      "candle_bucket_seconds": 1,
      "candles_limit": 64
    },
    "features": {
      "mom_fast_s": 3,
      "mom_mid_s": 10,
      "mom_slow_s": 30,
      "vol_window_s": 30
    }
  }
}

Processing

Model liczenia odpowiada definicjom z bot1.tex:

mom_k(t) = 10^4 * (c_t / c_{t-k} - 1)

oraz:

vol_W = stddev(r_i), gdzie r_i = 10^4 * (c_i / c_{i-1} - 1)

Serwis nie uzywa orderbooka ani tabel derived DLOB.

Wyjscie

V1 wystawia wynik przez:

• GET /healthz
• GET /readyz
• GET /status
• GET /result/latest
• POST /run

Przykladowy wynik GET /result/latest:

{
  "ok": true,
  "service": "momentum-service",
  "version": "momentum-service-v1",
  "bot": {
    "id": "uuid",
    "name": "sol-observer"
  },
  "market": {
    "name": "SOL-PERP",
    "candle_bucket_seconds": 1,
    "candles_limit": 64
  },
  "features": {
    "mom_3s": 3.8,
    "mom_10s": 6.1,
    "mom_30s": -12.5,
    "vol_30s": 4.2
  },
  "snapshot": {
    "latest_candle_at": "2026-03-27T22:44:10.000Z",
    "candles_count": 64,
    "query_latency_ms": 41,
    "compute_latency_ms": 1
  }
}

Runtime

Petla v1:

• laduje bot_config
• pobiera candles
• liczy momentum i volatility
• odswieza latest result

Domyslnie:

• loop 1000 ms
• candles 1s
• 64 swiece

Bledy

Serwis zwraca:

• 503 na /readyz, gdy nie ma swiezego poprawnego wyniku
• 404 na nieznane endpointy
• 500 na POST /run, jesli tick zakonczyl sie bledem

Blad Hasury nie zatrzymuje procesu na stale. Serwis pozostaje online, ale ready przechodzi na false, dopoki kolejny poprawny tick nie odswiezy wyniku.

Relacja do innych serwisow

momentum-service jest kandydatem na osobny building block dla:

• observer-service
• scoring-service
• downstream debug UI

W kolejnych wersjach wynik moze byc:

• nadal tylko czytany przez HTTP,
• albo dodatkowo zapisywany do osobnej tabeli w Hasurze.