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

Web3 앱에 사용자를 온보딩하는 것은 여전히 대부분의 사람들을 첫 단계에서부터 멀어지게 합니다. 시드 문구, 브라우저 확장 프로그램, 가스 요금은 두 번의 탭으로 끝날 가입을 10분간의 씨름으로 만듭니다. Privy API는 이 간극을 메우기 위해 이메일, SMS, Google, Apple 또는 MetaMask와 같은 기존 지갑과 같은 익숙한 로그인 뒤에 모든 신규 사용자에게 임베디드 지갑을 제공합니다. 누구에게도 브라우저 확장 프로그램을 설치하라고 요청하지 않고도 암호화폐-네이티브 사용자를 얻을 수 있습니다.

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 및 기타 EVM 체인을 지원하며, 주요 작업에 대한 선택적 내보내기 기능과 승인 서명을 제공합니다.
웹훅은 사용자 생성, 로그인 및 지갑 이벤트 시 발생하므로 폴링 없이 데이터베이스를 동기화할 수 있습니다.
Privy 정책 엔진은 앱 코드를 포크하지 않고도 MFA, 허용 목록 및 트랜잭션 규칙을 추가합니다.

Privy API란 무엇인가요?

Privy는 인증 및 지갑 인프라 플랫폼입니다. 앱에 세 가지 기능을 제공합니다: 로그인 UI, 사용자별로 프로비저닝되는 임베디드 지갑, 서버 측 확인을 위한 REST 엔드포인트 세트. 임베디드 지갑은 보안 인클레이브에 존재하므로 Privy는 개인 키를 볼 수 없으며 백엔드도 볼 수 없습니다. 사용자는 나중에 자체 보관 지갑으로 이동하고 싶을 경우 키를 내보낼 수 있습니다. 이러한 선택 가능성은 이 제안의 큰 부분입니다.

이 플랫폼은 월별 활성 지갑당 요금을 부과합니다. 즉, 무료로 프로토타입을 출시하고 트래픽이 증가함에 따라 가격을 조정할 수 있습니다. 무료 티어는 월 1,000명의 활성 사용자를 지원하며, Pro는 월 149달러부터 시작하고 Enterprise는 맞춤형 SLA를 처리합니다.

인증 및 설정

privy.io에서 시작하여 대시보드에서 새 앱을 만드세요. 다음 두 가지 중요한 값을 얻게 됩니다:

클라이언트 SDK용 앱 ID (clxxxxx...)
서버 SDK용 앱 시크릿

허용된 로그인 방법(이메일, SMS, Google, Apple, Farcaster, 지갑)을 설정하고, 기본 체인을 선택한 다음, 도메인을 허용된 원본 목록에 추가합니다. 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를 거의 사용하지 않습니다. 그러나 서버 SDK 및 웹훅 페이로드는 동일한 토큰 형식을 사용하므로 상황이 잘못될 때 기본 API를 아는 것이 도움이 됩니다.

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

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와 같은 제공업체의 데이터 액세스 패턴을 반영하고 싶다면 Privy는 이들과 잘 작동합니다. Privy는 키를 처리하고 Alchemy는 RPC를 처리합니다.

서버에서 토큰 확인

서버 SDK를 설치합니다:

npm install @privy-io/server-auth

프런트엔드에서 인증된 모든 요청은 Privy 액세스 토큰(JWT)을 전달합니다. 사용자 ID를 신뢰하기 전에 서버에서 이를 확인합니다:

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는 사용자가 언제든지 개인 키를 내보낼 수 있도록 합니다. UX는 단일 훅입니다:

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

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

Privy는 보안 아이프레임 모달을 표시하며, 앱은 키 자료에 전혀 접근하지 않습니다.

승인 서명 및 정책 엔진

민감한 작업(대규모 전송, 새 기기 로그인)의 경우 Privy는 승인 서명을 지원합니다. 대시보드에서 정책을 정의하고 앱에 연결하면 Privy는 트랜잭션이 완료되기 전에 MFA, 허용 목록 또는 서버 서명 승인을 적용합니다. 자세한 내용은 Privy 승인 키 가이드에 나와 있습니다. MFA 옵션(TOTP, SMS, 패스키)과 결합하여, 일반 지갑이 남겨두는 대부분의 계정 탈취 위험을 차단합니다.

웹훅

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": "a@b.com" } }
  }'

데이터베이스에 쓰기 전에 대시보드에서 웹훅 시크릿으로 svix-signature 헤더를 확인하십시오.

일반적인 오류 및 속도 제한

몇 가지 오류가 계속해서 나타납니다:

invalid_token: 프런트엔드 JWT가 만료되었습니다. 가져오기 직전에 usePrivy에서 getAccessToken()을 호출하십시오. 토큰은 1시간 동안 유효합니다.
403 origin_not_allowed: 앱 배포 URL이 Privy 대시보드 허용 목록에 없습니다. https://yourapp.com과 모든 미리보기 도메인을 추가하십시오.
wallet_not_ready: ready가 true로 전환되기 전에 useWallets를 읽었습니다. 모든 지갑 호출을 ready 플래그에 따라 게이트하십시오.
속도 제한: REST 엔드포인트는 무료 티어에서 앱당 초당 100개의 요청을 허용합니다. 대부분의 앱은 이 제한에 도달하지 않지만, 도달하는 경우 getUser 호출을 일괄 처리하거나 사용자 ID별로 캐시하십시오.

Apidog를 사용하여 실패한 웹훅을 로컬에서 재실행하세요. 원시 페이로드를 요청에 붙여넣고, 서명 헤더를 편집한 다음, 핸들러가 통과할 때까지 개발 서버에 반복적으로 요청을 보냅니다.

Privy 가격

무료: 최대 1,000개의 월별 활성 지갑, 핵심 로그인 방법, EVM + Solana 임베디드 지갑.
Pro: 월 149달러, 더 높은 MAW 제한, 전체 웹훅 스위트, 스테이징 앱.
Enterprise: 맞춤형 SLA, 전담 지원, 온콜 엔지니어링, 맞춤형 정책 엔진 규칙.

제품이 성장함에 따라 티어가 변경되므로 현재 수치는 privy.io/pricing에서 확인하세요.

Apidog로 Privy API 테스트하기

Privy의 클라이언트 SDK는 HTTPS 호출을 숨기지만, 백엔드가 처리하는 모든 토큰 확인, 사용자 조회 및 웹훅은 일반 REST 요청입니다. 이것이 Apidog가 제 역할을 하는 지점입니다. Apidog에서 Privy 컬렉션을 만들고, 앱 ID와 시크릿을 환경 변수로 입력한 다음, 도구를 벗어나지 않고 GET /api/v1/users/{userId} 또는 POST /api/v1/users/{userId}/wallets와 같은 엔드포인트를 호출하세요.

대시보드에서 웹훅 페이로드를 기록하고, Apidog 요청으로 저장한 다음, 로컬 터널에 대해 재실행할 수도 있습니다. 유효한 JWT가 사용자 객체를 반환하고 만료된 JWT가 401을 반환하는지 확인하는 자동화된 테스트를 설정하고, 모든 배포 시 실행하세요. Apidog를 무료로 다운로드하고 cURL 곡예를 건너뛰세요. Postman에서 이미 넘어오셨다면, 병렬 워크플로 가이드가 전체 마이그레이션을 다룹니다.

버튼

FAQ

Privy는 Web3Auth 또는 Magic과 어떻게 다른가요?세 가지 모두 임베디드 지갑을 제공하지만, Privy는 혼합 인증(이메일 + 지갑 + 소셜)과 대규모 앱에 필요한 정책 엔진에 더 중점을 둡니다. Web3Auth는 MPC 키 분할에 집중하고, Magic은 더 광범위한 매직 링크 제품을 제공합니다. 깨끗한 온보딩 UI와 지갑이 할 수 있는 작업에 대한 세밀한 제어가 모두 필요할 때 Privy를 선택하세요.

Privy는 Solana를 지원하나요?네. 임베디드 지갑은 Solana 메인넷 및 개발자넷에서 작동하며, React SDK는 트랜잭션 서명 및 전송을 위한 getSolanaProvider()를 노출합니다. 동일한 앱에서 EVM과 Solana를 모두 구성할 수 있습니다.

사용자가 자신의 지갑을 가져올 수 있나요?네. MetaMask, Coinbase Wallet, WalletConnect, Phantom 등 수십 개의 지갑이 즉시 작동합니다. Privy는 외부 지갑을 연결된 계정으로 취급하므로, 동일한 사용자 DID가 임베디드 및 외부 키를 모두 소유합니다.

Privy가 다운되면 어떻게 되나요?키가 사용자의 브라우저 인클레이브에 있으므로 사용자는 내보낸 지갑에 계속 액세스할 수 있습니다. 프로덕션 앱의 경우 지갑 내보내기 기능을 켜고 대체 경로를 문서화하세요. 공급업체 위험 패턴에 대한 자세한 내용은 ID 공급업체 비교 가이드를 참조하세요.

Privy는 MFA를 지원하나요?네. TOTP, SMS 및 패스키가 모두 내장되어 있으며, 정책 엔진을 통해 특정 작업(토큰 전송, 지갑 내보내기)에 MFA를 요구할 수 있습니다.

앱 코드가 서버 측에서 실행되나요, 클라이언트 측에서 실행되나요?둘 다입니다. 클라이언트 SDK는 로그인 UI 및 서명을 처리하고, 서버 SDK는 토큰을 확인하고 사용자 데이터를 가져옵니다. 앱 시크릿을 브라우저로 보내지 마세요.