How It Works

Agent guide and operating notes

This page explains how the AI-powered portfolio agents work: the deterministic scoring engine, LLM portfolio manager with critic review, dynamic risk management with regime-adaptive stop-losses, adaptive learning system, continuous improvement via replay challengers, and what the diagnostics mean on your Market Agent and Crypto Agent pages.

North Star

What the agents are optimizing for

Each agent manages a single portfolio sleeve with one objective: grow enabled capital (holdings value plus deployable cash) every week with controlled drawdown. Cash sitting idle is treated as drag on performance, so the system actively seeks quality deployment opportunities. But it never forces a trade when the expected improvement is not strong enough after fees and risk.

Enabled capital = holdings market value + buying power.
Growth is measured from capital appreciation, not from deposits or withdrawals.
Drawdown control is a first-class constraint, not an afterthought.
The system adapts its aggression level based on recent performance, regime, and learning feedback.

Crypto Agent

The crypto momentum engine: slow by design

The Crypto Agent runs a time-series momentum strategy on the five most liquid majors (BTC, ETH, SOL, XRP, DOGE). It was selected after 25+ documented experiments on real historical data — faster trading, intraday stops, profit-taking overlays, and a dozen other popular ideas all tested worse net of fees. The engine decides once per day at midnight Pacific and holds through the day: in bull regimes (Bitcoin above its 200-day average) it holds the single strongest major by 28-day return; in bear regimes it becomes cash-capable, exiting coins whose trend breaks. Decisions and the trades it REFUSES are both recorded and graded weeks later, so the strategy's live record is measured, not asserted.

Regime switch: BTC above its 200-day average → hold the strongest major, never cash. Below it → defensive mode that can exit to cash per-coin.
Rotation hysteresis: a challenger must beat the held coin's 28-day return by a full band (~4-5 points) before the engine will switch — photo-finish ranking flips don't churn fees.
Breakout confirmation: a rotation or entry target must be trading near its own recent high. 'Hot on 28 days but far below its peak' is the classic dead-cat bounce, and the engine refuses it.
Circuit breaker: if sleeve equity ever draws down 60% from its peak, everything is force-sold to cash and the sleeve stays parked until the owner manually re-arms it. Works even when market data is down.
Maker-first execution: orders rest as post-only limits before falling back to market, cutting measured round-trip costs roughly in half.
Self-grading: every rotation and every refused rotation is scored at 7 and 21 days against the alternative. Pre-agreed thresholds — not vibes — decide when the strategy gets revisited.
Expected cadence: a few trades per month. Days or weeks with no trades are the strategy working, not idling.

Market Agent Pipeline

Market Agent: deterministic scoring engine with LLM overlay and critic review

Every decision cycle runs through multiple layers before any order reaches your broker. First, a deterministic scoring engine evaluates all candidates using a composite score combining EV edge, signal strength, evidence quality, and confidence. The engine is regime-adaptive and scales entry aggressiveness based on market conditions. An LLM portfolio manager then receives a structured decision packet with the top-ranked candidates, live signals, holdings, regime, risk budgets, and full learning history. It proposes actions with confidence levels and theses. A critic LLM independently reviews every proposal and can approve, reduce size, delay, or reject. Finally, deterministic gates enforce hard rules the LLM cannot override: stop-loss floors, giveback exits, risk budget caps, fee floors, correlation guards, and more.

Deterministic Engine: composite scoring (EV edge × signal × evidence × confidence) with regime-adaptive thresholds. Operates independently of the LLM.
Portfolio Manager: receives 20+ candidates, holdings, regime context, learning state, counterfactual history, and improvement config in a structured packet.
Critic: reviews each proposed trade independently. Can reduce position sizes (0.1x–1.0x), delay for better entry, or reject outright.
Deterministic Gates: hard-coded rules that override any LLM output, including stop-loss enforcement, giveback profit-taking, risk budget limits, anti-churn guardrails, and minimum edge requirements.
Candle Gate (crypto): four structural pre-buy checks using Coinbase candle data — dump detection with recovery override, EMA crossover (short vs long), VWAP position, and lower-high pattern detection. Thresholds are tunable by the improvement system. Fail-open when data is unavailable.
Repair Layer: if the LLM returns malformed output, a secondary model attempts JSON recovery before the cycle is discarded.
Emergency Safe Mode: if the LLM is unavailable, only protective stop-loss and giveback exits are permitted with no new buys.

Risk Management

Dynamic risk budgets, hard safety floors, and circuit breakers

The agent operates within a dynamic risk budget that adjusts based on market regime, sleeve label, and a learning-derived pressure score. Hard stop-loss floors are enforced deterministically and cannot be overridden by the LLM. A circuit breaker system monitors daily PnL and can lock the sleeve at multiple severity levels if losses exceed defined thresholds.

Single-name cap: limits how large any one position can grow (typically 24–36% depending on regime).
Gross exposure cap: limits total invested percentage (72–96% depending on regime and learning pressure).
Non-core exposure cap: restricts allocation to higher-risk, non-core assets.
Turnover budget: limits how much of the portfolio can change per cycle, preventing over-trading.
Regime-adaptive stop-loss: core holdings at −1.85% to −2.20%, non-core at −2.50% to −3.00%, with floors scaling based on current risk regime.
Giveback profit-taking: ATR-adaptive thresholds (min 2.5%, ATR × 1.2) with progressive gain protection that tightens as peak grows. Capped at 30% to prevent stale peaks from blocking exits.
Stale peak auto-heal: if a stored profit peak diverges more than 30% from current gain (from bad cost basis data), it resets automatically so exits are never permanently blocked.
Circuit breaker: monitors daily PnL and locks the sleeve at escalating severity levels if losses breach thresholds. Prevents catastrophic drawdowns.
Anti-churn guardrails: max 4 trades per ticker per 6-hour window, 30–60 minute post-entry grace period, and winner-trim cooldown after 2 profitable trims.
Learning pressure (0–1.2): a composite score from win rate, expectancy, slip, discipline, drawdown, and counterfactual biases that dynamically tightens or loosens all risk budgets.

Exit Strategy

Multiple independent exit paths protect capital

The agent does not rely on a single exit signal. Multiple independent exit strategies run in parallel, and any one can trigger a sell. This ensures positions are never stuck even if one exit mechanism has stale data or an unusual edge case.

Hard stop-loss: regime-adaptive floors enforced deterministically. Core −1.85% to −2.20%, non-core −2.50% to −3.00%. Cannot be overridden by the LLM.
Giveback (profit-taking): exits when a position gives back too much from its peak. Threshold is ATR-adaptive (min 2.5%, ATR × 1.2). Progressive protection tightens the allowed giveback as peak grows.
Failed runner: positions that peaked at +2% or more but have since gone negative are exited as failed runners once giveback threshold is breached.
Signal deterioration: the deterministic engine exits positions when the composite signal score falls below regime-adaptive thresholds.
LLM-driven exit: the portfolio manager can propose sells based on thesis invalidation, regime shift, or capital reallocation.
Manual sell: an emergency sell button on the agent console lets you queue an immediate market sell for any position.

Learning

Adaptive intelligence across 20+ dimensions

The agents learn from every trade outcome and calibrate behavior over time. Learning data is injected into the LLM decision packet each cycle, so the PM sees its own historical track record. A counterfactual system tracks opportunities the agent passed on and resolves them after 2–72 hours, revealing patterns of excessive conservatism or aggression.

Setup tracking: win rates and expectancy for each entry type (breakout momentum, recovery rebound, core accumulation, etc.).
Ticker memory: per-asset performance history, exit patterns, and signal threshold overrides for chronically poor performers.
Hold duration optimization: which hold windows produce the best expectancy. The system biases toward optimal hold buckets.
Confidence calibration: actual win rates per confidence bucket (0.6, 0.7, 0.8, 0.9) vs predicted. Detects overconfidence or underconfidence.
Regime performance: cross-tabulated setup × regime matrix showing which strategies work best in risk-on, mixed, or risk-off markets.
Counterfactuals: missed winners, good skips, missed exits, good holds, and critic accuracy. Generates deploy bias, cash bias, and hold bias signals.
Correlation outcomes: tracks whether correlated entries outperform or underperform uncorrelated ones.
Archetype system: entry playbooks (breakout momentum, recovery rebound, core accumulation, regime defense, etc.) promoted or suppressed based on current regime and historical results.

Improvement System

Continuous optimization via replay and shadow challengers

Both the crypto and market agents include a multi-agent improvement system that continuously tests configuration variants. A replay evaluator replays recent market cycles against candidate parameter sets, and a shadow challenger system runs up to 3 alternative configurations in parallel without affecting live execution. When a challenger demonstrates a meaningful edge, it can be promoted to production automatically.

Champion version: the current live configuration running production trades.
Live challenger: a single A/B test configuration running in parallel with a 30–45 minute grace period before promotion eligibility.
Shadow challengers: up to 3 offline experiments capturing objective score and replay heuristic score without executing real trades.
Promotion logic: a challenger must demonstrate a minimum edge (0.15% for crypto, 0.20% for market) over the incumbent to trigger promotion.
Rollback: if a promoted challenger underperforms, the system reverts with the reason logged.
Capital allocation override: the improvement system can adjust the capital allocation percentage and sizing reduction based on correlation spike detection.
Config hot-reload: configuration changes from the improvement system are applied on the next cycle without requiring a restart.

Market Regime

How the agent reads the market environment

The agent classifies the current market into one of four regimes: risk-on, mixed, risk-off, or transition. Regime detection drives playbook selection, risk budget sizing, stop-loss floor calibration, and candidate filtering. A transition risk score (0–1) aggregates funding crowding, breadth collapse, and leadership narrowness to detect imminent regime flips.

Risk-on: broad market participation, alts in play, higher gross exposure allowed, looser stop-loss floors.
Mixed: selective opportunity, neutral breadth, standard budgets apply.
Risk-off: capital rotating to stablecoins, defensive positioning, tighter non-core limits, tighter stop-loss floors.
Transition: unstable, regime flip imminent. Higher confidence required for new entries, non-core exposure reduced.

Diagnostics

What the idle and funnel messages mean

When the agent does not trade in a cycle, the diagnostics explain exactly why. These are not errors. They show which stage of the pipeline filtered out each candidate and what constraints are binding. Both Crypto Diagnostics and Market Diagnostics provide a full console with tabbed navigation for deep inspection.

Missing live signal: the agent could not build a usable signal for that candidate in this cycle.
Failed setup: the candidate had signal data but did not qualify as a valid entry type.
Failed liquidity or spread gate: the candidate did not meet minimum dollar-liquidity or had too wide a spread.
Risk budget binding: the agent wanted to act but a risk limit (single-name, non-core, gross, or turnover) prevented it.
Critic rejected: the critic layer blocked the trade after the PM proposed it. Reason is logged.
Deterministic gate blocked: a hard rule (fee floor, correlation guard, stop-loss conflict, rebuy cooldown, etc.) prevented execution.
Candle gate blocked: intraday price structure check failed — the ticker is in a dump without recovery, EMA downtrend, below VWAP, or forming lower highs. Prevents buying into active downtrends.
Reuse decision: context unchanged from last cycle, so the previous no-trade decision was reused to save costs.
Rebuy cooldown: a 60-minute cooldown prevents rebuying the same ticker immediately after selling it.

Ledger

How to use the tables and history

The ledger below the chart gives a compact view of what the sleeve holds, what the agent is considering next, and what it actually did. It is designed to feel like a brokerage workstation.

Transactions: most recent broker and ticket history for the sleeve.
Live Queue: what the agent is considering or staging for the next cycle.
Execution: recent executed orders, warnings, blocks, and live outcomes.
Sleeve Positions: current holdings with cost basis, gain/loss, peak tracking, and weight context.

Common Questions

What you are most likely to run into

Why didn’t the agent trade even though there was buying power?
For the Crypto Agent this is usually the strategy working as designed: it decides once per day, and most days the right decision is to keep holding the same coin. It also deliberately refuses rotations that don't clear its quality bars (the hysteresis band and the breakout filter) — our backtests showed those refused trades were, on average, fee-burning mistakes. For the Market Agent, candidates must clear composite score, signal, setup, liquidity, spread, risk budget, and critic review before capital deploys.
Why does the Crypto Agent trade so rarely?
Because every attempt to make it faster tested worse on real data. Four-times-daily refresh, intraday crash stops, and quick profit-taking were each backtested and each lost to the plain once-a-day design — crypto majors trend over weeks, and extra trading mostly buys whipsaw and fees. A few trades per month is the expected cadence; the daily decision stamp (visible in diagnostics) shows the engine is alive and choosing to hold.
How long before the agent learns enough to be effective?
The learning system needs real round-trip trades (buy and sell) to calibrate. In the first 5–10 days, the agent operates in a cold-start mode where its win rate is unknown, which adds conservative ghost pressure to the risk budget. After roughly 50 completed trades (typically 3–4 weeks), the learning dimensions have enough data to meaningfully adjust behavior: confidence calibration, hold duration bias, regime-specific setup selection, and counterfactual feedback all begin to produce actionable signals.
What happens if the LLM makes a bad call?
Multiple layers of protection exist. First, the deterministic scoring engine operates independently and can trade without the LLM. Second, the critic LLM independently reviews every proposed trade and can reduce size or reject. Third, deterministic gates enforce hard rules: regime-adaptive stop-loss floors, giveback profit-taking, risk budget caps, minimum edge thresholds, and correlation guards. Fourth, a circuit breaker monitors daily PnL and locks the sleeve if losses exceed thresholds. Fifth, the learning system feeds back outcomes so the PM sees its own track record. If the LLM is unavailable, the agent enters emergency safe mode where only protective exits are permitted.
Why did the agent sell at a loss?
Stop-loss exits are enforced by hard deterministic floors that scale with market regime: −1.85% to −2.20% for core assets and −2.50% to −3.00% for non-core. When a holding breaches its floor, the engine forces an exit regardless of what the LLM believes. Giveback exits can also trigger if a position gives back too much from its peak, even if still slightly profitable. The agent learns from these exits and adjusts future entry criteria for that setup type and ticker.
Why was a trade size reduced from what the agent proposed?
The critic layer can reduce any proposed trade size via a size multiplier (0.1x to 1.0x). Common reasons include correlation risk (too many similar positions), low conviction relative to size, or elevated regime transition risk. The improvement system can also apply a sizing reduction when it detects a correlation spike. The system tracks critic accuracy over time through counterfactuals, so if the critic is consistently wrong, the PM learns to push back.
What is the improvement system doing in the background?
The improvement system continuously tests configuration variants by replaying recent market cycles. It maintains a live challenger running in parallel and up to 3 shadow challengers running offline. When a challenger demonstrates a meaningful edge over the current champion configuration, it gets promoted automatically. If the promoted config underperforms, it rolls back. You can see the current state of the improvement system in the diagnostics console under the Decision Engine or Optimizer tabs.
Why does a position show a different return than what I see on Coinbase?
The agent uses Coinbase's unrealized PnL as the source of truth for cost basis. After sell-and-rebuy cycles, Coinbase's data can carry stale cost basis from older trades. The agent includes a stale peak auto-heal: if the stored profit peak diverges more than 30% from the current gain, it resets automatically so giveback exits are never permanently blocked.

Practical Use

A simple way to use the agents well

1. Check the top cards
Start with buying power, invested capital, and enabled capital. These tell you how much is deployed, how much is idle, and the total value the agent is working with.
2. Read the regime and sleeve state
The current market regime (risk-on, mixed, risk-off, transition) and sleeve state (pressing, neutral, defending, recovering) tell you what playbook the agent is running and how aggressive it is being.
3. Review diagnostics when idle
If the agent is not trading, the diagnostics console explains which filter blocked candidates: signal quality, liquidity, risk budget, critic rejection, rebuy cooldown, or a deterministic gate. This is normal operating behavior, not an error.
4. Give the agent time to learn
The learning system needs completed round-trip trades to calibrate. Expect 5\u201310 days to exit cold-start mode and 3\u20134 weeks of trading before the agent has enough data to meaningfully adapt its behavior across setups, regimes, and confidence levels.
5. Check the improvement system
Open the diagnostics console and check the Optimizer tab to see if the improvement system is testing challenger configurations. Promotions and rollbacks happen automatically based on replay performance.
6. Judge results by enabled capital growth
The real measure is whether enabled capital improved over time with controlled drawdown. Frequent trading does not mean the agent is working well; growing enabled capital with reasonable risk does.