Crypto Arb Lab (MVP)

Monitor de oportunidades de arbitragem entre CEX×CEX spot, spot×futures e futures×futures. Não executa trades reais por padrão.

O que é / não é

• ✅ Coleta de cotações públicas, calcula spreads, fees estimados, ROI e sinaliza oportunidades.
• ✅ Modo demo para funcionar sem chaves, apenas com dados sintéticos.
• ✅ Flags para execução experimental/paper trading (desativado por padrão).
• 🚫 Não é recomendação ou conselho financeiro. 🚫 Não garante lucro. 🚫 Não usa links de afiliado.

Requisitos

• Python 3.12
• Opcional: Docker / Docker Compose

Instalação (venv)

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
cp .env.example .env

Configuração

• Ajuste .env ou um YAML opcional (--config) com exchanges e símbolos.
• Por padrão usa endpoints públicos do ccxt; chaves são opcionais e lidas de variáveis de ambiente.
• Ative modo demo definindo DEMO_MODE=true para rodar sem internet.
• Estrutura YAML de exemplo:

exchanges:
  - name: binance
    type: spot
  - name: okx
    type: futures
symbols:
  - symbol: BTC/USDT
  - symbol: ETH/USDT
runtime:
  interval_seconds: 30
  demo_mode: false

Uso da CLI

• Scan único: arb scan
• Loop contínuo: arb daemon
• Listar sinais: arb list-signals --limit 20
• Exportar: arb export --format csv
• Health quick check: arb health

API (opcional)

• Suba com uvicorn arb_lab.api.server:app --host 0.0.0.0 --port 8000
• Endpoints: /health, /signals, /config, /scan

Três tipos de arbitragem monitorados

• CEX×CEX spot: best ask de A vs best bid de B.
• Spot×Futures: basis (futuro - spot) + funding quando disponível.
• Futures×Futures: diferença de preços e funding entre venues.

Riscos reais (mesmo no papel)

• Slippage e books rasos, taxas (taker/maker), delays de transferência/saque, mudanças de funding, travas de saque/listagem, falhas de API e rate limits.

Logs e persistência

• Logs estruturados (JSON) com structlog; segredos são mascarados.
• SQLite em ./data/arb_lab.db via SQLModel. Crie a pasta data/ se necessário.

Execução via Docker

docker build -t arb-lab .
docker run --rm -v $(pwd)/data:/app/data --env-file .env.example arb-lab arb scan

Ou com compose (daemon + API): docker-compose up --build

Qualidade

• Lint: ruff check . | Format: black .
• Testes: pytest

Limitações / TODO curto prazo

• Adapter Hyperliquid está mockado; substituir por implementação real.
• Não há execução real; EXPERIMENTAL_TRADING ficará atrás de flag em fase 2.

Segurança

• Nunca logamos chaves; use variáveis de ambiente.
• Rate limit, retries com backoff e circuit breaker simples embutidos nos adapters.

Licença

MIT