Gerenciar a carteira

Além de consultar (getPortfolio), a API permite gerenciar a carteira da sua conta: criar carteiras, adicionar/remover ativos, lançar e editar transações e importar planilhas da B3, tudo por API, SDK, CLI ou MCP, com a mesma chave por usuário. Um agente de IA conectado ao MCP consegue montar e manter a sua carteira conversando com você.

Antes de começar:

• As operações escrevem na sua carteira real. Tudo é escopado ao dono da chave (db_live_..., criada em databolsa.com/conta/config); ninguém acessa carteira de terceiros.
• A posição é derivada do ledger. Você lança transações (compra, venda, split) e a posição, preço médio e P&L são calculados; nada de editar quantidade "na mão". Ativo sem transação funciona como watchlist.
• Import é idempotente. Reenviar o mesmo arquivo não duplica lançamentos — cada linha tem uma identidade estável e repetições são puladas (duplicates_skipped).
• O número de carteiras da conta depende do plano (planos); no teto, a criação responde 402.

Criar carteira e lançar uma compra

curl -X POST https://api.databolsa.com/v1/portfolios \
  -H "Authorization: Bearer db_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dividendos"}'

# "compra de 100 PETR4 a R$ 38,10" — o ativo entra na carteira automaticamente
curl -X POST https://api.databolsa.com/v1/portfolios/ID_DA_CARTEIRA/transactions \
  -H "Authorization: Bearer db_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"asset_type": "stock", "symbol": "PETR4", "kind": "buy", "trade_date": "2026-07-10", "quantity": 100, "price": 38.10}'

Ativos são identificados por asset_type + symbol (sem ids internos): stock, fii, bdr, tesouro (use o nome oficial do título, ex. TESOURO SELIC 2029), crypto, renda_fixa, option, index.

Importar uma planilha da B3

Aceita a Negociação e a Movimentação da Área do Investidor da B3 (.xlsx) e o template manual (.csv) — o formato é detectado pelo cabeçalho. O arquivo vai em base64:

databolsa importPortfolioFile ID_DA_CARTEIRA --file negociacao-2026.xlsx

A CLI lê o arquivo local com --file e preenche content_base64/filename por você. A resposta resume o resultado:

{
  "source": "negociacao",
  "imported": 142,
  "duplicates_skipped": 0,
  "rows_ignored": 3,
  "period": { "from": "2024-01-02", "to": "2026-07-10" },
  "warnings": []
}

O drill-down linha a linha fica em listPortfolioImportRows (o que entrou, o que foi ignorado e por quê).

Pelo SDK

import { DataBolsa } from "@databolsa/sdk";
import { readFileSync } from "node:fs";

const db = new DataBolsa("https://api.databolsa.com", { apiKey: process.env.DATABOLSA_API_KEY });

const { portfolios } = await db.listPortfolios();
const carteira = portfolios[0] ?? (await db.createPortfolio("Dividendos"));

await db.addPortfolioTransaction(carteira.id, { assetType: "stock", symbol: "PETR4" }, {
  kind: "buy",
  tradeDate: "2026-07-10",
  quantity: 100,
  price: 38.1,
});

await db.importPortfolioFile(carteira.id, {
  contentBase64: readFileSync("movimentacao.xlsx").toString("base64"),
  filename: "movimentacao.xlsx",
});

const detalhe = await db.getPortfolioDetail(carteira.id);

Pelo MCP (agentes de IA)

Conectando o servidor MCP (mcp.databolsa.com ou local), o agente ganha as mesmas operações como tools: listPortfolios, createPortfolio, addPortfolioTransaction, importPortfolioFile, updatePortfolioTransaction, deletePortfolio etc. Peça em linguagem natural:

"lança a compra de 50 HGLG11 a 160,00 de ontem na minha carteira de FIIs"

As descrições das tools de escrita avisam o agente de que elas modificam a carteira real — bons clientes MCP pedem sua confirmação antes de executar. Remoções (carteira, ativo, transação) são irreversíveis; revise antes de confirmar.

Operações disponíveis

A referência completa (parâmetros e respostas) está na seção Carteira da API.