Communitygithub.com

bitbankinc/bitbank-lab-cli

Obtén una visión general de tu portafolio de criptomonedas en bitbank: composición de activos, valoración en JPY y evolución del patrimonio ajustada por depósitos y retiros.

¿Qué es bitbank-lab-cli?

Este skill está diseñado para agentes de IA (como Claude Code) que interactúan con la CLI de bitbank. Su propósito es responder preguntas sobre el estado actual del portafolio de un usuario, como "muéstrame el portafolio", "¿cuánto tengo ahora?" o "¿cómo ha cambiado mi patrimonio?". No calcula ganancias/pérdidas no realizadas porque no conoce el precio de adquisición; para eso deriva a otro skill (`tax-report`). El flujo principal obtiene primero los activos mantenidos (`bitbank assets`), luego los precios actuales de todos los pares JPY (`bitbank tickers-jpy`) y, si el usuario solicita la evolución temporal, ejecuta `bitbank balance-history` con opciones de período y granularidad. El modelo (la IA) solo presenta los datos: no realiza cálculos propios sobre las cifras devueltas por la CLI, excepto para validar la suma de valoraciones y los porcentajes. La salida se compone de dos secciones principales: (1) una tabla con la composición actual de activos, valoración y porcentaje, y (2) una tabla de evolución del patrimonio en JPY que incluye advertencias, supuestos, desglose de cambios (simple, neto de flujos, ajustado) y la serie temporal. El skill también cuenta con una guía detallada para generar visualizaciones opcionales (gráfico de dona para la asignación y gráfico de líneas para la evolución), con reglas estrictas sobre etiquetas, agregación de tenencias pequeñas y anotaciones. Es fundamental respetar la precedencia de las notas y supuestos (mostrarlos antes que la tabla) y no ocultar las advertencias de integridad de los datos. Además, incluye una sección de "Gotchas" con errores comunes como la conversión de tipos (los montos vienen como strings), el manejo de `locked_amount` vs `onhand_amount`, la imposibilidad de obtener ticker para JPY, y la necesidad de no reconstruir manualmente el historial de balance. La autenticación se realiza mediante perfiles (`bitbank profile add`) o variables de entorno. En caso de error de API (código 20001), se guía al usuario a revisar su configuración.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Skill de Portafolio

Cuándo usarlo

Además de los disparadores principales, se activa con expresiones como:

  • "Quiero ver la evolución de mis activos" / "Revisa la proporción de mis tenencias"
  • "¿Han bajado mis activos?" / "¿Cuánto es en JPY?"
  • Preguntas generales sobre tenencias, saldos y ganancias/pérdidas

Cómo responder a "¿Tengo ganancias no realizadas?"

Este skill no tiene acceso al precio de adquisición, por lo que no puede calcular ganancias/pérdidas no realizadas (diferencia entre precio de compra y valor de mercado). Ante esta pregunta, no se debe redirigir inmediatamente a tax-report, sino seguir este orden:

  1. Mostrar la valoración actual y la composición (elemento de salida 1)
  2. Si lo solicita, mostrar la evolución del patrimonio (elemento de salida 2) e indicar el cambio ajustado por depósitos/retiros
  3. Luego, aclarar que "Para determinar ganancias/pérdidas no realizadas se necesita el precio de adquisición, y eso es competencia de tax-report (ganancias/pérdidas de referencia de tax pnl)"

El cambio ajustado no debe llamarse ganancia/pérdida no realizada. Es la variación de la valoración excluyendo depósitos y retiros, no una ganancia/pérdida basada en el costo de adquisición (incluso con la misma valoración, la ganancia/pérdida no realizada varía según cuándo se compró).

Requisito previo: Configuración de autenticación de API privada

Para usar comandos de API privada (assets / balance-history), se deben configurar la clave API y el secreto. Consulta "Autenticación" en _shared/references/cli-conventions.md.

Recomendado: perfil (profiles.json)

bitbank profile add main                    # Registrar una vez (el secreto se ingresa oculto)
bitbank assets --format=json --machine      # Usa el perfil por defecto
bitbank --profile=sub assets --format=json --machine   # Cambiar a otra cuenta

Compatibilidad hacia atrás: variables de entorno

set -a; source .env; set +a
bitbank assets --format=json --machine

Si no hay clave API configurada: Indica al usuario que ejecute bitbank profile add <nombre> y realiza el análisis solo con datos de API pública (ticker, candles).

Flujo de análisis

Paso 1: Obtener tenencias

bitbank assets --format=json --machine   # Ejecutar directamente si se usa perfil
# legacy: set -a; source .env; set +a; bitbank assets --format=json --machine

Paso 2: Obtener precios actuales

Obtener los tickers de todos los pares JPY de una sola vez:

bitbank tickers-jpy --format=json --machine

Paso 3: Obtener historial de saldos (solo para el elemento de salida 2)

# Por defecto: últimos 30 días, granularidad diaria
bitbank balance-history --format=json --machine

# Especificar período y granularidad (--days y --since no se pueden usar 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 la reconstrucción, valoración y ajuste por depósitos/retiros. Calcula hacia atrás las tenencias en cada punto a partir del saldo actual, los trades y los depósitos/retiros, y las valora usando el precio de apertura de la vela diaria de ese día. El modelo (IA) no hace cálculos (este skill no realiza cálculos). Simplemente lee y presenta los valores devueltos: points, current, flow, change, price_quality, completeness, warnings, note, assumptions.

Paso 4: Salida

El elemento de salida 1 se genera a partir de los datos de los Pasos 1 y 2 (el modelo calcula la valoración y los porcentajes). El elemento de salida 2 se presenta tal cual lo devuelve el Paso 3 (sin recalcular).

Elementos de salida

1. Composición actual de activos

Lista de tenencias, valoración y porcentaje.

=== Composición de activos ===

Valoración total: 2,500,000 JPY

Activo | Cantidad   | Valoración   | Porcentaje
JPY    | 500,000   | 500,000     | 20.0%
BTC    | 0.15      | 1,387,500   | 55.5%
ETH    | 2.0       | 612,500     | 24.5%
  • Valoración = cantidad × precio last del ticker (JPY es 1)
  • Porcentaje = valoración del activo / valoración total

2. Evolución del patrimonio en JPY

Presenta los resultados del Paso 3 (balance-history). Se debe respetar el siguiente orden. No colocar los supuestos después de la tabla — el orden es parte de la especificación (razón en "Posición de los supuestos" más abajo).

  1. Supuestos (note / assumptions)
  2. Advertencias (warnings / completeness / price_quality) — si las hay
  3. Desglose de cambios (change / flow)
  4. Tabla de evolución (points + punto final current)
=== Evolución del patrimonio (2025-08-01 - 2026-08-11 · Mensual) ===

Supuestos (léanse antes que la tabla):
- Las tenencias en cada punto se reconstruyen hacia atrás a partir del saldo actual, trades y depósitos/retiros; no son instantáneas históricas reales del saldo
- La valoración se calcula con el precio de apertura de la vela diaria (límite UTC). Los activos sin precio histórico se valoran con el precio actual
- La fila "Actual" es la única medida real (ticker last × saldo actual). Puede incluir activos en proceso de retiro, por lo que puede no coincidir con la valoración total del elemento 1
- Las operaciones en la plataforma de venta (compra/venta inmediata) no aparecen en la API, por lo que no se reflejan

Desglose de cambios:
  Cambio simple              : +150,000 JPY (+6.5%)   Diferencia de valoración desde el inicio
  Flujo neto de depósitos    : +120,000 JPY           Depósitos − Retiros (solo movimiento de capital)
  Cambio ajustado            :  +30,000 JPY (+1.3%)   Cambio simple − Flujo neto
  Comisiones de retiro       :      770 JPY           Ya incluidas en el cambio ajustado anterior

Fecha       | Valoración (JPY) | Cambio vs punto anterior
2025-08-01  |  2,300,000      | -
2025-09-01  |  2,180,000      | -5.2%
...
2026-08-01  |  2,420,000      | +1.7%
Actual (medido) |  2,450,000 | +1.2%

Disciplina en la presentación

  • No usar solo el cambio simple como título. Mostrar solo "+150,000 JPY" no transmite que 120,000 JPY provienen de un depósito. Siempre presentar los tres valores juntos: cambio simple, flujo neto y cambio ajustado (mostrar estos tres por separado es el objetivo mismo de este elemento)
  • No ocultar ni resumir las warnings. Transmitir el texto completo sin resumir, omitir ni añadir comentarios como "es leve". En particular, cuando completeness.complete es false (el historial se truncó por el límite de páginas / se redujo la resolución), declarar explícitamente antes de la tabla que "los valores reconstruidos no son fiables" y tratar las cifras como meramente referenciales
  • flow.withdrawal_fee_jpy es la suma total de comisiones (positiva). No invertir el signo mostrándolo como "−770". Su efecto como costo ya está incorporado en adjusted_change_jpy, por lo que no se debe restar dos veces en el desglose
  • No eliminar assumptions. El bloque de supuestos debe copiar textualmente note / assumptions de la salida. No reformular con propias palabras acortando las condiciones
  • Cuando price_quality.level no sea complete, mencionar explícitamente los fallback_assets (la valoración histórica de esos activos se ha sustituido por el precio actual)
  • Si partial: true / meta.truncated aparece en el envoltorio, también debe reportarse

Posición de los supuestos (el texto tiene la misma obligación que el gráfico)

La información de que son valores reconstruidos y que solo el punto final es medido debe ir antes de la tabla. Se aplica al texto la misma obligación de anotación que el gráfico tiene en la sección de visualización. Colocarlo en letra pequeña después de una tabla de 20 filas equivale a no tener anotación (los errores de lectura en implementaciones anteriores ocurrieron precisamente porque la nota estaba después de la tabla).

Autocomprobación (Bucle de validación)

Validación para el elemento de salida 1. Los errores de cantidad afectan directamente las decisiones de inversión del usuario, por lo que se debe evitar la salida sin validación. El elemento de salida 2 son valores definitivos calculados por la CLI, por lo que no se deben recalcular ni cotejar (rehacer los números violaría el principio de "no calcular" de este skill).

  1. ¿La suma de las valoraciones de cada activo es igual a la valoración total? Si no, hay un error de cálculo
  2. ¿La suma de los porcentajes da 100%? Se tolera un error de redondeo de ±0.1%, pero una desviación grande indica un error
  3. ¿La valoración de JPY es igual a su cantidad? Si se multiplicó JPY por el precio del ticker, es incorrecto
  4. ¿Las valoraciones son realistas? Si 0.01 BTC da miles de millones de JPY, probablemente hay un error de conversión numérica

Si hay alguna inconsistencia, identificar la causa, corregirla y luego mostrar la salida.

Visualización (Opcional)

La disciplina de disparadores, resolución del entorno de ejecución, destino de salida, estilo y normas de seguridad siguen lo establecido en _shared/references/visualization-guide.md. Desactivada por defecto (solo dibujar cuando el usuario lo solicite explícitamente, o cuando acepte una sugerencia). Los gráficos se dibujan después de la salida de texto (tablas de composición y evolución), y no deben reemplazarla.

Gráficos estándar de este skill:

ID del gráficoContenidoElementos principales
portfolio.allocationComposición de activosGráfico de dona con los porcentajes de valoración del elemento 1 (ordenado de mayor a menor valoración, incluye JPY, total en el centro). Etiquetas en leyenda por defecto; las tenencias pequeñas se agregan en "Otros" (ver más abajo). Marca de tiempo de la obtención del ticker en el pie. Se puede cambiar a versión de barras horizontales para comparación detallada
portfolio.value-historyEvolución del patrimonio en JPYLínea de los points (valores reconstruidos) del elemento 2 + punto final current (medido) con marcador diferente. Indicar claramente en el gráfico: reconstructed from current balances; last point measured y el flujo neto del período (flow.net_flow_jpy), para evitar que un aumento por depósitos se interprete como plusvalía. Si price_quality.level no es complete, indicar qué activos se valoraron con precio actual; si hay warnings, incluir un resumen

Notas específicas de los gráficos:

  • Las cantidades y porcentajes en el gráfico deben coincidir con las tablas del texto (aplicar la misma validación de consistencia que en el bucle de validación)
  • Disciplina de etiquetas de allocation (leyenda por defecto):
    • En la leyenda, listar cada activo con formato BTC 79.8% (47,997 JPY) (ticker, porcentaje, cantidad)
    • Solo incluir anotaciones de porcentaje dentro de las porciones grandes (aproximadamente >10%). Las porciones pequeñas se leen en la leyenda
    • No usar etiquetas periféricas con líneas de referencia (cuando hay porciones pequeñas adyacentes, las etiquetas interfieren. La leyenda, al ser colocada automáticamente por matplotlib, evita superposiciones estructuralmente)
  • Regla de agregación de tenencias pequeñas en allocation (bitbank admite más de 40 tickers, evitando que tenencias pequeñas y dust fragmenten el gráfico):
    • Los activos con un porcentaje menor al 3% se agregan en "Otros" (el umbral se puede ajustar según solicitud del usuario)
    • Incluso los activos que superan el umbral se limitan a un máximo de 6 porciones + Otros (el exceso se agrega a Otros, empezando por los más pequeños)
    • Indicar en la leyenda o nota al pie el número de elementos, porcentaje total y principales componentes de Otros (ejemplo: Otros = XRP, DOGE y otros 5 tickers (total 4.2%))
    • JPY (efectivo) debe ser siempre una porción independiente, independientemente de su porcentaje (la liquidez en efectivo es un criterio de primer orden, no debe ocultarse en Otros)
    • El desglose completo de todos los activos debe conservarse siempre en la tabla de texto (el gráfico no reemplaza al texto). Para examinar el dust, usar la versión de barras horizontales (que muestra todos los activos)
  • El gráfico contiene información de la cuenta (valoraciones y tenencias), por lo que se debe tener cuidado al compartir la imagen. Si el usuario declara explícitamente que se compartirá, sugerir mostrar solo los porcentajes sin las cantidades absolutas (consultar las normas de seguridad en visualization-guide.md)
  • Los puntos pasados de value-history son reconstrucciones retrospectivas, no instantáneas del saldo real en ese momento; solo el punto final es medido. No omitir esta premisa ni el flujo neto del período en las anotaciones del gráfico (misma obligación que para el texto. Evitar que quien vea solo el gráfico interprete "ha subido" incorrectamente). Cuando completeness.complete sea false, también debe indicarse en el gráfico

Aspectos a tener en cuenta (Gotchas)

  • Los montos se devuelven como cadenas de texto. Olvidar la conversión numérica provoca concatenación de strings, arruinando completamente las valoraciones. Todos los campos de assets y los precios del ticker son strings
  • Cuidado con locked_amount. Los activos en órdenes abiertas aparecen en locked_amount. Para mostrar el total, usar onhand_amount. Si solo se usa free_amount, los activos en órdenes desaparecen
  • JPY no tiene ticker. El "precio" de JPY es siempre 1. Intentar obtenerlo mediante ticker dará un error
  • No reconstruir manualmente los valores de balance-history. Multiplicar tenencias por precios pasados para construir la evolución es el método de implementaciones antiguas, que se desvía significativamente del saldo real en cuentas de acumulación (causa de errores de interpretación). Si se necesita la evolución, siempre llamar a este comando
  • --days y --since no se pueden usar juntos (producen un error). Por defecto: últimos 30 días, granularidad diaria. Ventanas de más de 1 año usar --granularity=month (la granularidad diaria tiene un límite de cuadrícula que descarta los datos más antiguos)
  • No pasar por alto un truncamiento. Si aparece completeness.complete: false / partial: true, aumentar --max-pages o reducir la ventana y re-ejecutar. Si no se soluciona, no usar los valores reconstruidos e informar al usuario (la falta de un solo registro histórico altera silenciosamente los puntos pasados)
  • Las operaciones de margen y las de la plataforma de venta no se reflejan en la evolución. Las operaciones de margen no mueven el saldo al contado, por lo que se excluyen de la reconstrucción; las de la plataforma de venta (compra/venta inmediata) no aparecen en la API. Ambas se indican en warnings / assumptions, por lo que deben transmitirse tal cual
  • La valoración total del elemento 1 y current.value_jpy pueden no coincidir exactamente. balance-history suma los activos en proceso de retiro (withdrawing_amount) al saldo real, por lo que si hay activos en proceso de retiro, será mayor. No reportar la diferencia como "error de cálculo"
  • En caso de error de API, consultar _shared/references/bitbank-api-formats.md
  • Error 20001 (fallo de autenticación) → Indicar al usuario que revise la configuración de .env

Skills relacionados