Blog

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

Ashley Innocent

Ashley Innocent

23 tháng 4 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Việc giới thiệu người dùng với một ứng dụng Web3 vẫn khiến hầu hết mọi người bỏ cuộc ngay từ bước đầu tiên. Các cụm từ khôi phục (seed phrase), tiện ích mở rộng trình duyệt và phí gas biến việc đăng ký chỉ cần hai lần chạm thành một cuộc vật lộn kéo dài mười phút. API của Privy khắc phục khoảng cách đó bằng cách cung cấp cho mỗi người dùng mới một ví nhúng (embedded wallet) đằng sau một hình thức đăng nhập quen thuộc: email, SMS, Google, Apple hoặc một ví hiện có như MetaMask. Bạn có được người dùng gốc crypto mà không cần yêu cầu bất cứ ai cài đặt tiện ích mở rộng trình duyệt.

Privy hiện hỗ trợ ví cho Blackbird, Friend.tech, OpenSea và hàng nghìn ứng dụng khác, đồng thời sản phẩm này trải rộng trên Ethereum, Solana và bất kỳ chuỗi EVM nào. Hướng dẫn này sẽ đi sâu vào toàn bộ quy trình làm việc của nhà phát triển: tạo ứng dụng Privy, tích hợp React SDK, xác minh token trên máy chủ, ký giao dịch bằng ví nhúng và triển khai webhook. Nếu bạn cũng muốn so sánh các tùy chọn như bộ công cụ dành cho nhà phát triển của MetaMask, hãy giữ trang này mở và chuyển đổi qua lại.

💡
Trước khi đọc code, một lưu ý về công cụ. Apidog là cách bạn nên kiểm tra mọi yêu cầu HTTPS mà SDK của Privy thực hiện ngầm. Trỏ ứng dụng của bạn đến một proxy cục bộ, nắm bắt payload thực tế và gỡ lỗi các lỗi xác thực trong vài giây thay vì phải theo dõi log.
button

Tóm tắt

API của Privy là gì?

Privy là một nền tảng cơ sở hạ tầng xác thực và ví. Nó cung cấp cho ứng dụng của bạn ba điều: giao diện người dùng đăng nhập, một ví nhúng được cấp cho mỗi người dùng và một bộ các điểm cuối REST để kiểm tra phía máy chủ. Ví nhúng nằm trong một khu vực an toàn (secure enclave), do đó Privy không bao giờ thấy khóa riêng và backend của bạn cũng vậy. Người dùng có thể xuất khóa của họ sau này nếu họ muốn chuyển sang một ví tự quản lý; tùy chọn đó là một phần lớn của đề xuất giá trị.

Nền tảng này tính phí theo số ví hoạt động hàng tháng, điều này có nghĩa là bạn có thể phát hành một bản thử nghiệm miễn phí và điều chỉnh giá khi mức độ tương tác tăng lên. Gói miễn phí bao gồm 1.000 người dùng hoạt động hàng tháng, gói Pro bắt đầu từ 149 đô la mỗi tháng và gói Enterprise xử lý các SLA tùy chỉnh.

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

Bắt đầu tại privy.io và tạo một ứng dụng mới từ bảng điều khiển. Bạn sẽ nhận được hai giá trị quan trọng:

Đặt các phương thức đăng nhập được phép (email, SMS, Google, Apple, Farcaster, ví), chọn chuỗi mặc định của bạn và thêm miền của bạn vào danh sách các nguồn gốc được phép (allowed origins). Đối với React, cài đặt SDK:

npm install @privy-io/react-auth

Bọc ứng dụng của bạn 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 một ví nhúng lần đầu tiên khi người dùng đăng nhập mà không có ví. Bạn kiểm soát các chuỗi được hỗ trợ; Solana nằm dưới một cấu hình solanaClusters riêng biệt.

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

React SDK của Privy xử lý hầu hết các luồng, vì vậy bạn hiếm khi cần sử dụng REST thô. Tuy nhiên, server SDK và payload webhook sử dụng cùng một định dạng token, vì vậy việc nắm rõ API cơ bản sẽ hữu ích khi mọi thứ không suôn sẻ.

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ề mọi ví mà người dùng đã liên kết, và trường walletClientType cho bạn biết ví nào do Privy tạo. Đây là mẫu bạn tuân theo cho ví nhúng của 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);
}

Đối với Solana, hãy đổi getEthereumProvider thành getSolanaProvider và truyền một giao dịch được tuần tự hóa (serialized transaction). Nếu bạn muốn phản ánh các mẫu truy cập dữ liệu từ các nhà cung cấp như Alchemy, Privy hoạt động tốt cùng với họ; Privy xử lý khóa, Alchemy xử lý RPC.

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

Cài đặt server SDK:

npm install @privy-io/server-auth

Mỗi yêu cầu được xác thực từ frontend của bạn đều mang một access token của Privy (JWT). Hãy xác minh nó trên máy chủ trước khi bạn tin tưởng bất kỳ ID người dùng nào:

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

Bạn cũng có thể tìm nạp đối tượng người dùng đầy đủ (privy.getUser(userId)) để kiểm tra các tài khoản đã liên kết, địa chỉ ví và metadata tùy chỉnh.

Xuất ví nhúng

Privy cho phép người dùng xuất khóa riêng của họ bất cứ lúc nào. UX là một hook duy nhất:

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

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

Privy hiển thị một cửa sổ modal iframe an toàn; ứng dụng của bạn không bao giờ chạm vào tài liệu khóa.

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

Đối với các hoạt động nhạy cảm (chuyển khoản lớn, đăng nhập thiết bị mới), Privy hỗ trợ chữ ký ủy quyền. Bạn định nghĩa một chính sách trong bảng điều khiển, gắn nó vào ứng dụng của mình và Privy thực thi MFA, danh sách cho phép (allowlists) hoặc phê duyệt có chữ ký của máy chủ trước khi một giao dịch được thực hiện. Chi tiết có trong hướng dẫn khóa ủy quyền của Privy. Kết hợp với các tùy chọn MFA (TOTP, SMS, passkey), điều này giúp đóng lại hầu hết các lỗ hổng chiếm quyền tài khoản mà các ví thông thường để ngỏ.

Webhooks

Privy gửi các sự kiện JSON đến điểm cuối của bạn khi có thay đổi trong vòng đời người dùng và ví:

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 tiêu đề svix-signature bằng khóa bí mật webhook từ bảng điều khiển trước khi bạn ghi bất kỳ thứ gì vào cơ sở dữ liệu của mình.

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

Sử dụng Apidog để phát lại webhook bị lỗi cục bộ. Dán payload thô vào một yêu cầu, chỉnh sửa tiêu đề chữ ký và gửi đến máy chủ phát triển của bạn nhiều lần cho đến khi trình xử lý thành công.

Giá của Privy

Kiểm tra privy.io/pricing để biết số liệu hiện tại; các cấp bậc sẽ thay đổi khi sản phẩm phát triển.

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

Client SDK của Privy ẩn các lệnh gọi HTTPS, nhưng mọi xác minh token, tìm kiếm người dùng và webhook mà backend của bạn xử lý đều là một yêu cầu REST thông thường. Đó là lúc Apidog phát huy tác dụng. Tạo một bộ sưu tập Privy trong Apidog, thêm ID ứng dụng và khóa bí mật của bạn làm biến môi trường, sau đó truy cập các điểm cuối như GET /api/v1/users/{userId} hoặc POST /api/v1/users/{userId}/wallets mà không cần rời khỏi công cụ.

Bạn cũng có thể ghi lại các payload webhook từ bảng điều khiển, lưu chúng dưới dạng yêu cầu Apidog và phát lại chúng thông qua một kênh cục bộ (local tunnel). Thiết lập các thử nghiệm tự động để xác minh rằng một JWT hợp lệ trả về một đối tượng người dùng và một JWT hết hạn trả về lỗi 401; chạy chúng trên mỗi lần triển khai. Tải Apidog miễn phí và bỏ qua các thao tác cURL phức tạp. Nếu bạn đã chuyển khỏi Postman, hướng dẫn quy trình làm việc song song sẽ bao gồm toàn bộ quá trình di chuyển.

button

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

Privy khác với Web3Auth hay Magic như thế nào?Cả ba đều cung cấp ví nhúng, nhưng Privy nhấn mạnh nhiều hơn vào xác thực hỗn hợp (email + ví + mạng xã hội) và một công cụ chính sách mà các ứng dụng lớn hơn cần. Web3Auth tập trung vào việc phân chia khóa MPC; Magic cung cấp một sản phẩm magic-link rộng hơn. Hãy chọn Privy khi bạn muốn cả giao diện người dùng onboarding rõ ràng và khả năng kiểm soát chi tiết những gì ví có thể làm.

Privy có hỗ trợ Solana không?Có. Ví nhúng hoạt động trên Solana mainnet và devnet, và React SDK cung cấp getSolanaProvider() để ký và gửi giao dịch. Bạn có thể cấu hình cả EVM và Solana trong cùng một ứng dụng.

Người dùng có thể sử dụng ví của riêng họ không?Có. MetaMask, Coinbase Wallet, WalletConnect, Phantom và hàng tá ví khác hoạt động ngay lập tức. Privy coi các ví ngoài là tài khoản đã liên kết, vì vậy cùng một DID người dùng sở hữu cả khóa nhúng và khóa ngoài.

Điều gì xảy ra nếu Privy ngừng hoạt động?Người dùng vẫn giữ quyền truy cập vào các ví đã xuất, vì khóa nằm trong khu vực an toàn của trình duyệt người dùng (browser enclave). Đối với các ứng dụng sản xuất, hãy bật tính năng xuất ví và ghi lại đường dẫn dự phòng. Xem hướng dẫn so sánh các nhà cung cấp danh tính để biết thêm về các mô hình rủi ro nhà cung cấp.

Privy có hỗ trợ MFA không?Có. TOTP, SMS và passkey đều được tích hợp sẵn, và bạn có thể yêu cầu MFA cho các hành động cụ thể (gửi token, xuất ví) thông qua công cụ chính sách.

Code ứng dụng của tôi chạy ở phía máy chủ hay phía client?Cả hai. Client SDK xử lý giao diện người dùng đăng nhập và ký; server SDK xác minh token và tìm nạp dữ liệu người dùng. Không bao giờ gửi khóa bí mật ứng dụng của bạn đến trình duyệt.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống