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

# Required for live anomaly detection
export COINAPI_KEY=your-api-key-here
export ENABLE_COINAPI=1

CONFIG Parameters

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 Reduce position size ×0.5
🔄 Wash Trading	>15% trades at identical prices	Blacklist for 1 hour Position size ×0.0
📊 Orderbook Spoofing	Bid/ask ratio >70/30	Delay entry +60s Reduce position size ×0.7
🌐 Cross-Exchange Spread	>2% arbitrage opportunity	Use multi-exchange mean price Increase position size ×1.2
⚡ Latency Arbitrage	>500ms delays	Compensate for latency 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)

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

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

# 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

# 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

# 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

python test_coinapi_integration.py

Tests include:

• ✅ Blacklist functionality
• ✅ Coherence adjustments
• ✅ Anomaly refinement logic
• ✅ Opportunity filtering
• ✅ Full system integration

Standalone CoinAPI Demo

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