Como Usar a API Mais Retorno

Guia completo com exemplos em Python e Node.js para consumir a API de dados Mais Retorno.

🔍

API Key

Autenticação

Todas as requisições exigem uma api_key vinculada a uma subscription ativa de algum plano (Free, Basic, Starter, Growth ou Enterprise).

Gere sua api_key

Acesse maisretorno.com/app/meu-perfil/api e gere sua api_key. O formato é mr_xxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Importante: a chave em texto plano é exibida apenas no momento da geração — o servidor armazena somente o hash. Salve em local seguro (variável de ambiente ou gerenciador de segredos). Se perder, gere uma nova no portal — a anterior será invalidada automaticamente.

Envie a api_key nas requisições

Dois headers são aceitos:

Server-side (recomendado): X-Api-Key: SUA_API_KEY
Alternativo: Authorization: Bearer SUA_API_KEY

Browser/Playground: o CORS do servidor libera apenas o header Authorization, então chamadas a partir de SPA, extensão ou playground precisam usar Authorization: Bearer. Para backends Python/Node, prefira X-Api-Key.

Dica: Cole sua api_key no campo acima para que ela seja usada automaticamente nos playgrounds desta página (que usam Authorization: Bearer pela restrição de CORS).

Créditos

Cada chamada consome créditos do seu plano, de forma proporcional ao valor entregue. Uso simples continua simples; uso mais rico consome mais. Buscar ativos é gratuito.

Operação	Créditos
Buscar ativos (`/api/search`)	0
Dados cadastrais (`/api/asset-info`)	1
Classificação (`/api/fund-class-subclass`)	1
Carteiras disponíveis (`/api/available-wallets`)	1
Cotações (`/api/quotes`)	1
Carteira detalhada (`/api/wallet-detail`)	5
Estatísticas (`/api/stats`)	5
Drawdown (`/api/drawdown`)	5
Comparativo de ativos (MCP `compare_assets`)	25

O custo de cada endpoint também aparece na sua descrição em Endpoints Disponíveis.

Identificadores de Ativos

Todos os endpoints usam um identifier no formato ativo:mercado:

Ações, BDRs, ETFs, FIIs

petr4:b3

ticker:b3

Fundos de Investimento

38000706000126:fi

cnpj:fi

Subclasses de Fundos

10338491000139-s0000255564:fi

cnpj-subclasse_id:fi

Criptomoedas

btc:cc

ticker:cc

Índices

cdi:idx

ticker:idx

Tesouro Direto

tesouro-selic-18-06-2008:td

slug:td

Títulos Públicos

ntn-r2-15-02-2004-brstncntr084:tp

slug:tp

Dica: Use o endpoint de Search para encontrar o identifier de qualquer ativo.

Endpoints Disponíveis

Base URL: https://data.maisretorno.com/mr-data/v4/api

#	Endpoint	Rota	Descrição
1	Search (Busca)	`GET /search/{query}`	Busca ativos por termo, com filtros opcionais
2	Asset Info (Info do Ativo)	`GET /asset-info/{identifier}`	Retorna informações cadastrais completas de um ativo (CNPJ, setor, segmento, etc). O formato da resposta varia de acordo com o tipo de ativo.
3	Quotes (Cotações)	`GET /quotes/{identifier}`	Busca cotações históricas de um ativo.
4	Stats (Estatísticas)	`GET /stats/{identifier}`	Retorna estatísticas detalhadas de performance de um ativo específico. Esta rota é atendida pelo microserviço mr-ms-stats através do API Gateway.
5	Available Wallets (Carteiras)	`GET /available-wallets/{identifier}`	Retorna as datas das carteiras disponíveis para um fundo específico
6	Wallet Detail (Detalhe da Carteira)	`GET /wallet-detail/{identifier}`	Retorna os detalhes completos da carteira de um fundo em um mês/ano específico
7	Fund Class/Subclass (Classe/Subclasse)	`GET /fund-class-subclass/{identifier}`	Retorna informações detalhadas de uma classe ou subclasse de fundo
8	/drawdown/{identifier}	`GET /drawdown/{identifier}`	Retorna a série temporal de drawdown desde o último topo dentro do range + summary com max e current.

1. Search (Busca)

GET/search/{query}Grátis

Busca ativos por termo, com filtros opcionais

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`has_quotes`	boolean	Não	true	Filtrar apenas ativos que possuem cotações

Python

Node.js

# Parâmetros opcionais — inclua apenas os que precisar
params = {}
params["has_quotes"] = "true"  # Filtrar apenas ativos que possuem cotações

response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/search/petrobras",
    headers={"X-Api-Key": api_key},
    params=params,
)

dados = response.json()
print(dados)

// 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);

Testar

Query (termo de busca)

has_quotes

GET https://data.maisretorno.com/mr-data/v4/api/search/petrobras?has_quotes=true

[
  {
    "identifier": "string",
    "nicename": "string",
    "type": "string",
    "has_quotes": true
  }
]

2. Asset Info (Info do Ativo)

GET/asset-info/{identifier}1 crédito

Retorna informações cadastrais completas de um ativo (CNPJ, setor, segmento, etc). O formato da resposta varia de acordo com o tipo de ativo.

Python

Node.js

response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/asset-info/petr4:b3",
    headers={"X-Api-Key": api_key},
)

dados = response.json()
print(dados)

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

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

Testar

Identifier

GET https://data.maisretorno.com/mr-data/v4/api/asset-info/petr4%3Ab3

Fund

Crypto

Index

DirectTreasure

PublicBounds

RFS

{
  "identifier": "string",
  "nicename": "string",
  "first_quote": "string",
  "last_quote": "string",
  "cnpj": "string",
  "name": "string",
  "trading_currency": "string",
  "admin": {},
  "asset_managers": [
    {
      "nicename": "XP Asset Management",
      "slug": "xp-asset",
      "cnpj": "12345678000190"
    }
  ],
  "classes_subclasses": [
    {
      "identifier": "10338491000139-s0000255564:fi",
      "nicename": "Classe A",
      "quotaholders": 150,
      "networth": 85362537.22
    }
  ]
}

{
  "nicename": "string",
  "identifier": "string",
  "first_quote": "string",
  "last_quote": "string",
  "last_update": "string",
  "has_quotes": true,
  "cnpj": 0,
  "code_cvm": 0,
  "company_name": "string",
  "actuation_segment": "string",
  "actuation_sector": "string",
  "actuation_subsector": "string",
  "issuer_company": "string",
  "ticker": "string",
  "asset_description": "string",
  "situation": "string",
  "specification_code": "string",
  "market_cap": 0,
  "corporate_governance_tier": "string",
  "trading_currency": "string",
  "isin": "string",
  "type": "string"
}

{
  "nicename": "string",
  "identifier": "string",
  "last_update": "string",
  "has_quotes": true,
  "name": "string",
  "slug": "string",
  "trading_currency": "string",
  "type": "string",
  "first_quote": "string",
  "last_quote": "string",
  "shortname": "string"
}

{
  "nicename": "string",
  "identifier": "string",
  "type": "string",
  "first_quote_date": "string",
  "last_quote_date": "string",
  "last_update": "string",
  "has_quotes": true,
  "ticker": "string",
  "description": "string",
  "trading_currency": "string",
  "situation": "string"
}

{
  "nicename": "string",
  "identifier": "string",
  "type": "string",
  "first_quote": "string",
  "last_quote": "string",
  "last_update": "string",
  "has_quotes": true,
  "maturity": "string",
  "security_type": "string",
  "trading_currency": "string"
}

{
  "nicename": "string",
  "identifier": "string",
  "type": "string",
  "first_quote": "string",
  "last_quote": "string",
  "last_update": "string",
  "has_quotes": true,
  "issuance_date": "string",
  "isin": "string",
  "maturity_date": "string",
  "indexer": "string",
  "code": 0,
  "pay_coupon": true,
  "coupon_rate": "string",
  "coupon_frequency": "string",
  "security_type": "string",
  "bond_stripping": "string",
  "trading_currency": "string"
}

{
  "identifier": "string",
  "nicename": "string",
  "type": "string",
  "first_quote": "string",
  "last_quote": "string",
  "has_quotes": true,
  "trading_currency": "string"
}

3. Quotes (Cotações)

GET/quotes/{identifier}1 crédito

Busca cotações históricas de um ativo.

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`start_date`	string	Não	2024-01-01	Data inicial para buscar cotações (formato: YYYY-MM-DD)
`end_date`	string	Não	2024-12-31	Data final para buscar cotações (formato: YYYY-MM-DD)

Python

Node.js

# Parâmetros opcionais — inclua apenas os que precisar
params = {}
params["start_date"] = "2024-01-01"  # Data inicial para buscar cotações (formato: YYYY-MM-DD)
params["end_date"] = "2024-12-31"  # Data final para buscar cotações (formato: YYYY-MM-DD)

response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/quotes/petr4:b3",
    headers={"X-Api-Key": api_key},
    params=params,
)

dados = response.json()
print(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)

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);

Testar

Identifier

start_date

end_date

GET https://data.maisretorno.com/mr-data/v4/api/quotes/petr4%3Ab3?start_date=2024-01-01&end_date=2024-12-31

{
  "market": "b3",
  "currency": "BRL",
  "nicename": "Petrobras PN",
  "shortname": "PETR4",
  "quotes": [
    {
      "d": "2024-01-15",
      "c": 25.67,
      "p": 1500000.5,
      "q": 1250
    }
  ]
}

4. Stats (Estatísticas)

GET/stats/{identifier}5 créditos

Retorna estatísticas detalhadas de performance de um ativo específico. Esta rota é atendida pelo microserviço mr-ms-stats através do API Gateway.

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`details`	boolean	Não	-	Incluir detalhes adicionais nas estatísticas
`currency`	string	Não	-	Moeda para conversão dos valores
`start_date`	string	Não	-	Data inicial para filtro (formato: YYYY-MM-DD)
`end_date`	string	Não	-	Data final para filtro (formato: YYYY-MM-DD)
`format_decimal`	boolean	Não	-	Formatar valores decimais

Python

Node.js

# Parâmetros opcionais — inclua apenas os que precisar
params = {}
# params["details"] = "..."  # Incluir detalhes adicionais nas estatísticas
# params["currency"] = "..."  # Moeda para conversão dos valores
# params["start_date"] = "..."  # Data inicial para filtro (formato: YYYY-MM-DD)
# params["end_date"] = "..."  # Data final para filtro (formato: YYYY-MM-DD)
# params["format_decimal"] = "..."  # Formatar valores decimais

response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/stats/petr4:b3",
    headers={"X-Api-Key": api_key},
    params=params,
)

dados = response.json()
print(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("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);

Testar

Identifier

details

currency

start_date

end_date

format_decimal

GET https://data.maisretorno.com/mr-data/v4/api/stats/petr4%3Ab3

{
  "stats": {
    "best_monthly_return": 0.01177933,
    "worst_monthly_return": 0.00360039,
    "positive_months": 9,
    "negative_months": 0,
    "timeframe": {
      "last_3_months": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "last_6_months": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "last_12_months": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "last_24_months": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "last_36_months": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "last_48_months": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "last_60_months": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "ytd": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "mtd": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      },
      "begin": {
        "profitability": 0.03048502,
        "sharpe_ratio": -85.08822365,
        "volatility": 0.00966557
      }
    },
    "first_quote_date": "2024-04-19",
    "last_quote_date": "2024-12-18"
  },
  "nicename": "Petróleo Brasileiro S.A. - Petrobras",
  "shortname": "PETR4",
  "trading_currency": "BRL",
  "years": {
    "2024": {
      "4": 0.00360039,
      "5": 0.01057483,
      "year": 0.08725725,
      "accrued": 0.08725725
    }
  }
}

5. Available Wallets (Carteiras)

GET/available-wallets/{identifier}1 crédito

Retorna as datas das carteiras disponíveis para um fundo específico

Python

Node.js

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

dados = response.json()
print(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);

Testar

Identifier

GET https://data.maisretorno.com/mr-data/v4/api/available-wallets/3168062000103%3Afi

[
  {
    "date": "2024-12-31",
    "open": true
  }
]

6. Wallet Detail (Detalhe da Carteira)

GET/wallet-detail/{identifier}5 créditos

Retorna os detalhes completos da carteira de um fundo em um mês/ano específico

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`month`	number	Não	12	Mês para buscar a carteira (1-12)
`year`	number	Não	2024	Ano para buscar a carteira

Python

Node.js

# Parâmetros opcionais — inclua apenas os que precisar
params = {}
params["month"] = "12"  # Mês para buscar a carteira (1-12)
params["year"] = "2024"  # Ano para buscar a carteira

response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/wallet-detail/3168062000103:fi",
    headers={"X-Api-Key": api_key},
    params=params,
)

dados = response.json()
print(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);

Testar

Identifier

month

year

GET https://data.maisretorno.com/mr-data/v4/api/wallet-detail/3168062000103%3Afi?month=12&year=2024

{
  "reference_month": "2024-12",
  "wallet_total": 0,
  "classes": [
    {
      "nicename": "string",
      "percentage": 0,
      "value": 0,
      "assets": [
        {
          "confidential": "...",
          "nicename": "...",
          "percentage": "...",
          "value": "...",
          "class_percentage": "..."
        }
      ]
    }
  ]
}

7. Fund Class/Subclass (Classe/Subclasse)

GET/fund-class-subclass/{identifier}1 crédito

Retorna informações detalhadas de uma classe ou subclasse de fundo

Python

Node.js

response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/fund-class-subclass/38120941000131:fi",
    headers={"X-Api-Key": api_key},
)

dados = response.json()
print(dados)

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

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

Testar

Identifier

GET https://data.maisretorno.com/mr-data/v4/api/fund-class-subclass/38120941000131%3Afi

{
  "identifier": "21624757000126-qzwjm1744745214:fi",
  "nicename": "KINEA CHRONOS FIF MULTIMERCADO RL",
  "quotaholders": 1,
  "networth": 85362537.22,
  "first_quote": "2025-04-25",
  "last_quote": "2026-01-02",
  "class_type": "FIF",
  "benchmark": "CDI",
  "invests_all_offshore": false,
  "long_term_tributation": true,
  "investor_type": null,
  "pension_fund": false,
  "exclusive": false,
  "open_condominium": true,
  "situation": "Em Funcionamento Normal",
  "target_audience": "Público Geral",
  "cvm_category": "Multimercado",
  "anbima_type": "Estratégia Livre"
}

8. /drawdown/{identifier}

GET/drawdown/{identifier}5 créditos

Retorna a série temporal de drawdown desde o último topo dentro do range + summary com max e current.

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
`start_date`	string	Não	2020-01-01	Data inicial para o cálculo do drawdown (YYYY-MM-DD)
`end_date`	string	Não	2024-12-31	Data final para o cálculo do drawdown (YYYY-MM-DD)

Python

Node.js

# Parâmetros opcionais — inclua apenas os que precisar
params = {}
params["start_date"] = "2020-01-01"  # Data inicial para o cálculo do drawdown (YYYY-MM-DD)
params["end_date"] = "2024-12-31"  # Data final para o cálculo do drawdown (YYYY-MM-DD)

response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/drawdown/petr4:b3",
    headers={"X-Api-Key": api_key},
    params=params,
)

dados = response.json()
print(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)

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);

Testar

Identifier

start_date

end_date

GET https://data.maisretorno.com/mr-data/v4/api/drawdown/petr4%3Ab3?start_date=2020-01-01&end_date=2024-12-31

{
  "nicename": "Verde Master FIM",
  "shortname": "verde-fim",
  "series": [
    {
      "d": "2020-03-23",
      "dd": -41.29
    }
  ],
  "summary": {
    "max_drawdown": -41.29,
    "max_drawdown_date": "2020-03-23",
    "current_drawdown": -11.31,
    "range_start": "2015-01-02",
    "range_end": "2026-05-26",
    "is_full_history": false
  }
}

Tratamento de Erros

A API retorna erros no formato padrão:

{
  "statusCode": 400,
  "message": "Identifier must be in format \"asset:market\" (e.g., \"petr4:b3\")",
  "error": "Bad Request"
}

Status	Significado	Quando acontece
`200`	Sucesso	Requisição processada corretamente
`400`	Bad Request	Identifier inválido ou parâmetros incorretos
`401`	Unauthorized	API key ausente ou inválida
`403`	Forbidden	API key válida, mas o plano não cobre o recurso solicitado
`404`	Not Found	Ativo não encontrado
`429`	Too Many Requests	Cota mensal do plano esgotada — aguarde a renovação ou faça upgrade
`500`	Internal Server Error	Erro interno do servidor

Limites e Cache

Cota mensal por plano

Cada plano tem uma cota mensal de requests. A cota é renovada automaticamente todo mês no dia âncora da conta (o dia em que a primeira cota foi configurada). Saldo não usado não acumula — não há rollover.

Plano	Requests/mês
Free	500
Basic	1.500
Starter	5.000
Growth	15.000
Enterprise	Volume contratado individualmente

Cota esgotada: requisições retornam 429 Too Many Requests. Aguarde a próxima renovação ou faça upgrade do plano.

Cache por endpoint

Endpoint	Cache (max-age)
`/search/{query}`	5 minutos (300s)
`/asset-info/{identifier}`	90 minutos (5400s)
`/quotes/{identifier}`	90 minutos (5400s)
`/stats/{identifier}`	90 minutos (5400s)
`/available-wallets/{identifier}`	90 minutos (5400s)
`/wallet-detail/{identifier}`	90 minutos (5400s)
`/fund-class-subclass/{identifier}`	90 minutos (5400s)

Dica: Utilize os headers Cache-Control retornados pela API para evitar requisições desnecessárias.