Ir para o conteúdo

B3 Futuros Agro

Ajustes diários (settlement prices) e posicoes em aberto (open interest) de contratos futuros agrícolas negociados na B3: boi gordo, milho, cafe, etanol, soja.

b3.ajustes()

Ajustes diários de uma data específica.

import agrobr

df = await agrobr.b3.ajustes(data="13/02/2025", contrato="boi")

Parâmetros

Parâmetro Tipo Obrigatório Descrição
data str \| date Sim date, datetime ou texto AAAA-MM-DD ou DD/MM/AAAA; outro formato levanta InvalidParameterError antes da rede
contrato str Não Nome ("boi", "milho") ou ticker ("BGI", "CCM"), sem diferença de caixa; fora de b3.contratos() levanta InvalidParameterError com a lista. Se None, todos
as_polars bool Não Se True, retorna polars.DataFrame
return_meta bool Não Se True, retorna (DataFrame, MetaInfo)

Colunas de Retorno

Coluna Tipo Descrição
data datetime Data do pregao
ticker str Código do contrato (BGI, CCM, ICF, CNL, ETH, SJC, SOY)
descricao str Slug do contrato (ex.: boi, milho, cafe_arabica)
vencimento_codigo str Código de vencimento (ex: "G25")
vencimento_mes int Mes de vencimento (1-12)
vencimento_ano int Ano de vencimento
ajuste_anterior float Preco de ajuste do dia anterior
ajuste_atual float Preco de ajuste do dia
variacao float Variacao em relacao ao dia anterior
ajuste_por_contrato float Valor do ajuste por contrato, em reais em todos os contratos (inclusive ICF, SJC e SOY, cotados em dólar)
unidade str Unidade (BRL/@, BRL/sc60kg, USD/sc60kg, etc.)

b3.historico()

Serie historica de ajustes. Itera sobre dias uteis no periodo, coletando ajustes de cada dia. Cada dia é um ZIP de ~11 MB, e o período inteiro soma um download por dia útil; no máximo AGROBR_HTTP_MAX_CONCURRENT_B3 dias (padrão 3) ficam abertos ao mesmo tempo. Sem linhas, o DataFrame sai vazio com os dtypes do contrato ajuste_diario.

from datetime import date
import agrobr

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

Parametros

Parametro Tipo Obrigatorio Descricao
contrato str Sim Nome ("boi") ou ticker ("BGI"), sem diferença de caixa; fora de b3.contratos() levanta InvalidParameterError com a lista
inicio str \| date Sim Data inicial: date, datetime ou texto AAAA-MM-DD ou DD/MM/AAAA
fim str \| date Sim Data final, no mesmo formato; inicio depois de fim levanta InvalidParameterError
vencimento str Nao Código do mês do contrato (ex.: "G25"). Os ajustes só têm futuros: outro formato, inclusive o código de uma opção (ex.: "FVI1"), levanta InvalidParameterError antes da rede
as_polars bool Nao Se True, retorna polars.DataFrame
return_meta bool Nao Se True, retorna (DataFrame, MetaInfo)

Colunas de Retorno

Mesmas colunas de b3.ajustes(), concatenadas para todas as datas do periodo.

b3.contratos()

Lista de contratos agrícolas disponíveis.

import agrobr

print(agrobr.b3.contratos())
# ['boi', 'cafe_arabica', 'cafe_conillon', 'etanol', 'milho', 'soja_cross', 'soja_fob']

Retorno

list[str] — Nomes dos contratos em ordem alfabetica.

b3.posicoes_abertas()

Posicoes em aberto (open interest) de futuros e opcoes agro de uma data específica.

import agrobr
from datetime import date

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

Parâmetros

Parâmetro Tipo Obrigatório Descrição
data str \| date Sim date, datetime ou texto AAAA-MM-DD ou DD/MM/AAAA; outro formato levanta InvalidParameterError antes da rede
contrato str Não Slug (boi, milho, cafe_arabica, cafe_conillon, etanol, soja_cross) ou ticker (BGI, CCM, ICF, CNL, ETH, SJC). Se None, retorna todos
tipo str Não "futuro" ou "opcao"; outro valor levanta InvalidParameterError. Se None, todos
as_polars bool Não Se True, retorna polars.DataFrame
return_meta bool Não Se True, retorna (DataFrame, MetaInfo)

Colunas de Retorno

Coluna Tipo Descrição
data datetime Data de referencia
ticker str Código do ativo (BGI, CCM, ICF, CNL, ETH, SJC)
descricao str Slug do contrato (ex.: boi, milho, cafe_conillon)
ticker_completo str Ticker completo (ex: "BGIF26", "BGIF26C030000")
vencimento_codigo str Código de vencimento publicado (XprtnCd): "F26" no futuro, MYOA na opção (ex.: "FVI1")
vencimento_mes int Mês do contrato (1-12), também na opção
vencimento_ano int Ano do contrato, também na opção
tipo str "futuro" ou "opcao"
posicoes_abertas int Número de posicoes em aberto (contratos)
variacao_posicoes int Variacao vs dia anterior
unidade str Unidade de cotação do contrato (BRL/@, BRL/sc60kg, USD/sc60kg, etc.); posicoes_abertas e variacao_posicoes são em número de contratos

O endpoint arquivos.b3.com.br limita a 2 requisições por 10s, com penalidade progressiva. Cada chamada consome 2 requisições (token + download); o agrobr espaca automaticamente (1 req/5s).

Janela de disponibilidade: a B3 mantém alguns dias recentes, não apenas o 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. Para posicionamento semanal histórico, use cftc.cot().

b3.posicoes_abertas_historico()

Série histórica de posições em aberto. Itera sobre dias úteis no período e concatena os arquivos disponíveis na janela recente da fonte. Dias sem arquivo são ignorados conforme a distinção entre token e download acima; demais falhas são propagadas. Sem linhas, o DataFrame sai vazio com os dtypes do contrato posicoes_abertas, como em b3.posicoes_abertas().

from datetime import date
import agrobr

df = await agrobr.b3.posicoes_abertas_historico(
    contrato="boi",
    inicio=date(2025, 12, 15),
    fim=date(2025, 12, 19),
    tipo="futuro",
)

Parametros

Parametro Tipo Obrigatorio Descricao
contrato str Sim Slug (boi, milho, cafe_arabica, cafe_conillon, etanol, soja_cross) ou ticker (BGI, CCM, ICF, CNL, ETH, SJC)
inicio str \| date Sim Data inicial: date, datetime ou texto AAAA-MM-DD ou DD/MM/AAAA
fim str \| date Sim Data final, no mesmo formato; inicio depois de fim levanta InvalidParameterError
vencimento str Nao Código do mês do contrato (ex.: "F26"), que traz o futuro e as opções daquele mês, ou código publicado de uma opção (ex.: "FVI1"); outro formato levanta InvalidParameterError antes da rede
tipo str Nao "futuro" ou "opcao"; outro valor levanta InvalidParameterError. Se None, todos
as_polars bool Nao Se True, retorna polars.DataFrame
return_meta bool Nao Se True, retorna (DataFrame, MetaInfo)

Colunas de Retorno

Mesmas colunas de b3.posicoes_abertas(), concatenadas para todas as datas do periodo.

Uso Síncrono

from agrobr import sync

df = sync.b3.ajustes(data="13/02/2025")
df = sync.b3.historico(contrato="boi", inicio="2025-02-10", fim="2025-02-14")
df = sync.b3.posicoes_abertas(data="2025-12-19", contrato="boi")
df = sync.b3.posicoes_abertas_historico(contrato="boi", inicio="2025-12-15", fim="2025-12-19")
print(sync.b3.contratos())

Fonte dos Dados

  • Provedor: B3 — Brasil, Bolsa, Balcao
  • URL Ajustes: b3.com.br/pesquisapregao/download (BVBG-086 ZIP/XML)
  • URL OI: arquivos.b3.com.br
  • Atualização: Diaria (após fechamento do pregao) Classificação: zona_cinza. A dispensa D-1 da FAQ e os termos do website têm alcances distintos; confira canal, uso e vigência da política em Licenças.