BCB SGS Time Series MCP
An MCP server providing 17 tools to access Banco Central do Brasil economic data, including SGS time series, Focus market expectations, and PTAX exchange rates. It allows agents to query indicators like Selic and IPCA, search a curated catalog of 135 series, and fetch detailed series information with provenance.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://bcb.sidneybissoli.com/mcpWhat its tools do
17 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Query current Selic rate
- Show monthly IPCA for 2024
- Get market expectations for 2027 inflation
- Retrieve PTAX closing rate for EUR
Source and maintenance
Community listingRegistry 1.19.0
- Maintenance checked
Protocol and capabilities
- Server
- bcb-br-mcp 1.19.0
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 17 advertised
- Resources
- 3 advertised
- Resource templates
- 0 advertised
- Prompts
- 3 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"prompts": {
"listChanged": true
},
"resources": {
"listChanged": true
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
17 advertised
bcb_serie_valores — Consultar valores da série
Advertised read-onlyOpen-world
Consulta o histórico de valores de UMA série temporal do BCB pelo código SGS, opcionalmente limitado por um intervalo de datas (dataInicial/dataFinal). Quando usar: para obter a série histórica completa ou uma janela de datas específica. Quando NÃO usar: para apenas os pontos mais recentes use bcb_serie_ultimos; para a variação percentual use bcb_variacao; para comparar várias séries use bcb_comparar; se não souber o código, descubra-o antes com bcb_buscar_serie ou bcb_series_populares. Retorna: objeto `serie` (codigo, nome, categoria, periodicidade), `totalRegistros`, `periodoInicial`, `periodoFinal` e `dados` (array de {data, valor}); quando não há dados, `totalRegistros` = 0 e uma `observacao` explicativa. Períodos longos: a API do BCB limita séries DIÁRIAS a 10 anos por consulta e recusa janela aberta (HTTP 406). Isso é tratado automaticamente — a janela é fatiada em requisições de até 3 anos e o resultado vem fundido e ordenado, com `chunking` na resposta dizendo quantas janelas foram usadas; se o período pedido estava aberto numa série diária, `janelaAplicada` diz qual janela foi usada e por quê. Harmonização: `frequencia` (mensal|trimestral|anual) reamostra a série antes de responder, com a convenção escolhida em `agregacao`; a resposta traz `harmonizacao` com `derived: true` e a nota do cálculo. O que cada número é: `data` é a data de referência na convenção do SGS — em série mensal, trimestral ou anual, o PRIMEIRO dia do período (01/03/2026 = março de 2026). Algumas séries já chegam ACUMULADAS da origem e só o nome diz isso: acumulado no ano (PIB 4381, 4386) e acumulado em 12 meses (13522, 4382, 5793) — o valor numa data é o acumulado até aquele período, então não some esses valores nem subtraia um do outro; para o valor de um mês, use a série mensal. Revisões: o valor é o que o SGS publica no instante da extração (`retrieved_at` na proveniência). O BCB revisa séries como PIB, IBC-Br, balanço de pagamentos e crédito, e o SGS não guarda a versão originalmente divulgada — um ponto passado pode mudar entre duas consultas, e este servidor não tem como devolver o número da primeira divulgação. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_serie_valores input schema
{
"type": "object",
"required": [
"codigo"
],
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic)"
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
},
"dataFinal": {
"type": "string",
"description": "Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"dataInicial": {
"type": "string",
"description": "Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)"
}
},
"additionalProperties": false
}bcb_serie_valores output schema
{
"type": "object",
"required": [
"serie",
"totalRegistros",
"dados",
"provenance",
"attribution"
],
"properties": {
"dados": {
"type": "array",
"items": {
"type": "object",
"required": [
"data",
"valor"
],
"properties": {
"data": {
"type": "string",
"description": "Data de referência da observação (dd/MM/yyyy), na convenção do SGS: em série mensal, trimestral ou anual é o PRIMEIRO dia do período (01/03/2026 = março de 2026); em série diária, o próprio dia"
},
"valor": {
"type": "number",
"description": "Valor numérico da observação"
},
"observacoes": {
"type": "number",
"description": "Só em resposta harmonizada: observações de origem agregadas neste ponto"
}
},
"additionalProperties": false
},
"description": "Observações históricas"
},
"serie": {
"type": "object",
"required": [
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"natureza": {
"enum": [
"nivel",
"variacao_no_periodo",
"acumulado_no_ano",
"acumulado_12_meses",
null
],
"type": [
"string",
"null"
],
"description": "O que o valor da série é em cada data: 'nivel' (o valor da grandeza no período — saldo, fluxo, preço, taxa vigente, razão ou índice), 'variacao_no_periodo' (a variação ou rendimento do próprio período, como o IPCA mensal), 'acumulado_no_ano' ou 'acumulado_12_meses' (o acumulado até aquela data: não some nem subtraia esses valores). null = tipo não identificado: a série está fora do catálogo curado ou o catálogo não diz o que ela mede."
},
"categoria": {
"type": "string",
"description": "Categoria econômica"
},
"periodicidade": {
"type": "string",
"description": "Periodicidade (Diária, Mensal, etc.)"
},
"periodicidadeInferida": {
"type": "boolean",
"description": "Presente e true quando a periodicidade foi inferida do espaçamento das observações, e não lida do catálogo — a API do SGS não publica metadados de série."
}
},
"description": "Identificação da série temporal",
"additionalProperties": false
},
"chunking": {
"type": "object",
"required": [
"janelas",
"fatiaAnos"
],
"properties": {
"janelas": {
"type": "number",
"description": "Quantidade de janelas consultadas"
},
"fatiaAnos": {
"type": "number",
"description": "Largura máxima de cada janela, em anos"
}
},
"description": "Presente quando a consulta foi fatiada em várias requisições à origem, por causa do limite de 10 anos por janela em séries diárias. As fatias são fundidas e ordenadas antes de responder.",
"additionalProperties": false
},
"observacao": {
"type": "string",
"description": "Mensagem informativa (ex.: quando não há dados)"
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"harmonizacao": {
"type": "object",
"required": [
"frequencia",
"agregacao",
"derived",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Descrição em prosa do que foi calculado"
},
"derived": {
"type": "boolean",
"description": "Sempre true: o valor é derivado, não publicado pela fonte"
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"description": "Convenção usada para agregar os valores de cada período"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Frequência de destino"
},
"observacoesOriginais": {
"type": "number",
"description": "Observações antes da agregação"
}
},
"description": "Presente quando `frequencia` foi informada: descreve a reamostragem aplicada. Valor DERIVADO — calculado por este servidor, não publicado pelo Banco Central.",
"additionalProperties": false
},
"periodoFinal": {
"type": "string",
"description": "Data da última observação"
},
"janelaAplicada": {
"type": "object",
"required": [
"dataInicial",
"dataFinal",
"motivo"
],
"properties": {
"motivo": {
"type": "string",
"description": "Por que a janela foi aplicada e como pedir outra"
},
"dataFinal": {
"type": "string",
"description": "Fim da janela efetivamente consultada (dd/MM/yyyy)"
},
"dataInicial": {
"type": "string",
"description": "Início da janela efetivamente consultada (dd/MM/yyyy)"
}
},
"description": "Presente quando o período pedido estava aberto numa série diária e o servidor aplicou uma janela própria (a origem recusa janela aberta em série diária com HTTP 406).",
"additionalProperties": false
},
"periodoInicial": {
"type": "string",
"description": "Data da primeira observação"
},
"totalRegistros": {
"type": "number",
"description": "Quantidade de observações retornadas"
}
},
"additionalProperties": false
}bcb_serie_valores annotations
{
"title": "Consultar valores da série",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_serie_ultimos — Últimos valores da série
Advertised read-onlyOpen-world
Obtém as últimas N observações de UMA série temporal do BCB (mais recentes primeiro a partir do fim da série). Quando usar: para ver os dados mais recentes sem precisar calcular datas (ex.: últimos 12 meses do IPCA). Quantidade entre 1 e 1000 (padrão 10). Quando NÃO usar: para um intervalo de datas ou o histórico completo use bcb_serie_valores. Retorna: objeto `serie`, `totalRegistros` e `dados` (array de {data, valor}); sem dados, `totalRegistros` = 0 com `observacao`. Acima de 20: o endpoint nativo do BCB rejeita N > 20 em qualquer periodicidade, então o servidor descobre a periodicidade da série e busca por janela de datas, devolvendo os N últimos pontos. O que cada número é: `data` é a data de referência na convenção do SGS — em série mensal, trimestral ou anual, o PRIMEIRO dia do período (01/03/2026 = março de 2026). Algumas séries já chegam ACUMULADAS da origem e só o nome diz isso: acumulado no ano (PIB 4381, 4386) e acumulado em 12 meses (13522, 4382, 5793) — o valor numa data é o acumulado até aquele período, então não some esses valores nem subtraia um do outro; para o valor de um mês, use a série mensal. Revisões: o valor é o que o SGS publica no instante da extração (`retrieved_at` na proveniência). O BCB revisa séries como PIB, IBC-Br, balanço de pagamentos e crédito, e o SGS não guarda a versão originalmente divulgada — um ponto passado pode mudar entre duas consultas, e este servidor não tem como devolver o número da primeira divulgação. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_serie_ultimos input schema
{
"type": "object",
"required": [
"codigo"
],
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"quantidade": {
"type": "number",
"default": 10,
"maximum": 1000,
"minimum": 1,
"description": "Quantidade de valores a retornar (1-1000, padrão: 10). A API do BCB tem teto de 20 no endpoint nativo; acima disso o servidor busca por janela de datas e devolve os N últimos."
}
},
"additionalProperties": false
}bcb_serie_ultimos output schema
{
"type": "object",
"required": [
"serie",
"totalRegistros",
"dados",
"provenance",
"attribution"
],
"properties": {
"dados": {
"type": "array",
"items": {
"type": "object",
"required": [
"data",
"valor"
],
"properties": {
"data": {
"type": "string",
"description": "Data de referência da observação (dd/MM/yyyy), na convenção do SGS: em série mensal, trimestral ou anual é o PRIMEIRO dia do período (01/03/2026 = março de 2026); em série diária, o próprio dia"
},
"valor": {
"type": "number",
"description": "Valor numérico da observação"
}
},
"additionalProperties": false
},
"description": "Observações mais recentes"
},
"serie": {
"type": "object",
"required": [
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"natureza": {
"enum": [
"nivel",
"variacao_no_periodo",
"acumulado_no_ano",
"acumulado_12_meses",
null
],
"type": [
"string",
"null"
],
"description": "O que o valor da série é em cada data: 'nivel' (o valor da grandeza no período — saldo, fluxo, preço, taxa vigente, razão ou índice), 'variacao_no_periodo' (a variação ou rendimento do próprio período, como o IPCA mensal), 'acumulado_no_ano' ou 'acumulado_12_meses' (o acumulado até aquela data: não some nem subtraia esses valores). null = tipo não identificado: a série está fora do catálogo curado ou o catálogo não diz o que ela mede."
},
"categoria": {
"type": "string",
"description": "Categoria econômica"
},
"periodicidade": {
"type": "string",
"description": "Periodicidade (Diária, Mensal, etc.)"
},
"periodicidadeInferida": {
"type": "boolean",
"description": "Presente e true quando a periodicidade foi inferida do espaçamento das observações, e não lida do catálogo — a API do SGS não publica metadados de série."
}
},
"description": "Identificação da série temporal",
"additionalProperties": false
},
"chunking": {
"type": "object",
"required": [
"janelas",
"fatiaAnos"
],
"properties": {
"janelas": {
"type": "number",
"description": "Quantidade de janelas consultadas"
},
"fatiaAnos": {
"type": "number",
"description": "Largura máxima de cada janela, em anos"
}
},
"description": "Presente quando a consulta foi fatiada em várias requisições à origem, por causa do limite de 10 anos por janela em séries diárias. As fatias são fundidas e ordenadas antes de responder.",
"additionalProperties": false
},
"observacao": {
"type": "string",
"description": "Mensagem informativa (ex.: quando não há dados)"
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"totalRegistros": {
"type": "number",
"description": "Quantidade de observações retornadas"
}
},
"additionalProperties": false
}bcb_serie_ultimos annotations
{
"title": "Últimos valores da série",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_serie_metadados — Metadados da série
Advertised read-onlyOpen-world
Obtém a descrição de UMA série do BCB (nome, periodicidade, categoria, fonte e último valor), sem trazer a série histórica. Quando usar: para confirmar o que uma série representa e com que frequência é publicada antes de consultar os dados. Quando NÃO usar: para os valores em si use bcb_serie_valores ou bcb_serie_ultimos. Retorna: codigo, nome, periodicidade, categoria, fonte, `ultimoValor` e URLs diretas da API (urlConsulta, urlUltimos10). Limite da fonte: a API do SGS NÃO publica endpoint de metadados por série — não há unidade de medida disponível. Nome e categoria vêm do catálogo curado do servidor (135 séries verificadas contra a origem) e, fora dele, a periodicidade é inferida do espaçamento das observações, sinalizada por `periodicidadeInferida`. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_serie_metadados input schema
{
"type": "object",
"required": [
"codigo"
],
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
}
},
"additionalProperties": false
}bcb_serie_metadados output schema
{
"type": "object",
"required": [
"codigo",
"nome",
"fonte",
"provenance",
"attribution"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série"
},
"fonte": {
"type": "string",
"description": "Fonte dos dados"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"categoria": {
"type": "string",
"description": "Categoria econômica"
},
"observacao": {
"type": "string",
"description": "Observação sobre a origem dos metadados"
},
"provenance": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"description": "Um bloco por procedência que contribuiu com esta resposta (bloco de proveniência do portfólio; licenças nunca se fundem)"
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"ultimoValor": {
"type": "object",
"required": [
"data",
"valor"
],
"properties": {
"data": {
"type": "string",
"description": "Data de referência da observação (dd/MM/yyyy), na convenção do SGS: em série mensal, trimestral ou anual é o PRIMEIRO dia do período (01/03/2026 = março de 2026); em série diária, o próprio dia"
},
"valor": {
"type": "number",
"description": "Valor numérico da observação"
}
},
"description": "Última observação disponível",
"additionalProperties": false
},
"urlConsulta": {
"type": "string",
"description": "URL da API do BCB para consulta completa"
},
"urlUltimos10": {
"type": "string",
"description": "URL da API do BCB para os últimos 10 valores"
},
"periodicidade": {
"type": "string",
"description": "Periodicidade da série"
},
"periodicidadeInferida": {
"type": "boolean",
"description": "Presente e true quando a periodicidade foi inferida do espaçamento das observações"
}
},
"additionalProperties": false
}bcb_serie_metadados annotations
{
"title": "Metadados da série",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_series_populares — Listar séries populares
Advertised read-only
Lista o catálogo interno curado de 135 séries econômicas do BCB com seus códigos, agrupadas por categoria (Juros, Inflação, Câmbio, Atividade Econômica, Emprego, Fiscal, Setor Externo, Crédito, Agregados Monetários, Poupança); aceita filtro por categoria. Quando usar: para navegar/descobrir as séries disponíveis por tema. Quando NÃO usar: para busca por palavra-chave use bcb_buscar_serie; esta ferramenta não busca valores. Retorna: `totalSeries`, `categorias` (nº de categorias) e `series` — objeto agrupado por categoria quando sem filtro, ou array plano quando filtrado por categoria; cada item tem codigo, nome, categoria, periodicidade e `fonteNome`. Catálogo local: não faz chamada de rede. Procedência: `fonteNome` = 'portal' quando o nome é transcrito do dataset da série no Portal de Dados Abertos do BCB (82 séries, com `unidade`), e 'medido' quando a série não tem dataset lá — nesse caso o nome é herdado e o que foi verificado contra a origem é a periodicidade e a ordem de grandeza. Expectativas do Focus NÃO estão aqui: use bcb_focus_expectativas.
bcb_series_populares input schema
{
"type": "object",
"properties": {
"categoria": {
"type": "string",
"description": "Filtrar por categoria: Juros, Inflação, Câmbio, Atividade Econômica, Emprego, Fiscal, Setor Externo, Crédito, Agregados Monetários, Poupança, Índices de Mercado, Expectativas"
}
},
"additionalProperties": false
}bcb_series_populares output schema
{
"type": "object",
"required": [
"totalSeries",
"categorias",
"series",
"provenance",
"attribution"
],
"properties": {
"series": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"required": [
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"unidade": {
"type": "string",
"description": "Unidade de medida publicada pelo portal. Ausente nas séries sem dataset (fonteNome 'medido')."
},
"categoria": {
"type": "string",
"description": "Categoria econômica"
},
"fonteNome": {
"enum": [
"portal",
"medido"
],
"type": "string",
"description": "Procedência do `nome`: 'portal' = transcrito do dataset da série no Portal de Dados Abertos do BCB; 'medido' = a série não tem dataset no portal, o nome é herdado e só a periodicidade e a ordem de grandeza foram verificadas contra a origem."
},
"periodicidade": {
"type": "string",
"description": "Periodicidade (Diária, Mensal, etc.)"
}
},
"description": "Identificação da série temporal",
"additionalProperties": false
}
},
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"required": [
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"unidade": {
"type": "string",
"description": "Unidade de medida publicada pelo portal. Ausente nas séries sem dataset (fonteNome 'medido')."
},
"categoria": {
"type": "string",
"description": "Categoria econômica"
},
"fonteNome": {
"enum": [
"portal",
"medido"
],
"type": "string",
"description": "Procedência do `nome`: 'portal' = transcrito do dataset da série no Portal de Dados Abertos do BCB; 'medido' = a série não tem dataset no portal, o nome é herdado e só a periodicidade e a ordem de grandeza foram verificadas contra a origem."
},
"periodicidade": {
"type": "string",
"description": "Periodicidade (Diária, Mensal, etc.)"
}
},
"description": "Identificação da série temporal",
"additionalProperties": false
}
}
}
],
"description": "Séries encontradas. Objeto agrupado por categoria quando sem filtro; array plano quando filtrado por categoria."
},
"categorias": {
"type": "number",
"description": "Quantidade de categorias distintas"
},
"observacao": {
"type": "string",
"description": "Dica de uso"
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"totalSeries": {
"type": "number",
"description": "Quantidade total de séries retornadas"
}
},
"additionalProperties": false
}bcb_series_populares annotations
{
"title": "Listar séries populares",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}bcb_buscar_serie — Buscar série no catálogo
Advertised read-onlyOpen-world
Busca séries do BCB por palavra-chave (ou pelo código) em DUAS camadas: o catálogo curado local de 135 séries verificadas contra a origem, que vem primeiro e com `fonteNome` dizendo se o nome é transcrito do portal do BCB ou herdado, e o índice do Portal de Dados Abertos do BCB, com milhares de séries identificadas por código. Ignora acentos e maiúsculas ('inflacao' encontra 'Inflação'); vários termos são combinados com E ('ipca servicos'). Quando usar: para descobrir o código de uma série antes de consultar valores. Quando NÃO usar: para navegar tudo por categoria use bcb_series_populares; para valores use bcb_serie_valores. Retorna: `termo`, `totalEncontradas`, `series` (cada item com codigo, nome, origem — 'curado' ou 'indice' — e, no índice, `dataset` com a página do portal), `catalogo` (origem, obtidoEm, seriesIndexadas, cobertura) e, quando aplicável, `observacao`, `avisos`, `mensagem` e `sugestao`. Cobertura: o índice NÃO é o SGS inteiro, portanto não encontrar aqui não prova que a série não exista — o campo `catalogo.cobertura` diz isso explicitamente em toda resposta. Comportamento de rede: o índice é servido de cache com validade de 24 h e a renovação é feita pela primeira busca após o vencimento (uma requisição ao portal, ~1 s); as demais buscas não tocam a rede. Se o portal estiver fora, a busca degrada para o catálogo curado (ou para o último índice obtido) e sinaliza em `avisos`, sempre com a data de obtenção visível.
bcb_buscar_serie input schema
{
"type": "object",
"required": [
"termo"
],
"properties": {
"termo": {
"type": "string",
"minLength": 2,
"description": "Termo de busca (mínimo 2 caracteres) ou o código da série. Vários termos são combinados com E, sem distinção de acento; a palavra de todo dia é traduzida para a do BCB (déficit→resultado primário, calote→inadimplência, desemprego→desocupação) e a resposta diz quando isso aconteceu (notasVocabulario)."
},
"limite": {
"type": "number",
"default": 20,
"maximum": 100,
"minimum": 1,
"description": "Máximo de séries a devolver (1-100, padrão: 20). `totalEncontradas` traz o total antes do corte."
}
},
"additionalProperties": false
}bcb_buscar_serie output schema
{
"type": "object",
"required": [
"termo",
"totalEncontradas",
"series",
"catalogo",
"provenance",
"attribution"
],
"properties": {
"termo": {
"type": "string",
"description": "Termo pesquisado"
},
"avisos": {
"type": "array",
"items": {
"type": "string"
},
"description": "Avisos de degradação (índice vencido ou indisponível)"
},
"series": {
"type": "array",
"items": {
"type": "object",
"required": [
"codigo",
"nome",
"origem"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série (revisado quando `origem` = curado; derivado do slug do portal quando = indice)"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"origem": {
"enum": [
"curado",
"indice"
],
"type": "string",
"description": "Camada de onde veio o achado"
},
"dataset": {
"type": "string",
"description": "Página do dataset no portal de dados abertos (só quando `origem` = indice)"
},
"categoria": {
"type": "string",
"description": "Categoria econômica (só no catálogo curado)"
},
"fonteNome": {
"enum": [
"portal",
"medido"
],
"type": "string",
"description": "Só quando `origem` = curado. 'portal' = nome transcrito do dataset da série no Portal de Dados Abertos do BCB; 'medido' = série sem dataset no portal, nome herdado e apenas periodicidade e ordem de grandeza verificadas contra a origem."
},
"periodicidade": {
"type": "string",
"description": "Periodicidade (só no catálogo curado)"
}
},
"additionalProperties": false
},
"description": "Séries que correspondem ao termo — as do catálogo curado primeiro"
},
"catalogo": {
"type": "object",
"required": [
"origem",
"seriesIndexadas",
"cobertura"
],
"properties": {
"origem": {
"type": "string",
"description": "Camadas consultadas"
},
"obtidoEm": {
"type": "string",
"description": "Timestamp ISO 8601 em que o índice do portal foi obtido"
},
"cobertura": {
"type": "string",
"description": "Limite explícito de cobertura do índice"
},
"seriesIndexadas": {
"type": "number",
"description": "Quantidade de séries no índice consultado"
}
},
"description": "Proveniência do índice usado na busca",
"additionalProperties": false
},
"mensagem": {
"type": "string",
"description": "Mensagem exibida quando nada é encontrado"
},
"sugestao": {
"type": "string",
"description": "Sugestões de termos alternativos"
},
"observacao": {
"type": "string",
"description": "Aviso de corte quando há mais resultados que `limite`"
},
"provenance": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"description": "Um bloco por procedência que contribuiu com esta resposta (bloco de proveniência do portfólio; licenças nunca se fundem)"
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"notasVocabulario": {
"type": "array",
"items": {
"type": "string"
},
"description": "Quando um termo foi ampliado para a palavra que o BCB usa (déficit→resultado primário), diz qual"
},
"totalEncontradas": {
"type": "number",
"description": "Quantidade de séries encontradas, antes do corte por `limite`"
}
},
"additionalProperties": false
}bcb_buscar_serie annotations
{
"title": "Buscar série no catálogo",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_indicadores_atuais — Indicadores econômicos atuais
Advertised read-onlyOpen-world
Atalho que retorna, em uma única chamada, o valor mais recente dos principais indicadores da economia brasileira: Selic (meta do Copom), IPCA mensal, IPCA acumulado 12 meses, dólar comercial de venda (série diária) e IBC-Br. Não recebe parâmetros. Quando usar: para um panorama econômico rápido. Quando NÃO usar: para qualquer outra série, para dados históricos ou para escolher o período use bcb_serie_ultimos ou bcb_serie_valores. Retorna: `consultadoEm` (timestamp ISO 8601) e `indicadores` (array com indicador, codigo, data, valor — ou `erro` no item). Resiliente: cada indicador é buscado de forma independente, então a falha de um não derruba os demais. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_indicadores_atuais input schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}bcb_indicadores_atuais output schema
{
"type": "object",
"required": [
"consultadoEm",
"indicadores",
"provenance",
"attribution"
],
"properties": {
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"indicadores": {
"type": "array",
"items": {
"type": "object",
"required": [
"indicador",
"codigo"
],
"properties": {
"data": {
"type": "string",
"description": "Data da observação"
},
"erro": {
"type": "string",
"description": "Mensagem de erro quando o indicador não pôde ser obtido"
},
"valor": {
"type": "number",
"description": "Valor mais recente"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"indicador": {
"type": "string",
"description": "Nome do indicador"
}
},
"additionalProperties": false
},
"description": "Lista de indicadores com seus valores mais recentes"
},
"consultadoEm": {
"type": "string",
"description": "Timestamp ISO 8601 da consulta"
}
},
"additionalProperties": false
}bcb_indicadores_atuais annotations
{
"title": "Indicadores econômicos atuais",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_variacao — Variação percentual da série
Advertised read-onlyOpen-world
Calcula a variação percentual de UMA série no período, mais estatísticas descritivas. Para série de NÍVEL (dólar, Selic, dívida, produção) é a variação entre o primeiro e o último ponto; para série que JÁ É uma variação por período (IPCA 433, INPC 188, IGP-M 189 e demais índices de preço mensais do catálogo; Selic/CDI acumulados no mês 4390/4391; rentabilidade da poupança 25/195) é o ACUMULADO do período por encadeamento — "quanto o IPCA acumulou em 2024" ou "quanto a Selic rendeu em 2024" é esta tool. O campo `analise.metodo` diz qual das duas contas foi feita; código fora do catálogo curado é tratado como nível. Série de acumulado móvel (IPCA em 12 meses, 13522) é recusada com orientação — o valor publicado já é a resposta. O período pode ser definido por datas (dataInicial/dataFinal) OU pelos últimos N períodos (parâmetro `periodos`, que tem precedência e ignora as datas). Quando usar: para medir tendência/variação/acumulado de uma única série. Quando NÃO usar: para comparar várias séries use bcb_comparar; para os valores brutos use bcb_serie_valores. Requer ao menos 2 observações no período (senão retorna `isError`). Retorna: `serie`, `periodo` (dataInicial, dataFinal, totalPeriodos), `analise` (metodo, valorInicial, valorFinal, diferencaAbsoluta — nula quando encadeado —, variacaoPercentual, variacaoFormatada) e `estatisticas` (maximo, minimo, media, amplitude). Períodos longos são tratados automaticamente: janela diária acima de 10 anos é fatiada (a API do BCB responde 406) e `periodos` acima de 20 é atendido por janela de datas; `chunking` e `janelaAplicada` aparecem na resposta quando isso acontece. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_variacao input schema
{
"type": "object",
"required": [
"codigo"
],
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"periodos": {
"type": "number",
"description": "Alternativa: calcular variação dos últimos N períodos (ignora datas se informado). Acima de 20 o servidor busca por janela de datas, porque o endpoint nativo do BCB tem esse teto."
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy). Se não informada, usa o último valor disponível."
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy). Se não informada, usa o primeiro valor disponível."
}
},
"additionalProperties": false
}bcb_variacao output schema
{
"type": "object",
"required": [
"serie",
"periodo",
"analise",
"estatisticas",
"derivacao",
"provenance",
"attribution"
],
"properties": {
"serie": {
"type": "object",
"required": [
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série no catálogo curado; 'Série N' quando o código está fora dele"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"categoria": {
"type": "string",
"description": "Categoria econômica no catálogo curado; 'Desconhecida' quando o código está fora dele"
}
},
"description": "Identificação da série",
"additionalProperties": false
},
"analise": {
"type": "object",
"required": [
"metodo",
"valorInicial",
"valorFinal",
"diferencaAbsoluta",
"variacaoPercentual",
"variacaoFormatada"
],
"properties": {
"metodo": {
"enum": [
"nivel",
"encadeamento"
],
"type": "string",
"description": "Como a variação foi medida: `nivel` = (último − primeiro) / primeiro, para série de nível; `encadeamento` = acumulado composto de todas as observações, para série que já é uma variação percentual por período (IPCA, INPC, IGP-M mensais e os núcleos/grupos do IPCA do catálogo; Selic e CDI acumulados no mês, 4390/4391; rentabilidade da poupança, 25/195 — nesta, uma observação por mês). A detecção cobre as séries de variação do catálogo curado; código fora dele é tratado como nível."
},
"valorFinal": {
"type": "number",
"description": "Última observação do período, verbatim da fonte"
},
"valorInicial": {
"type": "number",
"description": "Primeira observação do período, verbatim da fonte"
},
"diferencaAbsoluta": {
"type": [
"number",
"null"
],
"description": "valorFinal − valorInicial em série de nível; NULO em série encadeada, onde não se aplica"
},
"variacaoFormatada": {
"type": "string",
"description": "variacaoPercentual em texto, com sinal e duas casas (ex.: \"+4.83%\")"
},
"variacaoPercentual": {
"type": "number",
"description": "Variação (nível) ou acumulado (encadeamento), em %"
}
},
"description": "Resultado da variação no período. Em `metodo: \"nivel\"` é a variação entre o primeiro e o último valor; em `metodo: \"encadeamento\"` (série que já é variação por período, como IPCA e IGP-M mensais) é o acumulado composto de todas as observações",
"additionalProperties": false
},
"periodo": {
"type": "object",
"required": [
"dataInicial",
"dataFinal",
"totalPeriodos"
],
"properties": {
"dataFinal": {
"type": "string",
"description": "Data da última observação usada (dd/MM/yyyy, como o SGS publica)"
},
"dataInicial": {
"type": "string",
"description": "Data da primeira observação usada (dd/MM/yyyy, como o SGS publica)"
},
"totalPeriodos": {
"type": "number",
"description": "Quantidade de observações no período"
}
},
"description": "Janela temporal analisada",
"additionalProperties": false
},
"chunking": {
"type": "object",
"required": [
"janelas",
"fatiaAnos"
],
"properties": {
"janelas": {
"type": "number",
"description": "Quantidade de janelas consultadas"
},
"fatiaAnos": {
"type": "number",
"description": "Largura máxima de cada janela, em anos"
}
},
"description": "Presente quando a consulta foi fatiada em várias requisições à origem, por causa do limite de 10 anos por janela em séries diárias. As fatias são fundidas e ordenadas antes de responder.",
"additionalProperties": false
},
"derivacao": {
"type": "object",
"required": [
"derived",
"motor",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Convenções de cálculo e arredondamento, em prosa"
},
"motor": {
"type": "string",
"description": "Componente que computou a estatística"
},
"derived": {
"type": "boolean",
"description": "Sempre true: há número calculado nesta resposta"
}
},
"description": "Origem dos números calculados: o que é derivado, por qual motor e com quais convenções",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"estatisticas": {
"type": "object",
"required": [
"maximo",
"minimo",
"media",
"amplitude"
],
"properties": {
"media": {
"type": "number",
"description": "Média aritmética dos valores do período (derivada, 4 casas)"
},
"maximo": {
"type": "number",
"description": "Maior valor do período, verbatim da fonte"
},
"minimo": {
"type": "number",
"description": "Menor valor do período, verbatim da fonte"
},
"amplitude": {
"type": "number",
"description": "maximo − minimo (derivada, 4 casas)"
}
},
"description": "Estatísticas descritivas dos valores no período",
"additionalProperties": false
},
"janelaAplicada": {
"type": "object",
"required": [
"dataInicial",
"dataFinal",
"motivo"
],
"properties": {
"motivo": {
"type": "string",
"description": "Por que a janela foi aplicada e como pedir outra"
},
"dataFinal": {
"type": "string",
"description": "Fim da janela efetivamente consultada (dd/MM/yyyy)"
},
"dataInicial": {
"type": "string",
"description": "Início da janela efetivamente consultada (dd/MM/yyyy)"
}
},
"description": "Presente quando o período pedido estava aberto numa série diária e o servidor aplicou uma janela própria (a origem recusa janela aberta em série diária com HTTP 406).",
"additionalProperties": false
}
},
"additionalProperties": false
}bcb_variacao annotations
{
"title": "Variação percentual da série",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_comparar — Comparar séries
Advertised read-onlyOpen-world
Compara de 2 a 5 séries temporais no MESMO período (dataInicial e dataFinal obrigatórias), calculando a variação percentual de cada uma e ordenando-as num ranking (maior para menor variação). Série de nível entra pela variação entre as pontas; série que já é variação por período (IPCA, INPC, IGP-M mensais do catálogo; Selic/CDI acumulados no mês; poupança) entra pelo ACUMULADO encadeado do período — cada item diz em `metodo` qual conta foi feita, então "qual índice de preço subiu mais em 2024" é esta tool. Quando usar: para comparar/correlacionar a evolução de vários indicadores lado a lado. Quando NÃO usar: para uma única série use bcb_variacao. Retorna: `periodo`, `totalSeries`, `seriesComDados`, `seriesComErro`, `ranking` (cada item com posicao, codigo, nome, metodo, valorInicial, valorFinal, variacaoPercentual, maximo, minimo, media) e `erros`. Resiliente: séries sem dados no período, e séries de acumulado móvel (IPCA em 12 meses), são isoladas em `erros` sem invalidar a comparação. Periodicidades diferentes: comparar uma série diária com uma mensal alinha pontos que não são comparáveis, e a resposta avisa isso em `aviso`; informe `frequencia` (mensal|trimestral|anual) para harmonizar todas na mesma grade antes de comparar, escolhendo a convenção em `agregacao`. Janelas longas em séries diárias são fatiadas automaticamente (limite de 10 anos da API do BCB). Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_comparar input schema
{
"type": "object",
"required": [
"codigos",
"dataInicial",
"dataFinal"
],
"properties": {
"codigos": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 5,
"minItems": 2,
"description": "Array com 2 a 5 códigos de séries para comparar"
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy)"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy)"
}
},
"additionalProperties": false
}bcb_comparar output schema
{
"type": "object",
"required": [
"periodo",
"totalSeries",
"seriesComDados",
"seriesComErro",
"ranking",
"erros",
"derivacao",
"provenance",
"attribution"
],
"properties": {
"aviso": {
"type": "string",
"description": "Presente quando as séries comparadas têm periodicidades diferentes e nenhuma harmonização foi pedida — os números do ranking, nesse caso, não são diretamente comparáveis entre si."
},
"erros": {
"type": "array",
"items": {
"type": "object",
"required": [
"codigo",
"erro"
],
"properties": {
"erro": {
"type": "string"
},
"nome": {
"type": "string"
},
"codigo": {
"type": "number"
}
},
"additionalProperties": false
},
"description": "Séries que não retornaram dados, com o motivo"
},
"periodo": {
"type": "object",
"required": [
"dataInicial",
"dataFinal"
],
"properties": {
"dataFinal": {
"type": "string",
"description": "Data final pedida, em dd/MM/yyyy"
},
"dataInicial": {
"type": "string",
"description": "Data inicial pedida, em dd/MM/yyyy"
}
},
"description": "Janela temporal comparada",
"additionalProperties": false
},
"ranking": {
"type": "array",
"items": {
"type": "object",
"required": [
"posicao",
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string"
},
"media": {
"type": "number"
},
"codigo": {
"type": "number"
},
"maximo": {
"type": "number"
},
"metodo": {
"enum": [
"nivel",
"encadeamento"
],
"type": "string",
"description": "Como a variação foi medida: `nivel` = (último − primeiro) / primeiro, para série de nível; `encadeamento` = acumulado composto de todas as observações, para série que já é uma variação percentual por período (IPCA, INPC, IGP-M mensais e os núcleos/grupos do IPCA do catálogo; Selic e CDI acumulados no mês, 4390/4391; rentabilidade da poupança, 25/195 — nesta, uma observação por mês). A detecção cobre as séries de variação do catálogo curado; código fora dele é tratado como nível."
},
"minimo": {
"type": "number"
},
"posicao": {
"type": "number",
"description": "Posição no ranking"
},
"categoria": {
"type": "string"
},
"valorFinal": {
"type": "number"
},
"valorInicial": {
"type": "number"
},
"periodicidade": {
"type": "string"
},
"totalRegistros": {
"type": "number"
},
"variacaoFormatada": {
"type": "string"
},
"variacaoPercentual": {
"type": "number",
"description": "Variação entre as pontas (metodo nivel) ou acumulado encadeado do período (metodo encadeamento), em %"
}
},
"additionalProperties": false
},
"description": "Séries ordenadas pela variação percentual (maior para menor)"
},
"derivacao": {
"type": "object",
"required": [
"derived",
"motor",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Convenções de cálculo e arredondamento, em prosa"
},
"motor": {
"type": "string",
"description": "Componente que computou a estatística"
},
"derived": {
"type": "boolean",
"description": "Sempre true: há número calculado nesta resposta"
}
},
"description": "Origem dos números calculados: o que é derivado, por qual motor e com quais convenções",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"totalSeries": {
"type": "number",
"description": "Quantidade de séries solicitadas"
},
"harmonizacao": {
"type": "object",
"required": [
"frequencia",
"agregacao",
"derived",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Descrição em prosa do que foi calculado"
},
"derived": {
"type": "boolean",
"description": "Sempre true: o valor é derivado, não publicado pela fonte"
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"description": "Convenção usada para agregar os valores de cada período"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Frequência de destino"
},
"observacoesOriginais": {
"type": "number",
"description": "Observações antes da agregação"
}
},
"description": "Presente quando `frequencia` foi informada: descreve a reamostragem aplicada. Valor DERIVADO — calculado por este servidor, não publicado pelo Banco Central.",
"additionalProperties": false
},
"seriesComErro": {
"type": "number",
"description": "Quantidade de séries sem dados ou com erro"
},
"seriesComDados": {
"type": "number",
"description": "Quantidade de séries com dados no período"
}
},
"additionalProperties": false
}bcb_comparar annotations
{
"title": "Comparar séries",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_correlacao — Correlacionar séries
Advertised read-onlyOpen-world
Calcula a correlação estatística entre 2 a 5 séries temporais do BCB no MESMO período (dataInicial e dataFinal obrigatórias), par a par. Quando usar: para medir se dois indicadores se movem juntos (ex.: dólar e Selic, IPCA e IGP-M). Quando NÃO usar: para comparar a variação de cada série lado a lado use bcb_comparar; para uma série só use bcb_variacao. Métodos: `pearson` (padrão) mede relação LINEAR entre os valores; `spearman` mede relação MONÓTONA entre os postos e é o adequado quando a relação não é reta ou quando uma série fica parada em platôs (taxa de juros entre reuniões do Copom). Base: `nivel` (padrão) correlaciona os valores; `variacao` correlaciona a mudança percentual de um ponto para o outro — prefira `variacao` quando as duas séries têm tendência (preço, índice, estoque), porque o nível de duas séries crescentes tem correlação alta só porque ambas crescem com o tempo. Retorna: `periodo`, `metodo`, `base`, `series`, `alinhamento` (datas cruzadas, completas e parciais), `pares` (cada um com codigoA/codigoB, `coeficiente` entre -1 e 1, `n`, `descartados` e `interpretacao` em prosa), `erros` e `derivacao`. Coeficiente que não pode ser calculado vem `null` com `motivo` — nunca 0, que significaria ausência medida de relação. Periodicidades diferentes são RECUSADAS, não avisadas: cruzar uma série diária com uma mensal por data casa só as datas coincidentes (cerca de 7 por ano) e produziria um coeficiente sobre esse punhado; informe `frequencia` para harmonizar todas na mesma grade antes de correlacionar. Correlação não estabelece causalidade. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_correlacao input schema
{
"type": "object",
"required": [
"codigos",
"dataInicial",
"dataFinal"
],
"properties": {
"base": {
"enum": [
"nivel",
"variacao"
],
"type": "string",
"default": "nivel",
"description": "`nivel` correlaciona os valores; `variacao` correlaciona a mudança percentual de um ponto para o seguinte. Prefira `variacao` quando as duas séries têm tendência: o nível de duas séries crescentes tem correlação alta só porque ambas crescem com o tempo."
},
"metodo": {
"enum": [
"pearson",
"spearman"
],
"type": "string",
"default": "pearson",
"description": "`pearson` mede relação linear entre os valores; `spearman` mede relação monótona entre os postos (com posto médio nos empates) e é o adequado quando a relação não é reta ou quando uma das séries fica parada em platôs, como a Selic entre reuniões do Copom."
},
"codigos": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 5,
"minItems": 2,
"description": "Array com 2 a 5 códigos de séries para correlacionar par a par"
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy)"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy)"
}
},
"additionalProperties": false
}bcb_correlacao output schema
{
"type": "object",
"required": [
"periodo",
"metodo",
"base",
"series",
"alinhamento",
"pares",
"erros",
"derivacao",
"provenance",
"attribution"
],
"properties": {
"base": {
"enum": [
"nivel",
"variacao"
],
"type": "string",
"description": "Se o cálculo usou os valores ou as variações"
},
"erros": {
"type": "array",
"items": {
"type": "object",
"required": [
"codigo",
"erro"
],
"properties": {
"erro": {
"type": "string"
},
"nome": {
"type": "string"
},
"codigo": {
"type": "number"
}
},
"additionalProperties": false
},
"description": "Séries que não retornaram dados, com o motivo"
},
"pares": {
"type": "array",
"items": {
"type": "object",
"required": [
"codigoA",
"codigoB",
"coeficiente",
"n",
"descartados",
"interpretacao"
],
"properties": {
"n": {
"type": "number",
"description": "Pares de valores efetivamente usados"
},
"nomeA": {
"type": "string"
},
"nomeB": {
"type": "string"
},
"motivo": {
"type": "string",
"description": "Por que o coeficiente é `null`; ausente quando há coeficiente"
},
"codigoA": {
"type": "number"
},
"codigoB": {
"type": "number"
},
"coeficiente": {
"type": [
"number",
"null"
],
"description": "Coeficiente entre -1 e 1; `null` quando indefinido (ver `motivo`) — nunca 0 por omissão"
},
"descartados": {
"type": "number",
"description": "Datas descartadas por falta de valor em uma das pontas"
},
"interpretacao": {
"type": [
"string",
"null"
],
"description": "Leitura em prosa da força e do sentido; `null` quando não há coeficiente"
}
},
"additionalProperties": false
},
"description": "Um item por par de séries"
},
"metodo": {
"enum": [
"pearson",
"spearman"
],
"type": "string",
"description": "Método aplicado"
},
"series": {
"type": "array",
"items": {
"type": "object",
"required": [
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string"
},
"codigo": {
"type": "number"
},
"natureza": {
"enum": [
"nivel",
"variacao_no_periodo",
"acumulado_no_ano",
"acumulado_12_meses",
null
],
"type": [
"string",
"null"
],
"description": "O que o valor da série é em cada data: 'nivel' (o valor da grandeza no período — saldo, fluxo, preço, taxa vigente, razão ou índice), 'variacao_no_periodo' (a variação ou rendimento do próprio período, como o IPCA mensal), 'acumulado_no_ano' ou 'acumulado_12_meses' (o acumulado até aquela data: não some nem subtraia esses valores). null = tipo não identificado: a série está fora do catálogo curado ou o catálogo não diz o que ela mede."
},
"categoria": {
"type": "string"
},
"periodicidade": {
"type": "string"
},
"totalRegistros": {
"type": "number"
},
"periodicidadeInferida": {
"type": "boolean"
}
},
"additionalProperties": false
},
"description": "Séries que entraram no cálculo"
},
"periodo": {
"type": "object",
"required": [
"dataInicial",
"dataFinal"
],
"properties": {
"dataFinal": {
"type": "string",
"description": "Data final pedida, em dd/MM/yyyy"
},
"dataInicial": {
"type": "string",
"description": "Data inicial pedida, em dd/MM/yyyy"
}
},
"description": "Janela temporal correlacionada",
"additionalProperties": false
},
"derivacao": {
"type": "object",
"required": [
"derived",
"motor",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Convenções de cálculo e arredondamento, em prosa"
},
"motor": {
"type": "string",
"description": "Componente que computou a estatística"
},
"derived": {
"type": "boolean",
"description": "Sempre true: há número calculado nesta resposta"
}
},
"description": "Origem dos números calculados: o que é derivado, por qual motor e com quais convenções",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"alinhamento": {
"type": "object",
"required": [
"datas",
"completas",
"parciais"
],
"properties": {
"datas": {
"type": "number",
"description": "Datas distintas na união das séries"
},
"grade": {
"type": "string",
"description": "Grade temporal usada no cruzamento"
},
"parciais": {
"type": "number",
"description": "Datas em que ao menos uma série não publica"
},
"completas": {
"type": "number",
"description": "Datas em que todas as séries publicam"
}
},
"description": "Como as grades foram cruzadas. `completas` é o que efetivamente entra num coeficiente: datas em que TODAS as séries publicam. A distância entre `datas` e `completas` é a medida de quanto as séries não se sobrepõem.",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"harmonizacao": {
"type": "object",
"required": [
"frequencia",
"agregacao",
"derived",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Descrição em prosa do que foi calculado"
},
"derived": {
"type": "boolean",
"description": "Sempre true: o valor é derivado, não publicado pela fonte"
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"description": "Convenção usada para agregar os valores de cada período"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Frequência de destino"
},
"observacoesOriginais": {
"type": "number",
"description": "Observações antes da agregação"
}
},
"description": "Presente quando `frequencia` foi informada: descreve a reamostragem aplicada. Valor DERIVADO — calculado por este servidor, não publicado pelo Banco Central.",
"additionalProperties": false
}
},
"additionalProperties": false
}bcb_correlacao annotations
{
"title": "Correlacionar séries",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_deflacionar — Deflacionar série (valores reais)
Advertised read-onlyOpen-world
Converte uma série NOMINAL do BCB em valores REAIS (moeda constante), descontando a inflação do período — a diferença entre 'o salário mínimo subiu 46% desde 2020' e 'o salário mínimo subiu 5% em poder de compra'. Quando usar: sempre que valores em reais de épocas diferentes forem comparados. Quando NÃO usar: para séries que já são percentuais, índices ou taxas (deflacionar uma taxa de juros não significa nada); para a série nominal crua use bcb_serie_valores. Índice: `ipca` (padrão), `inpc` ou `igpm`. Base: `mesBase` no formato yyyy-MM define em reais de que mês os valores são expressos; sem ele, usa o último mês publicado do índice ('em reais de hoje'). Retorna: `serie`, `deflator` (índice, código, cobertura), `base`, `periodo`, `dados` (cada ponto com valorNominal, `valorReal` e `fator`), `variacao` (a percentual nominal ao lado da real no mesmo período), `derivacao` e `avisos`. Limite da fonte: o SGS não publica número-índice, então o índice é reconstruído compondo as variações mensais — reconstrução conferida contra a própria fonte (diferença máxima de 0,0052 ponto percentual contra o acumulado oficial em 12 meses). Observação fora da cobertura do índice recebe `valorReal: null`, nunca um valor inventado; como o índice sai com defasagem, o mês corrente costuma cair nesse caso. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
bcb_deflacionar input schema
{
"type": "object",
"required": [
"codigo",
"dataInicial",
"dataFinal"
],
"properties": {
"codigo": {
"type": "number",
"description": "Código da série NOMINAL a deflacionar (ex.: 1619 para salário mínimo)"
},
"indice": {
"enum": [
"ipca",
"inpc",
"igpm"
],
"type": "string",
"default": "ipca",
"description": "Índice de preços usado como deflator: IPCA (433), INPC (188) ou IGP-M (189)"
},
"mesBase": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}$",
"description": "Mês em cujos preços os valores serão expressos, no formato yyyy-MM. Sem ele, usa o último mês publicado do índice — isto é, 'em reais de hoje'."
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy)"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy)"
}
},
"additionalProperties": false
}bcb_deflacionar output schema
{
"type": "object",
"required": [
"serie",
"deflator",
"base",
"periodo",
"dados",
"variacao",
"derivacao",
"provenance",
"attribution"
],
"properties": {
"base": {
"type": "object",
"required": [
"mes",
"descricao"
],
"properties": {
"mes": {
"type": "string",
"description": "MM/yyyy"
},
"descricao": {
"type": "string",
"description": "O mês base em prosa, para repetir ao leitor"
}
},
"description": "Mês em cujos preços os valores reais estão expressos",
"additionalProperties": false
},
"dados": {
"type": "array",
"items": {
"type": "object",
"required": [
"data",
"valorNominal",
"valorReal",
"fator"
],
"properties": {
"data": {
"type": "string",
"description": "dd/MM/yyyy"
},
"fator": {
"type": [
"number",
"null"
],
"description": "Multiplicador aplicado; `null` pelo mesmo motivo"
},
"valorReal": {
"type": [
"number",
"null"
],
"description": "Valor em reais do mês base; `null` quando a data cai fora da cobertura do índice"
},
"valorNominal": {
"type": "number",
"description": "Valor como o BCB publicou"
}
},
"additionalProperties": false
},
"description": "Observações com o valor publicado e o valor em moeda constante"
},
"serie": {
"type": "object",
"required": [
"codigo",
"nome"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série no catálogo curado; 'Série N' quando o código está fora dele"
},
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"natureza": {
"enum": [
"nivel",
"variacao_no_periodo",
"acumulado_no_ano",
"acumulado_12_meses",
null
],
"type": [
"string",
"null"
],
"description": "O que o valor da série é em cada data: 'nivel' (o valor da grandeza no período — saldo, fluxo, preço, taxa vigente, razão ou índice), 'variacao_no_periodo' (a variação ou rendimento do próprio período, como o IPCA mensal), 'acumulado_no_ano' ou 'acumulado_12_meses' (o acumulado até aquela data: não some nem subtraia esses valores). null = tipo não identificado: a série está fora do catálogo curado ou o catálogo não diz o que ela mede."
},
"categoria": {
"type": "string",
"description": "Categoria econômica no catálogo curado; 'Desconhecida' quando o código está fora dele"
},
"periodicidade": {
"type": "string",
"description": "Periodicidade (Diária, Mensal, etc.): a do catálogo curado ou, fora dele, a inferida das observações"
},
"totalRegistros": {
"type": "number",
"description": "Quantidade de observações em `dados`"
},
"periodicidadeInferida": {
"type": "boolean",
"description": "Presente e true quando a periodicidade foi inferida do espaçamento das observações, e não lida do catálogo — a API do SGS não publica metadados de série."
}
},
"description": "Identificação da série nominal",
"additionalProperties": false
},
"avisos": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ressalvas sobre cobertura do índice ou mês base substituído"
},
"periodo": {
"type": "object",
"required": [
"dataInicial",
"dataFinal"
],
"properties": {
"dataFinal": {
"type": "string",
"description": "Data final pedida, em dd/MM/yyyy"
},
"dataInicial": {
"type": "string",
"description": "Data inicial pedida, em dd/MM/yyyy"
}
},
"description": "Janela pedida da série nominal",
"additionalProperties": false
},
"chunking": {
"type": "object",
"required": [
"janelas",
"fatiaAnos"
],
"properties": {
"janelas": {
"type": "number",
"description": "Quantidade de janelas consultadas"
},
"fatiaAnos": {
"type": "number",
"description": "Largura máxima de cada janela, em anos"
}
},
"description": "Presente quando a consulta foi fatiada em várias requisições à origem, por causa do limite de 10 anos por janela em séries diárias. As fatias são fundidas e ordenadas antes de responder.",
"additionalProperties": false
},
"deflator": {
"type": "object",
"required": [
"indice",
"codigo",
"nome",
"cobertura"
],
"properties": {
"nome": {
"type": "string",
"description": "Nome da série do índice"
},
"codigo": {
"type": "number",
"description": "Código SGS da série de variação mensal do índice"
},
"indice": {
"type": "string",
"description": "Índice usado como deflator: IPCA, INPC ou IGPM"
},
"cobertura": {
"type": "object",
"required": [
"primeiroMes",
"ultimoMes"
],
"properties": {
"ultimoMes": {
"type": "string",
"description": "MM/yyyy"
},
"primeiroMes": {
"type": "string",
"description": "MM/yyyy"
}
},
"description": "Primeiro e último mês com deflator — observação fora deste intervalo sai com `valorReal: null`",
"additionalProperties": false
}
},
"description": "Índice de preços usado e o intervalo que ele cobre",
"additionalProperties": false
},
"variacao": {
"type": [
"object",
"null"
],
"required": [
"nominal",
"real",
"dataInicial",
"dataFinal"
],
"properties": {
"real": {
"type": "number",
"description": "Variação percentual em poder de compra"
},
"nominal": {
"type": "number",
"description": "Variação percentual sem descontar inflação"
},
"dataFinal": {
"type": "string",
"description": "Data da última observação deflacionada (dd/MM/yyyy)"
},
"dataInicial": {
"type": "string",
"description": "Data da primeira observação deflacionada (dd/MM/yyyy)"
}
},
"description": "Variação percentual do período em moeda corrente ao lado da variação em moeda constante — é a comparação que a tool existe para entregar. `null` quando há menos de duas observações deflacionadas."
},
"derivacao": {
"type": "object",
"required": [
"derived",
"motor",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Convenções de cálculo e arredondamento, em prosa"
},
"motor": {
"type": "string",
"description": "Componente que computou a estatística"
},
"derived": {
"type": "boolean",
"description": "Sempre true: há número calculado nesta resposta"
}
},
"description": "Origem dos números calculados: o que é derivado, por qual motor e com quais convenções",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"harmonizacao": {
"type": "object",
"required": [
"frequencia",
"agregacao",
"derived",
"nota"
],
"properties": {
"nota": {
"type": "string",
"description": "Descrição em prosa do que foi calculado"
},
"derived": {
"type": "boolean",
"description": "Sempre true: o valor é derivado, não publicado pela fonte"
},
"agregacao": {
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"type": "string",
"description": "Convenção usada para agregar os valores de cada período"
},
"frequencia": {
"enum": [
"mensal",
"trimestral",
"anual"
],
"type": "string",
"description": "Frequência de destino"
},
"observacoesOriginais": {
"type": "number",
"description": "Observações antes da agregação"
}
},
"description": "Presente quando `frequencia` foi informada: descreve a reamostragem aplicada. Valor DERIVADO — calculado por este servidor, não publicado pelo Banco Central.",
"additionalProperties": false
},
"janelaAplicada": {
"type": "object",
"required": [
"dataInicial",
"dataFinal",
"motivo"
],
"properties": {
"motivo": {
"type": "string",
"description": "Por que a janela foi aplicada e como pedir outra"
},
"dataFinal": {
"type": "string",
"description": "Fim da janela efetivamente consultada (dd/MM/yyyy)"
},
"dataInicial": {
"type": "string",
"description": "Início da janela efetivamente consultada (dd/MM/yyyy)"
}
},
"description": "Presente quando o período pedido estava aberto numa série diária e o servidor aplicou uma janela própria (a origem recusa janela aberta em série diária com HTTP 406).",
"additionalProperties": false
}
},
"additionalProperties": false
}bcb_deflacionar annotations
{
"title": "Deflacionar série (valores reais)",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_focus_expectativas — Expectativas de mercado (Focus)
Advertised read-onlyOpen-world
Consulta as expectativas de mercado do boletim Focus para UM indicador, com o horizonte como parâmetro: mensal, trimestral, anual, inflação nos próximos 12 meses e nos próximos 24 meses. Devolve média, mediana, desvio padrão, mínimo, máximo e número de respondentes por data de coleta. Quando usar: para expectativa de IPCA, IGP-M, PIB, câmbio e afins em um mês, trimestre ou ano específico, ou para a inflação rolante. Quando NÃO usar: para expectativa de Selic por reunião do Copom use bcb_focus_selic; para o valor REALIZADO (não esperado) use bcb_serie_valores. Regras do contrato: `referencia` é obrigatória nos horizontes de calendário (mensal, trimestral, anual) e recusada nos rolantes; `suavizada` só vale nos rolantes; `top5: true` traz as expectativas das cinco instituições mais assertivas e existe nos cinco horizontes. Se não souber o texto exato do indicador ou da referência, chame bcb_focus_referencias primeiro — o conjunto de indicadores MUDA por horizonte, e pedir um indicador no horizonte em que a fonte não o publica é a causa mais comum de resposta vazia. Retorna: `indicador`, `horizonte`, `base` (consenso|top5), `filtro` (referencia, dataInicial, dataFinal, janelaPadrao, suavizada), `totalRegistros`, `expectativas` (array normalizado), `urlConsulta`, `consultadoEm` e, quando aplicável, `observacao`. Sem datas, a janela padrão é de 30 dias. Fonte: Expectativas de Mercado (Focus) do Banco Central do Brasil, via Olinda OData. O Focus é vintage por construção: `coletadoEm` é a data da coleta e `referencia` é o alvo da expectativa — a mesma referência aparece em muitas coletas, e é isso que permite ver a expectativa mudar no tempo. A contagem é feita do nosso lado porque a fonte ignora `$count`; e o filtro é obrigatório por construção porque consulta sem filtro não completa na origem. Microdados por instituição NÃO são expostos: a fonte desativou esse recurso por risco de quebra de confidencialidade.
bcb_focus_expectativas input schema
{
"type": "object",
"required": [
"indicador",
"horizonte"
],
"properties": {
"top5": {
"type": "boolean",
"default": false,
"description": "Expectativas do Top 5 (as cinco instituições mais assertivas) em vez do consenso; existe nos cinco horizontes"
},
"limite": {
"type": "number",
"default": 50,
"maximum": 500,
"minimum": 1,
"description": "Máximo de coletas a devolver (1-500, padrão 50)"
},
"dataFinal": {
"type": "string",
"description": "Fim da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje."
},
"horizonte": {
"enum": [
"mensal",
"trimestral",
"anual",
"inflacao_12m",
"inflacao_24m"
],
"type": "string",
"description": "mensal, trimestral e anual usam `referencia`; inflacao_12m e inflacao_24m são rolantes e não usam"
},
"indicador": {
"type": "string",
"minLength": 2,
"description": "Indicador exatamente como a fonte publica (ex.: 'IPCA', 'IGP-M', 'PIB Total', 'Câmbio'). Veja bcb_focus_referencias."
},
"suavizada": {
"type": "boolean",
"description": "Só nos horizontes rolantes: série suavizada (true) ou não suavizada (false)"
},
"referencia": {
"type": "string",
"description": "Alvo da expectativa: MM/yyyy (mensal), T/yyyy (trimestral) ou yyyy (anual). Obrigatória nesses três; proibida nos rolantes."
},
"dataInicial": {
"type": "string",
"description": "Início da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 30 dias antes do fim."
}
},
"additionalProperties": false
}bcb_focus_expectativas output schema
{
"type": "object",
"required": [
"indicador",
"horizonte",
"base",
"filtro",
"totalRegistros",
"expectativas",
"urlConsulta",
"consultadoEm",
"provenance",
"attribution"
],
"properties": {
"base": {
"enum": [
"consenso",
"top5"
],
"type": "string",
"description": "consenso (todas as instituições) ou top5 (as cinco mais assertivas)"
},
"filtro": {
"type": "object",
"required": [
"dataInicial",
"dataFinal",
"janelaPadrao"
],
"properties": {
"dataFinal": {
"type": "string",
"description": "Fim da janela de coleta aplicada (yyyy-MM-dd)"
},
"suavizada": {
"type": [
"boolean",
"null"
],
"description": "Filtro de série suavizada pedido; nulo quando não informado"
},
"referencia": {
"type": [
"string",
"null"
],
"description": "Referência pedida; nula quando não informada"
},
"dataInicial": {
"type": "string",
"description": "Início da janela de coleta aplicada (yyyy-MM-dd)"
},
"janelaPadrao": {
"type": "boolean",
"description": "true quando a janela de 30 dias foi assumida"
}
},
"description": "Filtro efetivamente aplicado na origem; nulo onde o parâmetro não foi informado",
"additionalProperties": false
},
"horizonte": {
"enum": [
"mensal",
"trimestral",
"anual",
"inflacao_12m",
"inflacao_24m"
],
"type": "string",
"description": "Horizonte consultado"
},
"indicador": {
"type": "string",
"description": "Indicador consultado, como pedido"
},
"observacao": {
"type": "string",
"description": "Presente quando `expectativas` foi cortado por `limite` ou quando a janela voltou vazia, com o que fazer"
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"urlConsulta": {
"type": "string",
"description": "URL OData consultada, reproduzível no navegador"
},
"consultadoEm": {
"type": "string",
"description": "Timestamp ISO 8601 da consulta"
},
"expectativas": {
"type": "array",
"items": {
"type": "object",
"required": [
"indicador",
"coletadoEm",
"mediana"
],
"properties": {
"media": {
"type": [
"number",
"null"
],
"description": "Média das expectativas"
},
"maximo": {
"type": [
"number",
"null"
],
"description": "Maior expectativa informada"
},
"minimo": {
"type": [
"number",
"null"
],
"description": "Menor expectativa informada"
},
"mediana": {
"type": [
"number",
"null"
],
"description": "Mediana das expectativas"
},
"indicador": {
"type": [
"string",
"null"
],
"description": "Indicador conforme publicado pela fonte"
},
"suavizada": {
"type": [
"boolean",
"null"
],
"description": "Só nos horizontes rolantes: indica a série suavizada"
},
"coletadoEm": {
"type": [
"string",
"null"
],
"description": "Data da coleta das expectativas (yyyy-MM-dd)"
},
"referencia": {
"type": [
"string",
"null"
],
"description": "Alvo da expectativa (data de referência ou reunião do Copom); nulo nos horizontes rolantes"
},
"baseCalculo": {
"type": [
"number",
"null"
],
"description": "Base de cálculo usada pela fonte; nulo no Top 5"
},
"tipoCalculo": {
"type": [
"string",
"null"
],
"description": "Só no Top 5: tipo de cálculo publicado pela fonte"
},
"desvioPadrao": {
"type": [
"number",
"null"
],
"description": "Desvio padrão das expectativas"
},
"respondentes": {
"type": [
"number",
"null"
],
"description": "Número de instituições respondentes; nulo no Top 5, que a fonte não acompanha deste campo"
},
"indicadorDetalhe": {
"type": [
"string",
"null"
],
"description": "Detalhe do indicador, quando a fonte publica"
},
"coeficienteVariacao": {
"type": [
"number",
"null"
],
"description": "Só no Top 5 da Selic: único recurso da fonte que publica este campo"
}
},
"additionalProperties": false
},
"description": "Expectativas por data de coleta, da mais recente para a mais antiga, até `limite`"
},
"totalRegistros": {
"type": "number",
"description": "Coletas encontradas (contagem client-side)"
}
},
"additionalProperties": false
}bcb_focus_expectativas annotations
{
"title": "Expectativas de mercado (Focus)",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_focus_selic — Expectativas de Selic (Focus)
Advertised read-onlyOpen-world
Consulta as expectativas de mercado do Focus para a taxa Selic, organizadas pela REUNIÃO do Copom (formato R1/2026 = 1ª reunião de 2026). Devolve média, mediana, desvio padrão, mínimo, máximo e número de respondentes por data de coleta. Quando usar: para 'o que o mercado espera da Selic na próxima reunião' ou a trajetória esperada de juros. Quando NÃO usar: para expectativa de Selic média de um ano civil use bcb_focus_expectativas com horizonte anual; para a Selic REALIZADA use bcb_serie_valores (códigos 432, 1178, 4390). É separada de bcb_focus_expectativas porque o eixo temporal é a reunião do Copom, não o calendário. Retorna: `base` (consenso|top5), `filtro`, `totalRegistros`, `expectativas` (com `referencia` = reunião), `urlConsulta`, `consultadoEm` e `observacaoEixo`. Sem datas, a janela padrão é de 30 dias. Fonte: Expectativas de Mercado (Focus) do Banco Central do Brasil, via Olinda OData. O Focus é vintage por construção: `coletadoEm` é a data da coleta e `referencia` é o alvo da expectativa — a mesma referência aparece em muitas coletas, e é isso que permite ver a expectativa mudar no tempo. A contagem é feita do nosso lado porque a fonte ignora `$count`; e o filtro é obrigatório por construção porque consulta sem filtro não completa na origem. Microdados por instituição NÃO são expostos: a fonte desativou esse recurso por risco de quebra de confidencialidade.
bcb_focus_selic input schema
{
"type": "object",
"properties": {
"top5": {
"type": "boolean",
"default": false,
"description": "Expectativas do Top 5 em vez do consenso"
},
"limite": {
"type": "number",
"default": 50,
"maximum": 500,
"minimum": 1,
"description": "Máximo de coletas a devolver (1-500, padrão 50)"
},
"reuniao": {
"type": "string",
"description": "Reunião do Copom no formato R1/2026 (opcional; sem ela, todas as reuniões da janela)"
},
"dataFinal": {
"type": "string",
"description": "Fim da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje."
},
"dataInicial": {
"type": "string",
"description": "Início da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 30 dias antes do fim."
}
},
"additionalProperties": false
}bcb_focus_selic output schema
{
"type": "object",
"required": [
"base",
"filtro",
"totalRegistros",
"expectativas",
"urlConsulta",
"consultadoEm",
"provenance",
"attribution"
],
"properties": {
"base": {
"enum": [
"consenso",
"top5"
],
"type": "string",
"description": "consenso (todas as instituições) ou top5 (as cinco mais assertivas)"
},
"filtro": {
"type": "object",
"required": [
"dataInicial",
"dataFinal",
"janelaPadrao"
],
"properties": {
"reuniao": {
"type": [
"string",
"null"
],
"description": "Reunião do Copom pedida (R1/2026); nula quando não informada"
},
"dataFinal": {
"type": "string",
"description": "Fim da janela de coleta aplicada (yyyy-MM-dd)"
},
"dataInicial": {
"type": "string",
"description": "Início da janela de coleta aplicada (yyyy-MM-dd)"
},
"janelaPadrao": {
"type": "boolean",
"description": "true quando a janela de 30 dias foi assumida"
}
},
"description": "Filtro efetivamente aplicado; `reuniao` é nula quando não foi informada",
"additionalProperties": false
},
"observacao": {
"type": "string",
"description": "Presente quando `expectativas` foi cortado por `limite` ou quando a janela voltou vazia, com o que fazer"
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"urlConsulta": {
"type": "string",
"description": "URL OData consultada, reproduzível no navegador"
},
"consultadoEm": {
"type": "string",
"description": "Timestamp ISO 8601 da consulta"
},
"expectativas": {
"type": "array",
"items": {
"type": "object",
"required": [
"indicador",
"coletadoEm",
"mediana"
],
"properties": {
"media": {
"type": [
"number",
"null"
],
"description": "Média das expectativas"
},
"maximo": {
"type": [
"number",
"null"
],
"description": "Maior expectativa informada"
},
"minimo": {
"type": [
"number",
"null"
],
"description": "Menor expectativa informada"
},
"mediana": {
"type": [
"number",
"null"
],
"description": "Mediana das expectativas"
},
"indicador": {
"type": [
"string",
"null"
],
"description": "Indicador conforme publicado pela fonte"
},
"suavizada": {
"type": [
"boolean",
"null"
],
"description": "Só nos horizontes rolantes: indica a série suavizada"
},
"coletadoEm": {
"type": [
"string",
"null"
],
"description": "Data da coleta das expectativas (yyyy-MM-dd)"
},
"referencia": {
"type": [
"string",
"null"
],
"description": "Alvo da expectativa (data de referência ou reunião do Copom); nulo nos horizontes rolantes"
},
"baseCalculo": {
"type": [
"number",
"null"
],
"description": "Base de cálculo usada pela fonte; nulo no Top 5"
},
"tipoCalculo": {
"type": [
"string",
"null"
],
"description": "Só no Top 5: tipo de cálculo publicado pela fonte"
},
"desvioPadrao": {
"type": [
"number",
"null"
],
"description": "Desvio padrão das expectativas"
},
"respondentes": {
"type": [
"number",
"null"
],
"description": "Número de instituições respondentes; nulo no Top 5, que a fonte não acompanha deste campo"
},
"indicadorDetalhe": {
"type": [
"string",
"null"
],
"description": "Detalhe do indicador, quando a fonte publica"
},
"coeficienteVariacao": {
"type": [
"number",
"null"
],
"description": "Só no Top 5 da Selic: único recurso da fonte que publica este campo"
}
},
"additionalProperties": false
},
"description": "Expectativas por data de coleta, da mais recente para a mais antiga, até `limite`; `referencia` é a reunião"
},
"observacaoEixo": {
"type": "string",
"description": "Lembrete de que o eixo é a reunião do Copom, não o calendário"
},
"totalRegistros": {
"type": "number",
"description": "Coletas encontradas na janela (contagem client-side), antes do corte por `limite`"
}
},
"additionalProperties": false
}bcb_focus_selic annotations
{
"title": "Expectativas de Selic (Focus)",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_focus_referencias — Indicadores e referências do Focus
Advertised read-onlyOpen-world
Lista, POR ESCOPO, os indicadores e as referências que o Focus efetivamente publica, para você usar o texto EXATO em bcb_focus_expectativas e em bcb_focus_selic. Escopo = os cinco horizontes de bcb_focus_expectativas mais 'selic', que não é horizonte: o eixo dela é a reunião do Copom, e quem a consome é bcb_focus_selic. Cada bloco diz em `tool` quem o consome. Quando usar: antes da primeira consulta ao Focus, ou quando uma consulta volta vazia — a causa mais comum não é o dado faltar, é o indicador não existir NAQUELE escopo (a fonte publica 9 indicadores no mensal e 26 no anual: 'PIB Total', por exemplo, não existe no mensal) ou a referência estar num formato diferente do publicado. Quando NÃO usar: para os valores das expectativas em si. Sem `escopo`, consulta os seis e devolve tudo; com `escopo`, consulta só aquele. Retorna: `escopos` (para cada um: `tool` que o consome, `formatoReferencia`, `exigeReferencia`, `temTop5`, `indicadores`, `referencias`, `urlConsulta` e `disponivel`), mais `indicadores` e `referencias` como união de todos, `janela`, `totalRegistros` e `consultadoEm`. Se algum escopo não responder, os demais voltam mesmo assim, com `falhas` preenchido. Fonte: Expectativas de Mercado (Focus) do Banco Central do Brasil, via Olinda OData. O Focus é vintage por construção: `coletadoEm` é a data da coleta e `referencia` é o alvo da expectativa — a mesma referência aparece em muitas coletas, e é isso que permite ver a expectativa mudar no tempo. A contagem é feita do nosso lado porque a fonte ignora `$count`; e o filtro é obrigatório por construção porque consulta sem filtro não completa na origem. Microdados por instituição NÃO são expostos: a fonte desativou esse recurso por risco de quebra de confidencialidade.
bcb_focus_referencias input schema
{
"type": "object",
"properties": {
"escopo": {
"enum": [
"mensal",
"trimestral",
"anual",
"inflacao_12m",
"inflacao_24m",
"selic"
],
"type": "string",
"description": "Restringe a descoberta a um escopo (opcional). 'selic' descobre as reuniões do Copom para bcb_focus_selic; os demais são os horizontes de bcb_focus_expectativas."
},
"indicador": {
"type": "string",
"description": "Filtrar por um indicador específico, para ver em quais escopos ele existe (opcional)"
}
},
"additionalProperties": false
}bcb_focus_referencias output schema
{
"type": "object",
"required": [
"indicadores",
"referencias",
"escopos",
"janela",
"totalRegistros",
"consultadoEm",
"provenance",
"attribution"
],
"properties": {
"falhas": {
"type": "array",
"items": {
"type": "object",
"required": [
"escopo",
"erro"
],
"properties": {
"erro": {
"type": "string"
},
"escopo": {
"type": "string"
}
},
"additionalProperties": false
},
"description": "Escopos que não responderam nesta consulta"
},
"filtro": {
"type": "object",
"properties": {
"escopo": {
"type": [
"string",
"null"
],
"description": "Um de: mensal, trimestral, anual, inflacao_12m, inflacao_24m, selic; nulo quando a consulta cobriu todos"
},
"indicador": {
"type": [
"string",
"null"
],
"description": "Indicador pedido; nulo quando não informado"
}
},
"description": "Filtro pedido; nulo onde o parâmetro não foi informado",
"additionalProperties": false
},
"janela": {
"type": "object",
"required": [
"dataInicial",
"dataFinal"
],
"properties": {
"dataFinal": {
"type": "string",
"description": "Fim da janela (yyyy-MM-dd): hoje"
},
"dataInicial": {
"type": "string",
"description": "Início da janela (yyyy-MM-dd): 15 dias antes de hoje"
}
},
"description": "Janela de coleta observada para montar as listas",
"additionalProperties": false
},
"escopos": {
"type": "array",
"items": {
"type": "object",
"required": [
"escopo",
"tool",
"exigeReferencia",
"temTop5",
"indicadores",
"referencias",
"urlConsulta",
"disponivel"
],
"properties": {
"tool": {
"type": "string",
"description": "Tool que consome este escopo"
},
"escopo": {
"enum": [
"mensal",
"trimestral",
"anual",
"inflacao_12m",
"inflacao_24m",
"selic"
],
"type": "string"
},
"temTop5": {
"type": "boolean"
},
"disponivel": {
"type": "boolean",
"description": "false quando a origem não respondeu por este escopo — listas vazias por indisponibilidade, não por ausência de dado"
},
"indicadores": {
"type": "array",
"items": {
"type": "string"
},
"description": "Indicadores publicados NESTE escopo"
},
"referencias": {
"type": "array",
"items": {
"type": "string"
},
"description": "Referências publicadas NESTE escopo; vazio nos rolantes, que não têm alvo de calendário"
},
"urlConsulta": {
"type": "string"
},
"exigeReferencia": {
"type": "boolean",
"description": "true nos horizontes de calendário, onde `referencia` é obrigatória"
},
"formatoReferencia": {
"type": [
"string",
"null"
],
"description": "Formato da referência; nulo nos horizontes rolantes, que não têm alvo de calendário"
}
},
"additionalProperties": false
},
"description": "Um bloco por escopo: regras do contrato mais o que a fonte publica nele"
},
"observacao": {
"type": "string",
"description": "Como usar as listas: o texto é sensível ao nome EXATO e o conjunto muda por escopo"
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"indicadores": {
"type": "array",
"items": {
"type": "string"
},
"description": "União dos indicadores de todos os escopos consultados"
},
"referencias": {
"type": "array",
"items": {
"type": "string"
},
"description": "União das referências de todos os escopos consultados"
},
"consultadoEm": {
"type": "string",
"description": "Timestamp ISO 8601 da consulta"
},
"totalRegistros": {
"type": "number",
"description": "Linhas lidas da fonte, somadas em todos os escopos que responderam"
},
"observacaoFalhas": {
"type": "string",
"description": "Presente quando algum escopo não respondeu, ou quando nenhum escopo publica o indicador pedido"
}
},
"additionalProperties": false
}bcb_focus_referencias annotations
{
"title": "Indicadores e referências do Focus",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_cambio_cotacao — Cotação de câmbio (PTAX)
Advertised read-onlyOpen-world
Consulta a cotação PTAX de uma moeda contra o real, em um dia específico ou num intervalo de datas. Padrão: dólar americano (USD). Devolve compra, venda, data/hora e tipo de boletim; para moedas não-dólar devolve também a paridade contra o USD, com a origem qualificada. Quando usar: para a cotação oficial de fechamento de um dia ou a série de um período curto. Quando NÃO usar: para a série histórica longa do dólar como série temporal do SGS use bcb_serie_valores (códigos 1 = livre venda, 3698 = PTAX venda, 3697 = PTAX compra, 3695 = PTAX média) — esta tool é a fonte primária do boletim, com compra e venda no mesmo registro; para descobrir o símbolo da moeda use bcb_cambio_moedas. Retorna: `moeda`, `periodo` (dataInicial, dataFinal, janelaPadrao), `totalRegistros`, `cotacoes`, `disclaimer`, `qualificacaoParidade` (só para moedas não-dólar), `urlConsulta`, `consultadoEm` e, quando aplicável, `observacao`. Sem datas, cobre os últimos 7 dias (para atravessar fim de semana e feriado). Fonte: PTAX / Cotações e boletins de câmbio do Banco Central do Brasil, via Olinda OData. A resposta repassa literalmente o disclaimer de responsabilidade do BCB, em `disclaimer`. Cotações existem só em dia útil com fechamento de câmbio. As paridades de moedas não-dólar vêm de agência de informação (Refinitiv), redistribuídas pelo BCB — não são apuradas pelo Banco Central.
bcb_cambio_cotacao input schema
{
"type": "object",
"properties": {
"data": {
"type": "string",
"description": "Dia específico (yyyy-MM-dd ou dd/MM/yyyy). Não combine com dataInicial/dataFinal."
},
"moeda": {
"type": "string",
"default": "USD",
"description": "Símbolo da moeda (ex.: USD, EUR, GBP, JPY). Padrão: USD."
},
"limite": {
"type": "number",
"default": 100,
"maximum": 1000,
"minimum": 1,
"description": "Máximo de boletins a devolver (1-1000, padrão 100)"
},
"dataFinal": {
"type": "string",
"description": "Fim do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje."
},
"dataInicial": {
"type": "string",
"description": "Início do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 7 dias antes do fim."
}
},
"additionalProperties": false
}bcb_cambio_cotacao output schema
{
"type": "object",
"required": [
"moeda",
"periodo",
"totalRegistros",
"cotacoes",
"disclaimer",
"urlConsulta",
"consultadoEm",
"provenance",
"attribution"
],
"properties": {
"moeda": {
"type": "string",
"description": "Símbolo da moeda consultada, em maiúsculas"
},
"periodo": {
"type": "object",
"required": [
"dataInicial",
"dataFinal",
"janelaPadrao"
],
"properties": {
"dataFinal": {
"type": "string",
"description": "Fim do intervalo (yyyy-MM-dd)"
},
"dataInicial": {
"type": "string",
"description": "Início do intervalo (yyyy-MM-dd)"
},
"janelaPadrao": {
"type": "boolean",
"description": "true quando a janela de 7 dias foi assumida"
}
},
"description": "Intervalo consultado; num dia específico, início e fim são o mesmo dia",
"additionalProperties": false
},
"cotacoes": {
"type": "array",
"items": {
"type": "object",
"required": [
"dataHora"
],
"properties": {
"dataHora": {
"type": [
"string",
"null"
],
"description": "Data e hora da cotação"
},
"tipoBoletim": {
"type": [
"string",
"null"
],
"description": "Tipo de boletim (ex.: Fechamento, Abertura, Intermediário). Nulo em USD: a fonte não publica este campo nos recursos de dólar, só nos de moeda."
},
"cotacaoVenda": {
"type": [
"number",
"null"
]
},
"cotacaoCompra": {
"type": [
"number",
"null"
]
},
"paridadeVenda": {
"type": [
"number",
"null"
],
"description": "Paridade de venda contra o USD (moedas não-dólar; origem: agência de informação)"
},
"paridadeCompra": {
"type": [
"number",
"null"
],
"description": "Paridade de compra contra o USD (moedas não-dólar; origem: agência de informação)"
}
},
"additionalProperties": false
},
"description": "Boletins de cotação, do mais recente para o mais antigo, até `limite`"
},
"disclaimer": {
"type": "string",
"description": "Disclaimer de responsabilidade do BCB, repassado literalmente"
},
"observacao": {
"type": "string",
"description": "Presente quando `cotacoes` foi cortado por `limite` ou quando o intervalo voltou vazio, com o que fazer"
},
"provenance": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"description": "Um bloco por procedência que contribuiu com esta resposta (bloco de proveniência do portfólio; licenças nunca se fundem)"
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"urlConsulta": {
"type": "string",
"description": "URL OData consultada, reproduzível no navegador"
},
"consultadoEm": {
"type": "string",
"description": "Timestamp ISO 8601 da consulta"
},
"totalRegistros": {
"type": "number",
"description": "Boletins encontrados no intervalo, antes do corte por `limite`"
},
"qualificacaoParidade": {
"type": "string",
"description": "Qualificação da origem das paridades não-dólar"
}
},
"additionalProperties": false
}bcb_cambio_cotacao annotations
{
"title": "Cotação de câmbio (PTAX)",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}bcb_cambio_moedas — Moedas com cotação no BCB
Advertised read-onlyOpen-world
Lista as moedas com cotação publicada pelo Banco Central, com símbolo, nome e tipo, e aceita um termo para filtrar. Quando usar: para descobrir o símbolo correto antes de chamar bcb_cambio_cotacao (é a causa mais comum de cotação vazia). Quando NÃO usar: para valores de cotação. Retorna: `termo`, `totalMoedas`, `moedas` (simbolo, nome, tipo), `disclaimer`, `qualificacaoParidade`, `urlConsulta` e `consultadoEm`. Fonte: PTAX / Cotações e boletins de câmbio do Banco Central do Brasil, via Olinda OData. A resposta repassa literalmente o disclaimer de responsabilidade do BCB, em `disclaimer`. Cotações existem só em dia útil com fechamento de câmbio.
bcb_cambio_moedas input schema
{
"type": "object",
"properties": {
"termo": {
"type": "string",
"description": "Filtro por símbolo ou nome (ex.: 'EUR', 'libra'). Opcional."
}
},
"additionalProperties": false
}bcb_cambio_moedas output schema
{
"type": "object",
"required": [
"totalMoedas",
"moedas",
"disclaimer",
"urlConsulta",
"consultadoEm",
"provenance",
"attribution"
],
"properties": {
"termo": {
"type": [
"string",
"null"
],
"description": "Termo aplicado no filtro; nulo quando não foi informado"
},
"moedas": {
"type": "array",
"items": {
"type": "object",
"required": [
"simbolo"
],
"properties": {
"nome": {
"type": [
"string",
"null"
]
},
"tipo": {
"type": [
"string",
"null"
],
"description": "Tipo da moeda conforme a fonte (A ou B)"
},
"simbolo": {
"type": [
"string",
"null"
],
"description": "Símbolo a usar em bcb_cambio_cotacao"
}
},
"additionalProperties": false
},
"description": "Moedas com cotação publicada pelo BCB"
},
"disclaimer": {
"type": "string",
"description": "Disclaimer de responsabilidade do BCB, repassado literalmente"
},
"observacao": {
"type": "string",
"description": "Lembrete de usar o `simbolo` em bcb_cambio_cotacao"
},
"provenance": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
},
"totalMoedas": {
"type": "number",
"description": "Moedas na lista, depois do filtro por `termo`"
},
"urlConsulta": {
"type": "string",
"description": "URL OData consultada, reproduzível no navegador"
},
"consultadoEm": {
"type": "string",
"description": "Timestamp ISO 8601 da consulta"
},
"qualificacaoParidade": {
"type": "string",
"description": "Qualificação da origem das paridades não-dólar"
}
},
"additionalProperties": false
}bcb_cambio_moedas annotations
{
"title": "Moedas com cotação no BCB",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}search — Busca para Deep Research
Advertised read-onlyOpen-world
Searches the Banco Central do Brasil time series (SGS: interest rates, inflation, exchange rates, credit, fiscal and external sector — the curated catalog plus the open data portal index) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched). This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools `search` and `fetch`. Pass one of the returned ids to `fetch` to read the document. For direct questions and for data (values, series, rankings) prefer the `bcb_*` tools, which return the actual data with provenance — this is a catalog index, not a data query. Query: natural language or keywords, Portuguese or English; accents and case are ignored. Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.
search input schema
{
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Termos de busca em linguagem natural ou palavras-chave (acentos e caixa são ignorados)"
}
},
"additionalProperties": false
}search output schema
{
"type": "object",
"required": [
"results",
"provenance",
"attribution"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"url"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Identificador único do documento no servidor; é o que `fetch` recebe"
},
"url": {
"type": "string",
"description": "URL pública canônica do documento — a citação do ChatGPT depende dela"
},
"title": {
"type": "string",
"description": "Título legível do documento"
}
},
"additionalProperties": false
},
"description": "Documentos encontrados, em ordem de relevância"
},
"provenance": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"description": "Um bloco por procedência que contribuiu com esta resposta (bloco de proveniência do portfólio; licenças nunca se fundem)"
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
}
},
"additionalProperties": false
}search annotations
{
"title": "Busca para Deep Research",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}fetch — Documento para Deep Research
Advertised read-onlyOpen-world
Returns the full document for an id obtained from `search`, as { id, title, text, url, metadata }: `text` is the readable content (Markdown) and `url` the canonical public page to cite. Companion of `search` in the OpenAI Deep Research contract, over the Banco Central do Brasil time series (SGS: interest rates, inflation, exchange rates, credit, fiscal and external sector — the curated catalog plus the open data portal index) catalog. Only ids returned by `search` are valid; an unknown id returns an error. The `bcb_*` tools remain the tools for data queries. Behavior: read-only and idempotent — a live GET against the public source when the document needs it.
fetch input schema
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Identificador de um documento devolvido por `search`"
}
},
"additionalProperties": false
}fetch output schema
{
"type": "object",
"required": [
"id",
"title",
"text",
"url",
"provenance",
"attribution"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Identificador único do documento no servidor; é o que `fetch` recebe"
},
"url": {
"type": "string",
"description": "URL pública canônica do documento — a citação do ChatGPT depende dela"
},
"text": {
"type": "string",
"description": "Conteúdo integral do documento, legível (Markdown)"
},
"title": {
"type": "string",
"description": "Título legível do documento"
},
"metadata": {
"type": "object",
"description": "Pares chave/valor adicionais sobre o documento (tipo, fonte, período…)",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"provenance": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"source_url",
"data_vintage",
"retrieved_at",
"retrieval",
"citation",
"license"
],
"properties": {
"source": {
"type": "string",
"description": "Fonte oficial do dado"
},
"derived": {
"type": "boolean",
"description": "Presente (true) só quando o servidor calculou o valor em vez de repassá-lo como veio da fonte"
},
"license": {
"type": [
"string",
"null"
],
"description": "Regime legal do dado (id SPDX quando há, senão o nome da licença)"
},
"notices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Avisos que a fonte publica junto com o dado (quebra de série, unidade, frescor), verbatim. Ausente quando não há aviso"
},
"citation": {
"type": "string",
"description": "Citação/atribuição pronta para uso"
},
"revision": {
"type": "object",
"required": [
"status",
"note"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "O específico da fonte: o que revisa, quando, por quê"
},
"status": {
"enum": [
"current",
"provisional",
"final"
],
"type": "string",
"description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte"
}
},
"description": "Se o dado ainda pode mudar na fonte",
"additionalProperties": false
},
"retrieval": {
"oneOf": [
{
"type": "object",
"required": [
"requests",
"attempts",
"anomalies",
"unstable"
],
"properties": {
"attempts": {
"type": "integer",
"minimum": 1,
"description": "Tentativas somadas, incluindo as repetidas (>= requests)"
},
"requests": {
"type": "integer",
"minimum": 1,
"description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)"
},
"unstable": {
"type": "boolean",
"description": "true se houve repetição (attempts > requests) ou alguma anomalia"
},
"anomalies": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"count"
],
"properties": {
"kind": {
"enum": [
"timeout",
"network",
"http_4xx",
"http_5xx",
"rate_limited",
"malformed_body"
],
"type": "string",
"description": "Classe da anomalia (vocabulário fechado do contrato)"
},
"count": {
"type": "integer",
"minimum": 1,
"description": "Ocorrências desta classe na chamada"
}
},
"additionalProperties": false
},
"description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma"
}
},
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede"
},
"source_url": {
"type": "string",
"description": "URL canônica que reproduz a consulta na fonte"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"
},
"retrieved_at": {
"type": "string",
"description": "Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"
},
"field_sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"fields",
"source_url",
"dataset_id",
"data_vintage",
"retrieved_at"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Campos do payload atribuídos a esta sub-fonte"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "Identificador do conjunto da sub-fonte"
},
"source_url": {
"type": "string",
"description": "URL canônica da sub-fonte que originou estes campos"
},
"data_vintage": {
"type": [
"string",
"null"
],
"description": "Vintage/competência da sub-fonte"
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 da extração desta sub-fonte na origem"
},
"served_from_cache": {
"type": [
"boolean",
"null"
],
"description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue"
}
},
"description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
"additionalProperties": false
},
"minItems": 1,
"description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só"
},
"derivation_note": {
"type": "string",
"description": "O que o servidor calculou; presente junto com derived"
}
},
"description": "Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar",
"additionalProperties": false
},
"description": "Um bloco por procedência que contribuiu com esta resposta (bloco de proveniência do portfólio; licenças nunca se fundem)"
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs canônicas das fontes desta resposta (lista de atribuição)"
}
},
"additionalProperties": false
}fetch annotations
{
"title": "Documento para Deep Research",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}Prompts
3 advertised
indicadores_atuais — Indicadores econômicos atuais
Consulta os principais indicadores econômicos do Brasil (Selic, IPCA, Dólar, IBC-Br)
panorama_economico — Panorama da economia brasileira
Gera um panorama completo da economia brasileira com os principais indicadores
comparar_inflacao — Comparar índices de inflação
Compara os principais índices de inflação do Brasil (IPCA, IGP-M, INPC) nos últimos 12 meses
Resources
3 advertised
series_populares — Catálogo curado de séries do BCB
Catálogo de 135 séries econômicas do BCB, verificadas contra a origem, organizadas por categoria; cada entrada traz `fonteNome` (nome transcrito do portal do BCB ou herdado com periodicidade medida)
series_populares URI
bcb://series/popularescategorias — Categorias do catálogo
Lista de categorias disponíveis no catálogo de séries do BCB
categorias URI
bcb://series/categoriascodigos_principais — Códigos dos indicadores mais usados
Códigos dos indicadores econômicos mais utilizados (Selic, IPCA, Dólar, PIB, etc.)
codigos_principais URI
bcb://series/principais90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-07: 1 of 1 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 649 ms
- 95th percentile latency
- 649 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 649 ms · metadata changed · 17 tool(s), 3 resource(s), 0 resource template(s), 3 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http bcb-sgs-time-series-mcp-sidneybissoli https://bcb.sidneybissoli.com/mcpCodex
Codex configuration
codex mcp add bcb-sgs-time-series-mcp-sidneybissoli --url https://bcb.sidneybissoli.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"bcb-sgs-time-series-mcp-sidneybissoli": {
"url": "https://bcb.sidneybissoli.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"bcb-sgs-time-series-mcp-sidneybissoli": {
"type": "streamableHttp",
"url": "https://bcb.sidneybissoli.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"bcb-sgs-time-series-mcp-sidneybissoli": {
"type": "http",
"url": "https://bcb.sidneybissoli.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http bcb-sgs-time-series-mcp-sidneybissoli https://bcb.sidneybissoli.com/mcpClaude Desktop
Claude Desktop configuration
https://bcb.sidneybissoli.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"bcb-sgs-time-series-mcp-sidneybissoli": {
"serverUrl": "https://bcb.sidneybissoli.com/mcp"
}
}
}Let your agent find its tools
Find servers like BCB SGS Time Series MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.