Jeeva

A modular trading engine, initially built to test trading with Jev. But turned out to be a pretty useful tool that can be extended with other algorithm's for Mid-Frequency trading.

A dashboard lets you turn markets on/off, tune how often and how aggressively each one trades, choose which decision engine drives it, and watch the resulting decisions, positions, and P&L in real time.

What it does

• Tracks markets. For every Hyperliquid PERP you enable sampling on, Jeeva continuously records price, open interest, volume, and spread. Samples older than the market-data TTL (7 days by default, MARKET_DATA_TTL_DAYS) are pruned automatically, so history doesn't grow unbounded.
• Makes trading decisions. For every PERP you enable trading on, Jeeva periodically builds a summary of recent market conditions and asks a DecisionMaker for a target direction: long, short, or flat.
• Executes the decision. If the target direction differs from the current position, Jeeva closes/opens the position accordingly. Nothing happens if the target direction is unchanged (no re-buying, no pyramiding).
• Trades safely by default. New markets and a fresh deployment always start in mock mode against a simulated wallet. Real Hyperliquid orders only happen once you explicitly flip a market-wide switch to live and the engine has real wallet credentials configured.
• Protects itself. If a PERP's decision cycle fails five times in a row (bad data, a down decision API, a broken order, etc.), Jeeva force-flattens that PERP's position rather than leaving it in an unmanaged state.

Architecture

flowchart LR
    subgraph Browser
        FE["Next.js Dashboard\n(frontend/)"]
    end

    subgraph API["Express API (api/)"]
        REST["REST endpoints\n/perps, /engine-mode,\n/decisions, /positions ..."]
    end

    subgraph Engine["Rust Trading Engine (engine/)"]
        SUP["Decision Supervisor\none task per trading-enabled PERP"]
        DM["DecisionMaker\n(Fake / TypeSafe Jev / OpenRouter Jev)"]
        EXEC["ExecutionAdapter\n(Mock or Live)"]
        SAMP["Market-Data Sampler"]
    end

    Mongo[("MongoDB\nperpConfigs, engineConfig\n(watched live via change streams)")]
    PG[("TimescaleDB / Postgres\nmarket data, decisions,\npositions, funding history")]
    HL["Hyperliquid\n(market data + order API)"]
    Jev["Jev\n(TypeSafe System One model,\ndirect or via OpenRouter)"]

    FE <--> REST
    REST -->|read/write PERP & mode config| Mongo
    REST -->|read history for charts| PG
    Mongo -->|change streams,\nno restart needed| SUP
    Mongo --> SAMP
    SUP --> DM
    DM -->|market state summary| Jev
    Jev -->|target direction| DM
    SUP --> EXEC
    EXEC -->|mock: simulate fill| PG
    EXEC -->|live: real order| HL
    SAMP -->|price / OI / volume / spread| HL
    SAMP --> PG
    SUP -->|decision log, health| PG

frontend/ — the operator dashboard (Next.js). Lists markets, shows live price/positions/health, and is where you enable trading/sampling per PERP, pick a PERP's decision maker, and flip the engine between mock and live execution. Its API URL is resolved at runtime from the container's API_URL (served to the browser from /runtime-config), so one built image can be reused across instances pointing at different API backends.

api/ — a small Express service that mediates between the dashboard and the shared state: PERP configuration and engine mode live in MongoDB; market data, decisions, positions, and funding history live in TimescaleDB (used as plain Postgres).

engine/ — the always-running Rust process that actually trades. It watches MongoDB for configuration changes and, for every PERP with trading enabled, runs an independent loop on that PERP's configured frequency. Nothing here requires a restart to pick up a config change (enabling a market, changing its frequency/leverage/decision maker, flipping mock/live) — every loop iteration reads the latest config fresh.

The decision cycle

Each tick of a trading-enabled PERP's loop does the following, in order:

1. Read recent market history for that PERP from TimescaleDB — only samples recorded within the session's configured history window (the last 24 hours by default, tunable per session from the dashboard). If nothing was sampled in that window, the cycle is skipped rather than deciding on stale data.
2. Read the current position (flat/long/short) from the configured ExecutionAdapter.
3. Summarize state and ask the DecisionMaker for a target direction (see What Jev sees below).
4. Diff target vs. current position:

   Current	Target	Action
   flat	long/short	open
   long/short	flat	close
   long	short (or vice versa)	close, then open the opposite side
   long/short	same direction	no-op (no pyramiding)

5. Apply the action through the ExecutionAdapter — a simulated fill in mock mode, a real signed Hyperliquid order in live mode.
6. Log the cycle (context, decision, action taken, any error) so every tick is auditable from the dashboard, even ticks that fail.

This is the beginning of the README. Read the rest at the original. Read the full README ↗