helius-wallet-kit SDK 통합 시 일반적인 문제와 해결 방법.
설정
지갑 모달이 스타일이 없거나 깨져 보임
SDK의 스타일시트가 로드되지 않았습니다. 루트 레이아웃에서 한 번 가져오세요:app/layout.tsx
훅 값이 절대 변경되지 않음 (loading에 멈춤)
useHeliusWallet()는 HeliusWalletProvider 내부에서만 작동하며, 제공자는 클라이언트 컴포넌트여야 합니다. 제공자가 파일의 맨 위에 "use client"가 있는지 확인하세요 — 설정을 참조하세요.
콘솔에 [HeliusWalletKit] WaaS bootstrap failed (…)
제공자가 API 키에서 프로젝트를 확인할 수 없습니다. 다음을 확인하세요:
NEXT_PUBLIC_HELIUS_API_KEY가 설정되고 유효합니다.- 프로젝트가 임베디드 지갑이 활성화된 유료 플랜에 있습니다.
- 키에 도메인 제한을 적용한 경우, 현재 출처가 허용 목록에 있는지 확인하세요 — 키 보안 강화를 참조하세요.
로그인
사용자가 지갑 대신 “업그레이드” 화면에 도착함
임베디드 지갑은 유료 Helius 플랜이 필요합니다. 해결된 플랜이 무료일 경우, 제공자가 업그레이드 프롬프트를 렌더링합니다 (백엔드도 요청을 서버 측에서 거부합니다). 대시보드에서 프로젝트를 업그레이드하세요.잘못된 로그인 방법이 나타남 (예: Google 표시, 외부 지갑 없음)
로그인 방법은 대시보드의 WaaS → 구성 아래 프로젝트 구성에서 옵니다. 프로젝트에 설정된 방법이 없으면, 모달은 조직 전체의 기본값을 사용합니다. 대시보드에서 원하는 방법을 설정하거나 환경당 재정의를 위해 제공자에authMethods를 전달하세요 — 로그인 방법 구성을 참조하세요.
패스키 로그인 실패 또는 패스키가 등록되지 않았다는 메시지 표시
패스키는 생성된 도메인 및 인증기에 바인딩됩니다 (WebAuthn 제약, Helius 제약 아님). 다른 사이트나 장치에서 등록된 패스키 또는 보안 키는 앱을 인증하지 않습니다. 테스트하는 도메인에서 패스키를 생성하세요 —localhost에서 만든 패스키는 localhost에 바인딩되며 배포된 도메인으로 전환되지 않습니다.
서명 및 송금
서명 시 No wallet available
내장된 지갑이 프로비저닝을 완료하기 전에 서명 메서드를 호출했습니다. status === "authenticated" 및 null이 아닌 address 둘 다에서 서명을 게이트하세요:
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
직접 모드(보안 RPC)에서 실행 중이며, 이 호출 — 전송 또는 우선수수료 요청 — 은 서버 라우트 핸들러가 필요합니다. /api/helius/[...path]에 마운트하고 HELIUS_API_KEY를 설정하세요:
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
거래 내역은 라우트 핸들러를 통해서만 사용할 수 있습니다. 위에 표시된 대로 추가하세요.
getPriorityFeeEstimate is not available
Devnet은 우선수수료 추정을 지원하지 않습니다 — 메인넷 기능입니다. Devnet에서는 조회를 건너뛰세요; 우선 수수료 없이도 전송은 작동합니다.
거래가 메인넷에 도달하지 않음
라우트 핸들러가 없으면 전송은 표준 RPC를 사용하여 Helius Sender를 포기하고 Sender의 최적화된 착륙을 포기할 수 있습니다. 최상의 메인넷 착륙을 위해 라우트 핸들러를 마운트하세요. 만약 전송이 완전히 실패하면 blockhash를 갱신하세요 — 오래된recentBlockhash는 빨리 만료됩니다.
키 및 액세스
키 잠금 후 RPC 또는 API 호출이 거부됨 (401 / 403)
도메인 제한 키에 호출 중인 출처가 포함되어 있지 않습니다. RPC 액세스 제어 아래에 사용하는 모든 출처 — 프로덕션, 스테이징, 미리보기 배포 및 개발용localhost — 를 추가하세요. 키 보안 강화를 참조하세요.
여전히 막혔나요?
Discord
커뮤니티 및 Helius 팀에 문의하세요.
Support
Helius 지원에 문의하세요.