Investimentos

A Malvo expõe as posições de investimento de um Item e, para cada posição, as suas movimentações. A posição vive no recurso Investment (GET /investments); as movimentações vivem em GET /investments/{id}/transactions.

Todos os endpoints exigem o header X-API-KEY e respondem em https://api.malvo.io. A lista de investimentos filtra por itemId (obrigatório); as movimentações são lidas por id de cada posição.

Listar posições (`GET /investments`)

curl "https://api.malvo.io/investments?itemId=207f5bcd-312a-439c-abbe-166b6632c980" \
  -H "X-API-KEY: $MALVO_API_KEY"

curl "https://api.malvo.io/investments?itemId=207f5bcd-312a-439c-abbe-166b6632c980&type=FIXED_INCOME" \
  -H "X-API-KEY: $MALVO_API_KEY"

const res = await fetch(
  `https://api.malvo.io/investments?itemId=${itemId}`,
  { headers: { "X-API-KEY": apiKey } },
);
const { results: investments } = await res.json();

Investment (exemplos)

{
  "page": 1,
  "total": 2,
  "totalPages": 1,
  "results": [
    {
      "id": "f77eccf4-7714-498e-92a9-1bebe70335d9",
      "code": "12.345.678/0001-00",
      "name": "Bahia AM Advisory FIC de FIM",
      "balance": 1359.39,
      "currencyCode": "BRL",
      "type": "MUTUAL_FUND",
      "subtype": "MULTIMARKET_FUND",
      "lastMonthRate": 0.24,
      "annualRate": 3.24,
      "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
      "value": 500,
      "quantity": 3,
      "amount": 1500,
      "taxes": 40.61,
      "taxes2": 100,
      "date": "2026-06-19T18:27:41.802Z",
      "owner": "João Pereira",
      "amountProfit": 310.5,
      "amountWithdrawal": 1310.5,
      "amountOriginal": 1000,
      "status": "ACTIVE"
    },
    {
      "id": "2a96b873-53bb-4d16-a3d8-385a57e78d7e",
      "name": "CDB1194KL0Z - BANCO MAXIMA S/A",
      "balance": 2000,
      "currencyCode": "BRL",
      "type": "FIXED_INCOME",
      "subtype": "CDB",
      "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
      "code": "0001-02",
      "amount": 2500,
      "rate": 30,
      "rateType": "CDI",
      "fixedAnnualRate": 10.5,
      "amountWithdrawal": 2000,
      "amountOriginal": 1000,
      "issuer": "Banco Exemplo S/A",
      "issuerCNPJ": "08.050.608/0001-32",
      "purchaseDate": "2026-06-15T10:00:00.000Z",
      "status": "ACTIVE"
    }
  ]
}

Types e subtypes

O campo type agrupa os investimentos; subtype detalha o produto:

`type`	Semântica	`subtype` (exemplos)
`MUTUAL_FUND`	Fundos (FIM, FIA, FIC)	`MULTIMARKET_FUND`, `FIXED_INCOME_FUND`, `STOCK_FUND`, `ETF_FUND`, `FIP_FUND`, `FI_INFRA`, `FI_AGRO`
`EQUITY`	Ações e equivalentes	`STOCK`, `BDR`, `REAL_ESTATE_FUND`, `DERIVATIVES`, `OPTION`
`ETF`	ETFs	`ETF`
`FIXED_INCOME`	Renda fixa	`TREASURY`, `CDB`, `LCI`, `LCA`, `LC`, `LF`, `CRI`, `CRA`, `DEBENTURES`, `CORPORATE_DEBT`
`COE`	Notas estruturadas	`STRUCTURED_NOTE`
`SECURITY`	Previdência (PGBL/VGBL)	`RETIREMENT`
`OTHER`	Qualquer outro	`OTHER`

Campos de valor

Campo	Descrição
`balance`	Saldo líquido atual (valor de mercado) da posição
`amount`	Valor bruto
`value`	Valor da cota em `date`
`quantity`	Cotas disponíveis
`amountProfit`	Lucro/prejuízo até a data
`amountWithdrawal`	Valor disponível para resgate
`amountOriginal`	Valor originalmente investido
`taxes` / `taxes2`	IR / IOF

Status da posição

`status`	Significado
`ACTIVE`	Posição aberta, em carteira
`PENDING`	Solicitada, ainda não liquidada
`TOTAL_WITHDRAWAL`	Totalmente resgatada (saldo zero)

Movimentações (`GET /investments/{id}/transactions`)

Lê as movimentações de uma posição (compras, vendas, impostos, rendimentos). Resposta paginada (page shape; pageSize padrão 500).

curl "https://api.malvo.io/investments/f77eccf4-7714-498e-92a9-1bebe70335d9/transactions" \
  -H "X-API-KEY: $MALVO_API_KEY"

const res = await fetch(
  `https://api.malvo.io/investments/${investmentId}/transactions`,
  { headers: { "X-API-KEY": apiKey } },
);
const { results: movements } = await res.json();

InvestmentTransaction

{
  "id": "f24f7eec-5a5b-4e54-8727-d40b0b91115a",
  "amount": 110000,
  "description": null,
  "value": 1100,
  "quantity": 100,
  "tradeDate": "2026-06-01T00:00:00.000Z",
  "date": "2026-06-01T00:00:00.000Z",
  "type": "BUY",
  "movementType": "CREDIT",
  "netAmount": 10000,
  "agreedRate": null,
  "brokerageNumber": "1234",
  "expenses": {}
}

Tipos de movimentação

`type`	Significado	`movementType` padrão
`BUY`	Aplicação/compra	`CREDIT` (entra na posição)
`SELL`	Resgate/venda	`DEBIT`
`TAX`	Retenção (IR/IOF)	`DEBIT`
`TRANSFER`	Portabilidade/transferência interna (`amount` pode ser `null`)	`DEBIT`
`INTEREST`	Rendimento creditado	`DEBIT`
`AMORTIZATION`	Amortização de principal	`DEBIT`

Despesas (`expenses`)

Quebra de custos da operação. Todos os campos são numéricos e opcionais; pode vir {}: serviceTax (ISS), brokerageFee, incomeTax (IRRF), tradingAssetsNoticeFee (ANA), maintenanceFee, settlementFee, clearingFee, stockExchangeFee (emolumentos), custodyFee, operatingFee, other.

As movimentações são retornadas para corretoras (XP, Clear, …) e para bancos de varejo/PJ.

Limitações do Open Finance

O Open Finance impõe limitações importantes na coleta de investimentos. Modele seu produto para estes casos desde o início:

Só posições ativas no primeiro sync

No primeiro sync, o Open Finance traz apenas as posições ativas — posições já resgadas antes da conexão não aparecem retroativamente. O histórico se forma a partir das próximas sincronizações.

Sem movimentações em alguns bancos

Alguns bancos não fornecem as investment transactions. Nesses casos, GET /investments traz a posição, mas GET /investments/{id}/transactions volta vazio. Trate a ausência de movimentações como normal, não como erro.

"Caixinhas" / "Cofrinhos" aparecem como CDB

Reservas de poupança automatizadas — as “Caixinhas”/“Cofrinhos” de alguns bancos — chegam classificadas como type=FIXED_INCOME, subtype=CDB. Não as confunda com um CDB tradicional de emissor bancário ao categorizar a carteira do usuário.

Próximos passos

Empréstimos e identidade

Leia contratos de crédito (CET, juros, parcelas) e os dados cadastrais do titular.

Reconciliação

Estratégia de robustez com webhooks e job noturno.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Investimentos

Listar posições (`GET /investments`)

Types e subtypes

Campos de valor

Status da posição

Movimentações (`GET /investments/{id}/transactions`)

Tipos de movimentação

Despesas (`expenses`)

Limitações do Open Finance

Próximos passos

Empréstimos e identidade

Reconciliação

​Listar posições (GET /investments)

​Types e subtypes

​Campos de valor

​Status da posição

​Movimentações (GET /investments/{id}/transactions)

​Tipos de movimentação

​Despesas (expenses)

​Limitações do Open Finance

​Próximos passos

Empréstimos e identidade

Reconciliação

Listar posições (`GET /investments`)

Types e subtypes

Campos de valor

Status da posição

Movimentações (`GET /investments/{id}/transactions`)

Tipos de movimentação

Despesas (`expenses`)

Limitações do Open Finance

Próximos passos