# Futuros
URL: /docs/futuros.mdx

Como usar a API de futuros da brapi (mini Ibov, mini Dolar, DI, boi, café, milho, soja). Veja os termos, o passo a passo e qual endpoint usar.

***

title: Futuros
description: >-
Como usar a API de futuros da brapi (mini Ibov, mini Dolar, DI, boi, café,
milho, soja). Veja os termos, o passo a passo e qual endpoint usar.
full: true
keywords: brapi, api, futuros, mini Ibovespa, mini Dolar, WIN, WDO, BGI, DI1, ICF, CCM, SJC, ajuste, settlement
openGraph:
title: Futuros
description: >-
Como usar a API de futuros da brapi, com passo a passo e exemplos.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
-----------

import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Para consultar futuros, o caminho normal é:

1. escolha o **ativo** (ex.: `WIN`, `BGI`, `DI1`)
2. liste os **contratos** ou veja a **curva de vencimentos**
3. pegue a **cotação** ou as **especificações** de um contrato
4. baixe o **histórico** do contrato

<Callout title="O que tem" type="info">
  Preços do fim do dia (após o pregão fechar): abertura, máxima, mínima,
  fechamento, preço de ajuste, variação do dia, negócios, contratos e
  volume em reais. Para DI e DAP, também a taxa de ajuste.
</Callout>

<Callout title="O que não tem" type="warn">
  Tempo real, gregas, contratos em aberto e livro de ofertas.
</Callout>

## Cobertura e atualização

* **Histórico:** cerca de **1 ano**, atualizado todo dia após o pregão.
* **Quando atualiza:** **após as 19h** (horário de Brasília). Antes disso,
  você vê os dados do pregão anterior.
* **Contratos:** mini Ibov (`WIN`), Ibov (`IND`), mini dólar (`WDO`),
  dólar (`DOL`), DI (`DI1`), boi (`BGI`), café (`ICF`), milho (`CCM`),
  soja (`SJC`) e outros.
* **Fuso horário:** `America/Sao_Paulo`. O campo `date` é um número (Unix em
  segundos) com a data do fechamento.
* **Datas em parâmetros:** use `YYYY-MM-DD`.

## Quem pode acessar

Futuros estão no plano **Pro**. Sem token, dá para testar com **WIN** (mini
Ibov) e **WDO** (mini Dolar).

| Plano               | Acesso                   |
| ------------------- | ------------------------ |
| Sem token (sandbox) | ✅ Só WIN e WDO           |
| Free                | ❌                        |
| Startup             | ❌                        |
| **Pro**             | **✅ Todos os contratos** |

## Termos

* **Ativo (`underlyingAsset` ou `asset`):** o código de 2 a 4 letras do
  produto, sem mês ou ano. Ex.: `WIN`, `WDO`, `BGI`, `DI1`.
* **Contrato (`symbol`):** o código que o mercado negocia. Formato:
  **`{ATIVO}{LETRA_MÊS}{ANO}`**. Ex.: `WINM26` = mini Ibov com vencimento em
  junho de 2026.
* **Vencimento (`expirationDate`):** data em que o contrato termina, no
  formato `YYYY-MM-DD`.
* **Preço de ajuste (`settlement`):** o preço oficial do dia, divulgado no
  fim do pregão. Vem sempre preenchido, mesmo em dias sem negócio.
* **Taxa de ajuste (`settlementRate`):** só vem em contratos de juros
  (DI, DAP). É a taxa anual (`%a.a.`) do ajuste.
* **Multiplicador (`contractMultiplier`):** quanto vale cada ponto.
  Ex.: `WIN = 0,2`, `WDO = 10`, `BGI = 330` (arrobas), `DI1 = 1`.
* **Lote (`allocationRoundLot`):** tamanho do lote. Quase sempre `1`.
* **Tipo de cotação (`quotationType`):** `price` para a maioria,
  `rate` para juros (DI, DAP). Veja abaixo.

## Contratos em taxa vs em preço

A maioria dos futuros é cotada em **preço**. O número em `close`, `high`,
`low` e `settlement` é o preço direto (pontos para WIN, reais para BGI etc.).

Os futuros de juros (`DI1`, `DI`, `DAP`) são cotados em **taxa anual**
(`%a.a.`):

* `close`, `high`, `low`, `average` vêm em **%a.a.** (ex.: `14.075` =
  14,075% a.a.).
* `settlement` vem em **reais** (preço unitário, ex.: `92179.44`).
* `settlementRate` vem em **%a.a.** (ex.: `14.059`).

O campo `quotationType` (`"price"` ou `"rate"`) na resposta diz qual
unidade usar.

<Callout type="info">
  Para o preço oficial do dia, **use sempre `settlement`**. O `close`
  (último negócio) pode vir vazio em contratos com pouca negociação.
</Callout>

## Como ler o `symbol`

Padrão: **`{ATIVO}{LETRA_MÊS}{ANO}`**.

* **Ativo:** 2 a 4 letras (`WIN`, `WDO`, `BGI`, `DI1`).
* **Letra do mês:** uma letra para cada mês.

| Mês       | Letra | Mês      | Letra |
| --------- | ----- | -------- | ----- |
| Janeiro   | F     | Julho    | N     |
| Fevereiro | G     | Agosto   | Q     |
| Março     | H     | Setembro | U     |
| Abril     | J     | Outubro  | V     |
| Maio      | K     | Novembro | X     |
| Junho     | M     | Dezembro | Z     |

* **Ano:** dois últimos dígitos.

Exemplos:

* `WINM26` → mini Ibov, junho de 2026.
* `DI1F27` → DI, janeiro de 2027.
* `BGIK26` → boi gordo, maio de 2026.

## Comece rápido

Exemplo do fluxo `curva → cotação → histórico` para o mini Ibov.

<Tabs items={['cURL', 'TypeScript', 'Python']}>
  <Tab value="cURL">
    ```bash
    # 1) Curva de vencimentos do mini Ibov
    curl "https://brapi.dev/api/v2/futures/term-structure?asset=WIN"

    # 2) Cotação do contrato
    curl "https://brapi.dev/api/v2/futures/quote?symbols=WINM26"

    # 3) Histórico dos últimos 12 meses
    curl "https://brapi.dev/api/v2/futures/historical?symbol=WINM26"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    const BASE = 'https://brapi.dev/api/v2/futures';
    const token = process.env.BRAPI_TOKEN; // opcional para WIN/WDO no sandbox

    const headers = token ? { Authorization: `Bearer ${token}` } : undefined;

    // 1) Curva
    const curve = await fetch(`${BASE}/term-structure?asset=WIN`, {
      headers,
    }).then((r) => r.json());

    // 2) Contrato mais próximo do vencimento
    const front = curve.contracts[0];
    const quote = await fetch(`${BASE}/quote?symbols=${front.symbol}`, {
      headers,
    }).then((r) => r.json());

    // 3) Histórico
    const history = await fetch(
      `${BASE}/historical?symbol=${front.symbol}`,
      { headers },
    ).then((r) => r.json());

    console.log(history);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os
    import requests

    BASE = "https://brapi.dev/api/v2/futures"
    token = os.getenv("BRAPI_TOKEN")  # opcional para WIN/WDO no sandbox
    headers = {"Authorization": f"Bearer {token}"} if token else {}

    # 1) Curva
    curve = requests.get(
        f"{BASE}/term-structure", params={"asset": "WIN"}, headers=headers
    ).json()
    front = curve["contracts"][0]

    # 2) Cotação
    quote = requests.get(
        f"{BASE}/quote", params={"symbols": front["symbol"]}, headers=headers
    ).json()

    # 3) Histórico
    history = requests.get(
        f"{BASE}/historical", params={"symbol": front["symbol"]}, headers=headers
    ).json()

    print(history)
    ```
  </Tab>
</Tabs>

## Passo a passo

<Steps>
  <Step>
    #### Liste os contratos

    Use [`/api/v2/futures/list`](/docs/futuros/lista) para ver o que existe,
    ou [`/api/v2/futures/term-structure`](/docs/futuros/curva-de-vencimentos)
    para ver todos os vencimentos de um ativo.
  </Step>

  <Step>
    #### Pegue cotação ou especificações

    Use [`/api/v2/futures/quote`](/docs/futuros/cotacao) para a cotação do
    dia de até 20 contratos, ou
    [`/api/v2/futures/specs`](/docs/futuros/especificacoes) para os dados do
    contrato (multiplicador, lote, vencimento, ISIN).
  </Step>

  <Step>
    #### Histórico

    Use [`/api/v2/futures/historical`](/docs/futuros/historico) com `symbol`
    para a série diária do contrato.
  </Step>

  <Step>
    #### Opções sobre o contrato

    Para opções sobre futuros (boi, café, milho, soja), veja
    [Opções sobre Futuros](/docs/futuros/opcoes).
  </Step>
</Steps>

## Casos comuns

* **Painel de futuros:** `list → quote`
* **Curva de juros do DI:** `term-structure?asset=DI1`
* **Curva do mini Ibov:** `term-structure?asset=WIN`
* **Backtest de boi:** `term-structure?asset=BGI → historical`
* **Margem e ajuste do dia:** `quote` (use `settlement` e `settlementRate`)

## Perguntas frequentes

<AnswerBox question="Os dados estão em tempo real?" answer="Não. Hoje a API entrega só dados do fim do dia, depois das 19h de Brasília." />

<AnswerBox question="Quanto histórico vocês têm?" answer="Cerca de 1 ano. A cada novo pregão, a janela avança um dia." />

<AnswerBox
  question="Por que close está null em alguns contratos?"
  answer="Contratos com pouca negociação podem não ter negócios no dia. Quando isso acontece, OHLC fica null mas o settlement vem preenchido. Use settlement para o preço oficial."
  relatedEndpoints={[
  { name: 'quote', path: '/api/v2/futures/quote' },
  { name: 'historical', path: '/api/v2/futures/historical' },
]}
/>

<AnswerBox question="Como ler DI1, DI ou DAP?" answer="São cotados em taxa anual. close/high/low vêm em %a.a. (ex.: 14.075 = 14,075% a.a.) e settlement vem em reais. O campo settlementRate traz a taxa correspondente. Confira quotationType na resposta." />

<AnswerBox
  question="Qual plano preciso?"
  answer="Pro. Sem token, dá para testar só com WIN e WDO."
  relatedEndpoints={[
  { name: 'list', path: '/api/v2/futures/list' },
  { name: 'quote', path: '/api/v2/futures/quote' },
]}
/>

<AnswerBox question="Posso pedir várias séries em /historical?" answer="Não. O /historical aceita um contrato por vez. Para vários, use /quote (até 20) ou /term-structure (todos os vencimentos de um ativo)." />

## Teste sem token

Para testar sem token, os endpoints aceitam só estes ativos:

* `/list`, `/term-structure`: `asset=WIN` ou `asset=WDO`.
* `/quote`, `/specs`: `symbols=` com `WIN` ou `WDO`.
* `/historical`: `symbol` com `WIN` ou `WDO`.
* `/options/expirations`, `/options/strikes`, `/options/chain`:
  `underlying=BGI`.
* `/options/historical`: `symbol` com `BGI`.

Para outros ativos, use um token do plano Pro.

## Endpoints

<Cards>
  <Card href="/docs/futuros/lista" title="Listar contratos" description="Lista de futuros com filtro por ativo e segmento." />

  <Card href="/docs/futuros/cotacao" title="Cotação" description="Cotação do dia para até 20 contratos." />

  <Card href="/docs/futuros/especificacoes" title="Especificações" description="Multiplicador, lote, vencimento, ISIN, CFI." />

  <Card href="/docs/futuros/historico" title="Histórico" description="Série diária de um contrato com OHLC + ajuste." />

  <Card href="/docs/futuros/curva-de-vencimentos" title="Curva de vencimentos" description="Todos os vencimentos de um ativo com o último ajuste." />

  <Card href="/docs/futuros/opcoes" title="Opções sobre futuros" description="Opções sobre boi, café, milho, soja e outros." />
</Cards>