DeBank Portfolio Scraper
Extrae instantáneas completas de portafolio de DeBank usando automatización de navegador, con integración opcional de OpenSea para precios de entrada de posiciones LP.
Prerrequisitos
- Playwright MCP - Automatización de navegador para navegación en DeBank
- OpenSea MCP - Datos de NFT/posiciones LP (opcional pero recomendado)
- Node.js 18+ - Para ejecutar scripts de persistencia
- SQLite - Base de datos para datos históricos
Consulte references/setup-guide.md para detalles de instalación.
Uso
scrape-portfolio <wallet_address>
scrape-portfolio --all # Extraer múltiples wallets desde un archivo de configuración
Fuentes de Datos
- DeBank (Playwright) - Posiciones DeFi, saldos de wallet, tasas de salud
- OpenSea API - Tenencias de NFT (NFTs de posición LP de Uniswap con precios de entrada)
Instrucciones
Paso 1: Navegar a DeBank
browser_navigate: https://debank.com/profile/{address}
Paso 2: Esperar a que cargue la página
browser_wait_for: time=5
Paso 3: Tomar instantánea
browser_snapshot
Paso 4: Expandir cadenas ocultas
Busque "Desplegar X cadenas" en la instantánea. Si aparece:
browser_click: ref=<unfold_button_ref>
browser_wait_for: time=2
browser_snapshot
Paso 5: Extraer datos del portafolio
Analice la instantánea y extraiga:
Perfil:
- Valor total (ej.,
$36,694) - Cambio en 24h en porcentaje
- Antigüedad de la cuenta en días
Asignación por cadena:
- Nombre de cadena, valor, porcentaje
Tokens del Wallet:
- Símbolo, cadena, precio, cantidad, valor en USD
Posiciones en Protocolos: Para cada protocolo (Aave, Compound, Uniswap, etc.):
- Nombre del protocolo y cadena
- Tipo de posición (Préstamo, Rendimiento, Pool de Liquidez)
- Tasa de salud (para posiciones de préstamo)
- Activos suministrados con cantidades y valores
- Activos prestados con cantidades y valores
- Saldos LP e IDs de pool
- Recompensas reclamables
Paso 6: Obtener datos de NFT (OpenSea)
Llame a la herramienta MCP de OpenSea:
get_nft_balances:
address: {wallet_address}
sortBy: RECEIVED_DATE
limit: 100
Esto devuelve NFTs de posición LP de Uniswap con:
- Token ID (ID del pool)
- Fecha de creación (fecha de entrada de la posición)
- Detalles del pool (par de tokens, nivel de comisión)
Paso 7: Obtener historial de actividad de NFT
get_activity:
entityType: profile
entityId: {wallet_address}
limit: 100
Esto proporciona:
- Precios de entrada para posiciones LP
- Hashes de transacciones
- Historial de acuñaciones/transferencias
Paso 8: Estructurar los datos
Cree JSON que coincida con el esquema en references/debank-portfolio-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"]
}
}
Paso 9: Guardar datos
Después de estructurar el JSON:
1. Escribir a archivo temporal:
Guarde el JSON en un archivo temporal (ej., /tmp/portfolio-snapshot.json)
2. Guardar instantánea JSON (copia de seguridad):
mkdir -p data/snapshots/{address}
# Escribir a data/snapshots/{address}/{YYYY-MM-DD}.json
3. Persistir en base de datos:
cd scripts && npx ts-node debank-snapshot-saver.ts --file /tmp/portfolio-snapshot.json
Establezca variables de entorno para la ubicación de la base de datos:
DB_PATH- Ruta a la base de datos SQLite (por defecto:../data/portfolio.db)SNAPSHOTS_DIR- Ruta a las instantáneas JSON (por defecto:../data/snapshots)
Registros de base de datos creados (cada extracción AÑADE nuevas filas, no sobrescribe):
portfolio_snapshots- Valor total + desglose por cadena (con marca de tiempo)position_snapshots- Posiciones DeFi individuales (con marca de tiempo)reward_history- Recompensas reclamables (con marca de tiempo)
Esto construye datos históricos para análisis de tendencias. Ejemplos de consultas:
-- Valor del portafolio a lo largo del tiempo
SELECT datetime(timestamp, 'unixepoch') as date, total_value
FROM portfolio_snapshots WHERE address = '0x...' ORDER BY timestamp;
-- Cambios en posiciones a lo largo del tiempo
SELECT datetime(timestamp, 'unixepoch') as date, protocol, net_value
FROM position_snapshots WHERE address = '0x...' ORDER BY timestamp;
Paso 10: Reportar resultados
Proporcione un resumen:
Portfolio extraído para 0x5a8a...ed45:
VALOR TOTAL: $36,694 (+0.11% 24h)
ASIGNACIÓN POR CADENA:
- Arbitrum: $26,011 (71%)
- Base: $10,650 (29%)
POSICIONES DEFI:
- Aave V3 (Arbitrum): $13,643 neto (Salud: 2.84)
- Suministrado: 18,784 USDC ($18,811)
- Prestado: 1.0168 WETH ($3,011) + 0.0241 WBTC ($2,156)
- Compound V3 (Base): $10,635
- Suministrado: 10,584 USDC
- Recompensas: 1.5 COMP ($36)
- Uniswap V4: $6,900
- Pool #103120: WBTC/USDC
- Recompensas: $50.21
- Uniswap V3: $5,142
- Pool #4721026: WBTC/WETH
- Recompensas: $18.92
POSICIONES LP (desde OpenSea):
- 11 NFTs de posición Uniswap
- Historial de entrada rastreado desde febrero 2025
RECOMPENSAS RECLAMABLES: $105.27
- COMP: $36.12
- Comisiones LP: $69.15
Datos guardados en:
- data/snapshots/{address}/{date}.json
- data/portfolio.db
Límite de Tasa
- Espere 30 segundos entre extracciones de múltiples wallets
- Si DeBank muestra limitación de tasa, espere 60 segundos y reintente
Manejo de Errores
- La página no carga: Reportar "DeBank inaccesible", omitir wallet
- No se encontraron datos: Reportar "El wallet puede estar vacío o ser inválido"
- Fallo parcial: Guardar lo recolectado, anotar errores
Esquema de Base de Datos
Consulte references/schema.sql para definiciones completas de tablas:
| Tabla | Propósito |
|---|---|
portfolio_snapshots | Valor total + desglose por cadena por marca de tiempo |
position_snapshots | Posiciones DeFi individuales con tokens/recompensas |
reward_history | Recompensas reclamables a lo largo del tiempo |
apy_history | Seguimiento de APY para protocolos |
transactions | Historial completo de transacciones |