Blame for docs/integrations/COINAPI_INTEGRATION.md

# 🌍⚡ CoinAPI Integration - Cross-Exchange Anomaly Detection

**Status**: ✅ **INTEGRATED** | November 30, 2025  
**Author**: Gary Leckey & GitHub Copilot

---

## 🎯 Overview

The CoinAPI integration adds **cross-exchange anomaly detection** to our trading system, enabling us to:

1. **Detect Market Manipulation** - Price discrepancies across exchanges
2. **Identify Wash Trading** - Circular trades inflating volume
3. **Spot Orderbook Spoofing** - Fake liquidity manipulation
4. **Find Arbitrage Opportunities** - Real price differences to exploit
5. **Refine Algorithms Automatically** - Adapt thresholds based on anomalies

### The Core Insight

> **"The Truth is in the Anomalies"**

When exchange data disagrees, the discrepancy reveals the *real story*:
- **Price manipulation** → Avoid the asset temporarily
- **Wash trading** → Blacklist completely
- **Orderbook spoofing** → Require higher confidence
- **Cross-exchange spreads** → Arbitrage opportunity!

---

## 🏗️ Architecture

```

┌─────────────────────────────────────────────────────────────────┐

│                     COINAPI.IO (300+ Exchanges)                 │

│  Professional aggregated data: OHLCV, quotes, orderbooks        │

└────────────────────────────┬────────────────────────────────────┘

                             ↓

┌─────────────────────────────────────────────────────────────────┐

│                    CoinAPIClient                                 │

│  - Rate-limited REST API calls                                   │

│  - Caching for efficiency                                        │

│  - Multi-exchange quote fetching                                 │

└────────────────────────────┬────────────────────────────────────┘

                             ↓

┌─────────────────────────────────────────────────────────────────┐

│                   AnomalyDetector                                │

│  Detects 9 types of anomalies:                                   │

│  • Price Manipulation (cross-exchange spread > 2%)               │

│  • Wash Trading (repeated identical prices)                      │

│  • Orderbook Spoofing (70/30 bid/ask imbalance)                 │

│  • Volume Inflation (3x normal volume)                           │

│  • Latency Arbitrage (>500ms delays)                             │

│  • Frontrunning (100ms windows)                                  │

│  • Liquidity Drain (sudden orderbook collapse)                   │

│  • Exchange Outage (missing data)                                │

│  • Cross-Exchange Spread (arbitrage opportunities)               │

└────────────────────────────┬────────────────────────────────────┘

                             ↓

┌─────────────────────────────────────────────────────────────────┐

│              Algorithm Refinement Engine                         │

│  Applies automatic adjustments:                                  │

│  • Blacklists symbols (wash trading)                             │

│  • Adjusts coherence thresholds (spoofing)                       │

│  • Uses multi-exchange mean prices (arbitrage)                   │

│  • Logs all refinements for analysis                             │

└────────────────────────────┬────────────────────────────────────┘

                             ↓

┌─────────────────────────────────────────────────────────────────┐

│                  AurisEngine Integration                         │

│  • scan_for_anomalies() - Periodic scanning                      │

│  • is_symbol_blacklisted() - Filter opportunities                │

│  • get_coherence_adjustment() - Dynamic thresholds               │

│  • _apply_anomaly_refinement() - Auto-adjust rules               │

└────────────────────────────┬────────────────────────────────────┘

                             ↓

┌─────────────────────────────────────────────────────────────────┐

│              find_opportunities() Pipeline                       │

│  1. Scan for anomalies every 5 minutes                           │

│  2. Filter blacklisted symbols                                   │

│  3. Apply coherence adjustments                                  │

│  4. Continue with HNC + Probability analysis                     │

└─────────────────────────────────────────────────────────────────┘

```

---

## 🔧 Configuration

### Environment Variables

```bash

# Required for live anomaly detection

export COINAPI_KEY=your-api-key-here

export ENABLE_COINAPI=1

```

### CONFIG Parameters

```python

CONFIG = {

    # CoinAPI Anomaly Detection

    'ENABLE_COINAPI': False,              # Requires API key

    'COINAPI_SCAN_INTERVAL': 300,         # Scan every 5 minutes

    'COINAPI_MIN_SEVERITY': 0.40,         # Act on anomalies ≥40% severity

    'COINAPI_BLACKLIST_DURATION': 3600,   # Blacklist for 1 hour

    'COINAPI_ADJUST_COHERENCE': True,     # Auto-adjust thresholds

    'COINAPI_PRICE_SOURCE': 'multi_exchange',  # Use aggregated prices

}

```

---

## 📊 Anomaly Types & Refinements

| Anomaly Type | Detection Method | Automatic Refinement |
|--------------|------------------|----------------------|
| 💰 **Price Manipulation** | Price >2% from cross-exchange mean | Increase coherence threshold +0.1<br>Reduce position size ×0.5 |
| 🔄 **Wash Trading** | >15% trades at identical prices | **Blacklist for 1 hour**<br>Position size ×0.0 |
| 📊 **Orderbook Spoofing** | Bid/ask ratio >70/30 | Delay entry +60s<br>Reduce position size ×0.7 |
| 🌐 **Cross-Exchange Spread** | >2% arbitrage opportunity | Use multi-exchange mean price<br>**Increase position size ×1.2** |
| ⚡ **Latency Arbitrage** | >500ms delays | Compensate for latency<br>Reduce position size ×0.8 |
| 📈 **Volume Inflation** | Volume >3× normal | Require higher volume confirmation |
| 🎯 **Frontrunning** | Suspicious <100ms patterns | Delay execution slightly |
| 💧 **Liquidity Drain** | Orderbook collapse | Avoid until liquidity returns |
| 🚨 **Exchange Outage** | Missing data feeds | Skip exchange temporarily |

---

## 🚀 Usage

### Basic Integration (Disabled by Default)

```python

from aureon_unified_ecosystem import AureonKrakenEcosystem



# Without CoinAPI (default)

eco = AureonKrakenEcosystem(initial_balance=200.0, dry_run=True)

# Anomaly detection is disabled but methods are available

```

### With CoinAPI Key

```python

import os

os.environ['COINAPI_KEY'] = 'your-key-here'

os.environ['ENABLE_COINAPI'] = '1'



from aureon_unified_ecosystem import AureonKrakenEcosystem



eco = AureonKrakenEcosystem(initial_balance=200.0, dry_run=True)

# CoinAPI anomaly detection is now ACTIVE

```

### Manual Anomaly Scanning

```python

# Scan specific symbols for anomalies

symbols = ['BTC/USD', 'ETH/USD', 'BNB/USD']

anomalies = eco.auris.scan_for_anomalies(symbols)



for anom in anomalies:

    print(f"Detected: {anom['type']}")

    print(f"Severity: {anom['severity']:.0%}")

    print(f"Recommendation: {anom['recommendation']}")

```

### Check Blacklist Status

```python

# Check if symbol is blacklisted

if eco.auris.is_symbol_blacklisted('BTC/USD'):

    print("BTC/USD is blacklisted due to anomaly")



# Get coherence adjustment

adjustment = eco.auris.get_coherence_adjustment('ETH/USD')

print(f"ETH/USD coherence threshold: ×{adjustment:.2f}")

```

---

## 📈 Integration with HNC + Probability Matrix

The CoinAPI layer works seamlessly with existing systems:

```

1. CoinAPI Anomaly Detection

   ↓ (Filters & Adjusts)

2. Opportunity Filtering

   ↓ (Blacklist check)

3. HNC Frequency Analysis

   ↓ (Harmonic bonus/penalty)

4. Probability Matrix

   ↓ (2-hour forecast)

5. Final Score & Position Sizing

   ↓

6. Trade Execution

```

### Example Flow

```python

# Symbol goes through complete pipeline:



# 1. CoinAPI detects orderbook spoofing on XYZ/USD

#    → Coherence threshold increased to 0.75 (from 0.65)



# 2. Opportunity filtering

#    → XYZ/USD requires 0.75 coherence instead of 0.65



# 3. HNC analysis shows 528Hz harmonic

#    → +15 score bonus, ×1.15 position size



# 4. Probability matrix shows 88% probability

#    → +20 score bonus



# 5. Final score: 145

#    → Passes thresholds despite higher coherence requirement

#    → Position opened with adjusted size

```

---

## 🧪 Testing

### Run Comprehensive Test Suite

```bash

python test_coinapi_integration.py

```

Tests include:
- ✅ Blacklist functionality
- ✅ Coherence adjustments
- ✅ Anomaly refinement logic
- ✅ Opportunity filtering
- ✅ Full system integration

### Standalone CoinAPI Demo

```bash

python coinapi_anomaly_detector.py

```

Demonstrates:
- Cross-exchange price analysis
- Anomaly detection with simulated data
- Algorithm refinement recommendations

---

## 💰 CoinAPI Free Tier

| Feature | Limit |
|---------|-------|
| **Requests/Day** | 100 |
| **Exchanges** | 300+ |
| **Data Types** | OHLCV, Quotes, Orderbooks, Trades |
| **Historical** | Limited |
| **WebSocket** | No (REST only) |

### Optimization Strategy

With 100 requests/day and 5-minute scans:
- **288 potential scans/day** (1 request per scan)
- **Scan 3-5 symbols per scan** (15-25 symbols covered)
- **Rotate through top opportunities** (not all symbols)
- **Cache results aggressively** (minimize duplicate calls)

---

## 📊 Real-World Example

### Detected Anomaly Report

```

╔══════════════════════════════════════════════════════════════════════════╗

║  🌍⚡ COINAPI ANOMALY REPORT: BTC/USD                                   ║

╠══════════════════════════════════════════════════════════════════════════╣

║  Exchanges Analyzed: 5                                                   ║

║  Mean Price: $69420.50                                                   ║

║  Price StdDev: $350.25                                                   ║

╠══════════════════════════════════════════════════════════════════════════╣

║  DETECTED ANOMALIES:                                                     ║

╠══════════════════════════════════════════════════════════════════════════╣

║  1. 💰 Price Manipulation                                                ║

║     Severity: ███████░░░ 75%                                             ║

║     Price 4.2% away from cross-exchange mean                             ║

║     → AVOID                                                              ║

╠══════════════════════════════════════════════════════════════════════════╣

║  2. 🌐 Cross-Exchange Spread                                             ║

║     Severity: ████░░░░░░ 45%                                             ║

║     2.8% arbitrage spread between exchanges                              ║

║     → ARBITRAGE OPPORTUNITY                                              ║

╠══════════════════════════════════════════════════════════════════════════╣

║  ALGORITHM REFINEMENTS:                                                  ║

╠══════════════════════════════════════════════════════════════════════════╣

║  1. Price manipulation detected - require higher confidence              ║

║     • coherence_threshold: +0.1                                          ║

║     • position_size: ×0.5                                                ║

╠══════════════════════════════════════════════════════════════════════════╣

║  2. Arbitrage opportunity - use aggregated price                         ║

║     • price_source: multi_exchange_mean                                  ║

║     • position_size: ×1.2                                                ║

╚══════════════════════════════════════════════════════════════════════════╝

```

---

## 🎯 Key Benefits

### 1. **Data Quality Validation**
- Cross-validates exchange data
- Detects feed manipulation
- Uses professional-grade aggregated data

### 2. **Adaptive Algorithm**
- Automatically adjusts to market conditions
- Learns from anomalies
- Refines thresholds in real-time

### 3. **Risk Reduction**
- Avoids manipulated markets
- Identifies wash trading
- Detects spoofed liquidity

### 4. **Opportunity Enhancement**
- Finds arbitrage opportunities
- Uses better pricing data
- Exploits market inefficiencies

---

## 🔮 Future Enhancements

1. **Historical Anomaly Analysis**
   - Track anomaly patterns over time
   - Machine learning on refinement effectiveness

2. **Exchange Reputation Scoring**
   - Rate exchanges by data quality
   - Prefer reliable exchanges

3. **Real-Time WebSocket Integration**
   - Upgrade to paid tier for WebSocket
   - Sub-second anomaly detection

4. **Cross-Asset Correlation**
   - Detect manipulation across asset pairs
   - Systemic risk indicators

---

## 📚 Files

| File | Purpose |
|------|---------|
| `coinapi_anomaly_detector.py` | Core anomaly detection engine |
| `test_coinapi_integration.py` | Comprehensive test suite |
| `aureon_unified_ecosystem.py` | Integration into main system |
| `COINAPI_INTEGRATION.md` | This documentation |

---

## 🏆 Success Metrics

Track these metrics to measure CoinAPI value:

- **Anomalies Detected** - Total count by type
- **Symbols Blacklisted** - Wash trading avoidance
- **Refinements Applied** - Algorithm adjustments
- **Arbitrage Opportunities** - Cross-exchange spreads found
- **False Positive Rate** - Good trades filtered incorrectly
- **Performance Impact** - Win rate before/after CoinAPI

---

## 🌟 Conclusion

CoinAPI integration adds a **professional data validation layer** to our trading system. By detecting anomalies in cross-exchange data, we:

✅ Avoid manipulated markets  
✅ Identify real arbitrage opportunities  
✅ Automatically refine our algorithms  
✅ Use higher-quality aggregated pricing  
✅ Reduce false signals and bad trades  

The system now combines:
1. **HNC Frequency Analysis** (Solfeggio harmonics)
2. **Probability Matrix** (2-hour temporal forecasting)
3. **CoinAPI Anomaly Detection** (cross-exchange validation)

**Result**: A self-improving trading algorithm that learns from market anomalies and adapts in real-time.

---

*"The Truth is in the Anomalies"*  
**Gary Leckey | November 30, 2025**