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 小時變化百分比
- 帳戶年齡（天數）
鏈上配置：
- 鏈名稱、價值、百分比
錢包代幣：
- 代號、鏈、價格、數量、美元價值
協議部位： 針對每個協議（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 中 schema 的 JSON：
{
"metadata": {
"source": "debank.com + opensea",
"scrapeTimestamp": "<ISO timestamp>",
"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（+0.11% 24 小時）
鏈上配置：
- 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 無法連線」，略過該錢包
- 找不到資料：回報「錢包可能為空或無效」
- 部分失敗：儲存已收集的資料，並註記錯誤
資料庫 Schema
完整的資料表定義請參閱 references/schema.sql：
| 資料表 | 用途 |
|---|---|
portfolio_snapshots | 每個時間點的總價值 + 鏈上明細 |
position_snapshots | 個別 DeFi 部位（含代幣/獎勵） |
reward_history | 隨時間變化的可領取獎勵 |
apy_history | 協議 APY 追蹤 |
transactions | 完整交易歷史 |