DeBank Portfolio Scraper
Extraia snapshots completos de portfólio do DeBank usando automação de navegador, com integração opcional com OpenSea para preços de entrada em posições LP.
Pré-requisitos
- Playwright MCP - Automação de navegador para navegação no DeBank
- OpenSea MCP - Dados de NFTs/posições LP (opcional, mas recomendado)
- Node.js 18+ - Para executar scripts de persistência
- SQLite - Banco de dados para dados históricos
Consulte references/setup-guide.md para detalhes de instalação.
Uso
scrape-portfolio <wallet_address>
scrape-portfolio --all # Extrai múltiplas carteiras de um arquivo de configuração
Fontes de Dados
- DeBank (Playwright) - Posições DeFi, saldos de carteira, taxas de saúde
- OpenSea API - Holdings de NFTs (NFTs de posição LP Uniswap com preços de entrada)
Instruções
Passo 1: Navegar até o DeBank
browser_navigate: https://debank.com/profile/{address}
Passo 2: Aguardar o carregamento da página
browser_wait_for: time=5
Passo 3: Tirar snapshot
browser_snapshot
Passo 4: Expandir chains ocultas
Procure por "Unfold X chains" no snapshot. Se presente:
browser_click: ref=<unfold_button_ref>
browser_wait_for: time=2
browser_snapshot
Passo 5: Extrair dados do portfólio
Analise o snapshot e extraia:
Perfil:
- Valor total (ex.:
$36.694) - Porcentagem de variação em 24h
- Idade da conta em dias
Alocação por Chain:
- Nome da chain, valor, porcentagem
Tokens da Carteira:
- Símbolo, chain, preço, quantidade, valor em USD
Posições em Protocolos: Para cada protocolo (Aave, Compound, Uniswap, etc.):
- Nome do protocolo e chain
- Tipo de posição (Empréstimo, Yield, Pool de Liquidez)
- Taxa de saúde (para posições de empréstimo)
- Ativos fornecidos com quantidades e valores
- Ativos emprestados com quantidades e valores
- Saldos LP e IDs de pool
- Recompensas disponíveis para saque
Passo 6: Obter dados de NFTs (OpenSea)
Chame a ferramenta MCP da OpenSea:
get_nft_balances:
address: {wallet_address}
sortBy: RECEIVED_DATE
limit: 100
Isso retorna NFTs de posição LP Uniswap com:
- Token ID (ID do pool)
- Data de criação (data de entrada na posição)
- Detalhes do pool (par de tokens, nível de taxa)
Passo 7: Obter histórico de atividade de NFTs
get_activity:
entityType: profile
entityId: {wallet_address}
limit: 100
Isso fornece:
- Preços de entrada para posições LP
- Hashes de transação
- Histórico de mints/transferências
Passo 8: Estruturar os dados
Crie um JSON seguindo o schema em 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"]
}
}
Passo 9: Salvar dados
Após estruturar o JSON:
1. Escrever em arquivo temporário:
Salve o JSON em um arquivo temporário (ex.: /tmp/portfolio-snapshot.json)
2. Salvar snapshot JSON (backup):
mkdir -p data/snapshots/{address}
# Escrever em data/snapshots/{address}/{YYYY-MM-DD}.json
3. Persistir no banco de dados:
cd scripts && npx ts-node debank-snapshot-saver.ts --file /tmp/portfolio-snapshot.json
Defina variáveis de ambiente para a localização do banco de dados:
DB_PATH- Caminho para o banco SQLite (padrão:../data/portfolio.db)SNAPSHOTS_DIR- Caminho para snapshots JSON (padrão:../data/snapshots)
Registros criados no banco (cada extração ADICIONA novas linhas, não sobrescreve):
portfolio_snapshots- Valor total + detalhamento por chain (com timestamp)position_snapshots- Posições DeFi individuais (com timestamp)reward_history- Recompensas disponíveis (com timestamp)
Isso constrói dados históricos para análise de tendências. Exemplos de consultas:
-- Valor do portfólio ao longo do tempo
SELECT datetime(timestamp, 'unixepoch') as date, total_value
FROM portfolio_snapshots WHERE address = '0x...' ORDER BY timestamp;
-- Mudanças nas posições ao longo do tempo
SELECT datetime(timestamp, 'unixepoch') as date, protocol, net_value
FROM position_snapshots WHERE address = '0x...' ORDER BY timestamp;
Passo 10: Relatar resultados
Forneça um resumo:
Portfólio extraído para 0x5a8a...ed45:
VALOR TOTAL: $36.694 (+0,11% 24h)
ALOCAÇÃO POR CHAIN:
- Arbitrum: $26.011 (71%)
- Base: $10.650 (29%)
POSIÇÕES DEFI:
- Aave V3 (Arbitrum): $13.643 líquido (Saúde: 2,84)
- Fornecido: 18.784 USDC ($18.811)
- Emprestado: 1,0168 WETH ($3.011) + 0,0241 WBTC ($2.156)
- Compound V3 (Base): $10.635
- Fornecido: 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
POSIÇÕES LP (da OpenSea):
- 11 NFTs de posição Uniswap
- Histórico de entrada rastreado desde fev de 2025
RECOMPENSAS DISPONÍVEIS: $105,27
- COMP: $36,12
- Taxas LP: $69,15
Dados salvos em:
- data/snapshots/{address}/{date}.json
- data/portfolio.db
Limitação de Taxa
- Aguarde 30 segundos entre extrações de múltiplas carteiras
- Se o DeBank mostrar limitação de taxa, aguarde 60 segundos e repita
Tratamento de Erros
- Página não carrega: Relate "DeBank inacessível", pule a carteira
- Nenhum dado encontrado: Relate "Carteira pode estar vazia ou inválida"
- Falha parcial: Salve o que foi coletado, anote os erros
Schema do Banco de Dados
Consulte references/schema.sql para definições completas das tabelas:
| Tabela | Propósito |
|---|---|
portfolio_snapshots | Valor total + detalhamento por chain por timestamp |
position_snapshots | Posições DeFi individuais com tokens/recompensas |
reward_history | Recompensas disponíveis ao longo do tempo |
apy_history | Rastreamento de APY para protocolos |
transactions | Histórico completo de transações |