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:
- Mostrar la valoración actual y la composición (elemento de salida 1)
- Si lo solicita, mostrar la evolución del patrimonio (elemento de salida 2) e indicar el cambio ajustado por depósitos/retiros
- 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 detax 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
lastdel 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).
- Supuestos (
note/assumptions) - Advertencias (
warnings/completeness/price_quality) — si las hay - Desglose de cambios (
change/flow) - Tabla de evolución (
points+ punto finalcurrent)
=== 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, cuandocompleteness.completeesfalse(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_jpyes la suma total de comisiones (positiva). No invertir el signo mostrándolo como "−770". Su efecto como costo ya está incorporado enadjusted_change_jpy, por lo que no se debe restar dos veces en el desglose- No eliminar
assumptions. El bloque de supuestos debe copiar textualmentenote/assumptionsde la salida. No reformular con propias palabras acortando las condiciones - Cuando
price_quality.levelno seacomplete, mencionar explícitamente losfallback_assets(la valoración histórica de esos activos se ha sustituido por el precio actual) - Si
partial: true/meta.truncatedaparece 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).
- ¿La suma de las valoraciones de cada activo es igual a la valoración total? Si no, hay un error de cálculo
- ¿La suma de los porcentajes da 100%? Se tolera un error de redondeo de ±0.1%, pero una desviación grande indica un error
- ¿La valoración de JPY es igual a su cantidad? Si se multiplicó JPY por el precio del ticker, es incorrecto
- ¿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áfico | Contenido | Elementos principales |
|---|---|---|
portfolio.allocation | Composición de activos | Grá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-history | Evolución del patrimonio en JPY | Lí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)
- En la leyenda, listar cada activo con formato
- 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-historyson 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). Cuandocompleteness.completeseafalse, 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
assetsy los precios del ticker son strings - Cuidado con
locked_amount. Los activos en órdenes abiertas aparecen enlocked_amount. Para mostrar el total, usaronhand_amount. Si solo se usafree_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 --daysy--sinceno 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-pageso 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_jpypueden no coincidir exactamente.balance-historysuma 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