Ir para o conteúdo

B3 Futuros Agro

Visao Geral

Campo Valor
Provedor B3 — Brasil, Bolsa, Balcao
Dados Ajustes diários (settlement prices) + posicoes em aberto (open interest) de futuros agrícolas
Acesso ZIP/XML BVBG-086 (b3.com.br) + CSV API (arquivos.b3.com.br)
Formato ZIP nested (XML streaming via lxml.etree.iterparse) + CSV (; separator)
Autenticação Nenhuma
Licença zona_cinza — FAQ D-1 e termos do site com alcances distintos
Contratos BGI (boi), CCM (milho), ICF (cafe arabica), CNL (cafe conillon), ETH (etanol), SJC (soja cross), SOY (soja FOB)

Origem dos Dados

A B3 publica diariamente os ajustes (settlement prices) de todos os contratos futuros negociados. A fonte e o arquivo BVBG-086 (ZIP nested contendo snapshots XML) disponível em b3.com.br/pesquisapregao/download. O ZIP contem snapshots intradiarios; o agrobr usa o ultimo (snapshot 03, definitivo). Parsing via lxml.etree.iterparse (streaming, sem carregar XML inteiro em memoria). Filtra apenas os 7 contratos agrícolas.

Adicionalmente, a B3 disponibiliza posicoes em aberto (open interest) de derivativos via CSV publico em arquivos.b3.com.br. O download segue fluxo de 2 etapas: (1) obter token via requestname, (2) baixar CSV com o token. O parser filtra apenas o segmento AGRIBUSINESS e classifica cada posicao como futuro ou opcao.

Contratos Agrícolas

Ticker Contrato Unidade
BGI Boi Gordo BRL/@
CCM Milho BRL/sc60kg
ICF Cafe Arabica USD/sc60kg
CNL Cafe Conillon BRL/sc60kg
ETH Etanol Hidratado BRL/m3
SJC Soja Cross USD/sc60kg
SOY Soja FOB Santos USD/ton

Detalhes Técnicos — Ajustes

Fonte primaria: BVBG-086 ZIP

  • URL: https://www.b3.com.br/pesquisapregao/download?filelist=PR{yymmdd}.zip
  • Estrutura: ZIP externo → ZIP interno (BVBG086.zip) → 3 snapshots XML (PR{yymmdd}01.xml, 02, 03)
  • Snapshot: Ultimo (03) e o definitivo
  • Namespace XML: urn:bvmf.217.01.xsd (inner), urn:bvmf.052.01.xsd (outer envelope)
  • Parsing: lxml.etree.iterparse com cleanup de parent refs (streaming, ~51K registros por arquivo)
  • Filtragem: Apenas futuros agro (regex ^[A-Z]{2,4}[FGHJKMNQUVXZ]\d{2}$, ticker-base in TICKERS_AGRO)

Exemplo de Uso

import agrobr

# Ajustes de uma data
df = await agrobr.b3.ajustes(data="13/02/2025")

# Filtrar por contrato (nome ou ticker)
df = await agrobr.b3.ajustes(data="13/02/2025", contrato="boi")
df = await agrobr.b3.ajustes(data="13/02/2025", contrato="CCM")

# Serie historica (loop de dias uteis)
from datetime import date
df = await agrobr.b3.historico(
    contrato="boi",
    inicio=date(2025, 2, 10),
    fim=date(2025, 2, 14),
)

# Filtrar por vencimento
df = await agrobr.b3.historico(
    contrato="boi",
    inicio=date(2025, 2, 10),
    fim=date(2025, 2, 14),
    vencimento="G25",
)

# Listar contratos disponiveis
print(agrobr.b3.contratos())

# Com metadados
df, meta = await agrobr.b3.ajustes(data="13/02/2025", return_meta=True)

Posicoes em Aberto (Open Interest)

Posicoes em aberto (open interest) de futuros e opcoes agro, via CSV publico da B3.

import agrobr
from datetime import date

# OI de uma data
df = await agrobr.b3.posicoes_abertas(data=date(2025, 12, 19))

# Filtrar por contrato
df = await agrobr.b3.posicoes_abertas(data=date(2025, 12, 19), contrato="boi")

# Apenas futuros (sem opcoes)
df = await agrobr.b3.posicoes_abertas(data=date(2025, 12, 19), tipo="futuro")

# Serie historica de OI
df = await agrobr.b3.posicoes_abertas_historico(
    contrato="boi",
    inicio=date(2025, 12, 15),
    fim=date(2025, 12, 19),
)

Detalhes Técnicos — Open Interest

  • URL: https://arquivos.b3.com.br/api/download/requestname?fileName=DerivativesOpenPosition&date=YYYY-MM-DD
  • Fluxo: 2 etapas (token + download)
  • Formato: CSV, separador ;, encoding UTF-8
  • Dados: ~500 linhas agro por dia (futuros + opcoes)
  • Assets agro: BGI, CCM, ETH, ICF, SJC (+ CNL em datas mais antigas)
  • Contract: POSICOES_ABERTAS_V1 (PK: data + ticker_completo)
  • Vencimento: vencimento_codigo é o XprtnCd publicado, nos dois formatos do glossário UP2DATA da B3: MYY no futuro (ex.: F26) e MYOA na opção (ex.: FVI1: mês, ano, código da opção e sequencial). vencimento_mes e vencimento_ano são o mês e o ano do contrato, também na opção. Vêm do ticker da série (BGIF26C030000 → janeiro de 2026), conferido com a letra do mês do código. Ticker ou código fora desses formatos levanta ParseError.
  • Expiração antes do mês do contrato: a data em que o instrumento expira (XprtnDt do cadastro da B3) pode cair no mês anterior. No cadastro de 22/09/2026, isso vale para as opções de café arábica e conillon e para futuros e opções de soja cross e soja FOB. Ex.: ICFH27C035000 expira em 12/02/2027 e SJCF27 em 29/12/2026. Boi, milho e etanol expiram no mês do contrato.
  • Filtro vencimento (posicoes_abertas_historico): o código do mês do contrato (ex.: F26, maiúsculas ou minúsculas) traz o futuro e as opções daquele mês; o código publicado de uma opção (ex.: FVI1) traz só aquela série. Outro formato levanta InvalidParameterError antes da rede.

Limitacoes

  • Open interest: não inclui breakdown por categoria de investidor (COT), apenas totais
  • Weekend e feriados retornam DataFrame vazio (sem pregao), com os dtypes do contrato (ajuste_diario ou posicoes_abertas). Em ajustes, o pregão ainda não publicado (antes de ~18h) também sai vazio, sem aviso: a B3 responde com um ZIP vazio nos 2 casos (22 bytes, sem arquivo dentro). Qualquer outro corpo curto, como um JSON de indisponibilidade com HTTP 200, levanta SourceUnavailableError e, no historico, entra em failed_dates
  • Contrato fora de b3.contratos() (nome ou ticker, sem diferença de caixa), data fora de AAAA-MM-DD/DD/MM/AAAA, inicio depois de fim e tipo fora de futuro/opcao levantam InvalidParameterError antes da rede
  • historico baixa um ZIP de ~11 MB por dia útil, com no máximo AGROBR_HTTP_MAX_CONCURRENT_B3 dias (padrão 3) abertos ao mesmo tempo; um ano são ~250 downloads
  • historico levanta SourceUnavailableError quando todos os dias consultados falham por erro de rede ou parsing; dias consultados com sucesso e sem publicação preservam o resultado vazio. Dia sem pregão (feriado ou pregão ainda não publicado) não conta como falha: entra em meta.source_details["coverage"]["empty_dates"], sem o aviso de histórico incompleto, e o período só com esses dias sai vazio.
  • datasets.futuros_agricolas sem data procura um resultado publicado nos cinco dias úteis recentes, continuando após dias vazios. Uma data explícita não inicia essa busca.
  • Rate limit recomendado: 1 req/s (respeitar o servidor)

Cache e Atualização

  • Não há cache local: cada chamada baixa os dados da B3.
  • Os ajustes são publicados uma vez por dia, após ~18h no dia do pregão.
  • No boi gordo (BGI), o ajuste do último dia de negociação não é o preço de liquidação: pela especificação do contrato na B3, a liquidação usa a média de 5 publicações do Indicador do Boi DATAGRO a partir do vencimento de fevereiro de 2025 (BGIG25) e do Indicador do Boi Gordo CEPEA/B3 até o de janeiro de 2025 (BGIF25), pelo Ofício Circular B3 135/2024-PRE; o preco_diario do agrobr publica o CEPEA, não o DATAGRO. No milho (CCM), o ajuste do vencimento é o preço de liquidação.
  • O arquivo do pregão também traz registros do after-hours datados de D+1 com o mesmo ajuste; ajustes() devolve só as linhas com a data pedida (o historico não repete contratos entre dias consecutivos).
  • Dados históricos são estáticos e não mudam retroativamente.

Licença

A B3 mantém a classificação zona_cinza. A FAQ dispensa autorização prévia para determinados dados de fim de dia e históricos a partir de D-1 obtidos das plataformas Market Data B3, mas os termos do website condicionam uso comercial e redistribuição. Não foi demonstrado que a dispensa cubra os arquivos de ajustes e posições em aberto usados pelo agrobr. A política vigente até 31/10/2026 e a política anunciada para 01/11/2026 têm vigências separadas; o conteúdo da política futura não fundamenta esta classificação. Conferir o canal e o uso concreto nos documentos oficiais da B3. A categoria não afirma permissão comercial nem ausência de termos.

Disponibilidade de posições em aberto

A B3 mantém alguns dias recentes de DerivativesOpenPosition, inclusive datas anteriores ao dia corrente, sem garantir um arquivo histórico completo. HTTP 400/404 na solicitação do token indica arquivo não publicado e retorna vazio após validação da data. No download, HTTP 404 retorna vazio, mas HTTP 400 levanta SourceUnavailableError. As operações token/download são serializadas no processo; o histórico consulta os dias sequencialmente. Se outra consulta das posições em aberto não solta a vez por AGROBR_HTTP_TIMEOUT_READ segundos (padrão 30), por exemplo uma tarefa do loop parado pelo agrobr.sync, a que espera levanta ResourceLimitError (não SourceUnavailableError: não é pregão indisponível); repita a consulta ou serialize as chamadas, e dentro de um loop prefira o await.