hood-traders 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,697 @@
+import { Address, Hash, Account } from 'viem';
+import * as hoodchain from 'hoodchain';
+import { HoodNetwork, HoodClient, SwapQuote, StockQuote } from 'hoodchain';
+import { Server } from 'node:http';
+
+/** Trading mode. `paper` simulates fills against live liquidity; `live` signs real swaps. */
+type Mode = 'paper' | 'live';
+/** A single actionable instruction produced by a strategy's `decide` step. */
+interface Intent {
+    /** `buy` = spend the quote token to acquire `token`; `sell` = the reverse. */
+    side: 'buy' | 'sell';
+    /** The non-quote token being acquired (buy) or disposed (sell). */
+    token: Address;
+    /** Human label for the token, for journal/dashboard readability. */
+    tokenSymbol: string;
+    /**
+     * Amount of the INPUT token, in its smallest unit. On a `buy` the input is the
+     * quote token (spend N USDG/WETH → receive `token`); on a `sell` the input is
+     * `token` itself (sell N token units → receive the quote token).
+     */
+    amountIn: bigint;
+    /** Which token `amountIn` is denominated in (what leaves the wallet on a buy). */
+    quoteToken: Address;
+    /** Quote token symbol, e.g. `USDG` or `WETH`. */
+    quoteSymbol: string;
+    /** Free-text reason the strategy fired — surfaced verbatim in the decision journal. */
+    reason: string;
+    /** Optional per-intent slippage override (bps). Falls back to the agent's cap. */
+    maxSlippageBps?: number;
+    /** Opaque strategy metadata persisted with the decision (take-profit level, curve %, premium bps…). */
+    meta?: Record<string, unknown>;
+}
+/** An alert a strategy raises without trading (e.g. premium-watch in alerts-only mode). */
+interface Alert {
+    level: 'info' | 'warn';
+    message: string;
+    meta?: Record<string, unknown>;
+}
+/** What a strategy returns each tick. */
+interface Decision {
+    intents: Intent[];
+    alerts: Alert[];
+}
+/** A position the agent is currently holding (paper or live). */
+interface Position {
+    token: Address;
+    tokenSymbol: string;
+    /** Token units held (smallest unit). */
+    amount: bigint;
+    /** Quote token spent to open (net of sells), smallest unit. */
+    costBasis: bigint;
+    /** USD cost basis at time of each buy (net of proportional sells) — the number the position cap bounds. */
+    investedUsd: number;
+    quoteToken: Address;
+    quoteSymbol: string;
+    /** ms epoch the position opened. */
+    openedAt: number;
+    /** Marked exit value in USD at last tick (null until first mark). */
+    markUsd: number | null;
+    /** Strategy metadata carried from the opening intent. */
+    meta: Record<string, unknown>;
+}
+/** Reason an intent was refused before execution. */
+type RefusalReason = 'position_cap' | 'daily_cap' | 'fleet_daily_cap' | 'slippage_bound' | 'cooldown' | 'kill_switch' | 'no_route' | 'eligibility_gate' | 'insufficient_balance' | 'zero_amount';
+/** A journaled trade (executed or simulated). */
+interface TradeRecord {
+    id?: number;
+    agentId: string;
+    mode: Mode;
+    ts: number;
+    side: 'buy' | 'sell';
+    token: Address;
+    tokenSymbol: string;
+    quoteToken: Address;
+    quoteSymbol: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    /** null in paper mode; the swap tx hash in live mode. */
+    txHash: Hash | null;
+    reason: string;
+    slippageBps: number;
+    gasEstimate: bigint;
+    meta: Record<string, unknown>;
+}
+/** A journaled decision that did NOT result in a trade (refused / held / alerted). */
+interface DecisionRecord {
+    id?: number;
+    agentId: string;
+    ts: number;
+    kind: 'refused' | 'alert' | 'observe';
+    detail: string;
+    meta: Record<string, unknown>;
+}
+/** A point on an agent's equity curve. */
+interface EquityPoint {
+    agentId: string;
+    ts: number;
+    /** Realized PnL to date (quote units, USDG cents-style as float USD). */
+    realizedUsd: number;
+    /** Marked value of open positions (USD). */
+    openValueUsd: number;
+    /** realized + open. */
+    equityUsd: number;
+}
+/** Per-agent risk limits. */
+interface RiskLimits {
+    maxPositionUsdg: number;
+    maxDailySpendUsdg: number;
+    maxSlippageBps: number;
+    cooldownSeconds: number;
+}
+/** Live snapshot of an agent for the dashboard. */
+interface AgentStatus {
+    id: string;
+    strategy: string;
+    mode: Mode;
+    running: boolean;
+    killed: boolean;
+    limits: RiskLimits;
+    spentTodayUsd: number;
+    realizedUsd: number;
+    openValueUsd: number;
+    equityUsd: number;
+    positions: Position[];
+    lastTickAt: number | null;
+    lastError: string | null;
+    ticks: number;
+    trades: number;
+    refusals: number;
+}
+
+/**
+ * The decision journal — the agent's black box recorder. Every observe, every
+ * refusal, every trade (paper or live), and every equity mark lands here so the
+ * dashboard can answer "why did this trade fire?" and the whole run is auditable
+ * after the fact.
+ *
+ * SQLite via better-sqlite3 (synchronous, zero-config, embedded). bigints are
+ * stored as decimal TEXT — SQLite integers are 64-bit signed and token amounts
+ * routinely exceed that, so TEXT is the only lossless option.
+ */
+declare class Journal {
+    private readonly db;
+    constructor(dbPath: string);
+    private migrate;
+    recordTrade(t: TradeRecord): number;
+    recordDecision(d: DecisionRecord): number;
+    recordEquity(e: EquityPoint): void;
+    /** Sum of USDG-denominated spend by an agent since a UTC-day boundary (ms). */
+    spentSince(agentId: string, sinceMs: number, quoteSymbol?: string): number;
+    recentTrades(agentId: string, limit?: number): TradeRecord[];
+    recentDecisions(agentId: string, limit?: number): DecisionRecord[];
+    equityCurve(agentId: string, limit?: number): EquityPoint[];
+    /** All trades across every agent, newest first — for the fleet-wide feed. */
+    allRecentTrades(limit?: number): TradeRecord[];
+    close(): void;
+}
+
+/** Fleet-wide configuration resolved from the environment. */
+interface FleetConfig {
+    network: HoodNetwork;
+    rpcUrl: string | undefined;
+    mode: Mode;
+    /** Set true only when HOOD_TRADERS_LIVE=1 AND a key is present. */
+    hasWallet: boolean;
+    privateKey: `0x${string}` | undefined;
+    stockTokenEligible: boolean;
+    fleetMaxDailySpendUsdg: number;
+    dashboardPort: number;
+    killFile: string;
+    /** Path to the SQLite journal. */
+    dbPath: string;
+    defaultLimits: RiskLimits;
+}
+/**
+ * Resolve fleet configuration from the environment.
+ *
+ * Live mode is deliberately hard to enable by accident: it requires BOTH
+ * `HOOD_TRADERS_LIVE=1` and a `ROBINHOOD_CHAIN_PRIVATE_KEY`. Missing either one
+ * falls back to paper mode rather than erroring, so a mis-set flag can never
+ * silently spend real funds.
+ */
+declare function loadFleetConfig(env?: NodeJS.ProcessEnv): FleetConfig;
+
+/** A memecoin/token spot price sourced from live Uniswap v3 liquidity. */
+interface SpotPrice {
+    token: Address;
+    /** USD value of one whole token, derived from a probe quote against USDG (direct or via WETH). */
+    priceUsd: number;
+    /** Quote token the probe routed through. */
+    via: 'usdg' | 'weth';
+    ts: number;
+}
+/**
+ * The market adapter. Everything the observe/simulate steps need, sourced from
+ * live Robinhood Chain state through the `hoodchain` SDK — Chainlink stock
+ * feeds, Uniswap v3 quotes (which ARE `eth_call` simulations against real
+ * pools), and an ETH/USD reference derived from the on-chain USDG/WETH pool.
+ *
+ * No price here is fabricated: a token with no liquidity resolves to `null`, and
+ * strategies must handle that rather than trade a made-up number.
+ */
+declare class Market {
+    readonly client: HoodClient;
+    readonly usdg: Address;
+    readonly weth: Address;
+    readonly usdgDecimals = 6;
+    private ethUsdCache;
+    constructor(config: FleetConfig, account?: Account);
+    /** Latest block number — a cheap liveness/observe heartbeat. */
+    blockNumber(): Promise<bigint>;
+    /**
+     * ETH price in USD from the on-chain USDG/WETH pool (quote 0.01 WETH → USDG).
+     * Cached for 30s — it moves slowly relative to a trading tick and every call
+     * is a real RPC round trip. Returns `null` if no USDG/WETH pool answers.
+     */
+    ethUsd(maxAgeMs?: number, now?: number): Promise<number | null>;
+    /**
+     * Spot USD price of one whole `token` from live liquidity. Probes token→USDG
+     * directly, then token→WETH→USDG, using a 1-token probe. Returns `null` when
+     * neither route has liquidity.
+     */
+    spotPrice(token: Address, tokenDecimals?: number, now?: number): Promise<SpotPrice | null>;
+    /**
+     * Quote a buy: how much `token` `amountIn` of `quoteToken` acquires, at live
+     * liquidity. This is the simulate step — a QuoterV2 `eth_call`, no state
+     * change. Returns `null` when no route fills.
+     */
+    quoteBuy(quoteToken: Address, token: Address, amountIn: bigint): Promise<SwapQuote | null>;
+    /** Quote a sell: proceeds in `quoteToken` from selling `amount` of `token`. */
+    quoteSell(token: Address, quoteToken: Address, amount: bigint): Promise<SwapQuote | null>;
+    /** Chainlink price for a Stock Token (already multiplier-adjusted). */
+    stockChainlinkPrice(symbol: string): Promise<StockQuote | null>;
+    /**
+     * DEX price of a Stock Token in USD from the USDG pool — the number the
+     * premium-watch strategy compares against the Chainlink oracle. Probes with a
+     * flat 10 USDG order (small enough to keep impact low across the priced
+     * registry) and backs out the implied per-token price from the fill.
+     */
+    stockDexPrice(tokenAddress: Address, referenceUsd: number): Promise<number | null>;
+    /** Priced Stock Tokens from the registry (those with a Chainlink feed). */
+    pricedStockTokens(): hoodchain.StockToken[];
+    /** Router/quoter/weth/usdg set for the active network. */
+    addresses(): {
+        quoterV2: Address;
+        router: Address;
+        routerKind: "swapRouter02" | "swapRouter";
+        weth: Address;
+        usdg: Address;
+    };
+}
+
+/**
+ * Global kill switch. Once tripped it is irreversible for the process lifetime:
+ * every agent checks `isKilled()` before each decide/execute step and refuses to
+ * open new positions. Three independent triggers, per the spec:
+ *
+ *   1. SIGINT / SIGTERM (Ctrl-C, container stop)
+ *   2. the presence of a `KILL` file on disk (drop-a-file panic button)
+ *   3. an HTTP `POST /kill` on the dashboard server (wired in server/)
+ *
+ * The switch never sells or unwinds on its own — it HALTS new risk. Unwinding is
+ * an explicit operator action, because a forced market-sell into thin liquidity
+ * during whatever caused the panic is usually worse than holding.
+ */
+declare class KillSwitch {
+    private readonly killFilePath;
+    private killed;
+    private reason;
+    private readonly listeners;
+    private fileTimer;
+    constructor(killFilePath: string);
+    /** Install SIGINT/SIGTERM handlers and begin polling the kill file. */
+    arm(): void;
+    /** Trip the switch. Idempotent. */
+    trip(reason: string): void;
+    isKilled(): boolean;
+    killReason(): string | null;
+    /** Subscribe to the trip event. Returns an unsubscribe fn. */
+    onKill(listener: (reason: string) => void): () => void;
+    /** Stop the file poller (used in tests/teardown). */
+    dispose(): void;
+}
+
+/** Which token a strategy denominates its orders in. */
+type QuoteKind = 'usdg' | 'weth';
+/** Documentation a strategy must publish about itself — surfaced in docs + dashboard. */
+interface StrategyMeta {
+    /** One-paragraph honest statement of why this could have an edge. */
+    edge: string;
+    /** The ways this strategy loses money — named plainly, no hand-waving. */
+    failureModes: string[];
+    /** Tunable parameters and their live values. */
+    params: Record<string, unknown>;
+}
+/** Context handed to a strategy on each decision tick. */
+interface StrategyTickContext {
+    market: Market;
+    /** This agent's currently open positions. */
+    positions: Position[];
+    /** Injected clock (ms) — deterministic in tests. */
+    now: number;
+    /** Resolved quote token address for this strategy's {@link QuoteKind}. */
+    quoteToken: Address;
+    quoteSymbol: string;
+    quoteDecimals: number;
+    /** Structured log line into the decision journal (kind = observe). */
+    log: (message: string, meta?: Record<string, unknown>) => void;
+}
+/** Context handed once at strategy startup (for stream subscriptions). */
+interface StrategyStartContext {
+    market: Market;
+    log: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * A trading strategy: pure observation → decision. It never touches wallets,
+ * risk caps, or the journal — the {@link Agent} owns simulate/execute/journal
+ * and enforces every risk rail around whatever the strategy proposes. A
+ * strategy that proposes a wild order simply gets refused; it cannot bypass the
+ * risk engine.
+ */
+interface Strategy {
+    readonly id: string;
+    readonly title: string;
+    readonly quote: QuoteKind;
+    readonly meta: StrategyMeta;
+    /** Optional: wire real-time subscriptions (e.g. launch stream). */
+    start?(ctx: StrategyStartContext): Promise<void> | void;
+    /** Optional teardown for subscriptions. */
+    stop?(): void;
+    /** Produce intents + alerts for this tick. */
+    tick(ctx: StrategyTickContext): Promise<Decision>;
+}
+
+/** Everything an {@link Agent} is constructed with. */
+interface AgentOptions {
+    id: string;
+    strategy: Strategy;
+    market: Market;
+    limits: RiskLimits;
+    journal: Journal;
+    kill: KillSwitch;
+    mode: Mode;
+    /** Account for live execution; null in paper mode. */
+    account: Account | null;
+    fleetMaxDailySpendUsdg: number;
+    /** Fleet-wide spend accessor + reporter, so the agent respects the global cap. */
+    fleetSpentTodayUsd: () => number;
+    reportFleetSpend: (usd: number) => void;
+    /** Milliseconds between decision ticks. */
+    tickIntervalMs: number;
+    /** Injected clock, for tests. Defaults to `Date.now`. */
+    clock?: () => number;
+}
+/**
+ * An autonomous trading agent = strategy + wallet + risk budget + journal.
+ *
+ * Each tick runs the full pipeline: observe (the strategy reads the {@link
+ * Market}) → decide (the strategy returns intents) → simulate (a real QuoterV2
+ * `eth_call`) → risk-check (the {@link RiskEngine}, fail-closed) → execute
+ * (paper: record the simulated fill; live: sign the swap) → journal (every
+ * decision, refusal, trade, and equity mark). The strategy proposes; the agent
+ * disposes, and never lets an intent skip the risk gate.
+ */
+declare class Agent {
+    readonly id: string;
+    readonly strategy: Strategy;
+    readonly mode: Mode;
+    private readonly market;
+    private readonly risk;
+    private readonly journal;
+    private readonly kill;
+    private readonly account;
+    private readonly opts;
+    private readonly clock;
+    private readonly positions;
+    private lastTradeAt;
+    private realizedUsd;
+    private spentTodayUsd;
+    private spentDay;
+    private ticks;
+    private trades;
+    private refusals;
+    private lastTickAt;
+    private lastError;
+    private timer;
+    private running;
+    private ticking;
+    constructor(opts: AgentOptions);
+    /** Begin the tick loop and wire the strategy's stream subscriptions. */
+    start(): Promise<void>;
+    /** Stop the loop and the strategy's subscriptions. */
+    stop(): void;
+    private scheduleTick;
+    /** Run one full pipeline pass. Safe to call directly (used by tests). */
+    tick(): Promise<void>;
+    private decide;
+    private quoteInfo;
+    private processIntent;
+    private executeLive;
+    private applyFill;
+    /** Mark every open position to its live exit value (a real sell-side quote). */
+    private markPositions;
+    private openValueUsd;
+    private recordEquity;
+    private rolloverDay;
+    /** Live status snapshot for the dashboard API. */
+    status(): AgentStatus;
+}
+
+/** Definition of one agent within a fleet. */
+interface AgentSpec {
+    id: string;
+    strategy: Strategy;
+    /** Overrides merged over the fleet default limits. */
+    limits?: Partial<RiskLimits>;
+    tickIntervalMs?: number;
+}
+/** Aggregate fleet numbers for the dashboard header. */
+interface FleetSummary {
+    network: string;
+    mode: Mode;
+    killed: boolean;
+    killReason: string | null;
+    fleetSpentTodayUsd: number;
+    fleetMaxDailySpendUsdg: number;
+    realizedUsd: number;
+    openValueUsd: number;
+    equityUsd: number;
+    agents: number;
+    startedAt: number;
+}
+/**
+ * The fleet: owns the shared market client, journal, and kill switch, then runs
+ * a set of agents against them and tracks the global daily-spend budget. It is
+ * the process-level object the dashboard server reads and the kill switch acts
+ * on.
+ */
+declare class Fleet {
+    readonly config: FleetConfig;
+    readonly journal: Journal;
+    readonly kill: KillSwitch;
+    readonly market: Market;
+    private readonly account;
+    private readonly agents;
+    private fleetSpentTodayUsd;
+    private spentDay;
+    private startedAt;
+    constructor(config: FleetConfig);
+    /** Build agents from specs. */
+    addAgents(specs: AgentSpec[]): void;
+    private currentFleetSpend;
+    private recordFleetSpend;
+    /** Arm the kill switch and start every agent's loop. */
+    start(): Promise<void>;
+    /** Stop all agents (kill switch stays tripped if it was). */
+    stop(): void;
+    /** Run exactly one tick per agent, in parallel, without arming the interval scheduler. Used by E2E tests. */
+    tickAllOnce(): Promise<void>;
+    /** Trip the kill switch — halts new orders across the fleet. */
+    tripKill(reason: string): void;
+    agentStatuses(): AgentStatus[];
+    summary(): FleetSummary;
+    close(): void;
+}
+
+/** Everything the risk engine needs to rule on a single intent. */
+interface RiskContext {
+    /** `buy` grows exposure and hits spend/position caps; `sell` reduces it and is exempt from those. */
+    side: 'buy' | 'sell';
+    /** USD notional of this order (agent computes it from live prices; USDG≈USD, WETH×ethUsd). */
+    notionalUsd: number;
+    /** USD value the token position would reach AFTER a buy fills. */
+    positionUsdAfter: number;
+    /** USD this agent has already spent this UTC day. */
+    spentTodayUsd: number;
+    /** USD the whole fleet has spent this UTC day. */
+    fleetSpentTodayUsd: number;
+    /** ms epoch of this agent's last executed trade, or null. */
+    lastTradeAt: number | null;
+    /** Slippage bound (bps) the order would execute with. */
+    slippageBps: number;
+    /** Whether the global kill switch is tripped. */
+    killed: boolean;
+    /** Current time (ms) — injected for deterministic tests. */
+    now: number;
+    /** Fleet-wide daily spend ceiling (USD). */
+    fleetMaxDailySpendUsdg: number;
+}
+/** Result of a risk check. */
+interface RiskVerdict {
+    ok: boolean;
+    reason?: RefusalReason;
+    /** Human explanation, safe to journal and surface on the dashboard. */
+    detail: string;
+}
+/**
+ * The risk engine. It is the last gate before any order — paper or live —
+ * reaches execution, and it fails CLOSED: any check it cannot satisfy refuses
+ * the trade rather than letting it through. Refusals are ordered from
+ * cheapest/most-fatal (kill switch) to most-specific (caps) so the journaled
+ * reason is the most meaningful one.
+ *
+ * Sells are intentionally exempt from spend and position caps: those caps exist
+ * to bound how much risk you take ON, and refusing a de-risking sell because of
+ * a spend cap would trap an agent in a losing position. Sells still honor the
+ * kill switch, cooldown, and slippage bound.
+ */
+declare class RiskEngine {
+    private readonly limits;
+    constructor(limits: RiskLimits);
+    get riskLimits(): RiskLimits;
+    check(ctx: RiskContext): RiskVerdict;
+}
+/** UTC-midnight ms boundary for `now` — the daily-cap accounting window. */
+declare function utcDayStart(now: number): number;
+
+/** Tunables for {@link LaunchSniper}. */
+interface LaunchSniperParams {
+    /** WETH spent per entry. */
+    entryWeth: number;
+    /** Take profit as a fraction (0.5 = +50%). */
+    takeProfitPct: number;
+    /** Stop loss as a fraction (0.3 = -30%). */
+    stopLossPct: number;
+    /** Force-exit a position after this many seconds regardless of PnL. */
+    maxHoldSeconds: number;
+    /** Reject a launch if the deployer still holds more than this fraction of supply. */
+    maxDeployerPct: number;
+    /** Reject if an immediate buy→sell round trip would lose more than this fraction (honeypot/thin-pool guard). */
+    maxRoundTripLossPct: number;
+    /** Only consider launches at most this many seconds old when first seen. */
+    maxLaunchAgeSeconds: number;
+}
+/**
+ * launch-sniper — enter brand-new launchpad coins that clear objective safety
+ * filters, then exit on take-profit, stop, or a hard time limit.
+ *
+ * EDGE HYPOTHESIS: the first minutes after a NOXA instant-listing are the most
+ * information-rich and most volatile window a memecoin ever has. A disciplined
+ * buyer who (a) only touches tokens that are actually round-trippable (not
+ * honeypots) and whose deployer is not sitting on the supply, and (b) exits
+ * mechanically instead of falling in love, harvests a slice of that opening
+ * volatility. The edge is speed + discipline, not prediction.
+ *
+ * FAILURE MODES: most new launches go to zero — the stop loss WILL fire often
+ * and the strategy is negative-carry unless the winners pay for the losers.
+ * Honeypots evolve (sell-tax toggled AFTER you buy); the round-trip check only
+ * sees the state at entry. Odyssey tokens on the bonding curve have no Uniswap
+ * pool yet, so they are skipped until graduation — this strategy is really a
+ * NOXA/graduated-pool sniper. Paper fills assume the QuoterV2 mid; a real
+ * sniper competes with faster bots and eats worse fills.
+ */
+declare class LaunchSniper implements Strategy {
+    readonly id = "launch-sniper";
+    readonly title = "Launch Sniper";
+    readonly quote: "weth";
+    private readonly p;
+    private readonly queue;
+    private readonly seen;
+    private unwatch;
+    constructor(params?: Partial<LaunchSniperParams>);
+    get meta(): StrategyMeta;
+    start(ctx: StrategyStartContext): void;
+    stop(): void;
+    tick(ctx: StrategyTickContext): Promise<Decision>;
+    private evaluate;
+    private deployerConcentration;
+}
+
+/** Tunables for {@link Momentum}. */
+interface MomentumParams {
+    /** USDG spent per entry. */
+    entryUsdg: number;
+    /** Minimum price gain over the lookback window to count as a breakout. */
+    breakoutPct: number;
+    /** How many price samples (ticks) form the lookback window. */
+    lookbackSamples: number;
+    /** Trailing stop: exit if price falls this fraction off its post-entry peak. */
+    trailingStopPct: number;
+    /** Hard time exit regardless of PnL. */
+    maxHoldSeconds: number;
+    /** How many graduated tokens to track price history for (most-recently-graduated first). */
+    maxTracked: number;
+    /** Blocks to look back for discovering graduated tokens. */
+    discoveryLookbackBlocks: bigint;
+}
+/**
+ * momentum — volume+price breakout entries on already-graduated (liquid)
+ * tokens, trailing-stop exits.
+ *
+ * EDGE HYPOTHESIS: a token that has already graduated to a locked Uniswap v3
+ * pool has survived the highest-mortality phase (the bonding curve / first
+ * minutes). A subsequent breakout — price up sharply over a short lookback,
+ * confirmed by the pool actually being tradable at size — reflects real
+ * incoming demand rather than launch-day noise, and trend-following that with
+ * a trailing stop captures the middle of the move while giving back only the
+ * tail.
+ *
+ * FAILURE MODES: breakouts on illiquid tokens are trivially fakeable by a
+ * single wallet round-tripping the pool; the strategy only looks at price, not
+ * depth, so it can chase a move that reverses the instant it stops buying.
+ * Trailing stops whipsaw in choppy markets — expect a string of small losses
+ * between real trends. Discovery only looks at NOXA (instant-listed, so
+ * "graduated" from day one) and Odyssey `PoolMigrated` history within the
+ * lookback window; a real breakout minutes after that window closes is missed
+ * until the next discovery pass.
+ */
+declare class Momentum implements Strategy {
+    readonly id = "momentum";
+    readonly title = "Momentum";
+    readonly quote: "usdg";
+    private readonly p;
+    private readonly history;
+    private readonly peakSinceEntry;
+    private lastDiscoveryAt;
+    constructor(params?: Partial<MomentumParams>);
+    get meta(): StrategyMeta;
+    tick(ctx: StrategyTickContext): Promise<Decision>;
+    private exitIntent;
+    private discover;
+}
+
+/** Tunables for {@link PremiumWatch}. */
+interface PremiumWatchParams {
+    /** Symbols to watch. Defaults to a handful of the most liquid priced Stock Tokens. */
+    symbols: string[];
+    /** Premium/discount (bps, |dex - oracle| / oracle) that triggers an alert. */
+    alertThresholdBps: number;
+    /** Premium/discount (bps) that triggers a convergence TRADE — only reachable in trade-eligible config. */
+    tradeThresholdBps: number;
+    /** USDG spent per convergence trade, when trading is enabled. */
+    tradeSizeUsdg: number;
+    /** Exit once the premium reverts to within this many bps of fair. */
+    exitThresholdBps: number;
+    /** Hard time exit for a convergence position regardless of premium. */
+    maxHoldSeconds: number;
+    /**
+     * Convergence TRADING is opt-in and requires BOTH this flag AND
+     * `market.client.acknowledgeStockTokenEligibility === true` (the operator's
+     * non-US-person affirmation, per `_shared.md`). Missing either keeps the
+     * strategy strictly alerts-only, which is the default and the recommended mode.
+     */
+    enableTrading: boolean;
+}
+/**
+ * premium-watch — tracks the spread between each Stock Token's Chainlink
+ * oracle price and its live Uniswap v3 DEX price, and alerts on premium/discount.
+ * Trades the convergence ONLY when explicitly enabled AND the operator has
+ * affirmed Stock Token eligibility — otherwise it is alerts-only, which is the
+ * default and the recommended mode for anyone who hasn't cleared the legal gate
+ * in `_shared.md`.
+ *
+ * EDGE HYPOTHESIS: Stock Token pools are much thinner than the underlying
+ * equity market, so DEX price can drift from the Chainlink oracle (itself fed
+ * by the real market) when flow is one-sided. If the drift is a liquidity
+ * artifact rather than new information, buying the discount / shorting the
+ * premium (here: buying the discount and later selling back at fair, since the
+ * SDK has no short primitive) captures the reversion as the pool re-equilibrates
+ * via arbitrage or the next informed trade.
+ *
+ * FAILURE MODES: a premium can be RIGHT — the DEX price can be reacting to
+ * information the Chainlink heartbeat (up to 24h) hasn't caught up to yet, in
+ * which case "fading" it loses money on purpose. Stock Token pools are thin;
+ * the $10 probe used to read `stockDexPrice` may not reflect the price your
+ * actual trade size gets, and the trade itself moves the price you're trying to
+ * arbitrage. Only long convergence is possible (no shorting), so premiums
+ * (DEX rich) are alert-only even when trading is enabled — asymmetric coverage
+ * by construction. Chainlink staleness (weekends, feed outages) can make a
+ * quote look like a discount when it is just old.
+ */
+declare class PremiumWatch implements Strategy {
+    readonly id = "premium-watch";
+    readonly title = "Premium Watch";
+    readonly quote: "usdg";
+    private readonly p;
+    constructor(params?: Partial<PremiumWatchParams>);
+    get meta(): StrategyMeta;
+    tick(ctx: StrategyTickContext): Promise<Decision>;
+    private readSpread;
+}
+
+/**
+ * The fleet dashboard: a tiny read API over {@link Fleet} plus a `POST /kill`
+ * panic button, serving the static `dashboard/` UI. No framework — this is a
+ * small, auditable surface that is also the E2E harness talks to.
+ *
+ * `staticRoot` is resolved by the caller rather than guessed from this
+ * module's own location: tsup flattens `src/**​/*.ts` into a single-level
+ * `dist/`, so a path relative to *this* file's directory would differ between
+ * `tsx` (unbundled, nested under `src/server/`) and the built bundle (flat).
+ * `main.ts` sits at a stable one-level depth in both trees, so it computes
+ * the path once and passes it in.
+ */
+declare function createDashboardServer(fleet: Fleet, staticRoot: string): Server;
+
+export { Agent, type AgentOptions, type AgentSpec, type AgentStatus, type Alert, type Decision, type DecisionRecord, type EquityPoint, Fleet, type FleetConfig, type FleetSummary, type Intent, Journal, KillSwitch, LaunchSniper, type LaunchSniperParams, Market, type Mode, Momentum, type MomentumParams, type Position, PremiumWatch, type PremiumWatchParams, type QuoteKind, type RefusalReason, type RiskContext, RiskEngine, type RiskLimits, type RiskVerdict, type SpotPrice, type Strategy, type StrategyMeta, type StrategyStartContext, type StrategyTickContext, type TradeRecord, createDashboardServer, loadFleetConfig, utcDayStart };