DeBank 投资组合抓取工具
通过浏览器自动化从 DeBank 抓取全面的投资组合快照，并可选集成 OpenSea 以获取 LP 持仓入场价格。
前提条件
- Playwright MCP - 用于 DeBank 导航的浏览器自动化
- OpenSea MCP - NFT/LP 持仓数据（可选，但推荐）
- Node.js 18+ - 用于运行持久化脚本
- SQLite - 用于历史数据的数据库
详见 references/setup-guide.md 安装说明。
用法
scrape-portfolio <wallet_address>
scrape-portfolio --all # 从配置文件中抓取多个钱包
数据来源
- DeBank（Playwright） - DeFi 持仓、钱包余额、健康率
- OpenSea API - NFT 持有量（含入场价格的 Uniswap LP 位置 NFT）
操作指南
步骤 1：导航至 DeBank
browser_navigate: https://debank.com/profile/{address}
步骤 2：等待页面加载
browser_wait_for: time=5
步骤 3：截图
browser_snapshot
步骤 4：展开隐藏链
在截图中查找“展开 X 条链”。如果存在：
browser_click: ref=<unfold_button_ref>
browser_wait_for: time=2
browser_snapshot
步骤 5：提取投资组合数据
解析截图并提取：
概况：
- 总价值（例如
$36,694） - 24 小时变化百分比
- 账户存在天数
链分配：
- 链名称、价值、百分比
钱包代币：
- 符号、链、价格、数量、USD 价值
协议持仓： 对于每个协议（Aave、Compound、Uniswap 等）：
- 协议名称和链
- 持仓类型（借贷、收益、流动性池）
- 健康率（对于借贷持仓）
- 供应资产及其数量和价值
- 借入资产及其数量和价值
- LP 余额和池 ID
- 可领奖励
步骤 6：获取 NFT 数据（OpenSea）
调用 OpenSea MCP 工具：
get_nft_balances:
address: {wallet_address}
sortBy: RECEIVED_DATE
limit: 100
这将返回 Uniswap LP 位置 NFT，包含：
- 代币 ID（池 ID）
- 创建日期（持仓入场日期）
- 池详情（代币对、费用层级）
步骤 7：获取 NFT 活动历史
get_activity:
entityType: profile
entityId: {wallet_address}
limit: 100
这将提供：
- LP 持仓的入场价格
- 交易哈希
- 历史铸造/转账记录
步骤 8：结构化数据
创建符合 references/debank-portfolio-schema.json 架构的 JSON：
{
"metadata": {
"source": "debank.com + opensea",
"scrapeTimestamp": "<ISO 时间戳>",
"profileUrl": "https://debank.com/profile/{address}"
},
"profile": {
"address": "0x...",
"accountAgeDays": 510
},
"portfolio": {
"totalValueUsd": 36694,
"change24h": { "percent": 0.11, "direction": "up" },
"chainAllocation": [...],
"protocolAllocation": [...]
},
"wallet": {
"totalValueUsd": 374,
"tokens": [...]
},
"protocols": [...],
"nfts": {
"lpPositions": [...],
"other": [...]
},
"summary": {
"totalWalletValue": 374,
"totalDeFiValue": 36320,
"totalSupplied": 18810,
"totalBorrowed": 5167,
"totalLiquidityProvided": 12042,
"totalClaimableRewards": 105,
"activeProtocols": ["Aave V3", "Compound V3", "Uniswap V4", "Uniswap V3"],
"activeChains": ["Arbitrum", "Base", "Scroll"]
}
}
步骤 9：保存数据
结构化 JSON 后：
1. 写入临时文件：
将 JSON 保存到临时文件（例如 /tmp/portfolio-snapshot.json）
2. 保存 JSON 快照（备份）：
mkdir -p data/snapshots/{address}
# 写入 data/snapshots/{address}/{YYYY-MM-DD}.json
3. 持久化到数据库：
cd scripts && npx ts-node debank-snapshot-saver.ts --file /tmp/portfolio-snapshot.json
设置数据库位置的环境变量：
DB_PATH- SQLite 数据库路径（默认：../data/portfolio.db）SNAPSHOTS_DIR- JSON 快照目录（默认：../data/snapshots）
创建的数据库记录（每次抓取添加新行，不会覆盖）：
portfolio_snapshots- 总价值 + 链分解（带时间戳）position_snapshots- 单个 DeFi 持仓（带时间戳）reward_history- 可领奖励（带时间戳）
这将建立用于趋势分析的历史数据。查询示例：
-- 投资组合价值随时间变化
SELECT datetime(timestamp, 'unixepoch') as date, total_value
FROM portfolio_snapshots WHERE address = '0x...' ORDER BY timestamp;
-- 持仓变化随时间变化
SELECT datetime(timestamp, 'unixepoch') as date, protocol, net_value
FROM position_snapshots WHERE address = '0x...' ORDER BY timestamp;
步骤 10：报告结果
提供摘要：
已抓取 0x5a8a...ed45 的投资组合：
总价值：$36,694（24 小时 +0.11%）
链分配：
- Arbitrum：$26,011（71%）
- Base：$10,650（29%）
DeFi 持仓：
- Aave V3（Arbitrum）：$13,643 净值（健康率：2.84）
- 供应：18,784 USDC（$18,811）
- 借入：1.0168 WETH（$3,011）+ 0.0241 WBTC（$2,156）
- Compound V3（Base）：$10,635
- 供应：10,584 USDC
- 奖励：1.5 COMP（$36）
- Uniswap V4：$6,900
- 池 #103120：WBTC/USDC
- 奖励：$50.21
- Uniswap V3：$5,142
- 池 #4721026：WBTC/WETH
- 奖励：$18.92
LP 持仓（来自 OpenSea）：
- 11 个 Uniswap 持仓 NFT
- 入场历史自 2025 年 2 月起跟踪
可领奖励：$105.27
- COMP：$36.12
- LP 费用：$69.15
数据已保存至：
- data/snapshots/{address}/{date}.json
- data/portfolio.db
速率限制
- 多次钱包抓取之间等待 30 秒
- 如果 DeBank 显示速率限制，等待 60 秒后重试
错误处理
- 页面无法加载：报告“DeBank 不可达”，跳过该钱包
- 未找到数据：报告“钱包可能为空或无效”
- 部分失败：保存已收集的数据，并记录错误
数据库架构
详见 references/schema.sql 中的完整表定义：
| 表名 | 用途 |
|---|---|
portfolio_snapshots | 每个时间戳的总价值 + 链分解 |
position_snapshots | 带有代币/奖励的单个 DeFi 持仓 |
reward_history | 随时间变化的可领奖励 |
apy_history | 协议 APY 跟踪 |
transactions | 完整交易历史 |