B3 Futuros Agro¶

Visao Geral¶

Campo	Valor
Provedor	B3 — Brasil, Bolsa, Balcao
Dados	Ajustes diarios (settlement prices) + posicoes em aberto (open interest) de futuros agricolas
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)
Autenticacao	Nenhuma
Licenca	zona_cinza — empresa privada, sem termos para acesso programatico
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) disponivel 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 agricolas.

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 Agricolas¶

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

Detalhes Tecnicos — 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.oi_historico(
    contrato="boi",
    inicio=date(2025, 12, 15),
    fim=date(2025, 12, 19),
)

Detalhes Tecnicos — 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)

Limitacoes¶

Open interest: nao inclui breakdown por categoria de investidor (COT), apenas totais
Weekend e feriados retornam DataFrame vazio (sem pregao)
Rate limit recomendado: 1 req/s (respeitar o servidor)

Cache e Atualizacao¶

TTL: 4 horas (ajustes publicados 1x/dia apos fechamento)
Ajustes sao publicados apos ~18h no dia do pregao
Dados historicos sao estatiticos (nao mudam retroativamente)

Licenca¶

Classificacao: zona_cinza

A B3 e empresa privada. Ajustes diarios sao referencia oficial para calculo de margem (exigencia CVM) e sao publicados abertamente sem autenticacao. Nao ha termos de uso especificos para acesso programatico.

Uso educacional e de pesquisa. Redistribuicao em produto comercial deve ser verificada com B3 (marketdata@b3.com.br).