B3 Agricultural Futures¶

Overview¶

Field	Value
Provider	B3 — Brasil, Bolsa, Balcao
Data	Daily settlements (settlement prices) + open interest of agricultural futures
Access	ZIP/XML BVBG-086 (b3.com.br) + CSV API (arquivos.b3.com.br)
Format	Nested ZIP (XML streaming via lxml.etree.iterparse) + CSV (`;` separator)
Authentication	None
License	zona_cinza — private company, no terms for programmatic access
Contracts	BGI (cattle), CCM (corn), ICF (arabica coffee), CNL (conillon coffee), ETH (ethanol), SJC (soybean cross), SOY (soybean FOB)

Data Origin¶

B3 publishes daily the settlements (settlement prices) of all traded futures contracts. The source is the BVBG-086 file (nested ZIP containing XML snapshots) available at b3.com.br/pesquisapregao/download. The ZIP contains intraday snapshots; agrobr uses the last one (snapshot 03, definitive). Parsing via lxml.etree.iterparse (streaming, without loading the entire XML into memory). It filters only the 7 agricultural contracts.

Additionally, B3 makes open interest of derivatives available via public CSV at arquivos.b3.com.br. The download follows a 2-step flow: (1) obtain a token via requestname, (2) download the CSV with the token. The parser filters only the AGRIBUSINESS segment and classifies each position as future or option.

Agricultural Contracts¶

Ticker	Contract	Unit
BGI	Live Cattle	BRL/@
CCM	Corn	BRL/sc60kg
ICF	Arabica Coffee	USD/sc60kg
CNL	Conillon Coffee	USD/ton
ETH	Hydrous Ethanol	BRL/m3
SJC	Soybean Cross	USD/sc60kg
SOY	Soybean FOB Santos	USD/ton

Technical Details — Settlements¶

Primary source: BVBG-086 ZIP¶

URL: https://www.b3.com.br/pesquisapregao/download?filelist=PR{yymmdd}.zip
Structure: outer ZIP → inner ZIP (BVBG086.zip) → 3 XML snapshots (PR{yymmdd}01.xml, 02, 03)
Snapshot: The last one (03) is the definitive
XML namespace: urn:bvmf.217.01.xsd (inner), urn:bvmf.052.01.xsd (outer envelope)
Parsing: lxml.etree.iterparse with cleanup of parent refs (streaming, ~51K records per file)
Filtering: Only agricultural futures (regex ^[A-Z]{2,4}[FGHJKMNQUVXZ]\d{2}$, base ticker in TICKERS_AGRO)

Usage Example¶

import agrobr

# Settlements for a date
df = await agrobr.b3.ajustes(data="13/02/2025")

# Filter by contract (name or ticker)
df = await agrobr.b3.ajustes(data="13/02/2025", contrato="boi")
df = await agrobr.b3.ajustes(data="13/02/2025", contrato="CCM")

# Historical series (loop over business days)
from datetime import date
df = await agrobr.b3.historico(
    contrato="boi",
    inicio=date(2025, 2, 10),
    fim=date(2025, 2, 14),
)

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

# List available contracts
print(agrobr.b3.contratos())

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

Open Interest¶

Open interest of agricultural futures and options, via B3's public CSV.

import agrobr
from datetime import date

# Open interest for a date
df = await agrobr.b3.posicoes_abertas(data=date(2025, 12, 19))

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

# Futures only (no options)
df = await agrobr.b3.posicoes_abertas(data=date(2025, 12, 19), tipo="futuro")

# Historical series of open interest
df = await agrobr.b3.oi_historico(
    contrato="boi",
    inicio=date(2025, 12, 15),
    fim=date(2025, 12, 19),
)

Technical Details — Open Interest¶

URL: https://arquivos.b3.com.br/api/download/requestname?fileName=DerivativesOpenPosition&date=YYYY-MM-DD
Flow: 2 steps (token + download)
Format: CSV, separator ;, UTF-8 encoding
Data: ~500 agricultural rows per day (futures + options)
Agricultural assets: BGI, CCM, ETH, ICF, SJC (+ CNL on older dates)
Contract: POSICOES_ABERTAS_V1 (PK: data + ticker_completo)

Limitations¶

Open interest: does not include breakdown by investor category (COT), only totals
Weekends and holidays return an empty DataFrame (no trading session)
Recommended rate limit: 1 req/s (respect the server)

Cache and Update¶

TTL: 4 hours (settlements published once a day after close)
Settlements are published after ~18h on the trading session day
Historical data is static (does not change retroactively)

License¶

Classification: zona_cinza

B3 is a private company. Daily settlements are the official reference for margin calculation (CVM requirement) and are published openly without authentication. There are no specific terms of use for programmatic access.

Educational and research use. Redistribution in a commercial product must be verified with B3 (marketdata@b3.com.br).