API de contratos futuros da B3: cotação, histórico e curva

Um ativo futuro tem vários contratos vivos. WIN identifica o mini Ibovespa, mas o mercado negocia símbolos completos, como WINV26. A letra e o ano indicam o vencimento.

A API separa descoberta, cotação, especificações, histórico e curva em rotas diferentes, então você não baixa uma série inteira quando só quer o ajuste do último pregão.

Qual endpoint usar

Consulte parâmetros e respostas na documentação de futuros.

Descobrir símbolos negociáveis

/api/v2/futures/list aceita asset, segmento, vencidos, paginação e ordenação. Use o código base sem mês ou ano.

curl "https://brapi.dev/api/v2/futures/list?asset=WIN&includeExpired=false&sortBy=expirationDate&sortOrder=asc"

A resposta usa a coleção futures, com símbolo, ativo base, vencimento, multiplicador, lote, ISIN e CFI por item. É cadastro, não preço.

Você também pode começar pela curva:

curl "https://brapi.dev/api/v2/futures/term-structure?asset=WIN"

Essa chamada retorna os contratos ordenados por vencimento, já com dados do último pregão. Serve bem quando a tela precisa comparar todos os prazos de uma vez.

Consultar cotação e especificações

Depois de escolher o contrato, envie o símbolo completo a /quote. O parâmetro symbols aceita uma lista separada por vírgulas.

import requests

response = requests.get(
    "https://brapi.dev/api/v2/futures/quote",
    params={"symbols": "WINV26"},
    timeout=30,
)
response.raise_for_status()

quotes = response.json()["quotes"]
for quote in quotes:
    print(quote["symbol"], quote.get("settlement"))

WINV26 vence. Um código fixo no programa funciona até a virada e depois passa a retornar vazio sem erro nenhum, que é o pior tipo de falha. Descubra o contrato ativo pela listagem ou pela curva a cada execução.

O endpoint /api/v2/futures/specs?symbols=WINV26 devolve dados fixos do contrato. contractMultiplier converte pontos em valor financeiro. allocationRoundLot informa o lote. quotationType diz se o contrato usa preço ou taxa.

Entender ajuste e fechamento

settlement é o preço de ajuste divulgado para o pregão e close é o último negócio. Em contrato pouco negociado, close vem nulo e o ajuste continua lá.

Os contratos de juros exigem mais cuidado, porque misturam duas unidades na mesma resposta: close, high e low podem vir como taxa anual, enquanto settlement é preço unitário e settlementRate é a taxa ligada ao ajuste.

Leia quotationType antes de formatar. Somar um preço unitário a uma taxa é um erro de unidade, não uma diferença de mercado.

Baixar o histórico diário

/api/v2/futures/historical recebe um symbol. As datas usam YYYY-MM-DD, e sortOrder aceita asc ou desc.

response = requests.get(
    "https://brapi.dev/api/v2/futures/historical",
    params={
        "symbol": "WINV26",
        "startDate": "2026-06-01",
        "endDate": "2026-07-31",
        "sortOrder": "asc",
    },
    timeout=30,
)
response.raise_for_status()

future = response.json()["future"]
history = future.get("history", [])

O schema traz OHLC, média, ajuste, preço de referência, variação e volumes. Em dias sem negócio alguns campos vêm nulos. Trocar um OHLC nulo pelo ajuste resolve o gráfico, mas então marque a linha como preenchida.

A série termina no vencimento do contrato, então uma série longa do ativo base exige emendar contratos. A virada produz um salto de preço que não veio do mercado. Registre a regra de rolagem junto com o backtest, ou o resultado vira artefato da emenda.

Ler a curva de vencimentos

/api/v2/futures/term-structure?asset=DI1 reúne contratos do mesmo produto. Para juros, compare settlementRate. Para contratos cotados em preço, compare settlement ou outro campo coerente.

Contango e backwardation nomeiam o formato da curva. Não dizem por que ela ficou assim: custo de carrego, juros, sazonalidade e oferta física entram todos na conta. A curva é um dado de entrada, não um sinal pronto.

O parâmetro includeExpired=true muda o universo consultado. Numa tela ao vivo isso só acrescenta ruído. Numa auditoria, é justamente o que você quer.

Fluxo para evitar códigos vencidos

1. Consulte a curva pelo ativo base.
2. Selecione o contrato conforme sua regra de vencimento.
3. Busque especificações e confirme a unidade.
4. Consulte cotação ou histórico com o símbolo completo.
5. Repita a descoberta quando o contrato vencer.

Teste agora o endpoint de curva de vencimentos com asset=WIN.