Documentação

Referência pública da API do Tesouro Direto — comece por aqui antes de pedir sua chave

Início rápido

Três passos para a sua primeira chamada — pense neles como o verso da apólice, onde ficam as instruções de uso do selo.

1. Pegue sua chave

Entre em /desenvolvedores e gere uma chave de API. Ela é mostrada uma única vez — guarde-a com cuidado.

2. Faça a primeira requisição

Envie a chave no cabeçalho X-Api-Key e liste os títulos disponíveis:

curl -H "X-Api-Key: SUA_CHAVE" \
  https://dadosdotesourodireto.com.br/api/v1/titulos

3. Siga o caminho quente

O fluxo típico é: listar os títulos, escolher um pelo codigo, consultar o preço atual e, se precisar de histórico, paginar a série de preços. 

curl -H "X-Api-Key: SUA_CHAVE" \
  https://dadosdotesourodireto.com.br/api/v1/titulos/{codigo}/preco-atual

curl -H "X-Api-Key: SUA_CHAVE" \
  "https://dadosdotesourodireto.com.br/api/v1/titulos/{codigo}/precos?page=1&pageSize=50"

Limites (429 + Retry-After), cache condicional (If-None-Match), paginação (X-Total-Count, _links) e erros (application/problem+json) estão documentados em detalhe nas seções abaixo.

Autenticação

Toda requisição autenticada leva a chave no cabeçalho X-Api-Key. Sem ela — ou com uma chave inválida ou revogada — a API responde 401.

Para obter sua chave, entre em /desenvolvedores e gere uma credencial.

Atenção: a chave é mostrada uma única vez, no momento em que é gerada. Guarde-a com cuidado — se perdê-la, gere uma nova.
Nunca exponha a chave em código client-side (JavaScript no navegador, app mobile, repositório público). Trate-a como um segredo de servidor.

Limites

  • Rate limit de 60 requisições por minuto, por chave — ao exceder, a API responde 429 com o cabeçalho Retry-After (segundos até liberar).
  • Flood-guard de 30 requisições por segundo, por IP, aplicado na borda (nginx), independente de autenticação.

Cache

Respostas de leitura trazem ETag. Envie o valor de volta no cabeçalho If-None-Match na próxima chamada; se nada mudou, a API responde 304 Not Modified sem corpo, economizando banda.

Paginação

Listas paginadas trazem o cabeçalho Link (RFC 8288) com as relações first, prev, next e last, e o cabeçalho X-Total-Count com o total de itens.

Recursos individuais trazem _links (HAL) no corpo, com atalhos para navegar entre recursos relacionados — por exemplo, de um título para seu preço atual.

Como resolver um href: os valores de _links e do cabeçalho Link já vêm prontos, com o caminho completo da API pública (incluindo o segmento /api). Basta resolvê-los contra o host: https://dadosdotesourodireto.com.br + /api/v1/titulos/tesouro-selic-2029-03-01 = https://dadosdotesourodireto.com.br/api/v1/titulos/tesouro-selic-2029-03-01.

Erros

Erros são retornados como application/problem+json, sempre com um correlationId para rastreio junto ao suporte. 

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Recurso não encontrado",
  "status": 404,
  "detail": "Nenhum título com o código informado foi encontrado.",
  "code": "titulo_nao_encontrado",
  "correlationId": "8f14e45f-ceea-467e-9de0-1e2b2c8f9ac3",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
Status Significado
400Requisição inválida — parâmetro ausente ou mal formado (ex.: codigo fora do padrão).
401Chave ausente, inválida ou revogada.
404Recurso não encontrado (título, preço ou tributo inexistente).
429Limite de requisições excedido — respeite o Retry-After.

Endpoints

Referência dos endpoints de consumo da API. Todos exigem o cabeçalho X-Api-Key.

GET /titulos

Lista os títulos cadastrados, com filtro opcional por indexador e por vencido.

GET /titulos

NomeTipoObrigatórioDescrição
indexadorquery · stringNãoFiltra pelo nome do indexador (ex.: Selic, IPCA, Prefixado).
vencidoquery · boolNãoFiltra títulos vencidos (true) ou não vencidos (false).
curl -H "X-Api-Key: SUA_CHAVE" \
  "https://dadosdotesourodireto.com.br/api/v1/titulos?indexador=Selic&vencido=false"
[
  {
    "tipoTitulo": "Tesouro Selic",
    "dataVencimento": "2029-03-01",
    "indexador": "Selic",
    "pagaJurosSemestrais": false,
    "vencido": false,
    "codigo": "tesouro-selic-2029-03-01",
    "_links": {
      "self": { "href": "/api/v1/titulos/tesouro-selic-2029-03-01" },
      "precos": { "href": "/api/v1/titulos/tesouro-selic-2029-03-01/precos" },
      "preco-atual": { "href": "/api/v1/titulos/tesouro-selic-2029-03-01/preco-atual" },
      "simular": { "href": "/api/v1/simulador", "method": "POST", "templated": true }
    }
  }
]

GET /titulos/{codigo}

Retorna um único título pelo código.

GET /titulos/{codigo}

NomeTipoObrigatórioDescrição
codigopath · stringSimIdentificador público do título, derivado do tipo e da data de vencimento (ex.: tesouro-selic-2029-03-01).
curl -H "X-Api-Key: SUA_CHAVE" \
  https://dadosdotesourodireto.com.br/api/v1/titulos/tesouro-selic-2029-03-01
{
  "tipoTitulo": "Tesouro Selic",
  "dataVencimento": "2029-03-01",
  "indexador": "Selic",
  "pagaJurosSemestrais": false,
  "vencido": false,
  "codigo": "tesouro-selic-2029-03-01",
  "_links": {
    "self": { "href": "/api/v1/titulos/tesouro-selic-2029-03-01" },
    "precos": { "href": "/api/v1/titulos/tesouro-selic-2029-03-01/precos" },
    "preco-atual": { "href": "/api/v1/titulos/tesouro-selic-2029-03-01/preco-atual" },
    "simular": { "href": "/api/v1/simulador", "method": "POST", "templated": true }
  }
}

GET /titulos/preco-atual

Retorna o preço e a taxa mais recentes de um título, buscado pelo nome.

GET /titulos/preco-atual

NomeTipoObrigatórioDescrição
nomequery · stringSimNome exato do título (ex.: Tesouro Selic 2029).
curl -H "X-Api-Key: SUA_CHAVE" \
  "https://dadosdotesourodireto.com.br/api/v1/titulos/preco-atual?nome=Tesouro%20Selic%202029"
{
  "dataBase": "2026-08-08",
  "taxaCompra": 11.85,
  "taxaVenda": 11.95,
  "puCompra": 985.32,
  "puVenda": 980.10,
  "puBase": 982.71
}

GET /titulos/{codigo}/preco-atual

Retorna o preço e a taxa mais recentes de um título, buscado pelo código.

GET /titulos/{codigo}/preco-atual

NomeTipoObrigatórioDescrição
codigopath · stringSimIdentificador público do título (ex.: tesouro-selic-2029-03-01).
curl -H "X-Api-Key: SUA_CHAVE" \
  https://dadosdotesourodireto.com.br/api/v1/titulos/tesouro-selic-2029-03-01/preco-atual
{
  "dataBase": "2026-08-08",
  "taxaCompra": 11.85,
  "taxaVenda": 11.95,
  "puCompra": 985.32,
  "puVenda": 980.10,
  "puBase": 982.71
}

GET /titulos/precos

Lista o histórico de preços e taxas de um título, buscado pelo nome.

GET /titulos/precos

NomeTipoObrigatórioDescrição
nomequery · stringSimNome exato do título.
dataInicioquery · date (yyyy-MM-dd)NãoInício do intervalo de datas.
dataFimquery · date (yyyy-MM-dd)NãoFim do intervalo de datas.
curl -H "X-Api-Key: SUA_CHAVE" \
  "https://dadosdotesourodireto.com.br/api/v1/titulos/precos?nome=Tesouro%20Selic%202029&dataInicio=2026-01-01&dataFim=2026-06-30"
[
  {
    "dataBase": "2026-06-30",
    "taxaCompra": 11.90,
    "taxaVenda": 12.00,
    "puCompra": 978.14,
    "puVenda": 973.02,
    "puBase": 975.55
  },
  {
    "dataBase": "2026-07-01",
    "taxaCompra": 11.88,
    "taxaVenda": 11.98,
    "puCompra": 979.40,
    "puVenda": 974.25,
    "puBase": 976.80
  }
]

GET /titulos/{codigo}/precos

Lista o histórico de preços e taxas de um título, buscado pelo código, com paginação opcional. Sem page, retorna a coleção inteira e não envia o cabeçalho Link.

GET /titulos/{codigo}/precos

NomeTipoObrigatórioDescrição
codigopath · stringSimIdentificador público do título.
dataInicioquery · date (yyyy-MM-dd)NãoInício do intervalo de datas.
dataFimquery · date (yyyy-MM-dd)NãoFim do intervalo de datas.
pagequery · intNãoPágina desejada (padrão 1). Presente ⇒ resposta paginada, com cabeçalhos Link e X-Total-Count.
pageSizequery · intNãoItens por página (padrão 100, máximo 500).
curl -H "X-Api-Key: SUA_CHAVE" \
  "https://dadosdotesourodireto.com.br/api/v1/titulos/tesouro-selic-2029-03-01/precos?dataInicio=2026-01-01&dataFim=2026-06-30&page=1&pageSize=50"

Cabeçalhos de resposta: X-Total-Count: 214 e Link: </api/v1/titulos/tesouro-selic-2029-03-01/precos?page=1&pageSize=50>; rel="first", </api/v1/titulos/tesouro-selic-2029-03-01/precos?page=2&pageSize=50>; rel="next", </api/v1/titulos/tesouro-selic-2029-03-01/precos?page=5&pageSize=50>; rel="last"

[
  {
    "dataBase": "2026-06-30",
    "taxaCompra": 11.90,
    "taxaVenda": 12.00,
    "puCompra": 978.14,
    "puVenda": 973.02,
    "puBase": 975.55
  }
]

GET /precos

Retorna o preço e a taxa de todos os títulos numa única data, em 1 requisição — o corte transversal dos endpoints de /titulos/... acima, para quem precisa do fechamento do dia inteiro sem consultar título por título.

GET /precos

NomeTipoObrigatórioDescrição
dataBasequery · date (yyyy-MM-dd)SimData do fechamento. Único parâmetro aceito — não há intervalo, filtro por indexador nem paginação.
curl -H "X-Api-Key: SUA_CHAVE" \
  "https://dadosdotesourodireto.com.br/api/v1/precos?dataBase=2026-06-30"

A resposta é um array cru (sem _links) ordenado por codigo crescente, cada item com o mesmo formato de preço dos endpoints acima acrescido de codigo. O cabeçalho X-Total-Count sempre acompanha a resposta.

Em dia sem pregão (fim de semana, feriado ou importação ainda não executada) a API responde 200 com lista vazia [] e X-Total-Count: 0 — nunca 404. É assim que você distingue "dia sem pregão" de "requisição inválida".

400 se dataBase estiver ausente ou fora do formato yyyy-MM-dd (PrecoTaxa.DataBaseInvalida) ou for uma data futura (PrecoTaxa.DataBaseFutura). 

[
  {
    "codigo": "tesouro-selic-2029-03-01",
    "dataBase": "2026-06-30",
    "taxaCompra": 11.90,
    "taxaVenda": 12.00,
    "puCompra": 978.14,
    "puVenda": 973.02,
    "puBase": 975.55
  },
  {
    "codigo": "tesouro-ipca-mais-2035-05-15",
    "dataBase": "2026-06-30",
    "taxaCompra": 5.85,
    "taxaVenda": 5.95,
    "puCompra": 3210.44,
    "puVenda": 3195.10,
    "puBase": 3202.77
  }
]

POST /simulador

Simula valor bruto/líquido, tributos aplicados e cupons (quando houver) para um título, valor investido, data de compra e taxa contratada.

POST /simulador

NomeTipoObrigatórioDescrição
codigobody · stringSimIdentificador público do título.
valorInvestidobody · decimalSimValor investido, em reais.
dataComprabody · date (yyyy-MM-dd)SimData da compra simulada.
taxaContratadabody · decimalSimTaxa contratada na compra, em percentual ao ano (10 = 10% a.a., não 0.10).
projecaoAnualbody · decimalNãoProjeção anual do indexador. Sem ela, para títulos indexados, usa a projeção de mercado do BCB Focus.
curl -X POST -H "X-Api-Key: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"codigo":"tesouro-selic-2029-03-01","valorInvestido":1000,"dataCompra":"2026-08-01","taxaContratada":10,"projecaoAnual":12.5}' \
  https://dadosdotesourodireto.com.br/api/v1/simulador
{
  "valorInvestido": 1000,
  "valorBruto": 1734.07,
  "rendimentoBruto": 734.07,
  "tributosAplicados": [
    { "nome": "Imposto de Renda", "base": 734.07, "aliquota": 15, "valor": 110.11 }
  ],
  "totalTributos": 110.11,
  "valorLiquido": 1623.96,
  "rendimentoLiquido": 623.96,
  "cupons": null,
  "projecaoUtilizada": {
    "valorAnual": 12.5,
    "dataReferencia": "2026-08-01",
    "obtidaEmUtc": "2026-08-01T12:00:00Z",
    "origem": "Bcb"
  }
}

POST /simulador/cenarios

Simula o mesmo investimento sob vários cenários nomeados, cada um com sua própria projeção anual informada explicitamente.

POST /simulador/cenarios

NomeTipoObrigatórioDescrição
codigobody · stringSimIdentificador público do título.
valorInvestidobody · decimalSimValor investido, em reais.
dataComprabody · date (yyyy-MM-dd)SimData da compra simulada.
taxaContratadabody · decimalSimTaxa contratada na compra, em percentual ao ano (10 = 10% a.a., não 0.10).
cenariosbody · arraySimLista de cenários, cada um com nome (string) e projecaoAnual (decimal).
curl -X POST -H "X-Api-Key: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"codigo":"tesouro-selic-2029-03-01","valorInvestido":1000,"dataCompra":"2026-08-01","taxaContratada":10,"cenarios":[{"nome":"otimista","projecaoAnual":13.0},{"nome":"conservador","projecaoAnual":10.5}]}' \
  https://dadosdotesourodireto.com.br/api/v1/simulador/cenarios
[
  {
    "nome": "otimista",
    "resultado": {
      "valorInvestido": 1000,
      "valorBruto": 1754.22,
      "rendimentoBruto": 754.22,
      "tributosAplicados": [
        { "nome": "Imposto de Renda", "base": 754.22, "aliquota": 15, "valor": 113.13 }
      ],
      "totalTributos": 113.13,
      "valorLiquido": 1641.09,
      "rendimentoLiquido": 641.09,
      "cupons": null,
      "projecaoUtilizada": null
    }
  },
  {
    "nome": "conservador",
    "resultado": {
      "valorInvestido": 1000,
      "valorBruto": 1655.64,
      "rendimentoBruto": 655.64,
      "tributosAplicados": [
        { "nome": "Imposto de Renda", "base": 655.64, "aliquota": 15, "valor": 98.35 }
      ],
      "totalTributos": 98.35,
      "valorLiquido": 1557.29,
      "rendimentoLiquido": 557.29,
      "cupons": null,
      "projecaoUtilizada": null
    }
  }
]

GET /configuracoes/tributos

Lista todos os tributos configurados (IOF, IR etc.), ativos ou não, com suas faixas.

GET /configuracoes/tributos

curl -H "X-Api-Key: SUA_CHAVE" \
  https://dadosdotesourodireto.com.br/api/v1/configuracoes/tributos

Exemplo com 2 das faixas reais — IOF tem 29 faixas (uma por dia corrido) e IR tem 4.

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "nome": "IOF",
    "baseCalculo": "Rendimento",
    "tipoCalculo": "TabelaDiaria",
    "faixas": [
      { "diasMin": null, "diasMax": null, "dia": 1, "aliquota": 96 }
    ],
    "ativo": true,
    "ordem": 1,
    "cumulativo": true
  },
  {
    "id": "5b1e2a3c-8f4d-4b2a-9c1e-7d6f5a4b3c2d",
    "nome": "Imposto de Renda",
    "baseCalculo": "Rendimento",
    "tipoCalculo": "FaixaPorDias",
    "faixas": [
      { "diasMin": 0, "diasMax": 180, "dia": null, "aliquota": 22.5 }
    ],
    "ativo": true,
    "ordem": 2,
    "cumulativo": false
  }
]
An unhandled error has occurred. Reload X