README

ProfitDLL — Documentação Técnica

Documentação de referência da ProfitDLL 4.0.0.42 (Nelogica), em Markdown, preparada para consumo por agentes de IA.

English version · Manual pt-BR · Manual en-US

O que é este repositório

Este repositório não é uma biblioteca nem um SDK. É um repositório de documentação. Ele reúne:

1. Os manuais oficiais da ProfitDLL convertidos para Markdown estruturado — a entrega principal, pensada para ser lida por assistentes de codificação e agentes de IA.
2. Os PDFs oficiais que deram origem a essas conversões.
3. Os exemplos de código das quatro linguagens distribuídos pela Nelogica (Python, C#, C++ e Delphi), mantidos exatamente como recebidos, como referência de uso real da API.
4. Referências externas, na seção Extras ao final deste README: o link oficial de download da DLL, a central de ajuda da Nelogica com os artigos sobre a DLL, uma tabela-resumo de todos os posts do blog da Nelogica sobre Data Solution e projetos da comunidade que usam a ProfitDLL em C# e Python.

A ProfitDLL.dll não está neste repositório. Ela é proprietária e licenciada pela Nelogica. Nada aqui executa sem a DLL, uma chave de ativação e credenciais de conta. O pacote oficial com a DLL, os manuais e os exemplos está em Extras → Download oficial.

Como usar com agentes de IA

Os manuais em Markdown foram estruturados especificamente para recuperação por agentes:

• Cada função e cada callback tem um heading #### com o nome exato entre crases. Buscar por `SendOrder` leva direto à seção da API.
• Front-matter YAML no topo declara versão da DLL, idioma e fonte.
• Índices no início do documento: delta entre versões, tabela de APIs deprecadas com suas substitutas, índice rápido de todas as APIs e mapeamento de tipos Delphi → C#/C++/Python.
• Tabelas de parâmetros preservadas (Nome / Tipo / Descrição) para cada função, com as células exatamente como no PDF.
• Declarações Delphi íntegras: as linhas que a impressão do PDF quebrou foram reunidas, e cada bloco de código é uma cópia fiel do original.
• Abaixo do separador ---, o conteúdo é o do PDF oficial, na mesma ordem e com a mesma redação; divergências entre manual e código são anotadas no preâmbulo, não silenciadas.
• Recursos externos ficam neste README, não nos manuais: os links oficiais, os posts do blog e os projetos da comunidade estão na seção Extras, para que os manuais permaneçam cópia fiel do PDF.

Aponte seu agente para o manual do idioma desejado e ele terá a referência completa da API sem precisar abrir o PDF.

ProfitDLL 4.0.0.42 — visão geral

A ProfitDLL é a biblioteca da Nelogica para integração com os serviços de market data e roteamento de ordens da B3.

• Plataforma: Windows, 32 ou 64 bits — a aplicação cliente precisa ter a mesma arquitetura da DLL.
• Convenção de chamada: stdcall, em ambas as arquiteturas.
• Modalidades: roteamento completo (DLLInitializeLogin, market data + envio de ordens) ou somente market data (DLLInitializeMarketLogin).

Funcionalidades

Exemplos por linguagem

Os quatro exemplos fazem o mesmo — inicializam a DLL com chave de ativação, usuário e senha e executam funções sob demanda — mas cada um coleta esses dados de um jeito:

• Python pede chave, usuário e senha no terminal e entra em um laço de comandos digitados (subscribe, offerbook, position, buyAtMarket, getHistoryTrades, healthStatus, exit, …).
• C# pede usuário, senha e chave no terminal; seu laço de comandos usa nomes próprios (subscribe, send order, get position, request history, exit, …).
• C++ tem chave, usuário, senha, conta e corretora como constantes no início de main() (marcadas com Preencher) e executa um roteiro fixo de chamadas, sem laço de comandos.
• Delphi é um formulário VCL com campos para as credenciais e uma lista de funções para acionar.

# Python — requer 3.10+ (main.py usa anotações "X | None"; quebra no 3.9).
# Sem dependências externas, só ctypes. Carrega "./ProfitDLL.dll" no import,
# portanto o diretório de trabalho importa.
cd "Exemplo Python" && python main.py

# C# — net9.0, AllowUnsafeBlocks. Copie ProfitDLL.dll para o diretório de saída.
dotnet run --project "Exemplo C#/ProfitDLLCSClient.csproj"

# C++ — sem arquivo de projeto; as linhas de compilação estão no cabeçalho de main.cpp:
cl main.cpp /link ws2_32.lib kernel32.lib     # MSVC
g++ main.cpp                                  # MinGW

# Delphi — abra "Exemplo Delphi/DLLClientP.dproj" no RAD Studio (VCL,
# Win32/Win64, Debug/Release) ou, em um prompt Delphi (após rsvars.bat):
msbuild DLLClientP.dproj /p:Config=Release /p:Platform=Win64

Como cada exemplo está organizado

Os quatro exemplos são a mesma integração reescrita em linguagens diferentes. Ao consultar um deles, o arquivo equivalente nos outros é:

Arquivos com prefixo Legacy contêm a API antiga (ver APIs deprecadas no manual). C#/Delphi fazem link estático pelo nome da DLL; Python usa ctypes.WinDLL; C++ resolve cada símbolo com LoadLibrary/GetProcAddress.

A cobertura da API não é idêntica entre eles: só o exemplo Python faz o binding das APIs de saúde (GetHealthStatus, SetHealthCallback, TSystemHealthState), e o exemplo C# manteve o comando request history enquanto o Python o renomeou para getHistoryTrades na 4.0.0.42.

Conceitos centrais

Estas regras são propriedades da DLL, não preferências de estilo. Elas explicam por que o código dos exemplos tem a forma que tem.

Callbacks rodam na ConnectorThread

Todos os callbacks são executados em uma thread interna da DLL e compartilham uma única fila de mensagens. Trabalho lento dentro de um callback atrasa a entrega de todos os outros.

Não chame funções de requisição da DLL de dentro de um callback. As funções acessórias — TranslateTrade, GetOrderDetails, GetPriceGroup, GetTheoreticalValues — são a exceção: existem para serem chamadas de dentro do callback que as acompanha.

O padrão correto é copiar os dados e processá-los em outra thread:

import queue, threading

fila = queue.Queue()

@WINFUNCTYPE(None, TAssetID, c_double, c_int, c_int)
def tinyBookCallback(assetId, price, qtd, side):
    fila.put((assetId.ticker, price, qtd, side))   # rápido: só enfileira

def consumidor():
    while True:
        dado = fila.get()
        processa(dado)                              # trabalho pesado aqui

threading.Thread(target=consumidor, daemon=True).start()

Referências de callback precisam sobreviver ao registro

Em C# o coletor de lixo recolhe o delegate assim que ele sai da pilha; por isso Program.cs mantém um campo static readonly por callback. Em Python, as funções decoradas com @WINFUNCTYPE no nível do módulo cumprem o mesmo papel — nunca crie o objeto de callback no próprio ponto da chamada.

Estruturas TConnector* têm campo Version

Toda estrutura moderna começa com Version : Byte, que você precisa preencher antes de passar a estrutura. Versão não preenchida ou não suportada devolve NL_VERSION_NOT_SUPPORTED. A maioria aceita 0; TConnectorSendOrder aceita 0 ou 1 (a versão 1 muda a codificação de OrderType/OrderSide).

Estruturas *Out exigem duas chamadas

Chame uma vez com os campos de texto vazios — a DLL preenche os contadores *Length. Aloque os buffers com esses tamanhos e chame de novo para receber o conteúdo. Pular a primeira chamada devolve strings vazias, não um erro.

def getAccountDetails(accountId):
    account = TConnectorTradingAccountOut(Version=1, AccountID=accountId)
    if profit_dll.GetAccountDetails(byref(account)) != NL_OK:
        return None
    account.BrokerName   = ' ' * account.BrokerNameLength     # aloca
    account.OwnerName    = ' ' * account.OwnerNameLength
    account.SubOwnerName = ' ' * account.SubOwnerNameLength
    if profit_dll.GetAccountDetails(byref(account)) != NL_OK: # 2ª chamada
        return None
    return account

O mesmo padrão vale para GetAgentNameLength → GetAgentName e para as APIs de contar-e-preencher (GetAccountCount → GetAccounts).

Códigos de retorno NResult

NL_OK é 0; erros são negativos (NL_INTERNAL_ERROR = 0x80000001). As funções de envio de ordem devolvem um LocalOrderID positivo em caso de sucesso — por isso teste < 0, e não != 0. A tabela do manual lista 32 códigos; a enumeração canônica, Exemplo Delphi/Types/ProfitConstantsU.pas, define 47. Os 15 que só existem no cabeçalho Delphi (13 deles adicionados desde a 4.0.0.31) são retornos válidos e estão aqui para que nenhum código fique sem nome:

Conexão é uma máquina de estados de quatro canais

O StateCallback(nConnStateType, nResult) informa cada canal separadamente. Só emita requisições depois que os canais relevantes estiverem prontos:

Desde a 4.0.0.39 o canal de market data também devolve MARKET_PERFORMANCE_WARNING (5) e MARKET_PARTIAL_CONNECTED (6) — o feed do servidor está bom, mas a entrega local de callbacks está degradada. Trate o estado 6 como aviso crítico.

Identificação de ativos

Um ativo é a tripla (ticker, bolsa, feed). A bolsa é um código de um caractere:

O campo de feed é 0 (Nelogica) ou 255 (outro).

Histórico de trades tem limites de janela

GetHistoryTrades recusa requisições cuja data inicial seja anterior a 30 dias (NL_HISTORY_PERIOD_LIMIT). Para tickers iniciados em WIN ou WDO, o intervalo entre dtDateStart e dtDateEnd não pode alcançar 10 dias (NL_INVALID_ARGS) — requisite o histórico desses contratos dia a dia e use TProgressCallback para detectar o fim de cada carga.

Novidades 4.0.0.31 → 4.0.0.42

4.0.0.42 em resumo

Versão de correções: nenhuma API, estrutura ou constante foi adicionada ou removida na DLL.

• DLL: corrigido atraso na entrega das callbacks de ordem; corrigida exceção ao realizar um novo SubscribeOfferBook; corrigido o identificador de processo (PID) enviado pela DLL ao servidor.
• Manual: GetHistoryTrades passou a documentar os limites de 30 dias (NL_HISTORY_PERIOD_LIMIT) e de 10 dias para WIN/WDO (NL_INVALID_ARGS); a seção de RequestSerieHistory foi removida — GetHistoryTrades é a única API de histórico de trades documentada.
• Exemplo Python: o comando requestHistory virou getHistoryTrades (a função já chamava GetHistoryTrades). Os demais exemplos não mudaram.

Novas APIs

A partir da 4.0.0.41 a DLL monitora suas threads internas (Main e Calc) com um watchdog e passa a gravar logs de performance (sampling profiler) em disco na versão 64 bits.

Novas constantes

Além desses, ProfitConstantsU.pas ganhou 14 códigos NResult desde a

4. .0.31, mas só NL_HISTORY_PERIOD_LIMIT entrou na tabela do manual — os demais estão listados em Códigos de retorno NResult.

Mudança de ABI — atenção

Na 4.0.0.38, os campos nMinOrderQtd, nMaxOrderQtd e nLote de TAssetListInfoCallback e TAssetListInfoCallbackV2 mudaram de Integer para Int64. Quem registra essas callbacks precisa atualizar as assinaturas — caso contrário a pilha é corrompida na chamada.

Correções relevantes

• SetTradeCallbackV2 parava de receber trades (4.0.0.38).
• Access Violation em PopulateOrderOutV0 durante picos de volume (4.0.0.39).
• Callbacks de ordem sem atualização: confirmações intermediárias de roteamento eram tratadas como definitivas (4.0.0.41). Espere mais eventos por ordem; o consumo precisa ser idempotente.
• Atraso na entrega das callbacks de ordem (4.0.0.42).
• Exceção ao realizar um novo SubscribeOfferBook (4.0.0.42).
• Identificador de processo (PID) enviado pela DLL ao servidor (4.0.0.42).

Troubleshooting

Extras — recursos oficiais e comunidade

Esta seção reúne os canais oficiais da Nelogica sobre a ProfitDLL e projetos abertos da comunidade que a utilizam. Nada aqui substitui a licença nem o suporte da Nelogica.

Download oficial da ProfitDLL

A última versão do pacote oficial — DLL de 32 e 64 bits, executável de teste em Delphi, arquivos de interface, os manuais em PDF e os exemplos nas quatro linguagens — está em:

https://download-setup.nelogica.com.br/connector/latest/ProfitDLL.zip

O mesmo pacote também é oferecido na área do cliente Nelogica (login → Assinaturas → licença DLL Feed → Download). A DLL só funciona com uma chave de ativação e uma conta habilitada; quem ainda não é cliente deve contratar o Data Solution pela NeloStore.

Ajuda oficial (Nelogica)

Para dúvidas gerais sobre o Data Solution (DLL) ou questões de suporte, use os canais da própria Nelogica:

• Central de ajuda: https://ajuda.nelogica.com.br/
• Seção DataFeed - DLL da central de ajuda, com os artigos abaixo: https://ajuda.nelogica.com.br/hc/pt-br/sections/11307712057883-DataFeed-DLL

Blog Nelogica — categoria Data Solution

Todos os posts publicados pela Nelogica na categoria https://blog.nelogica.com.br/categoria/data-solution/ (levantamento de 2026-09-10; posts em português):

Exemplos de utilização da comunidade

Projetos abertos, independentes da Nelogica, que mostram a ProfitDLL em uso real. A DLL em si continua tendo de ser obtida da Nelogica.

Agradecimentos

Obrigado a Marcelo Rahal Coutinho (YouTrade) e a Diogo Ribeiro por publicarem esses projetos em código aberto — eles são a melhor referência prática, além dos exemplos oficiais, de como a ProfitDLL se comporta em C# e em Python.

Licença e créditos

A ProfitDLL, seus manuais e os exemplos de código são propriedade da Nelogica. Este repositório apenas organiza e converte essa documentação para Markdown; não redistribui a biblioteca. Os projetos da comunidade citados acima têm licenças e autores próprios e não são afiliados à Nelogica.

Documentação oficial da ProfitDLL (central de ajuda, seção DataFeed - DLL): https://ajuda.nelogica.com.br/hc/pt-br/sections/11307712057883-DataFeed-DLL