Bitpanda v2 — 资产组合管理技能

一款简洁、可靠的技能，用于与 Bitpanda API 交互。返回原始数据，不执行自动聚合，确保数据准确性和透明性。

🎯 设计理念

少一点“智能”，多一分可靠。 上一版本存在聚合逻辑缺陷，导致返回错误数据。本技能具备以下特性：

• ✅ 直接返回来自 Bitpanda API 的原始数据
• ✅ 正确处理分页（pagination）
• ✅ 提供清晰明确的错误处理机制
• ❌ 不提供任何自动聚合（用户如需处理，可自行操作）

📋 前置条件

软件依赖

• curl — 用于发起 HTTP 请求
• jq — 用于解析 JSON 数据
• PowerShell 或 bash shell 环境

Bitpanda API Key

1. 访问 Bitpanda Developer Portal
2. 使用你的 Bitpanda 账户登录
3. 导航至 “API Keys” 或 “Settings” 页面
4. 创建一个新的 API key（请按需选择权限）
5. 复制该密钥并妥善保存

环境变量配置

PowerShell：

$env:BITPANDA_API_KEY = "tua-api-key-qui"
# 如需永久生效，请运行：
[System.Environment]::SetEnvironmentVariable("BITPANDA_API_KEY", "tua-api-key-qui", "User")

Bash（Linux / Mac）：

export BITPANDA_API_KEY="tua-api-key-qui"
# 如需永久生效，请将以下行添加至 ~/.bashrc 或 ~/.zshrc：
echo 'export BITPANDA_API_KEY="tua-api-key-qui"' >> ~/.bashrc

🛠️ 可用命令

balances — 显示余额大于 0 的加密货币钱包

列出所有余额大于零的加密货币 / 商品 / 证券类钱包。

Endpoint： /v1/asset-wallets（已过滤 balance > 0）

示例：

bitpanda.sh balances

输出： JSON 数组，仅包含你持有显著数量的资产。涵盖：

• 加密货币（BTC、ETH、LTC 等）
• 商品 / 金属（XAU-Gold、XAG-Silver 等）
• 证券 / 股票（AMD、ARM、QCOM 等）
• ETF 及其他金融产品

data — 完整资产组合数据

获取你完整的资产组合结构，所有钱包按类别组织呈现。

Endpoint： /v1/asset-wallets（完整响应）

示例：

bitpanda.sh data

输出： 完整 JSON，包含：

• 所有钱包按类型分类（cryptocoin、commodity、security 等）
• last_user_action：最后一次用户操作的时间戳
• 资产组合的完整层级结构

注意： 此命令返回全部钱包（包括 balance = 0 的），适用于查看整体结构。

trades [--limit N] — 交易历史记录

获取你的全部交易历史。支持自动分页，便于获取较早的交易记录。

示例：

# 最近 10 笔交易
bitpanda.sh trades --limit 10

# 所有交易（自动分页）
bitpanda.sh trades

# 限制为最多 50 笔交易
bitpanda.sh trades --limit 50

输出： JSON 格式，含每笔交易的详细信息（时间、类型、资产、数量、价格）。

price — 单个资产实时价格

获取指定资产的当前市场价格。

示例：

bitpanda.sh price BTC
bitpanda.sh price ETH
bitpanda.sh price EUR

输出： JSON 格式，含资产符号、当前价格及时间戳。

prices — 当前持有的全部资产价格

获取你当前资产组合中所有资产的最新市场价格。

示例：

bitpanda.sh prices

输出： JSON 格式，含资产符号及其对应价格的列表。

📚 API 参考文档

基础 URL：https://developer.bitpanda.com/

已使用的 Endpoint（均符合官方文档规范）

⚠️ 已移除的无效 Endpoint：

• /v1/balances — 官方文档中不存在！
• /v1/data — 官方文档中不存在！

分页机制（Pagination）

交易记录（trades）： 使用 cursor 和 page_size 实现分页。

{
  "data": [...],
  "meta": {
    "total_count": 197,
    "next_cursor": "...",
    "page_size": 10
  }
}

资产钱包（Asset Wallets）： 无分页 —— 单次请求即返回全部钱包。

⚠️ 常见错误与排障指南

401 Unauthorized

原因： API key 无效或未设置。
解决方法： 检查 $env:BITPANDA_API_KEY（PowerShell）或 $BITPANDA_API_KEY（Bash）是否已正确配置。

429 Rate Limit

原因： 短时间内请求过于频繁。
解决方法： 稍等数秒后重试。Bitpanda 对 API 调用设有速率限制（rate limit）。

Timeout

原因： 网络连接缓慢，或 Bitpanda API 未响应。
解决方法： 检查本地网络连接，稍后重试。

jq Not Found

原因： 系统未安装 jq。
解决方法：

• Windows：通过 Chocolatey 安装（choco install jq），或从 stedolan.github.io/jq 下载二进制文件
• Mac：brew install jq
• Linux：sudo apt install jq（Debian / Ubuntu）

JSON 输出未格式化

原因： jq 未正常工作。
解决方法： 运行 echo '{}' | jq '.' 测试；若失败，请重新安装 jq。

🔧 高级配置

自定义超时时间

修改脚本以调整请求超时值：

# 在 bitpanda.sh 文件中查找 --max-time 参数并修改
curl ... --max-time 30 ...

调试模式（Verbose Mode）

如需调试，请在脚本中的 curl 命令后添加 -v 参数。

📝 重要说明

• 无数据聚合： 本技能不对数据做任何计算或聚合，严格返回 Bitpanda API 原始响应内容。
• 分页自动处理： balances 与 trades 命令在必要时会自动处理分页逻辑。
• 原始数据交付： 若需进一步处理（如计算总资产价值等），请在调用后使用 jq 或其他工具完成。

🚀 实用示例

资产组合总价值

# 获取完整资产组合并提取总价值字段
bitpanda.sh data | jq '.total_value'

余额大于 0 的资产列表

# 筛选出你实际持有的资产（available > 0）
bitpanda.sh balances | jq '.[] | select(.available > 0) | {symbol, available}'

最新一笔交易

# 获取最近发生的一笔交易
bitpanda.sh trades --limit 1 | jq '.trades[0]'

🆚 与 bitpanda-official（旧版）对比

🔧 2026 年 3 月更新说明： 修正了旧版中 balances 与 data 命令所使用的非法 endpoint（/v1/balances、/v1/data）。新版已统一采用官方文档明确定义的 /v1/asset-wallets 接口。

📞 支持

如遇问题或疑问，请按以下步骤排查：

1. 查阅 Bitpanda 官方文档
2. 确认 API key 是否有效且权限正确
3. 使用 curl 直接调用 API，以隔离问题来源

BradiBot 设计哲学： 🦥 质量优于速度，可靠胜于“智能”。一个简单却稳定可靠的技能，远胜于复杂却输出错误结果的方案！ 💪