Skill de Portfólio
Quando Usar
Além dos gatilhos representativos, também é acionada pelas seguintes falas:
- "Quero ver a evolução dos ativos" / "Confirme a proporção dos ativos que possuo"
- "Meu patrimônio diminuiu?" / "Quanto vale em JPY?"
- Perguntas gerais sobre ativos em posse, saldo e lucros/perdas
Como responder a "Tive lucro/prejuízo não realizado?"
Esta skill não possui o preço de aquisição, portanto não pode apresentar lucros/perdas não realizados (diferença entre preço de aquisição e valor de mercado). Para esta fala, não encaminhe diretamente para tax-report, mas responda na seguinte ordem:
- Apresente o valor de avaliação atual e a composição (item de saída 1)
- Se desejar, apresente a evolução do patrimônio (item de saída 2), mostrando a variação excluindo depósitos e retiradas
- Em seguida, informe que "para determinar lucros/perdas não realizados, é necessário o preço de aquisição, e isso é responsabilidade do
tax-report(lucros/perdas de referênciatax pnl)"
Variação ajustada não deve ser chamada de lucro/prejuízo não realizado. Ela representa a variação do valor de avaliação excluindo depósitos e retiradas, e não o lucro/prejuízo com base no custo de aquisição (mesmo valor de avaliação, mas o lucro/prejuízo não realizado varia dependendo de quando foi comprado).
Pré-requisito: Configuração de Autenticação da API Privada
Para usar comandos da API privada (assets / balance-history), é necessário configurar a chave/secreta da API. Consulte "Autenticação" em _shared/references/cli-conventions.md para detalhes.
Recomendado: profile (profiles.json)
bitbank profile add main # Registre uma vez (secret é inserido oculto interativamente)
bitbank assets --format=json --machine # O profile padrão será usado
bitbank --profile=sub assets --format=json --machine # Alternar para outra conta
Compatibilidade retroativa: variáveis de ambiente
set -a; source .env; set +a
bitbank assets --format=json --machine
Se a chave da API não estiver configurada: Oriente o usuário a executar bitbank profile add <nome> e realize análises possíveis apenas com a API pública (ticker, candles).
Fluxo de Análise
Etapa 1: Obter Ativos em Posse
bitbank assets --format=json --machine # Ao usar profile, execute diretamente
# legado: set -a; source .env; set +a; bitbank assets --format=json --machine
Etapa 2: Obter Preços Atuais
Obter tickers de todos os pares JPY de uma só vez:
bitbank tickers-jpy --format=json --machine
Etapa 3: Obter Evolução do Patrimônio (apenas para o item de saída 2)
# Padrão: últimos 30 dias, granularidade diária
bitbank balance-history --format=json --machine
# Especificar período e granularidade (--days e --since não podem ser usados juntos)
bitbank balance-history --days=365 --granularity=month --format=json --machine
bitbank balance-history --since=1735689600000 --granularity=day --format=json --machine
Este comando realiza toda a reconstrução, avaliação e ajuste de depósitos/retiradas. Ele reconstrói a posse em cada ponto a partir do saldo atual, calculando retroativamente a partir de execuções de ordens e depósitos/retiradas, e retorna o resultado avaliado com a abertura da vela diária daquele dia. O modelo não realiza multiplicações (esta skill não calcula). Ele apenas lê e apresenta os campos retornados: points / current / flow / change / price_quality / completeness / warnings / note / assumptions.
Etapa 4: Saída
O item de saída 1 é gerado pelo modelo a partir dos dados das Etapas 1 e 2, apresentando valores de avaliação e proporções. O item de saída 2 apresenta diretamente os valores definitivos da Etapa 3 (sem recálculo).
Itens de Saída
1. Composição Atual de Ativos
Lista de ativos em posse, valor de avaliação e proporção.
=== Composição de Ativos ===
Valor total avaliado: 2.500.000 JPY
Ativo | Quantidade | Valor Avaliado | Proporção
JPY | 500.000 | 500.000 | 20,0%
BTC | 0,15 | 1.387.500 | 55,5%
ETH | 2,0 | 612.500 | 24,5%
- Valor avaliado = quantidade × preço
lastdo ticker (JPY é 1) - Proporção = valor avaliado de cada ativo / valor total avaliado
2. Evolução do Patrimônio em JPY
Apresente o resultado da Etapa 3 (balance-history). Respeite a seguinte ordem. Não coloque as premissas após a tabela — a ordem é especificação (veja "Posição de apresentação das premissas" abaixo para justificativa).
- Premissas (
note/assumptions) - Avisos (
warnings/completeness/price_quality) — se houver - Detalhamento da variação (
change/flow) - Tabela de evolução (
points+ ponto finalcurrent)
=== Evolução do Patrimônio (01/08/2025 a 11/08/2026 · Mensal) ===
Premissas (leia antes da tabela):
- A posse em cada ponto é um valor reconstruído a partir do saldo atual, calculando retroativamente execuções de ordens e depósitos/retiradas. Não é um snapshot do saldo naquela época.
- A avaliação é feita com a abertura da vela diária (limite do dia UTC) de cada ponto. Para ativos indisponíveis, o preço atual é usado como substituto.
- Apenas a última linha "Atual" é medida (ticker last × saldo atual. Como inclui ativos em processo de retirada, pode não coincidir com o valor total avaliado do item de saída 1).
- Transações na "Loja" (negociação instantânea) não aparecem na API e, portanto, não são refletidas.
Detalhamento da variação:
Variação simples : +150.000 JPY (+6,5%) Diferença do valor avaliado desde o início
Líquido dep./ret. : +120.000 JPY Depósitos − Retiradas (apenas movimentação de principal)
Variação ajustada : +30.000 JPY (+1,3%) Variação simples − Líquido depósitos/retiradas
Taxa de retirada : 770 JPY Já incluída na variação ajustada acima
Data | Valor Avaliado (JPY) | Variação vs. Anterior
01/08/2025 | 2.300.000 | -
01/09/2025 | 2.180.000 | -5,2%
...
01/08/2026 | 2.420.000 | +1,7%
Atual(medido)| 2.450.000 | +1,2%
Disciplina de Apresentação
- Não use apenas a variação simples como título. Se apenas "+150.000 ienes" for exibido, não ficará claro que 120.000 ienes disso é um depósito. Exiba sempre os três valores juntos: variação simples, líquido de depósitos/retiradas e variação ajustada (mostrar esses três separadamente é o próprio propósito deste item)
- Não oculte
warnings. Transmita o texto completo. Não resuma, omita ou adicione notas como "é leve". Especialmente quandocompleteness.completeforfalse(histórico truncado no limite de páginas / grade reduzida), afirme claramente antes da tabela que "os valores reconstruídos não são confiáveis" e trate os números como meramente referenciais flow.withdrawal_fee_jpyé a soma total de taxas como número positivo. Não inverta o sinal para exibir como "-770". O efeito como custo já está incorporado noadjusted_change_jpy, portanto, não subtraia novamente no detalhamento- Não remova
assumptions. O bloco de premissas deve extrair diretamente a saídanote/assumptions. Não reformule de forma resumida com suas próprias palavras para não perder condições - Quando
price_quality.levelnão forcomplete, mencione nominalmente osfallback_assets(a avaliação passada desses ativos foi substituída pelo preço atual) - Se
partial: true/meta.truncatedestiver presente no envelope, reporte também
Posição de Apresentação das Premissas (obrigação textual igual à do gráfico)
**"Ser um valor reconstruído e apenas o ponto final ser medido" deve ser colocado antes da tabela. A seção de visualização impõe ao gráfico uma obrigação de anotação com a mesma intensidade que agora é imposta ao texto. Colocar uma pequena nota após uma tabela de 20 linhas é tratado como se não houvesse anotação (a má leitura da implementação anterior ocorreu exatamente porque a nota estava após a tabela).
Autoavaliação (Loop de Validação)
Validação para o item de saída 1. Erros de valores afetam diretamente as decisões de investimento do usuário; portanto, evite saída sem validação. Para o item de saída 2, como são valores definitivos calculados pela CLI, não recalcule para confrontar (recriar números violaria o princípio desta skill de "não calcular").
- A soma dos valores avaliados de cada ativo é igual ao valor total avaliado? Se não, há erro de cálculo
- A soma das proporções é 100%? Erros de arredondamento (±0,1%) são tolerados, mas desvios grandes indicam erro de cálculo
- O valor avaliado de JPY é igual à quantidade em si? Se multiplicou JPY pelo preço do ticker, é um erro
- O valor avaliado está em uma faixa realista? Se 0,01 BTC vale bilhões de ienes, há provável erro de conversão numérica
Se houver inconsistência, identifique a causa, corrija e depois emita a saída.
Visualização (Opcional)
A disciplina de gatilho, resolução do ambiente de execução, destino da saída, estilo e regras de segurança seguem _shared/references/visualization-guide.md. Padrão é desligado (desenhe apenas quando o usuário solicitar explicitamente ou concordar com a sugestão).
Os gráficos são desenhados após a saída de texto (tabelas de composição de ativos e evolução do patrimônio), e não a substituem.
Gráficos padrão desta skill:
| ID do Gráfico | Conteúdo | Principais Elementos |
|---|---|---|
portfolio.allocation | Composição de ativos | Donut das proporções dos valores avaliados do item de saída 1 (maior valor primeiro, inclui JPY em espécie, valor total avaliado no centro). Rótulos em formato de legenda como padrão; ativos pequenos consolidados em "Outros" (veja abaixo). Alternável para versão de barras horizontais para comparação detalhada. Hora de obtenção do ticker no rodapé |
portfolio.value-history | Evolução do patrimônio em JPY | Linha dos points do item de saída 2 (valores reconstruídos) + marcador separado para o ponto final current (medido). Indique claramente no gráfico reconstructed from current balances; last point measured e o líquido de depósitos/retiradas (flow.net_flow_jpy) do período, para que aumentos por depósitos não sejam interpretados como valorização. Se price_quality.level não for complete, informe que há ativos avaliados por preço atual substituto; se houver warnings, inclua um resumo |
Avisos específicos do gráfico:
- Os valores e proporções no gráfico devem coincidir com as tabelas do texto (aplique a mesma validação de consistência do Loop de Validação ao gráfico)
- Disciplina de rótulos do
allocation(formato de legenda como padrão):- Na legenda, liste os ativos no formato
BTC 79,8% (47.997 JPY)com nome, proporção e valor - Anotações de % dentro das fatias apenas para fatias grandes (acima de 10%, como referência). Fatias pequenas devem ser lidas na legenda
- Não use rótulos externos com linhas de chamada (pois fatias pequenas adjacentes causam interferência de rótulos. A legenda é posicionada automaticamente pelo matplotlib, evitando sobreposição estrutural)
- Na legenda, liste os ativos no formato
- Regra de consolidação de ativos pequenos no
allocation(a bitbank suporta mais de 40 ativos, evitando que o gráfico fique fragmentado com detritos):- Ativos com proporção inferior a 3% são consolidados em "Outros" (o limite pode ser alterado por especificação do usuário)
- Mesmo acima do limite, o número de fatias é no máximo 6 + Outros (o excedente é consolidado em Outros, começando pelos menores)
- No rodapé ou legenda, informe a quantidade de itens, proporção total e principais componentes dos Outros (ex.:
Outros = XRP, DOGE e mais 5 ativos (total 4,2%)) - JPY (espécie) deve ser uma fatia independente independentemente da proporção (a capacidade de caixa é um elemento de decisão primário, não deve ser dobrada em Outros)
- O detalhamento completo de todos os ativos deve permanecer na tabela de texto (o gráfico não substitui o texto). Para examinar detritos, use a versão de barras horizontais (exibe todos os ativos)
- Como contém informações da conta (valores avaliados, quantidades), tenha cuidado ao compartilhar imagens. Se o usuário declarar explicitamente que compartilhará, sugira exibir apenas as proporções, ocultando os valores absolutos (regras de segurança em
visualization-guide.md) - Os pontos passados do
value-historysão reconstruídos por cálculo retroativo e não são snapshots do saldo na época; apenas o ponto final é medido. Não omita esta premissa e o líquido de depósitos/retiradas do período nas anotações do gráfico (mesma obrigação imposta ao texto. Evita que o gráfico seja lido isoladamente como "aumentou"). Quandocompleteness.completeforfalse, informe também no gráfico
Gotchas
- Valores monetários são retornados como strings. Se esquecer de converter para número, ocorrerá concatenação de strings, corrompendo completamente os valores avaliados. Todos os campos de
assetse preços de ticker são strings - Cuidado com
locked_amount. Ativos em ordens abertas ficam emlocked_amount. Useonhand_amount(total) para exibição. Se usar apenasfree_amount, os ativos em ordem desaparecerão - JPY não tem ticker. O "preço" de JPY é sempre 1. Tentar obter via ticker resultará em erro
- Não reconstrua os valores do
balance-history. Montar a evolução multiplicando quantidades por preços passados é o método da implementação antiga e divergirá significativamente do saldo real em contas com investimento programado (causa de má leitura). Quando precisar de evolução, chame este comando obrigatoriamente --dayse--sincenão podem ser usados juntos (especificação simultânea causa erro). Padrão são os últimos 30 dias com granularidade diária. Para janelas acima de 1 ano, use--granularity=month(diário pode truncar o lado antigo devido ao limite de grade)- Não ignore o truncamento silenciosamente. Se
completeness.complete: false/partial: trueaparecer, aumente--max-pagesou reduza a janela e reexecute. Se não resolver, não use os valores reconstruídos e informe ao usuário (a falta de um único histórico desloca silenciosamente os pontos passados) - Negociação de margem e "Loja" não são refletidas na evolução. Ordens de margem não movem o saldo à vista, portanto são excluídas da reconstrução; transações na "Loja" (negociação instantânea) não aparecem na API. Ambos aparecem em
warnings/assumptions, então transmita diretamente - O valor total avaliado do item de saída 1 e
current.value_jpypodem não coincidir perfeitamente. Obalance-historyadiciona de volta os ativos em processo de retirada (withdrawing_amount) ao saldo real, portanto, se houver ativos em processo de retirada, esse valor será maior. Não relate a diferença como "erro de cálculo" - Em caso de erro de API, consulte
_shared/references/bitbank-api-formats.md - Erro 20001 (falha de autenticação) → Oriente o usuário a verificar a configuração do
.env