SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场tracking-crypto-portfolio

tracking-crypto-portfolio

数据与分析

查看项目

更新于 10-15 08:06

技能介绍

用途

该技能提供加密货币投资组合的综合追踪能力，帮助用户掌握持仓的实时估值、资产配置与盈亏情况。数据来源为 CoinGecko 的实时价格。

主要能力

  • 实时估值：从 CoinGecko 获取当前价格。
  • 持仓明细：展示每种资产的数量、价值与占比。
  • 盈亏追踪：基于成本价计算未实现盈亏（P&L）。
  • 配置分析：按类别拆分并标记集中度风险。
  • 多种导出格式：表格、JSON、CSV。
  • 支持跨多个资产追踪持仓，计算组合总价值（美元），识别超配仓位（集中度风险），并导出供分析工具与税务申报使用。

使用方式

前置条件

  • 已安装 Python 3.8+。
  • 已安装 requests 库：pip install requests。
  • 具备访问 CoinGecko API 的网络连接。
  • 准备一个包含持仓的 portfolio JSON 文件。

持仓文件格式

创建持仓文件（例如 holdings.json）：

{
  "name": "My Portfolio",
  "holdings": [
    {"coin": "BTC", "quantity": 0.5, "cost_basis": 25000},
    {"coin": "ETH", "quantity": 10, "cost_basis": 2000},
    {"coin": "SOL", "quantity": 100}
  ]
}

字段说明：

  • coin：币种符号（BTC、ETH 等）——必填。
  • quantity：持有数量——必填。
  • cost_basis：每枚币的平均买入价（可选，用于 P&L）。
  • acquired：获取日期（可选，用于记录）。

执行步骤

第一步：判断用户意图，确定需要哪类组合信息：快速查看（总价值与主要持仓）、持仓列表（全部仓位明细）、详细分析（配置、P&L、风险标记）、导出（JSON 或 CSV 供外部工具使用）。

第二步：使用相应选项运行追踪脚本：

# 快速组合摘要
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json

# 完整持仓明细
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --holdings

# 含 P&L 与配置的详细分析
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --detailed

# 导出为 JSON
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format json --output portfolio_export.json

# 导出为 CSV
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format csv --output portfolio.csv

第三步：呈现结果，突出显示组合总价值、24 小时与 7 日变化、解释配置百分比、标记集中度风险；在详细模式下解释 P&L 计算。

命令行选项

  • --portfolio：持仓 JSON 文件路径（必填）。
  • --holdings：显示全部持仓明细（默认 false）。
  • --detailed：含 P&L 的完整分析（默认 false）。
  • --sort：排序方式，可选 value、allocation、name、change（默认 value）。
  • --format：输出格式，可选 table、json、csv（默认 table）。
  • --output：输出文件路径（默认 stdout）。
  • --threshold：配置警告阈值（默认 25%）。
  • --verbose：启用详细输出（默认 false）。

配置阈值

默认情况下，占比超过 25% 的仓位会被标记：

  • < 10%：低风险，正常仓位。
  • 10–25%：中风险，需密切关注。
  • 25–50%：高风险，考虑再平衡。

  • 50%：极高风险，存在显著集中度风险。

输出示例

表格格式（默认）会显示组合摘要（总价值、24h 变化、7d 变化、持仓数量）、主要持仓（币种、数量、价格、价值、占比、24h 变化），并在超过阈值时给出集中度警告。

JSON 格式包含 portfolio_name、total_value_usd、change_24h（amount、percent）、holdings 数组（coin、quantity、price_usd、value_usd、allocation_pct、change_24h_pct）以及 meta（timestamp、holdings_count）。

错误处理

  • 找不到持仓文件：路径无效，检查文件路径是否存在。
  • JSON 无效：文件格式错误，校验 JSON 语法。
  • 找不到币种：符号未知，检查符号拼写并使用标准符号。
  • API 限流：请求过多，等待后重试或使用缓存。

更多错误处理见 {baseDir}/references/errors.md，详细示例见 {baseDir}/references/examples.md。

快速示例

# 基础组合检查
python {baseDir}/scripts/portfolio_tracker.py --portfolio ~/crypto/holdings.json

# 按占比显示全部持仓
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --holdings --sort allocation

# 使用 15% 阈值的详细分析
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --detailed --threshold 15

# 导出供税务软件使用
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format csv --output tax_export.csv

# 导出 JSON 供交易机器人使用
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format json --output portfolio_data.json

适用场景

  • 快速查看加密资产组合的总价值与主要持仓。
  • 分析各资产配置比例并识别集中度风险。
  • 基于成本价追踪未实现盈亏。
  • 导出数据供分析工具、交易机器人或税务申报使用。

限制

  • 依赖 CoinGecko API 与网络连接，可能受 API 限流影响。
  • 需要用户自行准备符合格式的持仓 JSON 文件。
  • 需安装 Python 3.8+ 与 requests 库。
  • 关于收费、价格、平台支持范围等信息，资料中暂未提供。

资源

  • CoinGecko API：https://www.coingecko.com/en/api
  • 持仓 Schema：见 PRD.md。
  • 配置：见 {baseDir}/config/settings.yaml。
  • 集成示例：见 {baseDir}/references/examples.md。