Wallet — carteiras por workspace

A Wallet guarda carteiras, ativos, transações, importações da B3, custos e raio-X. Ela pertence a um workspace: o seu pessoal ou uma organização em que você tem assento. Instale-a em notebook.databolsa.com/extensoes (no workspace pessoal ela já vem instalada) e use por onde preferir:

O contrato da Wallet é publicado em https://api.databolsa.com/openapi-wallet.json (YAML em api/openapi-wallet.yaml no repositório público).

Workspace

Toda chamada age em um workspace. Por default, o pessoal do dono da chave. Para uma organização, envie o header x-databolsa-workspace com o id dela (o SDK, a CLI e o MCP têm uma opção para isso). Organização inexistente ou sem membership responde 404 workspace_not_found — nunca cai no pessoal. x-databolsa-workspace: personal força o pessoal.

Wallet desinstalada no workspace responde 404 wallet_not_installed; suspensa recusa escrita com 403 wallet_suspended. Apagar carteira exige dono ou administrador (403 wallet_role_required).

SDK

npm install @databolsa/wallet-sdk

import { DataBolsaWallet } from "@databolsa/wallet-sdk";

const wallet = new DataBolsaWallet({
  apiKey: process.env.DATABOLSA_API_KEY, // db_live_…
  workspace: "org_abc123",              // opcional: id da organização
});

const { data: carteiras } = await wallet.listPortfolios();
const detalhe = await wallet.getPortfolioDetail(carteiras[0].id);
await wallet.addPortfolioTransaction(carteiras[0].id, {
  symbol: "PETR4", asset_type: "stock", kind: "buy", quantity: 100, price: 38.2, trade_date: "2026-08-28",
});

Erros viram DataBolsaWalletError com status e o problem+json (title, detail, code, details). Os tipos crus do contrato saem como WalletPaths.

CLI

export DATABOLSA_API_KEY=db_live_SUACHAVE
npx -y @databolsa/wallet-cli listPortfolios
npx -y @databolsa/wallet-cli getPortfolioDetail <id> --json | jq .totals
npx -y @databolsa/wallet-cli importPortfolioFile <id> --file extrato-b3.xlsx

--list mostra as operações; --help <operação> os argumentos. DATABOLSA_WORKSPACE escolhe a organização; DATABOLSA_API_URL troca a origem.

MCP local

{
  "mcpServers": {
    "databolsa-wallet": {
      "command": "npx",
      "args": ["-y", "@databolsa/wallet-mcp"],
      "env": { "DATABOLSA_API_KEY": "db_live_SUACHAVE" }
    }
  }
}

Uma tool por operação do contrato, com anotações de escrita e destruição para o cliente pedir confirmação. O MCP hospedado (Conectar agentes) expõe as mesmas tools quando a Wallet está instalada no workspace da sessão.