Alice Connect Network

지원 방식

방식	언제	구현
Injected (EIP-1193)	지갑 앱의 dApp 브라우저에서 열었을 때(`window.ethereum` 존재)	wagmi `injected()` 커넥터. TokenPocket, MetaMask Mobile, Trust, Bitget, imToken 등 모두 해당
WalletConnect v2	일반 모바일 브라우저(Safari/Chrome)에서 열었을 때	wagmi `walletConnect({ projectId })`. `NEXT_PUBLIC_WC_PROJECT_ID` 설정 시에만 활성
딥링크	지갑이 감지되지 않을 때 앱으로 넘기기	`ConnectWallet.tsx`의 `walletDeepLinks()`

TokenPocket

TokenPocket 앱 → Discover(발견) 탭 → 상단 주소창에 dApp URL 입력.
페이지가 열리면 TokenPocket이 window.ethereum을 주입하며 UA에 TokenPocket이 포함된다(모바일 게이트 통과).
지갑 연결 버튼 → TokenPocket 승인 팝업 → 계정 주소 반환.
네트워크가 BSC가 아니면 네트워크 전환 버튼이 표시되고 wallet_switchEthereumChain을 요청한다.

딥링크(일반 브라우저에서 TokenPocket dApp 브라우저로 열기, 공식 문서):

tpdapp://open?params=<URL-encoded JSON>
params = {"url":"https://<dapp-host>/dapp","chain":"BSC","source":"ALICE"}

tpoutside://pull.activity?param=...는 로그인·전송 등 액션 호출용 스킴이라 URL 열기에 쓰면 TokenPocket이 "파라미터 오류"를 표시한다(2026-09-04 실제 발생, 수정됨). 딥링크가 동작하지 않는 환경을 위해 화면에 "주소 복사" 버튼과 수동 열기 안내를 함께 둔다.

MetaMask Mobile

dApp 브라우저: 앱 내 브라우저에서 URL 입력.
딥링크: https://metamask.app.link/dapp/<host>/<path>

전송 시퀀스

사용자        dApp(wagmi)                 지갑 앱                   BSC                 FastAPI
  │ 주소/수량 입력 │                           │                        │                    │
  │──────────────►│ parseUnits, isAddress     │                        │                    │
  │               │ writeContract(transfer) ─►│ 서명 UI 표시            │                    │
  │ 승인 ─────────────────────────────────────►│ 서명 + eth_sendRawTx ──►│                    │
  │               │◄──── tx hash ─────────────│                        │                    │
  │               │ waitForTransactionReceipt ─────────────────────────►│                    │
  │               │◄──── receipt(status=1) ────────────────────────────│                    │
  │               │ POST /api/transfers {txHash} ───────────────────────────────────────────►│
  │               │                           │                        │◄── getReceipt ─────│
  │               │◄──── 201 저장된 Transfer ──────────────────────────────────────────────│
  │ "전송 완료" ◄──│                           │                        │                    │

클라이언트 검증(전송 전)

받는 주소: viem.isAddress (체크섬 포함), 자기 자신 금지
수량: parseUnits(amount, decimals) 성공 && > 0
네트워크: chainId === 56이 아니면 전송 버튼 비활성
지갑이 잔액 부족을 시뮬레이션 단계에서 거부하면 writeError 메시지를 첫 줄만 표시

자주 겪는 문제