Como Usar a API Mais Retorno

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
params.set("has_quotes", "true"); // Filtrar apenas ativos que possuem cotações

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/search/petrobras?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
params.set("link_old_historic", "true"); // false (padrão): first_quote e last_quote são o início e o fim da série própria do identificador. true: passam a ser o início e o fim da série que /quotes devolve com link_old_historic=true — o histórico da classe emendado antes da subclasse que a continua e, no identificador da classe, a subclasse que a API escolhe — devolvida em linked_identifier. Use para validar o período antes de pedir as cotas com o mesmo parâmetro; as duas rotas precisam concordar. Só tem efeito em fundos (:fi).

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/asset-info/petr4:b3?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
params.set("start_date", "2024-01-01"); // Data inicial para buscar cotações (formato: YYYY-MM-DD)
params.set("end_date", "2024-12-31"); // Data final para buscar cotações (formato: YYYY-MM-DD)
params.set("adjusted", "false"); // true (padrão): série ajustada, que reinveste proventos, amortização e juros — é a base correta para calcular rentabilidade, mas é recalculada para trás a cada novo provento, então o valor devolvido para uma data passada muda com o tempo. false: preço efetivamente negociado no dia (o PU, no caso de renda fixa) — preserva o valor observado naquela data e é a base correta para registrar uma transação ou manter marcação a mercado histórica. As duas divergem, e quanto mais antiga a data, mais: PETR4 em 01/06/2015 fechou a R$ 12,37 negociado e vale cerca de R$ 3 na série ajustada. O parâmetro só tem efeito onde existem duas séries (ações :b3, :us e :lse, debêntures, tesouro direto, títulos públicos, securitizados e UCITS); fundos, índices, cripto e futuros têm série única e ignoram o parâmetro.
params.set("link_old_historic", "true"); // false (padrão): devolve só a série de cotas do identificador pedido. true: quando a subclasse pedida é a continuação direta da série da classe (a primeira cota dela vem até 5 dias depois da última cota da classe), as cotas da classe entram antes das cotas da subclasse — na sobreposição vale a da subclasse — e a série passa a começar na data mais antiga das duas. Por que existe: com a Resolução CVM 175, fundos que já existiam foram divididos em classe e subclasses; a série da subclasse começa na data em que ela foi criada e o histórico anterior ficou guardado na classe. Sem o parâmetro, um fundo de 2015 dividido em 2024 devolve cotas só a partir de 2024. Com true, a série é a mesma que o site da Mais Retorno exibe e a que /stats e /drawdown já usam sempre. Subclasse que não continua a série da classe (uma série nova de FIDC, por exemplo) devolve o mesmo com ou sem o parâmetro. Atenção ao pedir pelo identificador da classe (CNPJ sem o sufixo de subclasse): com true a API escolhe uma subclasse por regra técnica — se a classe não tem cotas, a de histórico mais antigo; se tem, pode trocar pela que cobre o mesmo período com dados mais recentes e emenda no fim a que continua a série. Essa escolha não é a "subclasse principal", cadastro que não existe; num FIDC pode cair na cota subordinada. Peça sempre o identificador da subclasse que o investidor detém; /fund-structure lista todas. Só tem efeito em fundos (:fi); nos demais mercados é ignorado.

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/quotes/petr4:b3?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
// params.set("details", "..."); // Incluir detalhes adicionais nas estatísticas
// params.set("currency", "..."); // Moeda para conversão dos valores
// params.set("deflator", "..."); // Deflaciona a série pelo índice de inflação (retorno real): ipca ou igpm
// params.set("start_date", "..."); // Data inicial para filtro (formato: YYYY-MM-DD)
// params.set("end_date", "..."); // Data final para filtro (formato: YYYY-MM-DD)
// params.set("format_decimal", "..."); // Formatar valores decimais

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/stats/petr4:b3?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
params.set("start_date", "2020-01-01"); // Data inicial para o cálculo do drawdown (YYYY-MM-DD)
params.set("end_date", "2024-12-31"); // Data final para o cálculo do drawdown (YYYY-MM-DD)
params.set("link_old_historic", "false"); // true (padrão): o drawdown é calculado sobre a mesma série que /quotes devolve com link_old_historic=true — o histórico da classe emendado antes da subclasse que a continua. Sempre foi assim nesta rota; o parâmetro existe para pedir o contrário. false: só a série própria do identificador. Só tem efeito em fundos (:fi).

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/drawdown/petr4:b3?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

const response = await fetch(
  "https://data.maisretorno.com/mr-data/v4/api/available-wallets/3168062000103:fi",
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
params.set("month", "12"); // Mês para buscar a carteira (1-12)
params.set("year", "2024"); // Ano para buscar a carteira

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/wallet-detail/3168062000103:fi?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
params.set("link_old_historic", "true"); // false (padrão): first_quote e last_quote são o início e o fim da série própria do identificador. true: passam a ser o início e o fim da série que /quotes devolve com link_old_historic=true — o histórico da classe emendado antes da subclasse que a continua e, no identificador da classe, a subclasse que a API escolhe — devolvida em linked_identifier. Use para validar o período antes de pedir as cotas com o mesmo parâmetro; as duas rotas precisam concordar. Só tem efeito em fundos (:fi).

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/fund-class-subclass/38120941000131:fi?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);

// Parâmetros opcionais — inclua apenas os que precisar
const params = new URLSearchParams();
params.set("page", "1"); // Página, começando em 1
params.set("page_size", "20"); // Linhas por página. Padrão 20, máximo 100.

const response = await fetch(
  `https://data.maisretorno.com/mr-data/v4/api/fund-structure/55912292000120:fi?${params}`,
  { headers: { "X-Api-Key": api_key } }
);

const dados = await response.json();
console.log(dados);