Visão geral

A API pública do DataBolsa serve os dados do mercado brasileiro em REST + JSON:

https://api.databolsa.com/v1

Toda rota exige uma chave de API no header Authorization: Bearer <key> — crie a sua gratuitamente em databolsa.com.

Grupos de endpoints

Navegue pelos grupos na barra lateral. Em resumo:

Três formas de ler

Objects é a álgebra: resolve um nome ou código para um objeto canônico e lê fatos, propriedades, relações e histórico dele. É por onde quase toda pergunta começa.

Functions são cálculos e composições que não cabem nas primitivas — a ficha de um fundo numa chamada, a distribuição de inadimplência de um FIDC por faixa, uma curva, o regime macro. Ache a que serve com listFunctions, leia o contrato dela em getFunction e execute com executeFunction, que resolve o sujeito pelo grafo. Onde ainda existe uma rota especializada com o mesmo dado, ela é um atalho da mesma Function e sai numa versão futura.

Actions são as escritas, e vivem no contrato do módulo que as executa (Wallet, Advisor, mesa). Todas seguem o mesmo protocolo: catálogo, spec, preview e execute com confirmação e chave de idempotência. Os módulos publicam também as suas Functions (as leituras e cálculos sobre os recursos deles), e a porta é a mesma do core: GET /v1/functions lista as Functions do core e as dos módulos instalados no workspace da credencial, e POST /v1/functions/{id}/execute executa qualquer uma — o primeiro segmento do id (wallet.portfolio.get) diz quem responde. Cada módulo expõe o mesmo protocolo também no próprio prefixo (/v1/wallet/functions), que é o que o SDK, a CLI e o MCP da extensão usam.

O domínio é o primeiro segmento de todo id: market, funds, credit, documents, events, macro, us, bonds, commodities e minerals no core; o namespace do módulo (wallet, advisor, credit) nas extensões. É por ele que se filtra (listFunctions?domain=credit) e é dele que vem o scope que a credencial precisa.

Como uma chamada acontece

Object, Function, Action e Module dizem o que existe; a invocação diz como se pede e o que volta, e é a mesma em todo plano.

O sujeito. Uma Function com sujeito recebe subject no corpo: entity_id de um objeto do grafo (ou de um recurso do módulo), ou resolve com um texto e, se preciso, kind. O servidor resolve, escolhe a instância e ecoa quem respondeu em subject na resposta. series escolhe o papel quando o objeto tem mais de um; at aplica o corte temporal no campo que o spec declara.

O objeto. getObject publica a mesma forma para qualquer tipo: id, kind, subkind, name, a âncora, keys (todos os identificadores, com share_class nas chaves de ticker), links, aspects (cada capítulo com a chamada executeFunction pronta) e declared_facts.

A coleção. Toda lista e toda série respondem { data, meta }, com meta.next_cursor e meta.count sempre presentes; rotas sem cursor trazem next_cursor: null.

A régua. Todo campo numérico que uma Function devolve declara no próprio schema os eixos do número: x-dimension (currency, rate, share, ratio, index, points, count, duration, area), x-scale (unit, percent, thousand, million, billion, bps, days, months, years, business_days, square_meters, cents), x-period (a janela que o número cobre: none, daily, monthly, quarterly, annual, ttm_12m, ytd, rolling_1m, rolling_3m, cagr_3y, cagr_5y) e, quando a dimensão é moeda, x-currency (BRL, USD ou native, a moeda da própria linha). x-unit sai desses eixos pela mesma tabela que rege axes.unit em getObjectFacts: rate/share em percent é pct (8,0 é 8%), em unit é ratio (0,08 é 8%); ratio é x; duration e area saem como count e se distinguem pela dimensão. Um campo só com x-unit: native remete ao campo unit da própria linha. As extensões viajam no output_schema de getFunction e em api/openapi.yaml, então o cliente formata pelo schema, não pelo nome do campo.

A recusa. Todo erro é application/problem+json com details.code, e o vocabulário é fechado: o cliente decide pelo código, nunca pela frase.

Um módulo pode ter códigos próprios (portfolio_name_taken); o status vem declarado com eles e o código continua em details.code.

A referência é gerada do contrato OpenAPI publicado no repositório — cada página traz parâmetros, respostas e exemplos com curl, SDK e CLI.