# 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

```python
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.

```python
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).

## Links

- [B3](https://www.b3.com.br)
- [BVBG-086 Download](https://www.b3.com.br/pesquisapregao/download)
