# Comece a usar a API da brapi.dev
URL: /docs.mdx

Guia rápido para começar a usar a API da brapi.dev. Encontre o endpoint certo para cotações, histórico, dividendos, fundamentos, FIIs, câmbio, cripto e indicadores econômicos do mercado financeiro brasileiro.

***

title: 'Comece a usar a API da brapi.dev'
description:
'Guia rápido para começar a usar a API da brapi.dev. Encontre o endpoint certo
para cotações, histórico, dividendos, fundamentos, FIIs, câmbio, cripto e
indicadores econômicos do mercado financeiro brasileiro.'
howToSteps:

* name: 'Obtenha sua chave de API (opcional para teste)'
  text: 'Para testar, use as 4 ações gratuitas (PETR4, MGLU3, VALE3, ITUB4) sem token. Para produção, crie uma conta no dashboard para gerar seu token.'
* name: 'Faça sua primeira requisição'
  text: 'Execute curl "[https://brapi.dev/api/v2/stocks/quote?symbols=PETR4](https://brapi.dev/api/v2/stocks/quote?symbols=PETR4)" no terminal para testar sem token, ou adicione o header Authorization: Bearer SEU\_TOKEN para acessar todos os ativos.'
* name: 'Receba os dados em JSON'
  text: 'A API retorna um JSON com results\[].data contendo preço, variação, volume, market cap e outros campos da cotação.'
  howToTools:
* 'Terminal ou linha de comando'
* 'cURL ou cliente HTTP'
* 'Navegador web'
  howToSupplies:
* 'Conta brapi.dev (opcional para teste)'
* 'Token de API brapi.dev (opcional para teste)'

***

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

A **brapi.dev** é uma API REST para dados financeiros brasileiros. Você acessa
ações, FIIs, BDRs, ETFs, índices, criptomoedas, câmbio e indicadores
econômicos em JSON, com dados de fontes como **CVM**, **IBGE** e **Banco Central
do Brasil**.

O objetivo da brapi é ser o jeito mais simples de levar esses dados para
produtos, planilhas, dashboards, robôs, assistentes de IA e sistemas internos.

## Primeira requisição

Você pode testar agora com 4 ações brasileiras populares, sem token ou cadastro:

<Callout title="Teste sem token" type="info">
  **PETR4** (Petrobras) • **MGLU3** (Magazine Luiza) • **VALE3** (Vale) •
  **ITUB4** (Itaú)
</Callout>

```bash title="Cotação de PETR4"
curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4"
```

```bash title="Múltiplas ações"
curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4,VALE3,MGLU3"
```

```bash title="Histórico e dividendos"
curl "https://brapi.dev/api/v2/stocks/historical?symbols=PETR4&range=1mo&interval=1d"
curl "https://brapi.dev/api/v2/stocks/dividends?symbols=ITUB4"
```

Essas ações de teste permitem consultar cotação, histórico, dividendos e dados
financeiros para experimentar a API antes de criar uma conta.

<Steps>
  <Step>
    #### Teste primeiro, autentique depois

    PETR4, MGLU3, VALE3 e ITUB4 funcionam sem token para você testar a API.
    Para acessar todos os ativos e usar em produção, crie sua conta e gere um
    token no dashboard.

    <Callout title="Onde encontrar seu token?" type="info">
      Seu token estará disponível na seção "Chaves de API" do seu
      **[Dashboard](/dashboard)** após o login.
    </Callout>
  </Step>

  <Step>
    #### Use o token no backend

    Em produção, envie o token no header `Authorization`:

    ```bash title="Terminal (cURL) - Produção"
    curl --request GET \
      --url 'https://brapi.dev/api/v2/stocks/quote?symbols=PETR4' \
      --header 'Authorization: Bearer SEU_TOKEN'
    ```
  </Step>

  <Step>
    #### Leia a resposta

    A resposta vem em JSON, com um item em `results` para cada ticker solicitado.

    ```jsonc title="Resposta da API (JSON)"
    {
      "results": [
        {
          "requestedSymbol": "PETR4",
          "symbol": "PETR4",
          "changed": false,
          "data": {
            "shortName": "PETROBRAS PN",
            "longName": "Petróleo Brasileiro S.A. - Petrobras",
            "currency": "BRL",
            "regularMarketPrice": 38.50,
            "regularMarketDayHigh": 39.00,
            "regularMarketDayLow": 38.20,
            "regularMarketChange": 0.30,
            "regularMarketChangePercent": 0.78,
            "regularMarketTime": "2026-06-14T17:08:00.000Z",
            "marketCap": 503100000000,
            "regularMarketVolume": 45678901,
            "logourl": "https://icons.brapi.dev/icons/PETR4.svg"
          }
        }
      ],
      "requestedAt": "2026-06-14T17:08:02.000Z",
      "took": 245
    }
    ```
  </Step>
</Steps>

## Encontre o Dado Certo

Use esta tabela para ir direto ao endpoint do dado que você precisa.

| Preciso de                  | Endpoint                                                       | Documentação                                           | Dados principais                                                              |
| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Buscar e validar tickers B3 | `/api/v2/tickers`                                              | [Tickers disponíveis](/docs/tickers)                   | Símbolo, nome, tipo, setor e filtros para autocomplete ou screener            |
| Cotação atual               | `/api/v2/stocks/quote?symbols=PETR4,VALE3`                     | [Cotação de ações](/docs/acoes/cotacao)                | Preço, variação, volume, market cap, faixa do dia, faixa de 52 semanas e logo |
| Histórico de preços         | `/api/v2/stocks/historical?symbols=PETR4&range=1y&interval=1d` | [Histórico de ações](/docs/acoes/historico)            | Série OHLCV, volume e preço ajustado                                          |
| Dividendos e JCP            | `/api/v2/stocks/dividends?symbols=ITUB4`                       | [Dividendos de ações](/docs/acoes/dividendos)          | Dividendos, JCP, bonificações e subscrições de ações                          |
| Perfil da empresa           | `/api/v2/stocks/profile?symbols=PETR4`                         | [Perfil de ações](/docs/acoes/perfil)                  | CNPJ, setor, indústria, endereço, site, descrição e logo                      |
| Múltiplos e estatísticas    | `/api/v2/stocks/statistics?symbols=WEGE3&mode=current`         | [Estatísticas de ações](/docs/acoes/estatisticas)      | P/L, P/VP, beta, dividend yield, EPS, market cap e séries históricas          |
| Dados financeiros           | `/api/v2/stocks/financial-data?symbols=WEGE3&mode=current`     | [Dados financeiros](/docs/acoes/dados-financeiros)     | Receita, lucro, EBITDA, margens, dívida e fluxo de caixa livre                |
| Balanço patrimonial         | `/api/v2/stocks/balance-sheet?symbols=PETR4&period=annual`     | [Balanço patrimonial](/docs/acoes/balanco-patrimonial) | Ativos, passivos, patrimônio líquido, caixa e dívida                          |
| DRE                         | `/api/v2/stocks/income-statement?symbols=PETR4&period=annual`  | [DRE de ações](/docs/acoes/dre)                        | Receita, custos, lucro bruto, despesas, EBITDA e lucro líquido                |
| Fluxo de caixa              | `/api/v2/stocks/cash-flow?symbols=PETR4&period=annual`         | [Fluxo de caixa](/docs/acoes/fluxo-de-caixa)           | Caixa operacional, investimento, financiamento e caixa livre                  |
| DVA                         | `/api/v2/stocks/value-added?symbols=PETR4&period=annual`       | [Valor adicionado](/docs/acoes/valor-adicionado)       | Demonstração de valor adicionado anual ou trimestral                          |
| Rendimentos de FIIs         | `/api/v2/fii/dividends?symbols=MXRF11`                         | [FIIs](/docs/fiis)                                     | Rendimentos, histórico, relatórios, imóveis e carteira de fundos imobiliários |

## Autenticação

Use o header `Authorization` em código backend e produção. Ele evita expor o
token em URLs, logs e histórico de navegação.

<Tabs items={['Header (Recomendado)', 'Query Param (apenas no-code)']}>
  <Tab value="Header (Recomendado)">
    ```bash
    curl -H "Authorization: Bearer SEU_TOKEN" \
      "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4"
    ```
  </Tab>

  <Tab value="Query Param (apenas no-code)">
    ```bash
    curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4&token=SEU_TOKEN"
    ```

    O parâmetro `?token=` funciona para ferramentas que não suportam headers
    (Google Sheets, Excel Power Query, Notion). Tokens na URL podem aparecer em
    histórico do navegador, logs de servidor e ferramentas de analytics.
    **Prefira header auth sempre que possível.**
  </Tab>
</Tabs>

<Callout title="Atenção" type="warn">
  Nunca exponha seu token no código do lado do cliente. Em aplicações web, faça
  as chamadas para a API da brapi.dev a partir do seu backend.
</Callout>

## Principais Conceitos

* **URL base:** todas as requisições usam `https://brapi.dev/api`.
* **Símbolos:** endpoints de mercado usam `symbols=PETR4,VALE3` para consultar
  um ou mais ativos na mesma chamada.
* **Resposta:** endpoints por ativo retornam `results[]`; o payload principal
  fica em `results[].data`.
* **Datas:** use `startDate` e `endDate` no formato `YYYY-MM-DD` quando quiser
  controlar a janela de consulta.
* **Períodos contábeis:** fundamentos aceitam `period=annual` ou
  `period=quarterly`; alguns endpoints também aceitam `mode=current` ou
  `mode=history`.

## Explore Nossos Endpoints

Navegue pelas seções para acessar todos os dados disponíveis.

<Cards>
  <Card href="/docs/acoes/cotacao" title="Cotação de Ações" description="Preço atual, variação, volume, market cap e logo de tickers B3." />

  <Card href="/docs/acoes/historico" title="Histórico de Ações" description="Séries OHLCV com range, intervalo ou datas específicas." />

  <Card href="/docs/acoes/dividendos" title="Dividendos de Ações" description="Dividendos, JCP, bonificações e subscrições de ações." />

  <Card href="/docs/acoes/dados-financeiros" title="Fundamentos" description="Perfil, estatísticas, dados financeiros e demonstrações contábeis." />

  <Card href="/docs/tickers" title="Tickers" description="Busque, filtre, valide e resolva símbolos de instrumentos B3." />

  <Card href="/docs/fiis" title="FIIs" description="Indicadores, histórico, relatórios, imóveis, carteira e rendimentos." />

  <Card href="/docs/criptomoedas" title="Criptomoedas" description="Cotações e informações das principais criptomoedas do mercado." />

  <Card href="/docs/moedas" title="Moedas (Câmbio)" description="Taxas de câmbio atualizadas e histórico PTAX." />

  <Card href="/docs/macro" title="Macroeconomia" description="SELIC, CDI, IPCA, IGP-M, TR, IBC-Br, PIB mensal, desemprego e mais." />

  <Card href="/docs/mcp" title="Servidor MCP para IAs" description="Use dados financeiros brasileiros em assistentes de IA compatíveis com MCP." />
</Cards>

## SDKs Oficiais

Use nossas bibliotecas oficiais quando quiser integração com tipos, helpers e
tratamento de erros pronto.

<Cards>
  <Card href="/docs/sdks/typescript" title="TypeScript / JavaScript" description="SDK oficial com suporte a Node.js e navegador." />

  <Card href="/docs/sdks/python" title="Python" description="SDK oficial Python com suporte síncrono e assíncrono." />
</Cards>

## Exemplos Práticos

Veja como buscar os mesmos dados em diferentes ambientes.

<Tabs items={['cURL', 'Python', 'JavaScript']}>
  <Tab value="cURL">
    ```bash title="Cotação, histórico e fundamentos"
    curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4,VALE3"

    curl -H "Authorization: Bearer SEU_TOKEN" \
      "https://brapi.dev/api/v2/stocks/historical?symbols=PETR4&range=1y&interval=1d"

    curl -H "Authorization: Bearer SEU_TOKEN" \
      "https://brapi.dev/api/v2/stocks/income-statement?symbols=PETR4&period=annual"
    ```
  </Tab>

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

    token = "SEU_TOKEN"
    response = requests.get(
        "https://brapi.dev/api/v2/stocks/quote",
        headers={"Authorization": f"Bearer {token}"},
        params={"symbols": "PETR4,VALE3"},
    )
    response.raise_for_status()

    data = response.json()
    for item in data["results"]:
        quote = item["data"]
        print(item["symbol"], quote["regularMarketPrice"])
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript title="fetch"
    const response = await fetch(
      'https://brapi.dev/api/v2/stocks/quote?symbols=PETR4,VALE3',
      {
        headers: {
          Authorization: `Bearer ${process.env.BRAPI_API_TOKEN}`,
        },
      },
    );

    if (!response.ok) {
      throw new Error(`Erro HTTP ${response.status}`);
    }

    const data = await response.json();
    for (const item of data.results) {
      console.log(item.symbol, item.data.regularMarketPrice);
    }
    ```
  </Tab>
</Tabs>

## Próximos Passos

* **[Consulte cotações de ações](/docs/acoes/cotacao):** comece com preço atual,
  variação e volume.
* **[Monte seu fluxo com tickers](/docs/tickers):** busque símbolos, valide
  entradas e descubra cobertura por endpoint.
* **[Veja todos os exemplos](/docs/examples):** aplique a API em planilhas,
  backends, sites e integrações.