Referência da API

DataBolsa API — v1.0.0

API aberta de dados do mercado financeiro brasileiro — companhias, ações, FIIs, títulos públicos, índices e séries macro, sempre rastreáveis à fonte primária.

Como começar

API v1 estável · contrato OpenAPI 3.1 · self-host ou hospedado

01
API aberta
Chamadas de leitura não exigem chave — use a base URL abaixo direto.
02
Autentique
Envie a chave no header Authorization: Bearer <api_key>.
03
Chame a API
Base https://api.databolsa.com/v1 — respostas em JSON, erros em RFC 9457.

curl

curl -H "Authorization: Bearer db_live_xxxxxxxxxxxx" \
  "https://api.databolsa.com/v1/stocks/PETR4/indicators"

SDK TypeScript

@databolsa/sdk

Cliente tipado oficial — a mesma interface que serve o site e a CLI por baixo. Tipos gerados do contrato OpenAPI, degradação 501/404 → erro tratável, e o objeto lineage em cada resposta.

instalação

npm install @databolsa/sdk

typescript

import { DataBolsa } from "@databolsa/sdk";

const db = new DataBolsa("https://api.databolsa.com", {
  apiKey: "db_live_xxxxxxxxxxxx",
});

const petr = await db.getStock("PETR4");
console.log(petr.company?.name, petr.lineage);

Convenções

Autenticação

sem autenticação

A API pública é aberta — chamadas de leitura não exigem chave. (Self-host pode exigir chave via DATABOLSA_API_KEYS.)

Paginação

?cursor=&limit=

Cursor opaco devolvido em meta.next_cursor; repasse-o em cursor até vir null. limit padrão 100, máximo 1000.

Erros

application/problem+json

Erros seguem RFC 9457 (Problem Details): type, title, status, detail e instance em todas as respostas de erro.

Unidades

unit: percent | ratio | brl

percent já vem em % (8.1 = 8,1%, nunca 0.081); ratio é múltiplo puro. Datas em ISO 8601; horários intraday no fuso America/Sao_Paulo.

Rate limit

429 + Retry-After

Ao exceder a cota, qualquer endpoint responde 429 com o header Retry-After indicando os segundos até a próxima janela.

Recursos

Endpoints por recurso

System

Saúde e metadados da API

getHealthsearchgetIngestHealth

Companies

Companhias abertas (cadastro CVM) e demonstrações

listCompaniesgetCompanylistCompanyDocuments

Stocks

Ações — cotações, indicadores, proventos e eventos

getStocklistQuotesgetStockIndicators…

Screener

Filtros multi-critério sobre ações e FIIs

screenStocksscreenFiis

Macro

Séries macroeconômicas, expectativas Focus e regime

getMacroGearsgetMacroRegimegetMarketExpectations…

Bonds

Títulos públicos (Tesouro Direto) e curvas de juros

getYieldCurvelistTesouroBonds

Indices

Índices da B3 (IBOV, IFIX, ...) e composições

listIndiceslistIndexQuotesgetIndexComposition

FIIs

Fundos imobiliários — indicadores e distribuições

getFiigetFiiIndicatorsgetFiiIndicatorHistory…

BDR

BDRs (recibos de ações estrangeiras) — catálogo e cotações

listBdrsgetBdrlistBdrQuotes

Options

Opções sobre ações — cadeia vigente e histórico EOD

getOptionsChainlistOptionExpirieslistOptionQuotes

Crypto

Criptoativos em BRL

listCryptoQuotes

Contrato completo (OpenAPI 3.1): openapi.json. Código aberto no GitHub — pacotes no npm: @databolsa/sdk, @databolsa/cli, @databolsa/mcp.