> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 문제 해결

> Helius 임베디드 지갑 통합 시 가장 일반적인 문제들에 대한 수정 사항 — 스타일링, 로그인, 서명, 송금 및 API 키 액세스.

[`helius-wallet-kit`](https://www.npmjs.com/package/helius-wallet-kit) SDK 통합 시 일반적인 문제와 해결 방법.

## 설정

### 지갑 모달이 스타일이 없거나 깨져 보임

SDK의 스타일시트가 로드되지 않았습니다. 루트 레이아웃에서 한 번 가져오세요:

```tsx app/layout.tsx theme={"system"}
import "helius-wallet-kit/ui/styles.css";
```

### 훅 값이 절대 변경되지 않음 (`loading`에 멈춤)

`useHeliusWallet()`는 `HeliusWalletProvider` 내부에서만 작동하며, 제공자는 **클라이언트** 컴포넌트여야 합니다. 제공자가 파일의 맨 위에 `"use client"`가 있는지 확인하세요 — [설정](/docs/ko/waas/quickstart#설정)을 참조하세요.

### 콘솔에 `[HeliusWalletKit] WaaS bootstrap failed (…)`

제공자가 API 키에서 프로젝트를 확인할 수 없습니다. 다음을 확인하세요:

* `NEXT_PUBLIC_HELIUS_API_KEY`가 설정되고 유효합니다.
* 프로젝트가 임베디드 지갑이 활성화된 **유료 플랜**에 있습니다.
* 키에 도메인 제한을 적용한 경우, 현재 출처가 허용 목록에 있는지 확인하세요 — [키 보안 강화](/docs/ko/waas/securing-your-key)를 참조하세요.

## 로그인

### 사용자가 지갑 대신 "업그레이드" 화면에 도착함

임베디드 지갑은 **유료** Helius 플랜이 필요합니다. 해결된 플랜이 무료일 경우, 제공자가 업그레이드 프롬프트를 렌더링합니다 (백엔드도 요청을 서버 측에서 거부합니다). [대시보드](https://dashboard.helius.dev)에서 프로젝트를 업그레이드하세요.

### 잘못된 로그인 방법이 나타남 (예: Google 표시, 외부 지갑 없음)

로그인 방법은 [대시보드](https://dashboard.helius.dev)의 **WaaS → 구성** 아래 프로젝트 구성에서 옵니다. 프로젝트에 설정된 방법이 없으면, 모달은 조직 전체의 기본값을 사용합니다. 대시보드에서 원하는 방법을 설정하거나 환경당 재정의를 위해 제공자에 `authMethods`를 전달하세요 — [로그인 방법 구성](/docs/ko/waas/configuration#로그인-방법-구성)을 참조하세요.

### 패스키 로그인 실패 또는 패스키가 등록되지 않았다는 메시지 표시

패스키는 생성된 **도메인 및 인증기**에 바인딩됩니다 (WebAuthn 제약, Helius 제약 아님). 다른 사이트나 장치에서 등록된 패스키 또는 보안 키는 앱을 인증하지 않습니다. 테스트하는 도메인에서 패스키를 생성하세요 — `localhost`에서 만든 패스키는 `localhost`에 바인딩되며 배포된 도메인으로 전환되지 않습니다.

## 서명 및 송금

### 서명 시 `No wallet available`

내장된 지갑이 프로비저닝을 완료하기 전에 서명 메서드를 호출했습니다. `status === "authenticated"` **및** null이 아닌 `address` 둘 다에서 서명을 게이트하세요:

```tsx theme={"system"}
const { status, address, signMessage } = useHeliusWallet();
const ready = status === "authenticated" && address;
```

### `… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler`

직접 모드(보안 RPC)에서 실행 중이며, 이 호출 — **전송** 또는 **우선수수료** 요청 — 은 서버 라우트 핸들러가 필요합니다. `/api/helius/[...path]`에 마운트하고 `HELIUS_API_KEY`를 설정하세요:

```ts app/api/helius/[...path]/route.ts theme={"system"}
import { createHeliusRouteHandler } from "helius-wallet-kit/next";

export const { GET, POST } = createHeliusRouteHandler();
```

[서버 라우트 핸들러](/docs/ko/waas/quickstart#설정)를 참조하세요.

### `getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode`

거래 내역은 라우트 핸들러를 통해서만 사용할 수 있습니다. 위에 표시된 대로 추가하세요.

### `getPriorityFeeEstimate is not available`

Devnet은 우선수수료 추정을 지원하지 않습니다 — 메인넷 기능입니다. Devnet에서는 조회를 건너뛰세요; 우선 수수료 없이도 전송은 작동합니다.

```tsx theme={"system"}
if (cluster === "mainnet-beta") {
  const fees = await getPriorityFeeLevels([address]);
}
```

### 거래가 메인넷에 도달하지 않음

라우트 핸들러가 없으면 전송은 표준 RPC를 사용하여 [Helius Sender](/docs/ko/sending-transactions/sender)를 포기하고 Sender의 최적화된 착륙을 포기할 수 있습니다. 최상의 메인넷 착륙을 위해 라우트 핸들러를 마운트하세요. 만약 전송이 완전히 실패하면 blockhash를 갱신하세요 — 오래된 `recentBlockhash`는 빨리 만료됩니다.

## 키 및 액세스

### 키 잠금 후 RPC 또는 API 호출이 거부됨 (401 / 403)

도메인 제한 키에 호출 중인 출처가 포함되어 있지 않습니다. **RPC 액세스 제어** 아래에 사용하는 모든 출처 — 프로덕션, 스테이징, 미리보기 배포 및 개발용 `localhost` — 를 추가하세요. [키 보안 강화](/docs/ko/waas/securing-your-key)를 참조하세요.

## 여전히 막혔나요?

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.com/invite/6GXdee3gBj">
    커뮤니티 및 Helius 팀에 문의하세요.
  </Card>

  <Card title="Support" icon="headset" href="/docs/ko/support">
    Helius 지원에 문의하세요.
  </Card>
</CardGroup>