Multi-Agent Arbitrage Engine

Production-grade multi-agent system for detecting and executing cross-marketplace arbitrage opportunities across Amazon, eBay, and MercadoLibre using quantitative risk management and game-theoretic pricing strategies.

🏗️ Architecture

graph TB
    subgraph "Agent Layer"
        SA[Scraping Agent<br/>Playwright + Stealth]
        PA[Pricing Agent<br/>Prophet + ARIMA]
        EA[Execution Agent<br/>Marketplace APIs]
        RA[Risk Agent<br/>VaR + Kelly]
    end
    
    subgraph "Infrastructure Layer"
        Redis[(Redis<br/>Message Bus)]
        Neo4j[(Neo4j<br/>Knowledge Graph)]
        Vault[Vault<br/>Secrets]
        DuckDB[(DuckDB<br/>Time-Series)]
    end
    
    subgraph "External Services"
        Amazon[Amazon SP-API]
        eBay[eBay Trading API]
        ML[MercadoLibre API]
    end
    
    SA -->|price.raw| Redis
    Redis -->|price.raw| PA
    PA -->|arbitrage.signal| Redis
    Redis -->|arbitrage.signal| EA
    Redis -->|arbitrage.signal| RA
    EA -->|execution.order| Redis
    Redis -->|execution.order| RA
    RA -->|risk.update| Redis
    
    SA --> DuckDB
    SA --> Neo4j
    PA --> Neo4j
    EA --> Neo4j
    
    SA --> Vault
    EA --> Vault
    
    EA --> Amazon
    EA --> eBay
    EA --> ML
    
    style SA fill:#e1f5ff
    style PA fill:#fff3e0
    style EA fill:#f3e5f5
    style RA fill:#ffebee

Loading

🎯 Features

Agent Architecture

1. Scraping Agent (agents/scraping_agent.py)

• Stealth scraping with Playwright and anti-detection plugins
• Proxy rotation to distribute requests across IP addresses
• User agent randomization and adaptive timing
• Rate limiting (1 req/sec per domain) to respect ToS
• Publishes to price.raw channel

2. Pricing Agent (agents/pricing_agent.py)

• Prophet + ARIMA forecasting for price trajectory prediction
• Isolation Forest + LSTM Autoencoder anomaly detection (>3σ)
• Arbitrage calculation: profit = (sell_price × (1 - fee_B)) - (buy_price × (1 + fee_A)) - shipping
• Publishes to arbitrage.signal channel if profit > threshold AND confidence > 90%

3. Execution Agent (agents/execution_agent.py)

• Marketplace API integrations:
  • Amazon SP-API (OAuth2 + LWA)
  • eBay Trading API (OAuth2)
  • MercadoLibre REST API (OAuth2)
• Saga pattern with compensation handlers for atomic buy/sell pairs
• Publishes to execution.order channel

4. Risk Agent (agents/risk_agent.py)

• Value-at-Risk (VaR) at 95% confidence using historical simulation
• Kelly Criterion position sizing: f* = (bp - q) / b
• Risk limits:
  • Max 2% of capital per position
  • Max 10% concentration per SKU
  • Max 20% drawdown alert threshold
• Publishes to risk.update channel

Core Infrastructure

• Message Bus (core/message_bus.py): Redis Pub/Sub with retry logic
• Knowledge Graph (core/knowledge_graph.py): Neo4j for SKU-Platform relationships
• Secret Management (core/vault_client.py): HashiCorp Vault / AWS Secrets Manager

🚀 Quick Start

Prerequisites

• Python 3.11+
• Docker & Docker Compose
• Redis, Neo4j, HashiCorp Vault (or use docker-compose)

Installation

# Clone repository
git clone https://github.com/example/arbitrage-engine.git
cd arbitrage-engine

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

Configuration

1. Copy secrets template:

   cp config/secrets.example.yaml config/secrets.yaml

2. Fill in credentials:

   • Amazon SP-API credentials
   • eBay Trading API OAuth tokens
   • MercadoLibre API keys
   • Database passwords

3. Upload secrets to Vault (optional):

   vault kv put secret/arbitrage/amazon @config/secrets.yaml

Running with Docker Compose

# Start all services (Redis, Neo4j, Vault, Agents)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Running Individual Agents

# Set environment variables
export REDIS_URL="redis://localhost:6379"
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_PASSWORD="your_password"
export VAULT_TOKEN="your_token"

# Run scraping agent
python -m agents.scraping_agent

# Run pricing agent (separate terminal)
python -m agents.pricing_agent

# Run execution agent (separate terminal)
python -m agents.execution_agent

# Run risk agent (separate terminal)
python -m agents.risk_agent

📊 Message Schemas

price.raw Channel

{
  "sku": "B08N5WRWNW",
  "platform": "amazon",
  "price": 299.99,
  "currency": "USD",
  "in_stock": true,
  "scraped_at": "2026-01-12T10:30:00Z"
}

arbitrage.signal Channel

{
  "opportunity_id": "uuid-1234",
  "sku": "B08N5WRWNW",
  "buy_platform": "ebay",
  "sell_platform": "amazon",
  "buy_price": 280.00,
  "sell_price": 320.00,
  "expected_profit": 25.50,
  "confidence": 0.95,
  "created_at": "2026-01-12T10:31:00Z"
}

execution.order Channel

{
  "order_id": "amz_abc123",
  "opportunity_id": "uuid-1234",
  "sku": "B08N5WRWNW",
  "platform": "amazon",
  "side": "sell",
  "status": "submitted",
  "executed_price": 320.00,
  "created_at": "2026-01-12T10:32:00Z"
}

risk.update Channel

{
  "var_95": 1250.00,
  "kelly_fraction": 0.045,
  "max_position_size": 2000.00,
  "current_exposure": 1500.00,
  "sharpe_ratio": 2.15,
  "max_drawdown": 850.00,
  "total_capital": 105000.00,
  "available_capital": 103500.00,
  "timestamp": "2026-01-12T10:35:00Z"
}

⚙️ Configuration

Platform Fees (config/platforms.yaml)

Platform	Referral Fee	Shipping	Rate Limit
Amazon	15%	$5.99	1 req/sec
eBay	12.5%	$4.99	1 req/sec
MercadoLibre	11%	$6.50	1 req/sec

Risk Parameters

risk:
  initial_capital: 100000.00
  max_position_fraction: 0.02  # 2% max per trade
  max_concentration: 0.10       # 10% max per SKU
  var_confidence: 0.95          # 95% VaR
  fractional_kelly: 0.50        # Half-Kelly for safety
  max_drawdown_threshold: 0.20  # 20% alert

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=agents --cov=core --cov-report=html

# Run specific agent tests
pytest tests/test_pricing_agent.py -v

📈 Monitoring

Prometheus Metrics

• Scraping metrics: arbitrage_scrapes_total, arbitrage_scrape_duration_seconds
• Pricing metrics: arbitrage_opportunities_detected, arbitrage_profit_distribution
• Execution metrics: arbitrage_orders_total{status="filled"}, arbitrage_execution_latency
• Risk metrics: arbitrage_var_95, arbitrage_sharpe_ratio, arbitrage_drawdown

Grafana Dashboards

Access Grafana at http://localhost:3000 (default credentials: admin/admin)

Pre-configured dashboards:

• Arbitrage Overview: Real-time opportunities and P&L
• Risk Dashboard: VaR, Kelly fractions, drawdown
• Agent Health: CPU, memory, message throughput

⚠️ Compliance & Risk Warnings

Legal Compliance

1. Marketplace Terms of Service:

   • Respect robots.txt and rate limits (1 req/sec)
   • No automated buying without explicit API support
   • Comply with seller agreements

2. Financial Regulations:

   • Not financial advice - use at your own risk
   • Ensure compliance with local securities laws
   • Consider tax implications of arbitrage profits

3. Data Privacy:

   • No personal data collection from marketplaces
   • Secure credential storage (Vault/AWS Secrets Manager)
   • Encrypt sensitive data in transit and at rest

Risk Disclaimers

• Market Risk: Prices change rapidly; opportunities may evaporate
• Execution Risk: Orders may fail, prices may slip
• Platform Risk: Marketplace APIs may change or become unavailable
• Capital Risk: Trading involves risk of capital loss
• No Guarantees: Past performance does not guarantee future results

Best Practices

✅ DO:

• Start with small capital and test in sandbox/staging
• Monitor risk metrics daily
• Respect marketplace rate limits
• Keep credentials secure
• Log all activities for audit trail

❌ DON'T:

• Hardcode credentials in source code
• Exceed marketplace rate limits
• Ignore VaR and drawdown alerts
• Run without monitoring and logging
• Deploy without understanding the code

🛠️ Development

Code Quality

# Format code
black agents/ core/

# Lint
ruff check agents/ core/

# Type checking
mypy agents/ core/

Project Structure

arbitrage-engine/
├── agents/               # Agent implementations
│   ├── scraping_agent.py
│   ├── pricing_agent.py
│   ├── execution_agent.py
│   └── risk_agent.py
├── core/                 # Infrastructure modules
│   ├── message_bus.py
│   ├── vault_client.py
│   └── knowledge_graph.py
├── config/               # Configuration files
│   ├── platforms.yaml
│   └── secrets.example.yaml
├── docker/               # Dockerfiles
│   ├── Dockerfile.scraping
│   ├── Dockerfile.pricing
│   ├── Dockerfile.execution
│   └── Dockerfile.risk
├── notebooks/            # Jupyter notebooks
│   └── arbitrage_simulation.ipynb
├── tests/                # Unit and integration tests
├── docker-compose.yml    # Multi-container orchestration
├── pyproject.toml        # Python project metadata
├── requirements.txt      # Dependencies
└── README.md             # This file

📚 Further Reading

• Amazon SP-API Documentation
• eBay Trading API Reference
• MercadoLibre API Docs
• Kelly Criterion Explained
• Value-at-Risk (VaR)
• Prophet Forecasting

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with the Autonomous Reasoning Cluster (ARC) framework
• Inspired by quantitative trading and multi-agent system research
• Uses open-source libraries: Playwright, Prophet, Neo4j, Redis

---

Disclaimer: This software is for educational and research purposes. The authors are not responsible for any financial losses incurred from using this system. Always conduct thorough testing and risk assessment before deploying with real capital.