DeBank 포트폴리오 스크래퍼
브라우저 자동화를 사용하여 DeBank에서 종합적인 포트폴리오 스냅샷을 스크래핑하고, LP 포지션 진입 가격을 위한 OpenSea 통합(선택 사항)을 제공합니다.
사전 요구 사항
- 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 보유 내역(진입 가격이 포함된 유니스왑 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
다음을 포함한 유니스왑 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 (+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개의 유니스왑 포지션 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 | 전체 트랜잭션 내역 |