Os trades históricos são as transações já executadas no mercado em períodos passados, registradas tick a tick, com preço, quantidade, agentes (corretoras) compradora e vendedora e horário exato da execução. São a base para backtests, análises de fluxo retrospectivas, cálculo de VWAP histórico, treinamento de modelos quantitativos e tape reading sobre dados consolidados.

A ProfitDLL entrega o histórico através de três peças que trabalham juntas: 

• GetHistoryTrades: função que requisita o intervalo desejado 

• THistoryTradeCallback: callback chamado uma vez para cada trade recebido 

• TProgressCallback: callback que sinaliza o progresso do download (0 a 100%) 

Limites e formato da requisição 

Antes do código, dois pontos definem todo o resto: 

Atenção:

• Por que requisitar dia a dia: ativos voláteis (WINFUT, WDOFUT) podem gerar centenas de milhares de trades por dia. Requisições amplas demoram, consomem muita memória e, em aplicações 32 bits, podem estourar o limite de 4 GB do processo.
  Quebrar em janelas diárias dá controle, permite retry isolado em caso de falha e simplifica persistência incremental.
   
• O formato da data é estrito. Use exatamente '%d/%m/%Y %H:%M:%S'.
  Inverter a ordem (MM/DD/YYYY), omitir os zeros (5/11/2024) ou usar separadores diferentes (- em vez de /) faz a requisição falhar, o callback não dispara e nenhum trade chega. Sempre prefira datetime.strftime(...) a concatenar strings manualmente.

Como funciona o fluxo 

Funções e callbacks envolvidos 

Estruturas e enums 

TAssetID 

Estrutura que identifica o ativo nos callbacks de histórico. 

from ctypes import Structure, c_wchar_p, c_int 
  
class TAssetID(Structure): 
    _fields_ = [ 
        ("ticker", c_wchar_p), 
        ("bolsa", c_wchar_p), 
        ("feed", c_int), 
    ] 

THistoryTradeCallback

Os tipos 2 e 3 são os mais comuns no cotidiano de leitura de fluxo: indicam se a execução veio de um comprador agredindo a oferta (tipo 2) ou de um vendedor agredindo o bid (tipo 3). 

TProgressCallback 

Quando progress atinge 100, o download terminou e nenhum trade adicional virá daquela requisição. 

Implementação em Python 

Os exemplos abaixo assumem que você já inicializou a DLL e está com a conexão completa (veja Como saber se a DLL está conectada).

• Passo 1: Definir os callbacks 

from ctypes import WINFUNCTYPE, c_double, c_int, c_uint, c_wchar_p 
import threading 


# Buffer para acumular os trades recebidos no intervalo atual 

trades_recebidos = [] 

historico_pronto = threading.Event() 


# Assinatura do callback de trade histórico. 

# Ordem dos argumentos: 

#   (asset, date, tradeNumber, price, vol, qtd, buyAgent, sellAgent, tradeType) 

#   asset       -> TAssetID passada POR VALOR (não como ponteiro) 

#   date        -> string "DD/MM/YYYY HH:mm:SS.ZZZ" 

#   qtd         -> Integer (c_int, 32 bits) 

@WINFUNCTYPE(None, 
             TAssetID,       # asset (por valor) 

             c_wchar_p,      # date 

             c_uint,         # tradeNumber 
             c_double,       # price 
             c_double,       # vol 
             c_int,          # qtd 
             c_int,          # buyAgent 
             c_int,          # sellAgent 
             c_int)          # tradeType 

def history_trade_callback(asset, date, trade_number, price, vol, 
                            qtd, buy_agent, sell_agent, trade_type): 

    # Importante: callbacks rodam na ConnectorThread. 

    # Apenas acumule aqui — nada de processamento pesado, I/O ou chamadas à DLL. 

    trades_recebidos.append({ 
        "ticker":       asset.ticker, 
        "date":         date, 
        "trade_number": trade_number, 
        "price":        price, 
        "vol":          vol, 
        "qtd":          qtd, 
        "buy_agent":    buy_agent, 
        "sell_agent":   sell_agent, 
        "trade_type":   trade_type, 
    }) 

# Callback de progresso (sinaliza fim quando chega a 100) 
@WINFUNCTYPE(None, TAssetID, c_int) 
def progress_callback(asset, progress): 
    print(f"{asset.ticker}: {progress}%") 
    if progress >= 100: 
        historico_pronto.set() 

Atenção à assinatura do callback: o TAssetID é passado por valor (não como ponteiro), e os campos do trade chegam destrinchados como argumentos individuais, não há tradução necessária. Note que qtd é c_int (32 bits), suficiente para quantidades típicas do mercado brasileiro.

profit_dll.SetHistoryTradeCallback(history_trade_callback) 
profit_dll.SetSerieProgressCallback(progress_callback) 

def baixar_dia(ticker, bolsa, data, hora_inicio="09:00:00", hora_fim="18:35:00"): 
    """Baixa o histórico de trades de um único dia.""" 
    inicio = f"{data} {hora_inicio}" 
    fim    = f"{data} {hora_fim}" 

    # Reseta o estado antes de cada requisição 
    historico_pronto.clear() 
    trades_recebidos.clear() 

    ret = profit_dll.GetHistoryTrades( 
        c_wchar_p(ticker), 
        c_wchar_p(bolsa), 
        c_wchar_p(inicio), 
        c_wchar_p(fim), 
    ) 
    if ret != 0: 
        raise RuntimeError(f"GetHistoryTrades falhou: código {ret}") 

    # Aguarda até o progresso atingir 100 

    if not historico_pronto.wait(timeout=300): 

        raise TimeoutError("Histórico não terminou dentro do timeout") 

      return list(trades_recebidos) 
      
# Uso 
trades = baixar_dia(ticker="WINZ24", bolsa="F", data="05/11/2024") 

print(f"Recebidos {len(trades)} trades") 

• Passo 4: Baixar múltiplos dias 

Para períodos maiores, faça em loop dia a dia: 

from datetime import date, timedelta 

def baixar_periodo(ticker, bolsa, data_inicial, data_final): 
    """Baixa o histórico de trades dia a dia entre duas datas (inclusive).""" 
    todos_trades = [] 
    d = data_inicial 
    while d <= data_final: 
        # Pula sábados e domingos 
        if d.weekday() < 5: 
            data_str = d.strftime("%d/%m/%Y") 
            try: 
                trades = baixar_dia(ticker, bolsa, data_str) 
                todos_trades.extend(trades) 
                print(f"{data_str}: {len(trades)} trades") 
            except (RuntimeError, TimeoutError) as e: 
                print(f"{data_str}: falhou — {e}") 
        d += timedelta(days=1) 
    return todos_trades 
    
# Uso 
todos = baixar_periodo( 
    ticker="WINZ24", 
    bolsa="F", 
    data_inicial=date(2024, 11, 4), 
    data_final=date(2024, 11, 8), 
) 

Parseando a data recebida 

A date chega no formato DD/MM/YYYY HH:mm:SS.ZZZ (com milissegundos): 

from datetime import datetime 

def parse_date(date_str): 

   return datetime.strptime(date_str, "%d/%m/%Y %H:%M:%S.%f") 

# Exemplo 
dt = parse_date("05/11/2024 14:23:07.142") 

Boas práticas

• Requisite dia a dia. Mesmo que a DLL aceite até 10 dias por chamada, dia a dia dá controle, permite retry isolado em caso de falha e simplifica persistência incremental.
   

• Use o callback de progresso para detectar o fim. Aguardar trades pararem de chegar é frágil, uma pausa breve da DLL ou da rede pode te enganar. progress == 100 é o sinal definitivo.
   

• Pule fins de semana e feriados. Requisições para datas sem pregão simplesmente não retornam trades, mas consomem tempo da DLL desnecessariamente.
   

• Não chame funções da DLL dentro dos callbacks. Apenas acumule os dados; deixe processamento pesado para outra thread.
   

• Persista incrementalmente. Em projetos de longo prazo, salve cada dia logo após recebê-lo (CSV, SQLite, Parquet, etc.) em vez de manter tudo em memória.
   

• Valide o formato da data antes de chamar. Use sempre datetime.strftime("%d/%m/%Y %H:%M:%S") em vez de concatenar strings manualmente, um caractere fora do padrão faz a requisição falhar sem retorno de trades.

Para mais informações, encaminhe um e-mail para corporativo@nelogica.com.br.

Achou útil este conteúdo?
Não esqueça de nos avaliar abaixo.
Desejamos bons trades!