# Complete Trading Workflow — All-Seeing Eye Orchestration

> End-to-end guide from market identification to live trading or signal automation.
> The All-Seeing Eye serves as the central AI orchestrator throughout the entire pipeline.

---

## Overview

Agencio Predict provides a complete, AI-guided workflow that takes users from raw market data to actionable trading decisions. The **All-Seeing Eye** orchestrates each stage, providing intelligence, validation, and safety guardrails at every step.

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           ALL-SEEING EYE ORCHESTRATION                           │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│   │   STAGE 1    │    │   STAGE 2    │    │   STAGE 3    │    │   STAGE 4    │  │
│   │  Market ID   │───▶│ Opportunities│───▶│  Algorithms  │───▶│   Testing    │  │
│   └──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘  │
│                                                                       │          │
│                                                                       ▼          │
│   ┌──────────────────────────────────────────────────────────────────────────┐  │
│   │                           STAGE 5: Paper Trading                          │  │
│   │                     (Graduation Track — 30 days minimum)                  │  │
│   └──────────────────────────────────────────────────────────────────────────┘  │
│                                           │                                      │
│                          ┌────────────────┴────────────────┐                    │
│                          ▼                                 ▼                    │
│               ┌──────────────────┐              ┌──────────────────┐            │
│               │  STAGE 6A: Live  │              │ STAGE 6B: Signals│            │
│               │ Broker Trading   │              │    Automation    │            │
│               └──────────────────┘              └──────────────────┘            │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘
```

---

## Stage 1: Market Identification

The All-Seeing Eye continuously aggregates data from 28+ sources across multiple categories.

### Data Sources

| Category | Sources | Update Frequency |
|----------|---------|------------------|
| **Price Data** | Yahoo Finance, CoinGecko, Finnhub, Polygon.io, Binance | Real-time / 1 min |
| **Derivatives** | VIX, Fear & Greed, Binance Funding, Deribit IV, Coinglass OI | 5 min |
| **Prediction Markets** | Polymarket, Kalshi, Metaculus, PredictIt | 15 min |
| **Social Sentiment** | Reddit, Twitter/X, Truth Social, Bluesky, Discord, Telegram, RSS | 15 min |
| **Macro/Economic** | FRED (Treasury, TIPS, SOFR), World Bank, BLS | Daily |
| **News** | NewsAPI, Finnhub News, GitHub | 15 min |

### Key Capabilities

- **Black Swan Detection**: Anomaly detection across all data streams
- **Correlation Matrix**: Real-time cross-asset correlation tracking
- **Human vs Bot Divergence**: Distinguishes organic moves from algorithmic activity

### API Endpoints

```
GET  /api/predict/v1/all-seeing-eye/data          # Aggregated market data
GET  /api/predict/v1/all-seeing-eye/status        # System health + active sources
GET  /api/predict/v1/overlays/{category}          # 188+ overlay series
GET  /api/predict/v1/derivatives/*                # VIX, funding, OI, liquidations
GET  /api/predict/v1/social/sentiment             # Multi-platform sentiment
```

### SSE Stream

```
GET  /api/predict/v1/sse/all-seeing-eye/stream    # Real-time data updates
```

---

## Stage 2: Opportunity Discovery

The All-Seeing Eye analyzes aggregated data to generate actionable insights.

### Insight Types

| Type | Description | Confidence Threshold |
|------|-------------|---------------------|
| **Ensemble** | Multi-source convergence on a prediction | ≥ 70% |
| **Correlation** | Unusual correlation changes between assets | ≥ 65% |
| **Anomaly** | Statistical outliers in price/volume/sentiment | ≥ 60% |
| **Black Swan** | Rare, high-impact event detection | ≥ 80% |

### Evidence Structure

Every insight includes a full evidence trail:

```json
{
  "insightType": "ensemble",
  "prediction": "BTC likely to test $72,000 resistance",
  "confidence": 0.78,
  "evidence": {
    "WHAT": "Bitcoin shows strong momentum with funding rates normalizing",
    "WHY": [
      "Funding rates dropped from 0.08% to 0.02% (bullish reset)",
      "Social sentiment shifted positive across 4/7 platforms",
      "VIX below 15 indicates risk-on environment"
    ],
    "HOW": "Ensemble of 12 signals with 78% convergence score"
  },
  "contributingSignals": [
    { "source": "binance_funding", "weight": 0.25, "value": 0.02 },
    { "source": "social_sentiment", "weight": 0.20, "value": 0.65 },
    { "source": "vix_regime", "weight": 0.15, "value": "low" }
  ]
}
```

### API Endpoints

```
GET  /api/predict/v1/all-seeing-eye/insights      # AI-generated insights
GET  /api/predict/v1/all-seeing-eye/warnings      # Black swan alerts
GET  /api/predict/v1/insights/human-automation/batch  # Human vs bot signals
GET  /api/predict/v1/platform-predictions         # Platform predictions feed
```

### Dual-Layer Validation

All insights pass through dual-layer validation before surfacing:
1. **Statistical Layer**: Confidence scoring, historical backtesting
2. **LLM Layer**: Reasoning validation, contradiction detection

---

## Stage 3: Algorithm Selection/Creation

Users can create trading algorithms or choose from pre-built templates.

### Option A: Strategy Templates (6 Pre-built)

| Template | Strategy Type | Risk Profile | Typical Sharpe |
|----------|--------------|--------------|----------------|
| **Momentum Rider** | RSI + Volume breakout | Aggressive | 1.2 - 1.8 |
| **Mean Reversion Pro** | Bollinger Band bounce | Moderate | 0.8 - 1.4 |
| **Trend Follower** | EMA crossover + ADX | Moderate | 1.0 - 1.6 |
| **Volatility Harvester** | VIX-based sizing | Aggressive | 1.5 - 2.2 |
| **Crypto Funding Arbitrage** | Funding rate extremes | Conservative | 0.6 - 1.0 |
| **Multi-Asset Diversifier** | Cross-asset correlation | Conservative | 0.7 - 1.2 |

```
GET  /api/predict/v1/algorithms/templates              # List all templates
GET  /api/predict/v1/algorithms/templates/{id}         # Template details
POST /api/predict/v1/algorithms/templates/{id}         # Create from template
```

### Option B: DSL Builder (40 Primitives)

Natural language to DSL translation:

```
POST /api/predict/v1/algorithms/translate
Body: { "prompt": "Buy NVDA when RSI drops below 30 and sentiment is positive" }

Response: {
  "dslYaml": "strategy: nvda_oversold_sentiment\nuniverse: [NVDA]\nsignals:\n  ...",
  "explanation": "This strategy buys NVDA when technically oversold with positive sentiment..."
}
```

### Option C: AI Suggestions

The All-Seeing Eye analyzes existing algorithm performance and suggests optimizations:

```
POST /api/predict/v1/algorithms/{id}/ai-suggestions    # Generate suggestions
POST /api/predict/v1/algorithms/ai-suggestions/{id}    # Apply suggestion
```

Suggestion types:
- **Parameter Optimization**: Adjust RSI period, stop-loss levels
- **Risk Adjustment**: Position sizing, correlation limits
- **New Signal Integration**: Add complementary indicators

### API Endpoints

```
GET  /api/predict/v1/algorithms                        # List user algorithms
POST /api/predict/v1/algorithms                        # Create new algorithm
GET  /api/predict/v1/algorithms/primitives             # DSL primitive reference
```

---

## Stage 4: Testing & Validation

Three levels of backtesting ensure strategy robustness before deployment.

### Standard Backtest

Historical performance with 12 metrics:

| Metric | Description |
|--------|-------------|
| Sharpe Ratio | Risk-adjusted returns |
| Sortino Ratio | Downside risk-adjusted |
| Calmar Ratio | Return / Max Drawdown |
| Max Drawdown | Largest peak-to-trough |
| Win Rate | Percentage of winning trades |
| Profit Factor | Gross profit / Gross loss |
| VaR (95%) | Value at Risk |
| CVaR (95%) | Conditional VaR |
| Alpha | Excess return vs benchmark |
| Beta | Market correlation |
| Skewness | Return distribution shape |
| Kurtosis | Tail risk measure |

```
POST /api/predict/v1/algorithms/{id}/backtest
Body: { "startDate": "2024-01-01", "endDate": "2024-12-31" }
```

### Walk-Forward Analysis

Detects overfitting by comparing in-sample vs out-of-sample performance:

```
POST /api/predict/v1/algorithms/{id}/walk-forward
Body: { "windowCount": 5, "inSampleRatio": 0.7 }

Response: {
  "windows": [...],
  "summary": {
    "avgIsSharpe": 1.45,
    "avgOosSharpe": 1.12,
    "avgSharpeDegradation": 22.8,
    "overfitPercentage": 20
  },
  "robustnessScore": 78,
  "recommendation": "Strategy shows moderate robustness. Consider reducing complexity."
}
```

### Monte Carlo Simulation

1000+ path simulation for statistical confidence:

```
POST /api/predict/v1/algorithms/{id}/monte-carlo
Body: { "simulationCount": 1000, "method": "bootstrap" }

Response: {
  "percentiles": {
    "p5":  { "totalReturnPct": -8.2, "maxDrawdownPct": 18.5 },
    "p50": { "totalReturnPct": 24.5, "maxDrawdownPct": 9.2 },
    "p95": { "totalReturnPct": 58.3, "maxDrawdownPct": 4.1 }
  },
  "riskMetrics": {
    "varAtConfidence": -12.5,
    "cvarAtConfidence": -18.2,
    "probabilityOfLoss": 0.15,
    "probabilityOfRuin": 0.02
  },
  "robustnessScore": 82
}
```

### Risk Controls

Configure safety limits before deployment:

```
PUT /api/predict/v1/algorithms/{id}/risk-controls
Body: {
  "maxPositionSizePct": 5.0,      // Max 5% per position
  "maxDailyLossPct": 3.0,         // Stop trading after 3% daily loss
  "maxDrawdownPct": 10.0,         // Pause at 10% drawdown
  "maxOpenPositions": 10,         // Max concurrent positions
  "stopLossPct": 2.0,             // Per-trade stop loss
  "pauseOnBreach": true           // Auto-pause on limit breach
}
```

---

## Stage 5: Paper Trading (Graduation Track)

Algorithms must prove themselves in paper trading before going live.

### Graduation Requirements

| Requirement | Default | Configurable |
|-------------|---------|--------------|
| Minimum Paper Days | 30 | Yes |
| Minimum Trades | 50 | Yes |
| Minimum Sharpe | 1.0 | Yes |
| Maximum Drawdown | 15% | Yes |

### Live Metrics Tracking

```
GET  /api/predict/v1/algorithms/{id}/live-metrics
Response: {
  "current": {
    "equity": 105420.50,
    "dailyPnl": 1250.00,
    "totalPnl": 5420.50,
    "sharpeRatio": 1.35,
    "maxDrawdown": 0.08,
    "winRate": 0.62
  },
  "history": [...],
  "breachAlerts": []
}
```

### Multi-Algorithm Dashboard

```
GET  /api/predict/v1/algorithms/live-dashboard
Response: {
  "algorithms": [...],
  "aggregated": {
    "totalEquity": 425000,
    "totalPnl": 18500,
    "avgSharpe": 1.28
  }
}
```

### Graduation Progress

```
GET  /api/predict/v1/algorithms/{id}/graduation
Response: {
  "requirements": { "minPaperDays": 30, "minTrades": 50, ... },
  "progress": {
    "daysProgress": 80,
    "tradesProgress": 100,
    "sharpeProgress": 100,
    "drawdownProgress": 100,
    "overallProgress": 95
  },
  "isEligible": true,
  "riskAcknowledged": false
}
```

### Leaderboard (Optional)

Opt-in to compete on the algorithm leaderboard:

```
POST /api/predict/v1/algorithms/{id}/leaderboard      # Opt in
DELETE /api/predict/v1/algorithms/{id}/leaderboard   # Opt out
GET  /api/predict/v1/algorithms/leaderboard           # View rankings
```

Composite Score: 40% Sharpe + 25% Return + 20% Low Drawdown + 10% Win Rate + 5% Consistency

---

## Stage 6A: Go Live (Broker Integration)

### Prerequisites

1. ✅ Paper trading requirements met
2. ✅ Risk acknowledgment signed (MFA-gated)
3. ✅ Broker credentials configured
4. ✅ Platform kill switch OFF

### Risk Acknowledgment

```
POST /api/predict/v1/algorithms/{id}/graduation/acknowledge
Headers: { "X-MFA-Token": "123456" }

Response: {
  "acknowledged": true,
  "acknowledgedAt": "2026-04-20T10:30:00Z",
  "ipAddress": "192.168.1.1"
}
```

### Graduate to Live

```
PUT /api/predict/v1/algorithms/{id}/graduation
Response: {
  "graduatedAt": "2026-04-20T10:35:00Z",
  "liveStartDate": "2026-04-20",
  "status": "live"
}
```

### Broker Configuration

```
POST /api/predict/v1/user/brokers/test               # Test credentials
POST /api/predict/v1/user/brokers/{brokerId}         # Configure broker
PATCH /api/predict/v1/user/brokers/{brokerId}/mode   # Switch paper↔live
```

### Supported Brokers

| Broker | Status | Asset Classes |
|--------|--------|---------------|
| Alpaca | ✅ Live | Stocks, ETFs |
| Interactive Brokers | 🚧 Planned | Stocks, Options, Futures, Forex |
| Binance | 🚧 Planned | Crypto |

### Safety Gates (4-Gate Preflight)

Before any live order:
1. **User Mode Check**: User's execution mode must be `live`
2. **Platform Kill Switch**: Admin kill switch must be OFF
3. **MFA Acknowledgment**: User must have acknowledged risks
4. **Adapter Ping**: Broker connection must be healthy

---

## Stage 6B: Signal Automation (Non-Broker Path)

For users who want trading signals without direct broker integration.

### Webhook Configuration

```
POST /api/predict/v1/user/webhooks
Body: {
  "name": "TradingView Alerts",
  "url": "https://your-endpoint.com/webhook",
  "events": ["trade_signal", "position_update", "risk_alert"],
  "secret": "your-hmac-secret"
}
```

### Trigger Actions

```
POST /api/predict/v1/triggers
Body: {
  "name": "BTC Momentum Signal",
  "conditions": [
    { "type": "indicator", "indicator": "rsi", "operator": "<", "value": 30 },
    { "type": "sentiment", "source": "social", "operator": ">", "value": 0.6 }
  ],
  "actions": [
    { "type": "webhook", "webhookId": "..." },
    { "type": "slack", "channel": "#trading-signals" },
    { "type": "email", "template": "trade_alert" }
  ]
}
```

### Available Actions

| Action | Description | Configuration |
|--------|-------------|---------------|
| **Webhook** | HTTP POST to custom endpoint | URL, secret, headers |
| **Slack** | Message to Slack channel | Webhook URL |
| **Discord** | Message to Discord channel | Webhook URL |
| **Teams** | Message to MS Teams channel | Webhook URL |
| **Email** | Email with trade details | Template, recipients |

### Public API (API-Key Authenticated)

For external platform integration:

```
GET  /api/public/v1/signals                          # Latest trade signals
GET  /api/public/v1/predictions                      # AI predictions
GET  /api/public/v1/algorithms/{id}/status           # Algorithm status
```

Header: `X-API-Key: your-api-key`

---

## All-Seeing Eye: Central Orchestration

The All-Seeing Eye monitors and orchestrates the entire workflow:

### Continuous Monitoring

- **Data Aggregation**: 28+ sources every 5-15 minutes
- **Insight Generation**: AI analysis on new data
- **Black Swan Detection**: Anomaly monitoring 24/7
- **Algorithm Health**: Performance tracking for all running algorithms

### Auto-Pilot Capabilities

| Feature | Description | Confidence Threshold |
|---------|-------------|---------------------|
| **Insight Suggestions** | Surface opportunities to user | ≥ 70% |
| **Algorithm Recommendations** | Suggest templates based on market | ≥ 75% |
| **Risk Alerts** | Warn on approaching limits | Any breach |
| **Auto-Pause** | Pause algorithm on risk breach | Configurable |

### Safety Guardrails

```typescript
const GUARDRAILS = {
  dailyActionLimit: 50,           // Max actions per day
  positionSizeLimit: 0.05,        // 5% max per position
  maxConcentration: 0.20,         // 20% max in one asset
  minConfidenceForTrade: 0.70,    // 70% min for trade signals
  minConfidenceForAutoExecute: 0.85  // 85% for autonomous execution
};
```

### SSE Streams

```
GET /api/predict/v1/sse/all-seeing-eye/stream        # Insights, warnings, status
GET /api/predict/v1/sse/algorithms/{id}/live         # Live algorithm metrics
GET /api/predict/v1/sse/market/prices                # Real-time prices
```

---

## Quick Reference: API by Stage

| Stage | Key Endpoints |
|-------|--------------|
| **1. Market ID** | `GET /all-seeing-eye/data`, `GET /overlays/*`, `GET /derivatives/*` |
| **2. Opportunities** | `GET /all-seeing-eye/insights`, `GET /insights/human-automation/batch` |
| **3. Algorithms** | `GET /algorithms/templates`, `POST /algorithms/translate`, `POST /algorithms` |
| **4. Testing** | `POST /algorithms/:id/backtest`, `POST /algorithms/:id/walk-forward`, `POST /algorithms/:id/monte-carlo` |
| **5. Paper Trading** | `POST /algorithms/:id/runs`, `GET /algorithms/:id/live-metrics`, `GET /algorithms/:id/graduation` |
| **6a. Go Live** | `POST /algorithms/:id/graduation/acknowledge`, `PUT /algorithms/:id/graduation` |
| **6b. Signals** | `POST /user/webhooks`, `POST /triggers`, `GET /api/public/v1/signals` |

---

## Related Documentation

- `docs/12-algorithm-builder.md` — DSL primitives and backtest engine
- `docs/32-algorithm-enhancements.md` — Live metrics, templates, leaderboard
- `docs/24-api-routes.md` — Complete API inventory (Section 0 has workflow overview)
- `docs/13-broker-integration.md` — Broker adapter architecture
- `CLAUDE.md` — Project-wide context

---

*Last updated: 2026-04-20*