Integração com a API Finnhub em Python

A API Finnhub disponibiliza dados financeiros de nível institucional, abrangendo cotações em tempo real, fundamentos globais, composição de ETFs e dados alternativos. Através do cliente oficial para Python, é possível acessar mais de 60 endpoints distintos que cobrem ações, moedas fiduciárias e criptoativos. Para iniciar a integração, instale a biblioteca necessária via terminal:

pip install finnhub-python

Após a instalação, é obrigatório obter uma chave de acesso (API Key) no portal oficial do Finnhub para autenticar as requisições.

Extração de Cotações em Tempo Real

O acompanhamento de preços em tempo real é a base para qualquer plataforma de análise quantitativa. A biblioteca permite consultar os dados de negociação atuais de forma direta:

import finnhub
from dotenv import load_dotenv
import os

load_dotenv()
api_connection = finnhub.Client(api_key=os.getenv("FINNHUB_SECRET"))

ticker = "MSFT"
current_quote = api_connection.quote(ticker)
print(f"Valor atual: ${current_quote['c']}")
print(f"Variação percentual: {current_quote['dp']}%")

O objeto retornado contém o preço atual, preço de abertura, máxima, mínima e volume, servindo como insumo para dashboards de monitoramento ou gatilhos de algoritmos de trading.

Processamento de Dados de Velas (OHLCV)

Os gráficos de velas japonesas são fundamentais para a análise técnica visual e quantitativa. É possível recuperar o histórico de preços com resoluções que variam de minutos a meses:

import pandas as pd
from datetime import datetime, timedelta

end_ts = int(datetime.now().timestamp())
start_ts = int((datetime.now() - timedelta(days=90)).timestamp())

ohlcv_data = api_connection.stock_candles("MSFT", "D", start_ts, end_ts)
price_df = pd.DataFrame(ohlcv_data)
print(f"Total de sessões de negociação extraídas: {len(price_df)}")

Esses dados formam a base para o cálculo de indicadores derivados, como Médias Móveis, RSI e MACD, utilizando bibliotecas de aálise técnica em conjunto com o Pandas.

Avaliação de Indicadores Técnicos Agregados

O Finnhub oferece um endpoint dedicado que consolida múltiplas ferramentas de análise técnica em um único sinal, facilitando a interpretação do cenário macro do ativo:

tech_signals = api_connection.aggregate_indicator("MSFT", "D")
analysis_result = tech_signals['technicalAnalysis']['signal']
trend_momentum = tech_signals['trend']['adx']

print(f"Sinal Técnico Dominante: {analysis_result}")
print(f"Força da Tendência (ADX): {trend_momentum}")

Essa agregação fornece uma visão rápida sobre a pressão de compra/venda e a força do movimento atual do mercado.

Coleta de Fundamentos e Perfil Corporativo

Para além da análise gráfica, a avaliação de fundamentos é crucial. A API permite acessar métricas de valuation e informações legais das empresas listadas:

metrics_data = api_connection.company_basic_financials("MSFT", "all")
pl_ratio = metrics_data['metric']['peNormalizedAnnual']
pvp_ratio = metrics_data['metric']['pbAnnual']

print(f"Índice Preço/Lucro: {pl_ratio}")
print(f"Índice Preço/Valor Patrimonial: {pvp_ratio}")

corp_profile = api_connection.company_profile(symbol="MSFT")
print(f"Razão Social: {corp_profile['name']}")
print(f"Setor de Atuação: {corp_profile['finnhubIndustry']}")

Implementação de um Módulo de Diagnóstico Integrado

Combinando os endpoints de cotação, velas, indicadores e perfil, podemos estruturar uma função de diagnóstico que retorna um dicionário consolidado para alimentar uma interface de usuário ou um motor de decisão:

import time

def generate_market_report(asset_symbol: str) -> dict:
    live_price = api_connection.quote(asset_symbol)
    
    current_epoch = int(time.time())
    past_month_epoch = current_epoch - (30 * 86400)
    historical_ohlcv = api_connection.stock_candles(asset_symbol, "D", past_month_epoch, current_epoch)
    
    aggregated_indicators = api_connection.aggregate_indicator(asset_symbol, "D")
    company_info = api_connection.company_profile(symbol=asset_symbol)
    
    return {
        "current_price_data": live_price,
        "historical_candles": historical_ohlcv,
        "technical_summary": aggregated_indicators,
        "company_details": company_info
    }

Otimização de Desempenho e Recursos Avançados

Ao construir aplicações em produção com esta API, observe os seguintes pontos de arquitetura e boas práticas:

• Gerenciamento de Credenciais: Armazene as chaves de acesso exclusivamente em variáveis de ambiente ou cofres de segredo (Secret Managers), nunca no código-fonte.
• Controle de Requisições: Implemente estratégias de cache local para dados de baixa volatilidade (como perfil corporativo) e respeite os limites de taxa (rate limits) do plano contratado.
• Resiliência: Envolva as chamadas à API em blocos de tratamento de exceções para lidar com falhas de rede ou respostas inesperadas.
• Validação de Payload: Verifique se os campos esperados existem no JSON retornado antes de processá-los, evitando erros de chave ausente.

A biblioteca também expõe funcionalidades avançadas para estratégias mais complexas, incluindo análise de sentimento de notícias de mercado, calendário de relatórios de lucros, posições de investidores institucionais, mapeamento de cadeias de suprimentos corporativos e pontuações de ESG (Ambiental, Social e Governança).