Sebastian Petrus

Posted on Apr 23 • Originally published at apidog.com

Cách Sử Dụng Privy API: Ví Nhúng và Xác Thực Mạng Xã Hội cho Web3

Việc giới thiệu người dùng với một ứng dụng Web3 thường gặp phải rào cản lớn: seed phrase, extension trình duyệt và phí gas khiến việc đăng ký kéo dài. API của Privy giải quyết vấn đề này bằng cách cung cấp ví nhúng (embedded wallet) cho mỗi người dùng mới chỉ với đăng nhập qua email, SMS, Google, Apple hoặc ví sẵn có như MetaMask. Người dùng gốc crypto không cần cài đặt extension nào.

Dùng thử Apidog ngay hôm nay

Privy đã được tích hợp cho Blackbird, Friend.tech, OpenSea và nhiều ứng dụng khác trên Ethereum, Solana cũng như các chuỗi EVM. Dưới đây là hướng dẫn từng bước: tạo app Privy, tích hợp React SDK, xác minh token backend, ký giao dịch với ví nhúng, triển khai webhook. Nếu cần so sánh với MetaMask API, hãy bookmark bài viết này để tham khảo.

💡Trước khi đọc code, lưu ý: Apidog là công cụ lý tưởng để kiểm tra mọi request HTTPS mà SDK Privy gửi ra. Trỏ app tới proxy cục bộ, bắt payload thực tế và debug xác thực nhanh chóng.

Tóm tắt

Privy kết hợp ví nhúng với các phương thức đăng nhập (email, SMS, social, ví ngoài) trong một SDK duy nhất.
React SDK cung cấp các hook: PrivyProvider, useLogin, useWallets, usePrivy để xử lý xác thực và ký.
@privy-io/server-auth xác minh access token phía backend, đảm bảo tính xác thực ID người dùng.
Hỗ trợ Ethereum, Solana, các chuỗi EVM; cho phép xuất khóa và ký uỷ quyền cho thao tác quan trọng.
Webhook đồng bộ hoá sự kiện người dùng, ví về backend, không cần polling.
Công cụ chính sách: thêm MFA, allowlists, rule giao dịch mà không cần sửa code app.

API của Privy là gì?

Privy là nền tảng cung cấp xác thực và ví với 3 thành phần: UI đăng nhập, ví nhúng cho mỗi user, REST endpoint để kiểm tra phía server. Ví nhúng nằm trong secure enclave, Privy và backend đều không truy cập được private key. Người dùng có thể export private key bất cứ lúc nào.

Chi phí tính theo số ví hoạt động/tháng. Gói miễn phí: 1.000 MAW, Pro từ $149/tháng, Enterprise hỗ trợ SLA tuỳ chỉnh.

Xác thực và thiết lập

Vào privy.io tạo app mới. Lưu lại:
- App ID (clxxxxx...) cho client SDK
- App secret cho server SDK
Cấu hình phương thức đăng nhập (email, SMS, Google, Apple, Farcaster, ví), chuỗi mặc định và allowed origins.
Cài React SDK:

npm install @privy-io/react-auth

Bọc app trong 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>
  );
}

Cờ createOnLogin sẽ cấp ví nhúng cho user đăng nhập lần đầu nếu chưa có ví.
Cấu hình Solana qua trường solanaClusters.

Các điểm cuối và lệnh gọi SDK cốt lõi

React SDK xử lý hầu hết luồng xác thực, ký. Tuy nhiên, backend và webhook sử dụng chuẩn token giống nhau; hiểu API cơ bản giúp debug hiệu quả.

Kích hoạt đăng nhập và đọc thông tin người dùng

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

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

  if (!ready) return <p>Loading...</p>;
  if (!authenticated) return <button onClick={login}>Sign in</button>;

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

  return (
    <div>
      <p>Hi {user.email?.address ?? user.id}</p>
      <p>Wallet: {embedded?.address}</p>
      <button onClick={logout}>Log out</button>
    </div>
  );
}

useWallets trả về toàn bộ ví liên kết của user, kiểm tra loại ví bằng walletClientType.
Đây là mẫu chuẩn cho ví nhúng Privy.

Ký giao dịch

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);
}

Với Solana, dùng getSolanaProvider và truyền transaction đã serialize.
Có thể kết hợp Privy (xử lý khóa) với RPC provider như Alchemy.

Xác minh token trên máy chủ

Cài đặt server SDK:

npm install @privy-io/server-auth

Kiểm tra access token từ frontend:

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 là Privy user DID
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

Có thể lấy toàn bộ user object qua privy.getUser(userId).

Xuất ví nhúng

Cho phép user export private key bằng hook:

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

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Export private key</button>;

Privy hiển thị modal an toàn, app không truy cập được private key.

Chữ ký ủy quyền và công cụ chính sách

Định nghĩa policy trong dashboard, gắn vào app.
Privy enforce MFA, allowlist, hoặc approval ký server trước khi thực hiện giao dịch nhạy cảm.
Tham khảo hướng dẫn policy Privy.

Webhooks

Privy gửi JSON sự kiện về endpoint của bạn khi có thay đổi:

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" } }
  }'

Xác minh header svix-signature bằng khóa webhook trước khi ghi vào DB.

Các lỗi thường gặp và giới hạn tốc độ

invalid_token: JWT frontend hết hạn. Gọi getAccessToken() từ usePrivy trước khi fetch dữ liệu.
403 origin_not_allowed: Chưa thêm domain deploy vào allow list trên Privy dashboard.
wallet_not_ready: Đọc useWallets khi ready chưa true. Luôn kiểm tra cờ ready.
Giới hạn tốc độ: REST endpoint giới hạn 100 req/s/app ở gói miễn phí. Nếu chạm trần, nhóm request getUser hoặc cache theo userId.

Dùng Apidog để phát lại webhook lỗi, chỉnh payload và header chữ ký, gửi lại tới server dev cho tới khi xử lý thành công.

Giá của Privy

Miễn phí: tối đa 1.000 ví hoạt động/tháng, các phương thức đăng nhập cơ bản, ví nhúng EVM + Solana.
Pro: $149/tháng, nâng giới hạn MAW, đầy đủ webhook, staging app.
Enterprise: SLA tuỳ chỉnh, hỗ trợ kỹ thuật chuyên sâu, chính sách riêng.

Chi tiết tại privy.io/pricing.

Kiểm tra API của Privy bằng Apidog

Privy client SDK ẩn các request HTTPS, nhưng backend vẫn là REST thông thường. Dùng Apidog để:

Tạo collection Privy, thêm app ID & secret làm biến môi trường.
Gọi các endpoint như GET /api/v1/users/{userId} hoặc POST /api/v1/users/{userId}/wallets ngay trong Apidog.
Ghi lại payload webhook từ dashboard, lưu thành request, phát lại qua local tunnel đến server dev.
Thiết lập test tự động: JWT hợp lệ trả user, JWT hết hạn trả lỗi 401.
Tải Apidog miễn phí để thay thế cURL phức tạp. Nếu đã từ bỏ Postman, xem hướng dẫn migration để chuyển toàn bộ quy trình.

Câu hỏi thường gặp

Privy khác gì Web3Auth, Magic?

Cả ba cung cấp ví nhúng, nhưng Privy tập trung vào xác thực kết hợp (email + ví + mạng xã hội) và policy engine cho app lớn. Web3Auth thiên về chia khoá MPC; Magic cung cấp magic-link. Chọn Privy nếu muốn onboarding đơn giản lẫn kiểm soát granular.

Privy hỗ trợ Solana không?

Có. Ví nhúng chạy trên Solana mainnet/devnet, SDK React hỗ trợ getSolanaProvider() để ký/gửi giao dịch. Có thể cấu hình EVM & Solana cùng lúc.

User có dùng ví riêng không?

Có. MetaMask, Coinbase, WalletConnect, Phantom..., Privy coi chúng là "liên kết" bên cạnh ví nhúng.

Nếu Privy dừng hoạt động?

User vẫn giữ ví đã export vì private key nằm trong enclave trình duyệt. App production nên bật export wallet và ghi lại đường dẫn backup. Xem so sánh các nhà cung cấp danh tính để đánh giá rủi ro.

Privy có MFA không?

Có. MFA (TOTP, SMS, passkey) tích hợp sẵn, có thể yêu cầu MFA cho action cụ thể qua policy engine.

Code app chạy client hay server?

Cả hai. Client SDK xử lý UI đăng nhập/ký; server SDK xác minh token, truy vấn user. Không bao giờ gửi app secret sang client.

DEV Community