Wallet

A Wallet adiciona carteiras ao workspace pessoal ou de uma organização. Ela guarda o ledger de transações e deriva posição, preço médio, custos, resultado, histórico e análises sem duplicar a identidade dos ativos do mercado.

No workspace pessoal, a Wallet é instalada por padrão. Em uma organização, a instalação e o acesso seguem as permissões daquele workspace.

No Notebook

A página Wallet reúne as carteiras acessíveis à pessoa. O antigo bloco de documento wallet.portfolios foi descontinuado; documentos que ainda o contêm mostram um aviso e direcionam para a página da extensão.

Carteiras de uma organização podem ser privadas, restritas a membros escolhidos ou compartilhadas no workspace. Ativos, transações e importações herdam o acesso da carteira.

Functions e Actions

A Wallet publica o que faz como capacidades, no mesmo protocolo dos demais módulos: Functions são as leituras e Actions são as escritas. As duas ficam em /v1/wallet, e o sujeito de uma capacidade de carteira é a própria carteira — o id vai em subject, não no caminho.

As leituras são quinze: wallet.session.get, wallet.portfolios.list, wallet.portfolio.get, wallet.portfolio.history, wallet.portfolio.transactions, wallet.portfolio.imports, wallet.portfolio.import_rows, wallet.portfolio.xray, wallet.portfolio.costs, wallet.portfolio.look_through, wallet.portfolio.factor_exposure, wallet.import_template.get, wallet.consolidated.get, wallet.consolidated.history e wallet.suitability.get. wallet.portfolio.factor_exposure regride o retorno mensal da carteira (o mesmo do TWR) contra os fatores de risco publicados — NEFIN para o Brasil, Fama-French para emergentes, EUA e desenvolvidos — e devolve um beta por fator com erro-padrão, o alfa anualizado e o R², na mesma forma que a Function market.factor_exposure.get do core responde para um papel ou fundo. É descrição do passado, não recomendação. As escritas são as treze Actions de carteira, ativo, transação, importação e reconciliação, incluindo wallet.position.balance_reconcile para reconciliar renda fixa ao saldo bruto do extrato.

curl https://api.databolsa.com/v1/wallet/functions \
  -H "Authorization: Bearer $DATABOLSA_API_KEY"

curl -X POST https://api.databolsa.com/v1/wallet/functions/wallet.portfolio.get/execute \
  -H "Authorization: Bearer $DATABOLSA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"subject":{"entity_id":"<id da carteira>"},"input":{"include":"transactions"}}'

GET /v1/wallet/functions lista os descritores curtos, GET /v1/wallet/functions/{id} devolve o spec com input_schema e output_schema, e POST /v1/wallet/functions/{id}/execute executa. wallet.session.get não recebe sujeito: ela informa o workspace já vinculado à credencial, sem permitir trocá-lo. subject.resolve aceita o nome da carteira quando o id não está à mão; dois nomes iguais recusam com subject_ambiguous em vez de escolher. Carteira fora do alcance da credencial responde 404 subject_not_found.

No SDK, o id escolhe o input aceito e o tipo do result:

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

const wallet = new DataBolsaWallet({ apiKey: process.env.DATABOLSA_API_KEY });

const carteira = await wallet.executeFunction("wallet.portfolio.get", {
  subject: { entity_id: "<id da carteira>" },
  input: { include: "transactions" },
});
carteira.result.patrimonio; // number, sem cast

const nova = await wallet.executeAction("wallet.portfolio.create", {
  input: { name: "Longo prazo" },
  confirmed: true,
});
nova.result.id; // string

Id publicado depois da versão instalada do SDK vai em executeFunctionAny ou executeActionAny, que devolvem result sem tipo.

O que substituiu cada rota

As rotas especializadas /v1/portfolios/*, /v1/portfolio e /v1/suitability saíram do contrato. Cada uma tinha uma sucessora sobre o mesmo serviço, e é ela que responde hoje:

O que era caminho virou subject, e o que era corpo virou input. As escritas ganharam preview e confirmação explícita. Quando uma Action publica preview_schema, o campo changes da prévia é validado pelo servidor contra essa forma antes de ser devolvido.

wallet.position.balance_reconcile aceita apenas saldo bruto positivo em BRL e papéis com taxa contratada suficiente para calcular o accrual na data do extrato. Sem taxa, configure o papel com wallet.asset.update. Vencimento ou resgate não é reconciliação de saldo: registre uma venda com o valor recebido para preservar os fluxos de caixa e o cálculo de retorno.

No agente

O MCP hospedado acrescenta as tools da Wallet quando a extensão está instalada e a sessão tem acesso ao workspace. Leituras consultam os dados reais; escritas como criar uma carteira, importar um extrato ou lançar uma transação devem mostrar alvo e efeito e pedir confirmação.

A sessão abre com sete tools: o catálogo, o spec e a execução de Functions e Actions. Sete nomes alcançam tudo o que a extensão lê e escreve, em vez de uma tool por rota — e como o contrato é só o protocolo, o perfil full mostra exatamente as mesmas sete.

Conecte o seu agente pelo guia em Agentes e integrações.

API e clientes

O contrato da Wallet é separado do contrato de mercado:

• Referência da API
• OpenAPI
• @databolsa/wallet-sdk
• @databolsa/wallet-cli
• @databolsa/wallet-mcp para uso local

SDK

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

const db = new DataBolsa("https://api.databolsa.com", {
  apiKey: process.env.DATABOLSA_API_KEY,
});
const carteira = db.use(wallet()); // o workspace vem da chave

const lista = await carteira.executeFunction("wallet.portfolios.list", {});
const detalhe = await carteira.executeFunction("wallet.portfolio.get", {
  subject: { entity_id: lista.result.data[0].id },
});

O plugin reaproveita a origem e a credencial do cliente core. Também é possível instanciar DataBolsaWallet diretamente.

CLI

export DATABOLSA_API_KEY=db_live_SUACHAVE
npx -y @databolsa/wallet-cli --list
npx -y @databolsa/wallet-cli walletListFunctions --json
npx -y @databolsa/wallet-cli walletExecuteFunction wallet.portfolios.list --json

A credencial é vinculada a um único workspace quando emitida; no OAuth, o workspace é escolhido no consentimento e gravado no token. A CLI não muda esse alvo. Para usar outro workspace, emita outra credencial ou refaça a conexão. A CLI principal mantém databolsa wallet como atalho, mas @databolsa/wallet-cli é a entrada canônica para scripts.

Dentro do checkout do DataBolsa, use bun run cli:wallet -- <operação>: o npm pode resolver o workspace local antes do pacote publicado, cujo binário ainda não existe antes do build.

Comportamento de acesso

• Wallet ausente responde 404 wallet_not_installed.
• Organização inexistente ou inacessível responde 404 workspace_not_found.
• Suspensão preserva leitura e recusa escrita com 403 wallet_suspended.
• Apagar uma carteira exige permissão de administração sobre o recurso.

A Wallet registra posições e análises; não executa ordens nem recomenda investimentos.