Privy API 사용법: 웹3를 위한 내장 지갑 및 소셜 인증

Web3 앱 사용자 온보딩은 여전히 진입 장벽이 높습니다. 시드 문구, 브라우저 확장 프로그램, 가스 요금 등으로 인해 간단한 회원가입이 복잡해집니다. Privy API는 이메일, SMS, Google, Apple 또는 MetaMask와 같은 익숙한 로그인 방식을 지원하여 임베디드 지갑을 자동으로 제공합니다. 브라우저 확장 설치 없이 암호화폐 네이티브 사용자를 확보할 수 있습니다.

지금 Apidog을 사용해 보세요

Privy는 Blackbird, Friend.tech, OpenSea 등 다양한 앱에서 사용되며 Ethereum, Solana, 모든 EVM 체인을 지원합니다. 이 가이드에서는 Privy 앱 생성, React SDK 연동, 서버 토큰 검증, 임베디드 지갑 트랜잭션 서명, 웹훅 처리까지 전체 개발 과정의 실전 예시를 제공합니다. MetaMask 개발자 툴킷과의 비교가 필요하다면 해당 링크를 참고하세요.

💡Privy SDK의 내부 HTTPS 요청을 빠르게 디버깅하려면 Apidog을 사용하세요. 로컬 프록시 연결, 페이로드 캡처, 로그 추적 없이 인증 문제를 신속하게 파악할 수 있습니다.

요약

• Privy는 임베디드 지갑과 이메일, SMS, 소셜, 외부 지갑 로그인을 하나의 SDK로 제공합니다.
• React SDK는 인증/서명 전 과정을 위한 PrivyProvider, useLogin, useWallets, usePrivy 훅을 제공합니다.
• @privy-io/server-auth 패키지로 백엔드에서 액세스 토큰을 검증해 사용자 ID 신뢰성을 확보할 수 있습니다.
• 지갑은 Ethereum, Solana 등 다양한 체인을 지원하며, 주요 작업에 대한 내보내기 및 승인 서명을 제공합니다.
• 웹훅으로 사용자 생성, 로그인, 지갑 이벤트에 대한 실시간 동기화를 구현할 수 있습니다.
• 정책 엔진으로 MFA, 허용 목록, 트랜잭션 규칙을 앱 코드 수정 없이 적용할 수 있습니다.

Privy API란 무엇인가요?

Privy는 인증 및 지갑 인프라 플랫폼입니다. 앱에 다음을 제공합니다:

1. 로그인 UI
2. 사용자별로 프로비저닝되는 임베디드 지갑
3. 서버 검증용 REST 엔드포인트

임베디드 지갑은 브라우저 보안 인클레이브에 존재하며, Privy나 백엔드가 개인 키를 볼 수 없습니다. 사용자는 원하면 지갑 키를 내보낼 수 있습니다.

가격 모델은 월별 활성 지갑 단위로 과금되며, 무료 티어는 월 1,000명까지 지원합니다. Pro(월 $149~) 및 Enterprise(맞춤형 SLA) 옵션도 있습니다.

인증 및 설정

1. privy.io에서 대시보드에 로그인하여 새 앱을 만듭니다.
2. 아래 두 값을 확보합니다:
   • 앱 ID (클라이언트용, 예: clxxxxx...)
   • 앱 시크릿 (서버용)
3. 허용할 로그인 방식(이메일, SMS, Google 등), 기본 체인, 허용 도메인 등을 설정합니다.

React SDK 설치 및 적용

npm install @privy-io/react-auth

앱을 PrivyProvider로 감쌉니다:

import { PrivyProvider } from '@privy-io/react-auth';

export default function App({ Component, pageProps }) {
  return (
    <PrivyProvider
      appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
      config={{
        loginMethods: ['email', 'wallet', 'google'],
        embeddedWallets: { createOnLogin: 'users-without-wallets' },
        defaultChain: { id: 8453 }, // Base
        supportedChains: [{ id: 1 }, { id: 8453 }, { id: 137 }],
      }}
    >
      <Component {...pageProps} />
    </PrivyProvider>
  );
}

• createOnLogin은 지갑 없는 신규 사용자에게 임베디드 지갑을 자동 생성합니다.
• 지원 체인은 설정에서 조정할 수 있습니다.
• Solana는 별도 solanaClusters 옵션으로 설정합니다.

핵심 엔드포인트 및 SDK 호출

Privy의 React SDK가 대부분의 흐름을 처리하지만, 기본 REST API 및 서버 SDK 활용법도 알아두면 좋습니다.

로그인 트리거 및 사용자 정보 읽기

import { usePrivy, useWallets } from '@privy-io/react-auth';

function LoginButton() {
  const { ready, authenticated, login, logout, user } = usePrivy();
  const { wallets } = useWallets();

  if (!ready) return <p>로딩 중...</p>;
  if (!authenticated) return <button onClick={login}>로그인</button>;

  const embedded = wallets.find((w) => w.walletClientType === 'privy');

  return (
    <div>
      <p>안녕하세요 {user.email?.address ?? user.id}</p>
      <p>지갑: {embedded?.address}</p>
      <button onClick={logout}>로그아웃</button>
    </div>
  );
}

• useWallets로 연결된 모든 지갑을 가져오고, walletClientType이 privy이면 임베디드 지갑입니다.
• Privy 임베디드 지갑 설명 참고.

트랜잭션 서명하기

const { wallets } = useWallets();
const wallet = wallets.find((w) => w.walletClientType === 'privy');

async function sendTx() {
  const provider = await wallet.getEthereumProvider();
  const hash = await provider.request({
    method: 'eth_sendTransaction',
    params: [{
      to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2',
      value: '0x38d7ea4c68000', // 0.001 ETH
    }],
  });
  console.log('tx hash', hash);
}

• Solana는 getEthereumProvider 대신 getSolanaProvider 사용, 트랜잭션 직렬화 필요.
• Alchemy 연동 패턴과도 호환됩니다.

서버에서 토큰 검증

서버 SDK 설치:

npm install @privy-io/server-auth

프론트엔드에서 전달된 JWT를 검증:

import { PrivyClient } from '@privy-io/server-auth';

const privy = new PrivyClient(
  process.env.PRIVY_APP_ID,
  process.env.PRIVY_APP_SECRET
);

export async function GET(req) {
  const auth = req.headers.get('authorization')?.replace('Bearer ', '');
  try {
    const claims = await privy.verifyAuthToken(auth);
    // claims.userId는 Privy 사용자 DID입니다
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

• 전체 사용자 객체는 privy.getUser(userId)로 조회할 수 있습니다.

임베디드 지갑 내보내기

Privy는 사용자가 개인 키를 내보낼 수 있도록 지원합니다:

import { useExportWallet } from '@privy-io/react-auth';

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>개인 키 내보내기</button>;

• 안전한 아이프레임 모달을 통해 키 내보내기 지원, 앱은 키 자료에 접근하지 않습니다.

승인 서명 및 정책 엔진

• 대규모 전송, 새 기기 로그인 등 민감 작업에는 Privy 승인 서명 사용 가능.
• 대시보드에서 MFA, 허용 목록, 서버 서명 등 정책을 설정합니다.
• 자세한 내용은 Privy 승인 키 가이드 참고.

웹훅 처리

Privy는 주요 이벤트(사용자 생성, 로그인, 지갑 변경 등) 발생 시 지정된 엔드포인트로 JSON 페이로드를 전송합니다:

curl -X POST https://yourapp.com/webhooks/privy \
  -H "Content-Type: application/json" \
  -H "svix-id: msg_..." \
  -H "svix-signature: v1,..." \
  -d '{
    "type": "user.created",
    "user": { "id": "did:privy:...", "email": { "address": "[e-mail]" } }
  }'

• 데이터베이스 반영 전, svix-signature 헤더로 웹훅 시크릿 검증 필수.

일반적인 오류 및 속도 제한

자주 발생하는 이슈와 해결 방법:

• invalid_token: JWT 만료. 요청 직전 usePrivy의 getAccessToken() 호출.
• 403 origin_not_allowed: 배포 URL이 Privy 허용 목록에 없음. 도메인 추가 필수.
• wallet_not_ready: ready가 true가 되기 전 지갑 접근 시도. 모든 지갑 관련 로직은 ready 체크 후 실행.
• 속도 제한: 무료 티어 기준 초당 100요청. 대량 호출 시 getUser 일괄 처리/캐싱 권장.

Apidog으로 실패한 웹훅을 로컬에서 반복 테스트할 수 있습니다. 페이로드 복사, 헤더 수정, 핸들러 안정화에 유용합니다.

Privy 가격

• 무료: 월 1,000 지갑, 핵심 로그인, EVM+Solana 임베디드 지갑 지원.
• Pro: 월 $149, 더 높은 MAW, 전체 웹훅, 스테이징 앱.
• Enterprise: 맞춤 SLA, 전담 지원, 온콜 엔지니어링, 정책 엔진 확장.

최신 가격은 privy.io/pricing에서 확인하세요.

Apidog로 Privy API 테스트하기

Privy의 클라이언트 SDK는 HTTPS 호출을 추상화하지만, 백엔드 토큰 검증, 사용자 조회, 웹훅 등은 REST API로 직접 호출 가능합니다.

Apidog에서 Privy 컬렉션을 만들고, 앱 ID와 시크릿을 환경 변수로 입력한 뒤, GET /api/v1/users/{userId} 또는 POST /api/v1/users/{userId}/wallets 엔드포인트를 바로 호출하세요.

• 대시보드 웹훅 페이로드를 기록/저장해 로컬 터널로 재실행 가능
• 유효한 JWT/만료된 JWT에 따른 자동화 테스트를 구축해 배포 시마다 실행할 수 있습니다
• Apidog 다운로드 후 cURL 반복작업 없이 테스트하세요
• Postman에서 이전할 경우 병렬 워크플로 가이드 참고

FAQ

Privy는 Web3Auth 또는 Magic과 어떻게 다른가요?

세 가지 모두 임베디드 지갑을 지원하지만, Privy는 혼합 인증(이메일+지갑+소셜)과 정책 엔진에 집중합니다. Web3Auth는 MPC 키 분할에, Magic은 매직 링크 기반 인증에 특화되어 있습니다. 온보딩 UI와 세밀한 지갑 제어가 필요하다면 Privy 선택을 권장합니다.

Privy는 Solana를 지원하나요?

네. 임베디드 지갑은 Solana 메인넷/Devnet에서 동작하며, React SDK는 트랜잭션 서명용 getSolanaProvider()를 제공합니다. EVM, Solana 모두 한 앱에서 동시 지원 가능합니다.

사용자가 자신의 지갑을 가져올 수 있나요?

네. MetaMask, Coinbase Wallet, WalletConnect, Phantom 등 다양한 외부 지갑이 즉시 연동됩니다. Privy는 외부 지갑을 연결된 계정으로 취급하여 한 DID에 임베디드/외부 키를 모두 연결할 수 있습니다.

Privy가 다운되면 어떻게 되나요?

키는 사용자의 브라우저 인클레이브에 저장되어 있으므로, 지갑 내보내기 기능 활성화 시 사용자는 언제든 개인 키에 접근할 수 있습니다. 프로덕션 앱에서는 지갑 내보내기를 반드시 지원하고 대체 경로를 안내하세요. 공급업체 리스크 관리에 대해서는 ID 공급업체 비교 가이드 참고.

Privy는 MFA를 지원하나요?

네. TOTP, SMS, 패스키를 지원하며, 정책 엔진으로 특정 작업에 MFA를 요구할 수 있습니다.

앱 코드가 서버/클라이언트 어디서 실행되나요?

클라이언트 SDK는 로그인 UI 및 서명을, 서버 SDK는 토큰 검증 및 사용자 데이터 조회를 담당합니다. 앱 시크릿은 브라우저로 전달하지 마세요.