# 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';

Use a API de opções para montar telas de cadeia, acompanhar séries negociadas,
consultar histórico EOD e adicionar gregas/volatilidade implícita ao seu
produto.

O fluxo mais comum é:

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

<Callout type="info">
  Esta seção cobre opções sobre **ações, ETFs e índices** (PETR4, VALE3,
  BOVA11, IBOV, etc.). Para opções sobre **futuros** (boi gordo, café,
  milho, soja e similares), veja
  [Opções sobre Futuros](/docs/futuros/opcoes).
</Callout>

<Callout title="Dados disponíveis" type="info">
  A API entrega dados **EOD**: abertura, máxima, mínima, média, fechamento,
  bid, ask, negócios, volume, volume financeiro, gregas e volatilidade implícita.
  O arquivo diário é processado após o fechamento do pregão.
</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`. Em respostas
  de preços/histórico, `date` é timestamp Unix em segundos; em respostas de
  analytics, `date` vem em `YYYY-MM-DD`.
* **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) | PETR4               |
| Free                | Não incluso         |
| Startup             | Não incluso         |
| **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 do fluxo `vencimentos → séries negociadas → histórico` para opções de
**PETR4**. Funciona no sandbox sem token.

<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 firstSeries = chain.series[0];
    const history = await fetch(
      `${BASE}/historical?symbol=${firstSeries.symbol}&expirationDate=${firstSeries.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
    first_series = chain["series"][0]
    history = requests.get(
        f"{BASE}/historical",
        params={"symbol": first_series["symbol"], "expirationDate": first_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>

  <Step>
    #### Consulte gregas e IV

    Use [`/api/v2/options/analytics`](/docs/opcoes/analytics) para a foto EOD
    de um vencimento, ou
    [`/api/v2/options/analytics/history`](/docs/opcoes/analytics-historico)
    para a série temporal de uma opção específica.
  </Step>
</Steps>

## Casos de uso mais comuns

* **Tela simples de opções no seu app:** `expirations -> chain`
* **Filtro por strike:** `expirations -> strikes -> chain`
* **Gregas e volatilidade implícita por vencimento:** `expirations -> analytics`
* **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` e `analytics/history`

## 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="A API entrega dados EOD (fim do pregão), processados após ~19h de Brasília." note="Para o pregão atual antes desse horário, use o último pregão consolidado." />

<AnswerBox question="A API retorna as gregas (delta, gamma, vega, theta)?" answer="Sim. Use /api/v2/options/analytics para a foto de um vencimento, ou /api/v2/options/analytics/history para a série temporal de uma opção específica. Quando faltam dados suficientes, os campos calculados ficam null e nullReason explica o motivo." />

<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="/historical consulta 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="Em /historical e /chain, é o timestamp Unix em segundos do fechamento daquele pregão, em America/Sao_Paulo. Em /analytics e /analytics/history, é a data do pregão em YYYY-MM-DD." />

## 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/cadeia-opcoes-b3-python-tutorial-api-brapi" title="Cadeia de Opções em Python" description="Monte uma options chain visual com calls e puts." />

  <Card href="/blog/backtesting-opcoes-python-brapi-tutorial" title="Backtest de Opções" description="Teste covered call e cash-secured put com PETR4." />

  <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>

## Próximas melhorias

O foco atual é histórico EOD, cadeia, strikes, vencimentos, gregas e IV. As
próximas frentes em avaliação são:

* Snapshots intraday durante o pregão.
* Interesse em aberto por série.

Pedidos de clientes ajudam a definir a ordem dessas entregas.

## 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/analytics`: apenas com `underlying=PETR4`.
* `GET /api/v2/options/historical`: apenas com `symbol` começando com `PETR`
  (ou seja, opções do subjacente PETR4).
* `GET /api/v2/options/analytics/history`: apenas com `symbol` começando com
  `PETR`.

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/analytics" title="Gregas e IV" description="Consulte volatilidade implícita e gregas por vencimento." />

  <Card href="/docs/opcoes/analytics-historico" title="Histórico de Gregas e IV" description="Consulte a série temporal de gregas e IV de uma opção." />

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

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