Scraper de Portefeuille DeBank
Extrayez des snapshots complets de portefeuille depuis DeBank en utilisant l'automatisation de navigateur, avec une intégration optionnelle OpenSea pour les prix d'entrée des positions LP.
Prérequis
- Playwright MCP - Automatisation de navigateur pour la navigation DeBank
- OpenSea MCP - Données NFT/positions LP (optionnel mais recommandé)
- Node.js 18+ - Pour exécuter les scripts de persistance
- SQLite - Base de données pour les données historiques
Voir references/setup-guide.md pour les détails d'installation.
Utilisation
scrape-portfolio <wallet_address>
scrape-portfolio --all # Extraire plusieurs wallets depuis un fichier de configuration
Sources de Données
- DeBank (Playwright) - Positions DeFi, soldes wallet, taux de santé
- API OpenSea - Holdings NFT (NFT de positions LP Uniswap avec prix d'entrée)
Instructions
Étape 1 : Naviguer vers DeBank
browser_navigate: https://debank.com/profile/{address}
Étape 2 : Attendre le chargement de la page
browser_wait_for: time=5
Étape 3 : Prendre un snapshot
browser_snapshot
Étape 4 : Développer les chaînes cachées
Cherchez « Unfold X chains » dans le snapshot. Si présent :
browser_click: ref=<unfold_button_ref>
browser_wait_for: time=2
browser_snapshot
Étape 5 : Extraire les données du portefeuille
Analysez le snapshot et extrayez :
Profil :
- Valeur totale (ex.
$36,694) - Pourcentage de changement sur 24h
- Âge du compte en jours
Allocation par chaîne :
- Nom de la chaîne, valeur, pourcentage
Jetons Wallet :
- Symbole, chaîne, prix, quantité, valeur en USD
Positions Protocole : Pour chaque protocole (Aave, Compound, Uniswap, etc.) :
- Nom du protocole et chaîne
- Type de position (Prêt, Rendement, Pool de Liquidité)
- Taux de santé (pour les positions de prêt)
- Actifs fournis avec montants et valeurs
- Actifs empruntés avec montants et valeurs
- Soldes LP et ID de pool
- Récompenses réclamables
Étape 6 : Obtenir les données NFT (OpenSea)
Appelez l'outil MCP OpenSea :
get_nft_balances:
address: {wallet_address}
sortBy: RECEIVED_DATE
limit: 100
Cela retourne les NFT de position LP Uniswap avec :
- ID du jeton (ID du pool)
- Date de création (date d'entrée de la position)
- Détails du pool (paire de jetons, niveau de frais)
Étape 7 : Obtenir l'historique des activités NFT
get_activity:
entityType: profile
entityId: {wallet_address}
limit: 100
Cela fournit :
- Prix d'entrée pour les positions LP
- Hashes de transaction
- Mints/transferts historiques
Étape 8 : Structurer les données
Créez un JSON correspondant au schéma dans references/debank-portfolio-schema.json :
{
"metadata": {
"source": "debank.com + opensea",
"scrapeTimestamp": "<timestamp 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"]
}
}
Étape 9 : Sauvegarder les données
Après avoir structuré le JSON :
1. Écrire dans un fichier temporaire :
Sauvegardez le JSON dans un fichier temporaire (ex. /tmp/portfolio-snapshot.json)
2. Sauvegarder le snapshot JSON (sauvegarde) :
mkdir -p data/snapshots/{address}
# Écrire dans data/snapshots/{address}/{YYYY-MM-DD}.json
3. Persister dans la base de données :
cd scripts && npx ts-node debank-snapshot-saver.ts --file /tmp/portfolio-snapshot.json
Définissez les variables d'environnement pour l'emplacement de la base de données :
DB_PATH- Chemin vers la base SQLite (par défaut :../data/portfolio.db)SNAPSHOTS_DIR- Chemin vers les snapshots JSON (par défaut :../data/snapshots)
Enregistrements créés dans la base (chaque extraction AJOUTE de nouvelles lignes, n'écrase pas) :
portfolio_snapshots- Valeur totale + répartition par chaîne (horodaté)position_snapshots- Positions DeFi individuelles (horodaté)reward_history- Récompenses réclamables (horodaté)
Cela construit des données historiques pour l'analyse des tendances. Exemples de requêtes :
-- Valeur du portefeuille au fil du temps
SELECT datetime(timestamp, 'unixepoch') as date, total_value
FROM portfolio_snapshots WHERE address = '0x...' ORDER BY timestamp;
-- Évolution des positions au fil du temps
SELECT datetime(timestamp, 'unixepoch') as date, protocol, net_value
FROM position_snapshots WHERE address = '0x...' ORDER BY timestamp;
Étape 10 : Rapporter les résultats
Fournissez un résumé :
Portefeuille extrait pour 0x5a8a...ed45 :
VALEUR TOTALE : $36,694 (+0,11 % 24h)
ALLOCATION PAR CHAÎNE :
- Arbitrum : $26,011 (71 %)
- Base : $10,650 (29 %)
POSITIONS DEFI :
- Aave V3 (Arbitrum) : $13,643 net (Santé : 2,84)
- Fourni : 18 784 USDC ($18,811)
- Emprunté : 1,0168 WETH ($3,011) + 0,0241 WBTC ($2,156)
- Compound V3 (Base) : $10,635
- Fourni : 10 584 USDC
- Récompenses : 1,5 COMP ($36)
- Uniswap V4 : $6,900
- Pool #103120 : WBTC/USDC
- Récompenses : $50,21
- Uniswap V3 : $5,142
- Pool #4721026 : WBTC/WETH
- Récompenses : $18,92
POSITIONS LP (depuis OpenSea) :
- 11 NFT de position Uniswap
- Historique d'entrée suivi depuis février 2025
RÉCOMPENSES RÉCLAMABLES : $105,27
- COMP : $36,12
- Frais LP : $69,15
Données sauvegardées dans :
- data/snapshots/{address}/{date}.json
- data/portfolio.db
Limitation de Débit
- Attendez 30 secondes entre les extractions de plusieurs wallets
- Si DeBank montre une limitation de débit, attendez 60 secondes et réessayez
Gestion des Erreurs
- La page ne se charge pas : Signalez « DeBank inaccessible », ignorez le wallet
- Aucune donnée trouvée : Signalez « Le wallet peut être vide ou invalide »
- Échec partiel : Sauvegardez ce qui a été collecté, notez les erreurs
Schéma de Base de Données
Voir references/schema.sql pour les définitions complètes des tables :
| Table | Objectif |
|---|---|
portfolio_snapshots | Valeur totale + répartition par chaîne par horodatage |
position_snapshots | Positions DeFi individuelles avec jetons/récompenses |
reward_history | Récompenses réclamables au fil du temps |
apy_history | Suivi APY pour les protocoles |
transactions | Historique complet des transactions |