Communitygithub.com

bitbankinc/bitbank-lab-cli

Compreenda a situação atual do seu portfólio (composição de ativos, valor em JPY e evolução ajustada por depósitos/retiradas) usando dados de ativos e preços da bitbank.

O que é bitbank-lab-cli?

Esta skill é especializada em fornecer uma visão geral do portfólio de um usuário na bitbank, focando exclusivamente na avaliação de ativos em posse. Ela se destaca por não realizar cálculos complexos por conta própria, mas sim por consumir e apresentar dados de comandos da CLI oficial (`bitbank assets`, `bitbank tickers-jpy`, `bitbank balance-history`). A skill produz dois principais grupos de saída: (1) a composição atual dos ativos com valores e proporções, e (2) a evolução do patrimônio em JPY ao longo do tempo, já ajustada por depósitos e retiradas, usando dados históricos reconstruídos a partir do saldo atual. É importante notar que esta skill **não** calcula lucros/perdas não realizados (que exigem o preço de aquisição) e, para isso, encaminha o usuário para a skill `tax-report`. Para operações de análise de correlação entre pares ou perfil de volatilidade de um ativo, ela referencia as skills `correlation-analysis` e `volatility-profile`, respectivamente. A skill também oferece visualizações opcionais de gráficos (donut para alocação e linha para evolução) seguindo regras rigorosas de rotulagem e segurança para evitar interpretações errôneas dos dados.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bitbankinc/bitbank-lab-cli/tree/HEAD/skills/portfolio

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. Apresente o valor de avaliação atual e a composição (item de saída 1)
  2. Se desejar, apresente a evolução do patrimônio (item de saída 2), mostrando a variação excluindo depósitos e retiradas
  3. 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ência tax 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 last do 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).

  1. Premissas (note / assumptions)
  2. Avisos (warnings / completeness / price_quality) — se houver
  3. Detalhamento da variação (change / flow)
  4. Tabela de evolução (points + ponto final current)
=== 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 quando completeness.complete for false (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 no adjusted_change_jpy, portanto, não subtraia novamente no detalhamento
  • Não remova assumptions. O bloco de premissas deve extrair diretamente a saída note / assumptions. Não reformule de forma resumida com suas próprias palavras para não perder condições
  • Quando price_quality.level não for complete, mencione nominalmente os fallback_assets (a avaliação passada desses ativos foi substituída pelo preço atual)
  • Se partial: true / meta.truncated estiver 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").

  1. A soma dos valores avaliados de cada ativo é igual ao valor total avaliado? Se não, há erro de cálculo
  2. A soma das proporções é 100%? Erros de arredondamento (±0,1%) são tolerados, mas desvios grandes indicam erro de cálculo
  3. O valor avaliado de JPY é igual à quantidade em si? Se multiplicou JPY pelo preço do ticker, é um erro
  4. 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áficoConteúdoPrincipais Elementos
portfolio.allocationComposição de ativosDonut 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-historyEvolução do patrimônio em JPYLinha 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)
  • 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-history sã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"). Quando completeness.complete for false, 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 assets e preços de ticker são strings
  • Cuidado com locked_amount. Ativos em ordens abertas ficam em locked_amount. Use onhand_amount (total) para exibição. Se usar apenas free_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
  • --days e --since nã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: true aparecer, aumente --max-pages ou 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_jpy podem não coincidir perfeitamente. O balance-history adiciona 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

Habilidades Relacionadas