XCAP — Foreign Capital Flow Tracker

O que está realmente "ao vivo"

Stack

┌────────────────────────────────────────┐
│   Browser (React via CDN + Recharts)   │
└────────────────┬───────────────────────┘
                 │  HTTP JSON
┌────────────────▼───────────────────────┐
│   FastAPI · uvicorn                    │
│   ├── /api/* endpoints                 │
│   ├── /static/* (frontend)             │
│   └── APScheduler (cron diário)        │
└────────────────┬───────────────────────┘
                 │
┌────────────────▼───────────────────────┐
│   SQLite (xcap.db) · WAL mode          │
│   ├── fact_flow_daily                  │
│   ├── fact_flow_monthly                │
│   ├── fact_index_daily                 │
│   ├── fact_macro_annual                │
│   └── signals                          │
└────────────────────────────────────────┘
                 │
┌────────────────▼───────────────────────┐
│   Conectores                           │
│   ├── yfinance        (preços)         │
│   ├── World Bank API  (macro)          │
│   ├── TWSE JSON       (TW flow)        │
│   └── Stubs: B3, NSDL, KRX, HKEX...    │
└────────────────────────────────────────┘

Como rodar

1. Executável standalone (sem Python instalado)

• Windows: xcap-windows-x64.zip → descompacte → duplo-clique em xcap.exe
• macOS: xcap-macos-arm64.tar.gz → descompacte → cd xcap && ./xcap
• Linux: xcap-linux-x64.tar.gz → descompacte → cd xcap && ./xcap

1. Abre o navegador automaticamente em http://localhost:8000
2. Cria xcap.db no mesmo diretório (modo portátil) ou no diretório do usuário, conforme permissões
3. Baixa o histórico do yfinance (~40s)
4. Atualiza diariamente via scheduler embarcado

2. Script de execução com auto-install (com Python já instalado)

3. Docker

4. Python direto (modo desenvolvedor)

Deploy gratuito

Hugging Face Spaces (recomendado — grátis, não dorme)

1. Crie um Space novo: https://huggingface.co/new-space
2. Tipo: Docker
3. Faça push do repo. Pronto — URL pública em ~2min.

Render.com (grátis com sleep de 15min)

1. https://render.com → New → Web Service
2. Conecte o repo
3. Build: docker (auto-detecta Dockerfile)
4. Start command: já no Dockerfile

Fly.io (grátis com 256MB, não dorme)

Endpoints

GET  /                                  # Frontend (index.html)
GET  /api/health                        # status
GET  /api/countries                     # metadados dos 10 mercados
GET  /api/flows/daily?country=BR&days=120
GET  /api/flows/monthly?country=BR
GET  /api/indices/{country}?days=252
GET  /api/macro/{country}               # World Bank: portfolio + FDI
GET  /api/signals?days=60&severity=critical&country=BR
GET  /api/overview                      # dashboard summary
POST /api/admin/refresh                 # trigger manual (X-Admin-Token header)
POST /api/admin/seed                    # reseed real monthly data

Variáveis de ambiente

XCAP_DB=xcap.db                       # caminho do SQLite
XCAP_ADMIN_TOKEN=change-me            # auth para /api/admin/*
XCAP_SCHEDULE=0 22 * * 1-5            # cron do daily update
XCAP_PORT=8000

Conector B3 — como funciona (implementado)

1. Download do CSV oficial em https://sistemaswebb3-listados.b3.com.br/marketDataProxy/MarketDataCall/GetDownloadMarketData/RELATORIO_DADOS_DE_MERCADO.csv (na verdade um ZIP, apesar da extensão).
2. Extração do CSV de dentro do ZIP, decodificação latin-1.
3. Parsing da seção "Movimentação dos Investidores Estrangeiros Mensal (R$ Milhões)" usando regex para localizar o cabeçalho e parser de números no formato brasileiro (1.234,56 e parênteses para negativos).
4. Conversão BRL→USD via API PTAX do Banco Central (olinda.bcb.gov.br/.../CotacaoDolarDia), com fallback para taxa estática se a BCB estiver fora.
5. Upsert no fact_flow_monthly com kind='real' e nota com a taxa de câmbio usada.
6. Redistribuição diária via seed_daily_from_monthly(db_path, country='BR') — preserva o total mensal exato, gera ruído gaussiano por dia útil.
7. Audit trail: cada download é arquivado em data/snapshots/b3/RELATORIO_YYYY-MM-DD.bin (rotação 30 dias).

Troubleshooting do build PyInstaller

• Adicione exceção no Defender / outro AV
• Para distribuição pública, assine o exe com um certificado (Authenticode)
• Use o GitHub Releases — binários baixados de fonte conhecida têm reputação melhor

• Remova pandas se não usa nada além de filtragem básica (substitua por dict + csv)
• Use --exclude-module para libs realmente não usadas
• Não use UPX (false positives de AV)

Implementando os scrapers restantes

• NSDL FPI: https://www.fpi.nsdl.co.in/Reports/Latest.aspx — ASP.NET, precisa POST do __VIEWSTATE com a data
• KRX KIND: http://data.krx.co.kr/comm/bldAttendant/getJsonData.cmd — POST com bld=dbms/MDC/STAT/standard/MDCSTAT02401
• HKEX Stock Connect: turnover apenas; net diário foi descontinuado em Ago/2024 pela SSE/SZSE
• JPX Japan: relatório semanal (sextas) em CSV
• EPFR: API paga; não cobrimos no tier gratuito

Estrutura de arquivos

xcap/
├── launcher.py           # Entry point com auto-browser + port detection
├── app.py                # FastAPI + scheduler + rotas
├── connectors.py         # Fetchers + signal engine
├── database.py           # SQLite schema + seed + queries
├── static/
│   └── index.html        # Frontend (React via CDN)
├── data/                 # xcap.db + snapshots/ (gitignored)
├── requirements.txt
├── xcap.spec             # PyInstaller config (hidden imports, datas)
├── build.sh / build.bat  # Constrói executável standalone
├── run.sh / run.bat      # Auto-instala deps e roda (precisa Python)
├── Dockerfile
├── docker-compose.yml
├── fly.toml              # Deploy Fly.io
├── .github/workflows/
│   └── build.yml         # CI: builds Windows/Mac/Linux a cada tag
└── README.md

Modelo de dados

• countries: registry com bandeira, exchange, currency, cobertura.
• fact_flow_daily: 1 linha por (date, exchange, investor_bucket, asset_class, source).
• fact_flow_monthly: agregados mensais publicados (com flag de confiança).
• fact_index_daily: closes dos índices, via yfinance.
• fact_macro_annual: World Bank — portfolio e FDI por país por ano.
• signals: surge, abrupt outflow, MA crossover, com severity.

Motor de sinais

• z-score 252d sobre net_flow_usd
• |z| ≥ 2.3 → severity = warn; |z| ≥ 3 → critical
• Cruzamento MA20 × MA60 → severity = info
• Persiste em signals com timestamp e mensagem

Licença