Posições em aberto em derivativos agropecuários¶
Resumo¶
O arquivo DerivativesOpenPosition da B3 traz, depois de cada pregão, as posições em aberto de todos os contratos de derivativos listados. O fetcher guarda o arquivo diário e o lake mantém só as linhas do segmento AGRIBUSINESS, particionadas por contrato (ativo-objeto). Serve para acompanhar o interesse aberto dos futuros e opções agropecuários.
Ficha técnica¶
| Campo | Valor |
|---|---|
| Dataset | b3/derivativos_agro |
| Órgão | B3 S.A. - Brasil, Bolsa, Balcão |
| Página oficial | https://b3.com.br/data/files/1E/D1/BA/58/C841B810E9C1AAA8AC094EA8/DerivativesOpenPositionFile%202023.pdf |
| Licença | Não informado pela fonte. O glossário diz que o arquivo é um dado regulatório divulgado conforme a política de dados regulatórios da B3; veja também os Termos e Condições de Uso (https://www.b3.com.br/pt_br/termos-de-uso-e-protecao-de-dados/termos-de-uso/) |
| Periodicidade | diária, após o pregão (dias úteis) |
| Cobertura | 2026-10 a em-curso |
| Unidade (uma linha) | um instrumento (contrato com vencimento) do segmento AGRIBUSINESS em um dia |
| Granularidade | espacial: nacional (bolsa); temporal: dia |
| Formato bruto | CSV separado por ponto e vírgula, UTF-8, vírgula decimal, uma linha de cabeçalho; algumas respostas têm antes uma linha 'Status do Arquivo' |
| Estado no lake | convertido |
| Partições | ano, mes, dia, contrato |
| Chave | data_referencia, ticker |
| Colunas | 17 |
| Unidades de medida | contratos_em_aberto: contratos; variacao_contratos_em_aberto: contratos; qtd_coberta: quantidade (sempre nula neste dataset); total_posicoes_bloqueadas: posições (sempre nula neste dataset); qtd_descoberta: quantidade (sempre nula neste dataset); total_posicoes: posições (sempre nula neste dataset); qtd_tomador: clientes (sempre nula neste dataset); qtd_doador: clientes (sempre nula neste dataset); qtd_atual: ações (sempre nula neste dataset); preco_termo: moeda não informada pela fonte (sempre nulo neste dataset) |
| Dados pessoais | nenhum |
| Eras | nenhuma |
| Revisado em | 2026-11-09 |
| Versão do fetcher | 0.4.1 |
Origem e coleta¶
- O serviço de arquivos da B3 entrega o arquivo em duas etapas: um pedido com o nome do arquivo (
DerivativesOpenPosition) e a data devolve um token, e o download usa o token. Datas sem arquivo (fim de semana, feriado, data futura) respondem erro 400, que o fetcher ignora sem erro. - Por padrão o fetcher lista os últimos 5 dias úteis; o prazo é ajustável.
- No bruto, cada dia é
derivativos_agro-<AAAA-MM-DD>.csv. - Conferido em 2026-11-09 pela listagem do bruto: cinco dias (2026-10-29, 2026-10-30, 2026-11-03, 2026-11-04 e 2026-11-05). Não há histórico anterior a 2026-10-29 no bruto conferido.
Conteúdo¶
- Unidade: um instrumento (ticker) em um dia. Duas amostras convertidas em 2026-11-09 (2026-10-29 e 2026-11-05) somam 1.489 linhas e 799 tickers; o ticker é único em cada dia.
- Contratos (valor de
ativo_objetoe da partiçãocontrato) nas amostras: BGI, CCM, CNL (uma linha), ETH, ICF e SJC. - O arquivo original contém também outros segmentos (como
EQUITY CALL,EQUITY PUTeEQUITY FORWARD); o conversor mantém sóAGRIBUSINESS. Por isso as colunas de empréstimo e opções sobre ações (deid_distribuicaoapreco_termo) ficam todas nulas neste dataset. - Não há eras: o layout é o mesmo nas duas amostras.
Variáveis¶
Descrições do glossário oficial da B3 para o arquivo DerivativesOpenPosition (versão de 05/10/2023). A coluna ano, mes, dia e contrato são partições.
| Coluna no lake | Na fonte | Tipo | Descrição | Unidade / códigos | Período |
|---|---|---|---|---|---|
ano |
data do nome do arquivo | inteiro (partição) | Ano da data do arquivo | ano de 4 dígitos | todo |
mes |
data do nome do arquivo | inteiro (partição) | Mês da data do arquivo | 1 a 12 | todo |
dia |
data do nome do arquivo | inteiro (partição) | Dia da data do arquivo | 1 a 31 | todo |
contrato |
Asst |
texto (partição) | Ativo-objeto do instrumento; repete ativo_objeto |
BGI, CCM, CNL, ETH, ICF, SJC (amostras) |
todo |
data_referencia |
RptDt |
data | Data de referência da informação | AAAA-MM-DD na fonte |
todo |
ticker |
TckrSymb |
texto | Código que identifica um instrumento negociado ou registrado em bolsa | como BGIF27 |
todo |
codigo_isin |
ISIN |
texto | International Securities Identification Number do instrumento (estrutura BR AAAA BBB CC D, segundo o glossário) | 12 caracteres | todo |
ativo_objeto |
Asst |
texto | Mercadoria associada ao instrumento | exemplos do glossário: DOL, BGI, OZ1, WDL, CNI, ICF, CCM | todo |
codigo_vencimento |
XprtnCd |
texto | Código de expiração do contrato, no formato MYY (mês e dois dígitos do ano) ou MYOA (mês, ano, código da opção e sequência alfanumérica) | como F27 (futuro) ou VVK7 (opção) |
todo |
segmento |
SgmtNm |
texto | Nome do segmento | AGRIBUSINESS (único valor mantido) |
todo |
contratos_em_aberto |
OpnIntrst |
inteiro | Quantidade de contratos em aberto | contratos | todo |
variacao_contratos_em_aberto |
VartnOpnIntrst |
inteiro | Variação da quantidade de contratos abertos de um dia para o outro | contratos; pode ser negativa | todo |
id_distribuicao |
DstrbtnId |
texto | Código de distribuição do papel; o glossário diz que não há distribuição de derivativos | sempre nulo aqui | todo |
qtd_coberta |
CvrdQty |
inteiro | Quantidade coberta | sempre nula aqui | todo |
total_posicoes_bloqueadas |
TtlBlckdPos |
inteiro | Total de posições travadas | sempre nula aqui | todo |
qtd_descoberta |
UcvrdQty |
inteiro | Quantidade descoberta | sempre nula aqui | todo |
total_posicoes |
TtlPos |
inteiro | Total de posições | sempre nula aqui | todo |
qtd_tomador |
BrrwrQty |
inteiro | Quantidade de clientes tomadores | sempre nula aqui | todo |
qtd_doador |
LndrQty |
inteiro | Quantidade de clientes doadores | sempre nula aqui | todo |
qtd_atual |
CurQty |
inteiro | Quantidade de ações vinculadas a contratos em aberto | sempre nula aqui | todo |
preco_termo |
FwdPric |
decimal(28,8) | Preço médio das posições em aberto | vírgula decimal na fonte; sempre nulo aqui | todo |
No lake¶
- Dataset
b3/derivativos_agro, particionado porano,mes,diaecontrato, um Parquet por contrato e dia. - Só as linhas com
SgmtNm = AGRIBUSINESSentram; linhas sem ativo-objeto são descartadas. - O arquivo é lido todo como texto; só as quantidades viram inteiro e
preco_termodecimal, com conversão estrita (valor inválido faz o arquivo falhar). Tickers e ISIN nunca viram número. - O conversor falha se o arquivo não tiver o cabeçalho esperado (por exemplo, uma página HTML no lugar do CSV).
- Nomes de coluna renomeados do inglês para português (tabela acima).
- Esquema de referência (
derivativos_agro.schema.json): 17 colunas, de uma conversão de duas datas.
Cuidados de uso¶
- Nove colunas sempre nulas.
id_distribuicao,qtd_coberta,total_posicoes_bloqueadas,qtd_descoberta,total_posicoes,qtd_tomador,qtd_doador,qtd_atualepreco_termosão nulas nas 1.489 linhas das amostras (2026-11-09). Elas pertencem a outros segmentos do mesmo arquivo. - Cobertura curta. O bruto conferido só tem cinco dias; não há série histórica longa.
- Sem arquivo em dias sem pregão. Fim de semana e feriado não geram linhas.
- Interesse aberto não é volume negociado.
contratos_em_abertoé um estoque ao fim do dia. - Licença. Não informada pela fonte; consulte os termos de uso da B3 antes de redistribuir.
Exemplos¶
Contratos em aberto de boi gordo (BGI) por vencimento no último dia coletado:
import polars as pl
d = pl.scan_parquet("lake/b3/derivativos_agro/**/*.parquet", hive_partitioning=True)
ultimo = d.select(pl.col("data_referencia").max()).collect().item()
bgi = (
d.filter((pl.col("data_referencia") == ultimo) & (pl.col("ativo_objeto") == "BGI"))
.select(
"ticker",
"codigo_vencimento",
"contratos_em_aberto",
"variacao_contratos_em_aberto",
)
.sort("contratos_em_aberto", descending=True)
.collect()
)
Referências¶
- Glossário do arquivo DerivativesOpenPosition (B3, 05/10/2023): https://b3.com.br/data/files/1E/D1/BA/58/C841B810E9C1AAA8AC094EA8/DerivativesOpenPositionFile%202023.pdf
- Termos e Condições de Uso da B3: https://www.b3.com.br/pt_br/termos-de-uso-e-protecao-de-dados/termos-de-uso/