Clawdfolio

O que Clawdfolio faz?

Kit de ferramentas quantitativas para portfólio voltado a investidores profissionais. Agregação multi-corretora (Longport, Moomoo/Futu, demo), análises institucionais de risco, gerenciamento do ciclo de vida de estratégias com opções, mais de 20 fluxos de trabalho financeiros automatizados e exportação de dados CSV/JSON.

PyPI: pip install clawdfolio · Repositório: https://github.com/YichengYang-Ethan/clawdfolio · Python >= 3.10 (testado 3.10–3.13)

Consulte API.md para a referência completa da API Python e CONFIG.md para configuração, variáveis de ambiente, configuração de corretoras e detalhes de monitores.

---

Comandos CLI

Todos os comandos aceitam --broker {longport,futu,demo,all}, --output {console,json} e --config CAMINHO.

Portfólio

clawdfolio summary              # Visão geral do portfólio (comando padrão)
clawdfolio summary --top 20     # Mostrar as 20 principais posições
clawdfolio quotes AAPL MSFT     # Cotações em tempo real
clawdfolio alerts               # Alertas de preço/RSI/PnL/concentração
clawdfolio alerts --severity critical

Análise de Risco

clawdfolio risk                 # Volatilidade, Beta, Sharpe, Sortino, VaR, CVaR, drawdown
clawdfolio risk --detailed      # + Extremos de RSI, concentração, exposição setorial, RSI do portfólio

Métricas de risco calculadas:

• Volatilidade: 20d, 60d, anualizada
• Beta: vs SPY, vs QQQ
• Índice de Sharpe: anualizado, retorno excedente / volatilidade total
• Índice de Sortino: anualizado, retorno excedente / apenas volatilidade negativa
• VaR: 95% e 99% (histórico), absoluto e percentual
• CVaR / Expected Shortfall: 95% e 99% — risco de cauda além do VaR
• Drawdown Máximo: histórico e atual
• HHI: Índice de concentração Herfindahl-Hirschman
• RSI: RSI de 14 dias do portfólio
• Correlação: detecção de pares com alta correlação (>= 0.8)

Earnings

clawdfolio earnings             # Próximos earnings (padrão 14 dias)
clawdfolio earnings --days 30   # Visualização de 30 dias

DCA (Dollar-Cost Averaging)

clawdfolio dca                  # Sinais DCA para o portfólio (rebalanceamento + detecção de queda)
clawdfolio dca AAPL --months 12 --amount 1000   # Backtest histórico de DCA

Tipos de sinal: REGULAR (agendado), DIP (queda de preço em relação à máxima recente), REBALANCE (desvio de peso em relação ao alvo).

Exportação

clawdfolio export portfolio                  # CSV para stdout
clawdfolio export portfolio --format json    # JSON para stdout
clawdfolio export risk --file risk.csv       # Métricas de risco para arquivo
clawdfolio export alerts --format json --file alerts.json

Alvos de exportação: portfolio, risk, alerts. Formatos: csv, json.

Opções

clawdfolio options expiries TQQQ
clawdfolio options chain TQQQ --expiry 2026-03-21 --side calls --limit 10
clawdfolio options quote TQQQ --expiry 2026-03-21 --strike 80 --type C
clawdfolio options buyback          # Verificar disparos de recompra a partir da configuração
clawdfolio options buyback --strict # Código de saída 1 se nenhum alvo for acionado

Fluxos de Trabalho Financeiros

20 fluxos de trabalho agrupados em 7 categorias. Sequência de configuração validada:

1. Verificar conectividade da corretora: clawdfolio summary --broker demo (deve mostrar 10 posições demo)
2. Inicializar workspace: clawdfolio finance init depois verificar com ls ~/.clawdfolio/finance
3. Listar fluxos disponíveis: clawdfolio finance list
4. Executar um fluxo: clawdfolio finance run portfolio_daily_brief_tg
5. Verificar saída: adicione --output json para resultados legíveis por máquina; em caso de erro, tente novamente com --broker demo para isolar problemas de corretora vs. fluxo

clawdfolio finance list --category alerts_monitors  # Filtrar por categoria
clawdfolio finance run dca_proposal_tg -- --budget 5000  # Passar argumentos extras

Categorias: portfolio_reports, briefing_cards, alerts_monitors, market_intel, broker_snapshots, strategy, security.

Fluxos principais:

ID	Descrição
portfolio_report	Relatório diário do portfólio com desempenho, risco e posições
portfolio_daily_brief_tg	Cartão de resumo diário amigável para Telegram
portfolio_alert_monitor	Alertas de RSI/PnL/concentração/movimentação com deduplicação
option_buyback_monitor	Monitor de disparo de recompra de opções com estado
earnings_calendar	Próximos earnings para as posições atuais
dca_proposal_tg	Cartão de proposta DCA com restrição orçamentária
account_report	Instantâneo combinado Longport + moomoo

Workspace: ~/.clawdfolio/finance (configurável com --workspace).

---

Instalação

pip install clawdfolio               # Núcleo (yfinance + corretora demo)
pip install clawdfolio[longport]     # + Corretora Longport
pip install clawdfolio[futu]         # + Corretora Moomoo/Futu
pip install clawdfolio[all]          # Todas as corretoras
pip install clawdfolio[dev]          # + pytest, mypy, ruff (desenvolvimento)

---

API Python

Principais imports para uso programático:

from clawdfolio import Symbol, Position, Quote, Portfolio, RiskMetrics, Alert
from clawdfolio.brokers import get_broker
from clawdfolio.analysis.risk import analyze_risk
from clawdfolio.analysis.technical import calculate_rsi, calculate_macd
from clawdfolio.market import get_price, get_history, is_market_open
from clawdfolio.strategies.dca import DCAStrategy, calculate_dca_performance
from clawdfolio.output import export_portfolio_csv, export_risk_json

Consulte API.md para a referência completa da API com exemplos de uso.

---

Configuração

Ordem de busca: flag --config > variável de ambiente CLAWDFOLIO_CONFIG > ./config.yaml > ~/.config/clawdfolio/config.yaml. Suporta YAML e JSON.

Corretoras suportadas: Longport (variáveis de ambiente), Moomoo/Futu (OpenD local), Demo (embutida), Agregador (fusão multi-corretora).

Consulte CONFIG.md para a referência completa de configuração, variáveis de ambiente, configuração de corretoras e detalhes de monitores.