B3 Agricultural Futures

Daily settlement prices and open interest of agricultural futures contracts traded on B3: live cattle, corn, coffee, ethanol, soybean.

b3.ajustes()

Daily settlement prices for a specific date.

import agrobr

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

Parameters

Parameter	Type	Required	Description
data	str \| date	Yes	Date in "dd/mm/yyyy" format or a date object
contrato	str	No	Name ("boi", "milho") or ticker ("BGI", "CCM"). If None, all
as_polars	bool	No	If True, returns polars.DataFrame
return_meta	bool	No	If True, returns (DataFrame, MetaInfo)

Returned Columns

Column	Type	Description
data	datetime	Trading session date
ticker	str	Contract code (BGI, CCM, ICF, CNL, ETH, SJC, SOY)
descricao	str	Contract name (e.g. "Boi gordo")
vencimento_codigo	str	Expiration code (e.g. "G25")
vencimento_mes	int	Expiration month (1-12)
vencimento_ano	int	Expiration year
ajuste_anterior	float	Previous day's settlement price
ajuste_atual	float	Current day's settlement price
variacao	float	Change relative to the previous day
ajuste_por_contrato	float	Settlement amount per contract
unidade	str	Unit (BRL/@, BRL/sc60kg, USD/sc60kg, etc.)

---

b3.historico()

Historical settlement series. Iterates over business days in the period, collecting settlement prices for each day.

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",
)

Parameters

Parameter	Type	Required	Description
contrato	str	Yes	Name ("boi") or ticker ("BGI")
inicio	str \| date	Yes	Start date ("YYYY-MM-DD" format or date)
fim	str \| date	Yes	End date ("YYYY-MM-DD" format or date)
vencimento	str	No	Filter by expiration (e.g. "G25")
as_polars	bool	No	If True, returns polars.DataFrame
return_meta	bool	No	If True, returns (DataFrame, MetaInfo)

Returned Columns

Same columns as b3.ajustes(), concatenated for every date in the period.

---

b3.contratos()

List of available agricultural contracts.

import agrobr

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

Returns

list[str] — Contract names in alphabetical order.

---

---

b3.posicoes_abertas()

Open interest of agricultural futures and options for a specific date.

import agrobr
from datetime import date

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

Parameters

Parameter	Type	Required	Description
data	str \| date	Yes	Date in "YYYY-MM-DD" format or a date object
contrato	str	No	Name ("boi", "milho") or ticker ("BGI", "CCM"). If None, all
tipo	str	No	"futuro" or "opcao". If None, all
as_polars	bool	No	If True, returns polars.DataFrame
return_meta	bool	No	If True, returns (DataFrame, MetaInfo)

Returned Columns

Column	Type	Description
data	datetime	Reference date
ticker	str	Asset code (BGI, CCM, ICF, ETH, SJC)
descricao	str	Contract name (e.g. "boi", "milho")
ticker_completo	str	Full ticker (e.g. "BGIF26", "BGIF26C030000")
vencimento_codigo	str	Expiration code (e.g. "F26")
vencimento_mes	int	Expiration month (1-12)
vencimento_ano	int	Expiration year
tipo	str	"futuro" or "opcao"
posicoes_abertas	int	Number of open positions (contracts)
variacao_posicoes	int	Change vs the previous day
unidade	str	Unit (BRL/@, BRL/sc60kg, USD/sc60kg, etc.)

The arquivos.b3.com.br endpoint limits requests to 2 per 10s, with a progressive penalty. Each call consumes 2 requests (token + download); agrobr spaces them automatically (1 req/5s).

Availability window: the file only exists for the current day, published after the trading session closes — past dates return 404 (verified live in Jun/2026). The historical series only accumulates by collecting it daily; for historical weekly positioning use cftc.cot().

---

b3.oi_historico()

Historical open interest series. Iterates over business days in the period — due to the source's availability window (above), retroactive periods return empty.

from datetime import date
import agrobr

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

Parameters

Parameter	Type	Required	Description
contrato	str	Yes	Name ("boi") or ticker ("BGI")
inicio	str \| date	Yes	Start date ("YYYY-MM-DD" format or date)
fim	str \| date	Yes	End date ("YYYY-MM-DD" format or date)
vencimento	str	No	Filter by expiration (e.g. "F26")
tipo	str	No	"futuro" or "opcao". If None, all
as_polars	bool	No	If True, returns polars.DataFrame
return_meta	bool	No	If True, returns (DataFrame, MetaInfo)

Returned Columns

Same columns as b3.posicoes_abertas(), concatenated for every date in the period.

---

Synchronous Usage

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.oi_historico(contrato="boi", inicio="2025-12-15", fim="2025-12-19")
print(sync.b3.contratos())

Data Source

• Provider: B3 — Brasil, Bolsa, Balcao
• Settlement URL: b3.com.br/pesquisapregao/download (BVBG-086 ZIP/XML)
• Open interest URL: arquivos.b3.com.br
• Update: Daily (after the trading session closes)
• License: zona_cinza — private company, data published without authentication