# B3 Futuros Agro

## Visao Geral

| Campo | Valor |
|-------|-------|
| **Provedor** | B3 — Brasil, Bolsa, Balcao |
| **Dados** | Ajustes diarios (settlement prices) de futuros agricolas |
| **Acesso** | HTML scraping de pagina publica (www2.bmf.com.br) |
| **Formato** | HTML (BeautifulSoup + lxml) |
| **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. Os dados sao publicados apos o fechamento do pregao em uma pagina HTML publica no dominio legado `www2.bmf.com.br`.

O agrobr acessa a tabela `tblDadosAjustes` da pagina de ajustes, filtra apenas os contratos agricolas (7 tickers) e converte os numeros do formato brasileiro (`.` milhares, `,` decimal) para float.

## 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

- **URL**: `https://www2.bmf.com.br/pages/portal/bmfbovespa/boletim1/Ajustes1.asp`
- **Parametro**: `?txtData=dd/mm/yyyy`
- **Encoding**: `iso-8859-1` (meta tag declara, httpx precisa de decode manual)
- **Weekend/feriado**: pagina retorna 200 mas sem `ATUALIZADO EM` — parser retorna DataFrame vazio
- **Servidor**: Cloudflare, sem autenticacao, sem CAPTCHA

## 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)
```

## Limitacoes

- Dados somente de ajustes diarios (settlement). Volume e open interest nao incluidos
- Pagina legada pode mudar sem aviso — golden tests detectam breaking changes
- 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)
- [Ajustes Diarios](https://www2.bmf.com.br/pages/portal/bmfbovespa/boletim1/Ajustes1.asp)
