# B3 Futuros Agro

Ajustes diarios (settlement prices) e posicoes em aberto (open interest) de contratos futuros agricolas negociados na B3: boi gordo, milho, cafe, etanol, soja.

## `b3.ajustes()`

Ajustes diarios de uma data especifica.

```python
import agrobr

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

### Parametros

| Parametro | Tipo | Obrigatorio | Descricao |
|-----------|------|-------------|-----------|
| `data` | `str \| date` | Sim | Data no formato "dd/mm/yyyy" ou objeto `date` |
| `contrato` | `str` | Nao | Nome ("boi", "milho") ou ticker ("BGI", "CCM"). Se None, todos |
| `return_meta` | `bool` | Nao | Se True, retorna `(DataFrame, MetaInfo)` |

### Colunas de Retorno

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `data` | datetime | Data do pregao |
| `ticker` | str | Codigo do contrato (BGI, CCM, ICF, CNL, ETH, SJC, SOY) |
| `descricao` | str | Nome do contrato (ex: "Boi gordo") |
| `vencimento_codigo` | str | Codigo 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 |
| `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.

```python
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") |
| `inicio` | `str \| date` | Sim | Data inicial (formato "YYYY-MM-DD" ou `date`) |
| `fim` | `str \| date` | Sim | Data final (formato "YYYY-MM-DD" ou `date`) |
| `vencimento` | `str` | Nao | Filtrar por vencimento (ex: "G25") |
| `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 agricolas disponiveis.

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

```python
import agrobr
from datetime import date

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

### Parametros

| Parametro | Tipo | Obrigatorio | Descricao |
|-----------|------|-------------|-----------|
| `data` | `str \| date` | Sim | Data no formato "YYYY-MM-DD" ou objeto `date` |
| `contrato` | `str` | Nao | Nome ("boi", "milho") ou ticker ("BGI", "CCM"). Se None, todos |
| `tipo` | `str` | Nao | `"futuro"` ou `"opcao"`. Se None, todos |
| `return_meta` | `bool` | Nao | Se True, retorna `(DataFrame, MetaInfo)` |

### Colunas de Retorno

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `data` | datetime | Data de referencia |
| `ticker` | str | Codigo do ativo (BGI, CCM, ICF, ETH, SJC) |
| `descricao` | str | Nome do contrato (ex: "boi", "milho") |
| `ticker_completo` | str | Ticker completo (ex: "BGIF26", "BGIF26C030000") |
| `vencimento_codigo` | str | Codigo de vencimento (ex: "F26") |
| `vencimento_mes` | int | Mes de vencimento (1-12) |
| `vencimento_ano` | int | Ano de vencimento |
| `tipo` | str | "futuro" ou "opcao" |
| `posicoes_abertas` | int | Numero de posicoes em aberto (contratos) |
| `variacao_posicoes` | int | Variacao vs dia anterior |
| `unidade` | str | Unidade (BRL/@, BRL/sc60kg, USD/sc60kg, etc.) |

---

## `b3.oi_historico()`

Serie historica de posicoes em aberto. Itera sobre dias uteis no periodo.

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

### Parametros

| Parametro | Tipo | Obrigatorio | Descricao |
|-----------|------|-------------|-----------|
| `contrato` | `str` | Sim | Nome ("boi") ou ticker ("BGI") |
| `inicio` | `str \| date` | Sim | Data inicial (formato "YYYY-MM-DD" ou `date`) |
| `fim` | `str \| date` | Sim | Data final (formato "YYYY-MM-DD" ou `date`) |
| `vencimento` | `str` | Nao | Filtrar por vencimento (ex: "F26") |
| `tipo` | `str` | Nao | `"futuro"` ou `"opcao"`. Se None, todos |
| `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 Sincrono

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

## Fonte dos Dados

- **Provedor:** B3 — Brasil, Bolsa, Balcao
- **URL Ajustes:** [www2.bmf.com.br/Ajustes1.asp](https://www2.bmf.com.br/pages/portal/bmfbovespa/boletim1/Ajustes1.asp)
- **URL OI:** [arquivos.b3.com.br](https://arquivos.b3.com.br/api/download/requestname?fileName=DerivativesOpenPosition)
- **Atualizacao:** Diaria (apos fechamento do pregao)
- **Licenca:** zona_cinza — empresa privada, dados publicados sem autenticacao
