### Launch Real-Time Trading Dashboard

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Starts a web dashboard in a background thread for live trading visualization and RL metrics. It provides functions to update dashboard state, RL metrics, and emit trade events, making the trading activity and performance visible in real-time.

```python
from dashboard_cinematic import run_dashboard, update_dashboard_state, update_rl_metrics, emit_trade
import threading
import asyncio

# Start dashboard server in background thread
dashboard_thread = threading.Thread(
    target=run_dashboard,
    kwargs={'port': 5050},
    daemon=True
)
dashboard_thread.start()

# Update dashboard state during trading loop
update_dashboard_state(
    strategy_name="rl",
    total_pnl=1234.56,
    trade_count=87,
    win_count=20,
    positions={
        "btc_condition_id": {
            'side': 'UP',
            'size': 50.0,
            'entry_price': 0.620
        }
    },
    markets={
        "btc_condition_id": {
            'asset': 'BTC',
            'prob': 0.635,
            'time_left': 8.5,
            'velocity': 0.015
        }
    }
)

# Emit RL training metrics
update_rl_metrics({
    'policy_loss': 0.0234,
    'value_loss': 0.1567,
    'entropy': 0.892,
    'approx_kl': 0.0045,
    'explained_variance': 0.78
})

# Emit trade eventsemit_trade("BUY_MD", "BTC", size=50.0, pnl=12.50)

# Dashboard accessible at http://localhost:5050
```

--------------------------------

### RL Agent PPO Training and Inference (Python)

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Initializes and utilizes a Proximal Policy Optimization (PPO) reinforcement learning agent, incorporating temporal encoding for capturing market momentum. This snippet outlines the setup for training the agent and subsequently using it for making trading decisions based on processed market features. It depends on the MLX framework for efficient on-device computations.

```python
from strategies.rl_mlx import RLStrategy
from strategies.base import MarketState, Action

# Placeholder for agent creation, training, and inference logic
# agent = RLStrategy()
# agent.train(...)
# action = agent.predict(features)
```

--------------------------------

### Initialize and Train RL Agent for Trading

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Initializes a Reinforcement Learning agent with a temporal architecture, sets it to training mode, simulates a trading loop for experience collection, and updates the agent's policy. It also includes saving the trained model and switching to inference mode.

```python
agent = RLStrategy(
    input_dim=18,
    hidden_size=64,  # Actor hidden size
    critic_hidden_size=96,  # Larger critic
    history_len=5,  # Process last 5 states
    temporal_dim=32,  # Temporal encoder output
    lr_actor=1e-4,
    lr_critic=3e-4,
    gamma=0.95,  # Short horizon for 15-min markets
    buffer_size=256,  # Fast adaptation
    batch_size=64,
    n_epochs=10
)

# Training modeagent.train()

# Trading loop with experience collection
state = MarketState(asset="BTC", prob=0.60, time_remaining=0.9)
action = agent.act(state)  # Returns Action.HOLD, Action.BUY, or Action.SELL

# Execute trade and get reward
next_state = MarketState(asset="BTC", prob=0.62, time_remaining=0.85)
reward = 15.50  # Realized PnL from closed position
done = False  # Market not expired

# Store experience
agent.store(state, action, reward, next_state, done)

# Update when buffer is full (256 experiences)
if len(agent.experiences) >= agent.buffer_size:
    metrics = agent.update()
    print(f"Policy Loss: {metrics['policy_loss']:.4f}")
    print(f"Value Loss: {metrics['value_loss']:.4f}")
    print(f"Entropy: {metrics['entropy']:.3f}")
    print(f"Approx KL: {metrics['approx_kl']:.4f}")
    print(f"Explained Variance: {metrics['explained_variance']:.2f}")

# Save trained model
agent.save("rl_model")

# Inference mode
agent.eval()
agent.load("rl_model")
action = agent.act(state)  # Greedy policy
```

--------------------------------

### Execute Paper Trading Engine with Strategy Selection

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Runs the complete trading system, allowing for strategy selection (RL, momentum, mean_revert, random), market data streaming, and position management. It supports both training and inference modes for RL strategies and includes graceful shutdown procedures.

```python
import asyncio
from run import TradingEngine
from strategies import create_strategy

# Create strategy (rl, momentum, mean_revert, random)
strategy = create_strategy("rl")

# Load trained model if using RL
if hasattr(strategy, 'load'):
    strategy.load("rl_model")
    strategy.eval()

# Initialize trading engine
engine = TradingEngine(strategy, trade_size=50.0)

# Run async trading loop
try:
    await engine.run()
except KeyboardInterrupt:
    print("Shutting down...")
    engine.close_all_positions()
    engine.print_final_stats()

    # Save RL model if training
    if hasattr(strategy, 'save') and strategy.training:
        strategy.save("rl_model")

# Example CLI usage:
# python run.py rl --train --size 50    # Train RL with $50 positions
# python run.py rl --load rl_model --size 100  # Inference with $100 positions
# python run.py momentum --size 25      # Run momentum baseline
```

--------------------------------

### Training Logger for Performance Analysis

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Logs individual trades and Reinforcement Learning training updates to CSV files for post-session performance analysis. It initializes a logger using `get_logger` from `helpers.training_logger` and provides methods to log trade details and PPO metrics.

```python
from helpers.training_logger import get_logger

# Initialize logger (creates timestamped CSV files)
logger = get_logger()

# Log completed trade
logger.log_trade(
    asset="BTC",
    action="BUY",  # BUY or SELL
    side="UP",  # UP or DOWN
    entry_price=0.620,
    exit_price=0.645,
    size=50.0,
    pnl=12.50,
    duration_sec=456.0,
    time_remaining=0.75,  # At entry
    prob_at_entry=0.620,
    prob_at_exit=0.645,
    binance_change=0.0123,  # Spot price change since market open
    condition_id="0x1234..."
)

# Log PPO update
logger.log_update(
    metrics={
        'policy_loss': 0.0234,
        'value_loss': 0.1567,
        'entropy': 0.892,
        'approx_kl': 0.0045,
        'explained_variance': 0.78
    },
    buffer_rewards=[0.5, -0.3, 1.2, 0.0, -0.8],  # Rewards from buffer
    cumulative_pnl=1234.56,
    cumulative_trades=87,
    cumulative_wins=20
)
```

--------------------------------

### Fetch Binance Futures Market State (Python)

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Retrieves comprehensive real-time and snapshot data for Binance futures markets. It includes funding rates, mark price, open interest, various time-frame returns, cumulative volume delta (CVD), and trade flow imbalance. This data is essential for informing trading decisions by capturing the dynamics of the futures market.

```python
import asyncio
from helpers.binance_futures import get_futures_snapshot, FuturesStreamer

# One-shot snapshot
state = get_futures_snapshot("BTC")
print(f"Funding Rate: {state.funding_rate:.4%}")
print(f"Mark Price: ${state.mark_price:,.2f}")
print(f"Open Interest: {state.open_interest:,.0f} contracts")
print(f"1m Return: {state.returns_1m:.3%}")
print(f"5m Return: {state.returns_5m:.3%}")
print(f"10m Return: {state.returns_10m:.3%}")
print(f"CVD (Cumulative Volume Delta): {state.cvd:,.0f}")
print(f"Trade Flow Imbalance: {state.trade_flow_imbalance:.2f}")

# Real-time streaming (for production trading)
streamer = FuturesStreamer(assets=["BTC", "ETH", "SOL", "XRP"])
asyncio.create_task(streamer.stream())

# Access live state during trading loop
btc_state = streamer.get_state("BTC")
if btc_state:
    print(f"Real-time CVD: {btc_state.cvd:,.0f}")
    print(f"Trade Intensity: {btc_state.trade_intensity:.2f} trades/sec")
    print(f"Large Trade Flag: {btc_state.large_trade_flag}")
```

--------------------------------

### Define Trading Actions with Confidence Sizing

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Creates trading actions (HOLD, BUY, SELL) with dynamic position sizing based on the extremeness of probability. This allows for more aggressive sizing at high-confidence predictions and conservative sizing at neutral probabilities. The `Action` class from `strategies.base` is used.

```python
from strategies.base import Action

# Basic actions
hold = Action.HOLD
buy_up = Action.BUY    # Long UP token
sell_up = Action.SELL  # Long DOWN token

# Check action properties
print(f"Is Buy: {buy_up.is_buy}")
print(f"Is Sell: {sell_up.is_sell}")
print(f"Base Size: {buy_up.size_multiplier}")

# Dynamic sizing based on probability
prob_extreme = 0.15  # Very low, high edge
size_extreme = buy_up.get_confidence_size(prob_extreme)
print(f"Size at prob=0.15: {size_extreme:.2f}")

prob_neutral = 0.50  # No edge
size_neutral = buy_up.get_confidence_size(prob_neutral)
print(f"Size at prob=0.50: {size_neutral:.2f}")

prob_moderate = 0.35
size_moderate = buy_up.get_confidence_size(prob_moderate)
print(f"Size at prob=0.35: {size_moderate:.2f}")
```

--------------------------------

### Stream Live Orderbook Data via WebSocket

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Connects to Polymarket CLOB WebSocket for real-time orderbook updates. It allows subscribing to specific market tokens, streaming data asynchronously, and accessing live orderbook information such as mid-price, best bid/ask, and orderbook imbalance.

```python
from helpers.orderbook_wss import OrderbookStreamer
import asyncio

# Initialize streamer
ob_streamer = OrderbookStreamer()

# Subscribe to market tokens
condition_id = "0x1234567890abcdef..."
token_up = "0xabc..."
token_down = "0xdef..."
ob_streamer.subscribe(condition_id, token_up, token_down)

# Start streaming in background
asyncio.create_task(ob_streamer.stream())

# Access live orderbook during trading
orderbook = ob_streamer.get_orderbook(condition_id, "UP")
if orderbook:
    print(f"Mid Price: {orderbook.mid_price:.3f}")
    print(f"Best Bid: {orderbook.best_bid:.3f}")
    print(f"Best Ask: {orderbook.best_ask:.3f}")
    print(f"Spread: {orderbook.spread:.4f}")

    # Top 5 levels
    print("\nBids:")
    for price, size in orderbook.bids[:5]:
        print(f"  {price:.3f} x {size:.2f}")

    print("\nAsks:")
    for price, size in orderbook.asks[:5]:
        print(f"  {price:.3f} x {size:.2f}")

    # Orderbook imbalance
    bid_vol = sum(size for _, size in orderbook.bids[:5])
    ask_vol = sum(size for _, size in orderbook.asks[:5])
    imbalance = (bid_vol - ask_vol) / (bid_vol + ask_vol)
    print(f"\nL5 Imbalance: {imbalance:.3f}")
```

--------------------------------

### Compute Multi-Timeframe Returns from 1-Minute Klines

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Calculates trading returns and realized volatility across various timeframes (e.g., 1m, 5m, 1h) using historical 1-minute klines data. It requires helper functions `fetch_klines` and `compute_multi_tf_returns` from `helpers.binance_futures`.

```python
from helpers.binance_futures import compute_multi_tf_returns, fetch_klines

# Fetch 1-minute klines (65 bars for 1h lookback)
klines = fetch_klines("BTC", interval="1m", limit=65)

# Compute multi-timeframe statistics
returns = compute_multi_tf_returns(klines)

print(f"1-Minute Return: {returns['1m']:.4%}")
print(f"5-Minute Return: {returns['5m']:.4%}")
print(f"10-Minute Return: {returns['10m']:.4%}")
print(f"15-Minute Return: {returns['15m']:.4%}")
print(f"1-Hour Return: {returns['1h']:.4%}")
print(f"Realized Vol (1h): {returns['realized_vol_1h']:.4%}")
```

--------------------------------

### Discover Active Polymarket 15-Minute Markets (Python)

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Fetches currently active 15-minute UP/DOWN binary prediction markets on Polymarket for specified cryptocurrency assets. It iterates through the results, printing market details such as time remaining, token prices, condition ID, and token IDs. This function is crucial for identifying trading opportunities.

```python
from helpers.polymarket_api import get_15m_markets
from datetime import datetime, timezone

# Get all active 15-minute markets
markets = get_15m_markets(assets=["BTC", "ETH", "SOL", "XRP"])

for market in markets:
    mins_left = (market.end_time - datetime.now(timezone.utc)).total_seconds() / 60
    print(f"{market.asset} - {mins_left:.1f} minutes remaining")
    print(f"  UP token price: {market.price_up:.3f}")
    print(f"  DOWN token price: {market.price_down:.3f}")
    print(f"  Condition ID: {market.condition_id}")
    print(f"  Token IDs: UP={market.token_up}, DOWN={market.token_down}")
```

--------------------------------

### Micro-bonus Reward Calculations (Problematic)

Source: https://github.com/humanplane/cross-market-state-fusion/blob/master/TRAINING_JOURNAL.md

These Python snippets illustrate the original reward calculation which included micro-bonuses for trading with momentum and for larger positions. These bonuses, similar in magnitude to actual PnL, led the agent to optimize for collecting bonuses rather than actual profitability, causing entropy collapse.

```python
reward += 0.002 * momentum_aligned  # Bonus for trading with momentum
reward += 0.001 * size_multiplier   # Bonus for larger positions
reward -= 0.001 * wrong_momentum    # Penalty for fighting momentum
```

--------------------------------

### Calculate PnL: Probability-Based vs. Share-Based

Source: https://github.com/humanplane/cross-market-state-fusion/blob/master/TRAINING_JOURNAL.md

Compares two methods for calculating Profit and Loss (PnL). The older method (Phases 1-3) used a simple dollar-based calculation. The newer method (Phase 4) incorporates the number of shares, which is dependent on the entry price, to more accurately reflect market economics and asymmetric payoffs.

```python
# Old (Phases 1-3): probability-based
pnl = (exit_price - entry_price) * dollars

# New (Phase 4): share-based
shares = dollars / entry_price
pnl = (exit_price - entry_price) * shares
```

--------------------------------

### Step Reward Calculation (Pure PnL)

Source: https://github.com/humanplane/cross-market-state-fusion/blob/master/TRAINING_JOURNAL.md

This Python code defines the reward calculation for Phase 2, where reward is only computed upon position close, based solely on realized Profit and Loss (PnL). This approach removes the problematic micro-bonuses and ensures the agent is trained on actual trading outcomes.

```python
# Reward is 0 for all steps EXCEPT position close
def _compute_step_reward(self, cid, state, action, pos):
    return self.pending_rewards.pop(cid, 0.0)

# pending_rewards is set when position closes:
# pnl = (exit_prob - entry_prob) * size
self.pending_rewards[cid] = pnl
```

--------------------------------

### Phase 1: Shaped Rewards Function

Source: https://github.com/humanplane/cross-market-state-fusion/blob/master/TRAINING_JOURNAL.md

Implements a reward function used in Phase 1 of training, providing intermediate feedback. It includes bonuses for unrealized PnL delta and penalties for transaction and spread costs. This approach was later abandoned due to failures.

```python
# Reward given every step (not just on close)
reward = 0.0

# 1. Unrealized PnL delta - scaled DOWN by 0.1
if has_position:
    reward += (current_pnl - prev_pnl) * 0.1

# 2. Transaction cost penalty
if is_trade:
    reward -= 0.002 * size_multiplier

# 3. Spread cost on entry
if opening_position:
    reward -= spread * 0.5
```

--------------------------------

### Calculate Share-Based PnL

Source: https://github.com/humanplane/cross-market-state-fusion/blob/master/TRAINING_JOURNAL.md

Calculates Profit and Loss (PnL) based on shares traded, reflecting the economics of binary markets. This method is used after Phase 4 of the training to better match market mechanics and improve ROI.

```python
shares = dollars / entry_price
pnl = (exit_price - entry_price) * shares
```

--------------------------------

### Reward Normalization Formula

Source: https://github.com/humanplane/cross-market-state-fusion/blob/master/TRAINING_JOURNAL.md

This snippet shows the z-score normalization formula applied to raw PnL rewards before training. This technique helps stabilize training by scaling rewards to have zero mean and unit variance, using a running mean and standard deviation.

```python
norm_reward = (raw_pnl - running_mean) / (running_std + 1e-8)
```

--------------------------------

### Convert Market State to Normalized Features (Python)

Source: https://context7.com/humanplane/cross-market-state-fusion/llms.txt

Transforms detailed market observations into a standardized, normalized 18-dimensional feature vector suitable for machine learning models. This process involves mapping various metrics like price, time remaining, returns, order book imbalances, and trade flow into a consistent range, typically [-1, 1]. This is a critical preprocessing step for the RL agent.

```python
from strategies.base import MarketState
import numpy as np

# Create market state with observations
state = MarketState(
    asset="BTC",
    prob=0.65,  # Current UP token price
    time_remaining=0.8,  # 80% of 15 minutes left
    returns_1m=0.002,  # 0.2% return last minute
    returns_5m=0.008,
    returns_10m=0.015,
    order_book_imbalance_l1=0.3,  # More bids than asks
    order_book_imbalance_l5=0.2,
    trade_flow_imbalance=0.4,  # Buy pressure
    cvd_acceleration=0.1,
    spread=0.02,
    trade_intensity=5.2,
    large_trade_flag=1.0,
    realized_vol_5m=0.012,
    vol_expansion=0.5,
    has_position=True,
    position_side="UP",
    position_pnl=12.50,
    vol_regime=1.0,
    trend_regime=1.0
)

# Convert to normalized features [-1, 1]
features = state.to_features()
# Returns: array of shape (18,) with normalized values
# [returns_1m*50, returns_5m*50, returns_10m*50, ob_imbalance_l1, ob_imbalance_l5,
#  trade_flow, cvd_accel*10, spread_pct*20, trade_intensity/10, large_trade_flag,
#  vol_5m*20, vol_expansion, has_position, position_side, position_pnl/50, time_remaining,
#  vol_regime, trend_regime]
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.