# Opções
URL: /docs/opcoes.mdx

Guia simples para integrar opções na brapi: entenda os termos principais, o fluxo recomendado e qual endpoint usar em cada caso.

***

title: Opções
description: >-
Guia simples para integrar opções na brapi: entenda os termos principais, o
fluxo recomendado e qual endpoint usar em cada caso.
full: true
keywords: brapi, api, opções, vencimento, strike, série
openGraph:
title: Opções
description: >-
Guia simples para integrar opções na brapi, com fluxo recomendado e
exemplos de uso.
type: website
locale: pt\_BR
lastUpdated: '2026-04-22T12: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';

Esta API foi desenhada para o fluxo mais comum de consulta de opções:

1. escolher o **ativo subjacente**
2. descobrir os **vencimentos**
3. ver os **preços de exercício**
4. listar as **séries negociadas**
5. pegar o **histórico** de uma série específica

<Callout title="O que esta API entrega" type="info">
  Dados **EOD** de opções. Ou seja: preço de abertura, máxima, mínima, média,
  fechamento, bid, ask, negócios, volume e volume financeiro do dia.
</Callout>

<Callout title="O que esta API não entrega nesta versão" type="warn">
  Não há dados em tempo real, gregas, volatilidade implícita, interesse em
  aberto ou livro de ofertas.
</Callout>

## Cobertura e frequência

* **Histórico:** a partir de **2009**, com consolidação diária após o fechamento.
* **Atualização:** o arquivo EOD é processado **após \~19h de Brasília** (BRT/BRT-3).
  Até lá, o "último pregão disponível" corresponde ao pregão anterior.
* **Contratos cobertos:** opções de ações, ETFs e índices (ex.: IBOV) listados
  na bolsa brasileira.
* **Fuso horário:** todas as datas estão em `America/Sao_Paulo`. Campos `date`
  em respostas são **timestamps Unix em segundos** do fechamento do pregão.
* **Formato de datas em query params:** `YYYY-MM-DD`.

## Acesso por plano

Opções fazem parte do plano **Pro**. O sandbox abaixo permite experimentação
sem token para **PETR4**.

| Plano               | Acesso a opções       |
| ------------------- | --------------------- |
| Sandbox (sem token) | ✅ Apenas PETR4        |
| Free                | ❌                     |
| Startup             | ❌                     |
| **Pro**             | **✅ Todos os ativos** |

## Termos que você vai ver

* **Ativo subjacente:** a ação, ETF ou índice da opção. Ex.: `PETR4`.
* **Vencimento (`expirationDate`):** a data em que a opção vence.
  Ex.: `2026-05-15`.
* **Preço de exercício / strike:** preço combinado na opção. Ex.: `34`.
* **Série:** a combinação prática que o mercado negocia. Na resposta da API,
  aparece como `symbol`, `expirationDate`, `side` e `strike`.
* **`symbol`:** o ticker da série (ex.: `PETRE370`), composto pelo ativo
  subjacente + letra do mês/tipo + identificador do strike (veja abaixo).
* **Opção de compra (`call`):** direito de **comprar** o ativo subjacente.
* **Opção de venda (`put`):** direito de **vender** o ativo subjacente.
* **Titular:** quem compra a opção. Paga o prêmio e exerce o direito se for
  vantajoso.
* **Lançador:** quem vende a opção. Recebe o prêmio e assume a obrigação.
* **Prêmio:** preço pago/recebido pela opção. É o que aparece como `close`,
  `bid`, `ask` no histórico.
* **Opção americana:** pode ser exercida a qualquer momento até o vencimento
  (padrão de opções de ações).
* **Opção europeia:** só pode ser exercida no vencimento (padrão de opções
  de índice, como IBOV).

## Formato do `symbol`

O ticker de uma série segue o padrão da bolsa brasileira:
**`{ATIVO}{LETRA_MÊS}{ID_STRIKE}`**.

* **Ativo:** as 4 letras do subjacente (ex.: `PETR`).
* **Letra do mês + tipo:**
  * `A–L` para **calls** (A = janeiro, B = fevereiro, ..., L = dezembro).
  * `M–X` para **puts** (M = janeiro, N = fevereiro, ..., X = dezembro).
* **ID do strike:** número de 1 a 3 dígitos atribuído pela bolsa para aquele
  strike no vencimento.

Exemplos:

* `PETRE370` → **PETR4**, **call** (`E` = maio), strike mapeado como `370`.
* `PETRQ28` → **PETR4**, **put** (`Q` = maio), strike mapeado como `28`.

<Callout type="info">
  O ID do strike **não é o valor em reais**. Para saber o strike em reais,
  use `/api/v2/options/chain` ou `/api/v2/options/strikes`.
</Callout>

## Início rápido

Exemplo completo do fluxo `vencimentos → séries negociadas → histórico` para
opções de **PETR4**.

<Tabs items={['cURL', 'TypeScript', 'Python']}>
  <Tab value="cURL">
    ```bash
    # 1) Descubra os vencimentos disponíveis
    curl "https://brapi.dev/api/v2/options/expirations?underlying=PETR4"

    # 2) Liste as séries negociadas em um vencimento
    curl "https://brapi.dev/api/v2/options/chain?underlying=PETR4&expirationDate=2026-05-15"

    # 3) Consulte o histórico de uma série específica
    curl "https://brapi.dev/api/v2/options/historical?symbol=PETRE370&expirationDate=2026-05-15"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    const BASE = 'https://brapi.dev/api/v2/options';
    const token = process.env.BRAPI_TOKEN; // dispensável para PETR4 no sandbox

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

    // 1) Vencimentos
    const expirations = await fetch(
      `${BASE}/expirations?underlying=PETR4`,
      { headers },
    ).then((r) => r.json());

    const nextExpiration = expirations.expirations[0];

    // 2) Séries negociadas no vencimento
    const chain = await fetch(
      `${BASE}/chain?underlying=PETR4&expirationDate=${nextExpiration}`,
      { headers },
    ).then((r) => r.json());

    // 3) Histórico da série ATM mais próxima
    const series = chain.options[0];
    const history = await fetch(
      `${BASE}/historical?symbol=${series.symbol}&expirationDate=${series.expirationDate}`,
      { headers },
    ).then((r) => r.json());

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

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

    BASE = "https://brapi.dev/api/v2/options"
    token = os.getenv("BRAPI_TOKEN")  # dispensável para PETR4 no sandbox
    headers = {"Authorization": f"Bearer {token}"} if token else {}

    # 1) Vencimentos
    expirations = requests.get(
        f"{BASE}/expirations", params={"underlying": "PETR4"}, headers=headers
    ).json()
    next_exp = expirations["expirations"][0]

    # 2) Séries negociadas no vencimento
    chain = requests.get(
        f"{BASE}/chain",
        params={"underlying": "PETR4", "expirationDate": next_exp},
        headers=headers,
    ).json()

    # 3) Histórico da primeira série
    series = chain["options"][0]
    history = requests.get(
        f"{BASE}/historical",
        params={"symbol": series["symbol"], "expirationDate": series["expirationDate"]},
        headers=headers,
    ).json()

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

## Fluxo recomendado

<Steps>
  <Step>
    #### Descubra os vencimentos

    Comece em [`/api/v2/options/expirations`](/docs/opcoes/vencimentos) quando
    você só sabe o ativo, como `PETR4`, e ainda não sabe qual vencimento usar.
  </Step>

  <Step>
    #### Descubra os preços de exercício

    Depois de escolher o vencimento, use
    [`/api/v2/options/strikes`](/docs/opcoes/precos-de-exercicio) para saber
    quais strikes existem naquele vencimento.
  </Step>

  <Step>
    #### Liste as séries negociadas

    Use [`/api/v2/options/chain`](/docs/opcoes/series) para montar a tela que a
    maioria das pessoas espera ver: séries negociadas por vencimento, com preço
    e volume.
  </Step>

  <Step>
    #### Busque o histórico de uma série

    Quando você já sabe qual série quer acompanhar, use
    [`/api/v2/options/historical`](/docs/opcoes/historico) com `symbol` e
    `expirationDate`. Se precisar, informe também `strike`.
  </Step>
</Steps>

## Casos de uso mais comuns

* **Tela simples de opções no seu app:** `expirations -> chain`
* **Filtro por strike:** `expirations -> strikes -> chain`
* **Gráfico de uma opção específica:** `chain -> historical`
* **Backtest ou persistência diária:** escolher a série via `chain` e depois
  buscar o histórico em `historical`

## Quando você pode pular etapas

* Se você **já sabe o vencimento**, pode ir direto para `strikes` ou `chain`.
* Se você **já sabe a série**, pode ir direto para `historical`.
* Se você quer só montar uma tela simples por vencimento, pode **pular
  `strikes`** e ir direto para `chain`.

## Perguntas frequentes

<AnswerBox question="Os dados estão em tempo real?" answer="Não — hoje a API entrega apenas dados EOD (fim do pregão), processados após ~19h de Brasília." note="Dados intraday estão no roadmap; por enquanto, use o histórico EOD consolidado do dia anterior." />

<AnswerBox question="A API retorna as gregas (delta, gamma, vega, theta)?" answer="Ainda não. Nesta versão entregamos OHLCV, bid/ask, negócios e volume — sem cálculo de gregas nem volatilidade implícita." />

<AnswerBox
  question="Qual é o plano mínimo para acessar opções?"
  answer="Plano Pro. O sandbox sem token funciona apenas para opções de PETR4, para você testar antes de assinar."
  relatedEndpoints={[
  { name: 'expirations', path: '/api/v2/options/expirations' },
  { name: 'chain', path: '/api/v2/options/chain' },
]}
/>

<AnswerBox question="Como descobrir o strike em reais de um symbol como PETRE370?" answer="Consulte /api/v2/options/chain com underlying e expirationDate — cada item da lista traz symbol, side e strike em reais." codeExample={`curl "https://brapi.dev/api/v2/options/chain?underlying=PETR4&expirationDate=2026-05-15"`} />

<AnswerBox question="Posso consultar várias séries de uma vez em /historical?" answer="Não — /historical foi desenhado para uma série por requisição. Para múltiplas séries, use /chain com filtros de strike e side." />

<AnswerBox question="O que significa o campo date nas respostas de histórico?" answer="É o timestamp Unix em segundos do fechamento daquele pregão, em America/Sao_Paulo." />

## Receitas prontas

Guias e tutoriais publicados no blog com código pronto para copiar:

<Cards>
  <Card href="/blog/opcoes-b3-guia-completo-iniciantes-calls-puts" title="Opções para iniciantes" description="Entenda calls, puts, strikes e vencimentos do zero, em português." />

  <Card href="/blog/dividendos-sinteticos-opcoes-covered-call-2026" title="Covered call passo a passo" description="Como usar opções para gerar renda extra sobre ações que você já tem." />

  <Card href="/blog/backtesting-estrategias-python-brapi-guia-completo" title="Backtesting com Python" description="Puxe histórico da brapi e teste estratégias em notebook Python." />
</Cards>

## Limitações conhecidas e o que vem por aí

**Hoje, a API não entrega:**

* Cotação intraday (time & sales, snapshot do livro).
* Gregas (delta, gamma, vega, theta, rho).
* Volatilidade implícita e superfície de vol.
* Interesse em aberto (open interest).
* Opções flexíveis (FLEX) e exercício antecipado detalhado.

**No roadmap:**

* Gregas e volatilidade implícita calculadas.
* Snapshots intraday durante o pregão.
* Interesse em aberto por série.

Se algo aqui é bloqueante para o seu caso, conta pra gente pelo suporte — a
ordem de prioridade depende muito do que os clientes pedem.

## Sandbox sem token

Para facilitar a experimentação, todos os endpoints de opções aceitam
consultas no sandbox sem token, restritas a opções de **PETR4**:

* `GET /api/v2/options/expirations`, `/strikes` e `/chain`: apenas com
  `underlying=PETR4`.
* `GET /api/v2/options/historical`: apenas com `symbol` começando com `PETR`
  (ou seja, opções do subjacente PETR4).

Para qualquer outro ativo, é necessário autenticar com um token do plano Pro.

## Endpoints

<Cards>
  <Card href="/docs/opcoes/vencimentos" title="Vencimentos" description="Descubra os vencimentos disponíveis para um ativo." />

  <Card href="/docs/opcoes/precos-de-exercicio" title="Preços de Exercício" description="Veja os strikes disponíveis em um vencimento." />

  <Card href="/docs/opcoes/series" title="Séries Negociadas" description="Liste as séries negociadas de um vencimento com preço e volume." />

  <Card href="/docs/opcoes/historico" title="Histórico" description="Consulte o histórico diário de uma série específica." />
</Cards>