Blog

Cara Menggunakan Privy API: Dompet Tertanam dan Autentikasi Sosial untuk Web3

Ashley Innocent

Ashley Innocent

23 April 2026

Cara Menggunakan Privy API: Dompet Tertanam dan Autentikasi Sosial untuk Web3

Apidog untuk Perusahaan

Penerapan On-Premises

SSO & RBAC

Sesuai SOC 2

Jelajahi Apidog Enterprise

Mendaftarkan pengguna ke aplikasi Web3 masih membuat kebanyakan orang mundur pada langkah pertama. Frasa pemulihan (seed phrase), ekstensi browser, dan biaya gas mengubah pendaftaran dua kali ketuk menjadi perjuangan sepuluh menit. Privy API mengatasi kesenjangan tersebut dengan memberikan setiap pengguna baru dompet tersemat di balik login yang familiar: email, SMS, Google, Apple, atau dompet yang sudah ada seperti MetaMask. Anda mendapatkan pengguna asli kripto tanpa meminta siapa pun untuk menginstal ekstensi browser.

Privy kini mendukung dompet untuk Blackbird, Friend.tech, OpenSea, dan ribuan aplikasi lainnya, dan produk ini mencakup Ethereum, Solana, serta rantai EVM lainnya. Panduan ini menjelaskan alur kerja developer secara lengkap: membuat aplikasi Privy, menghubungkan React SDK, memverifikasi token di server, menandatangani transaksi dengan dompet tersemat, dan mengirimkan webhook. Jika Anda juga ingin membandingkan opsi seperti perangkat pengembang MetaMask, biarkan halaman ini tetap terbuka dan bolak-balik.

💡
Sebelum Anda membaca kode, satu catatan alat. Apidog adalah cara Anda harus memeriksa setiap permintaan HTTPS yang dibuat oleh SDK Privy di balik layar. Arahkan aplikasi Anda ke proxy lokal, tangkap payload aktual, dan debug kegagalan otentikasi dalam hitungan detik alih-alih menelusuri log.
tombol

Singkatnya

Apa itu Privy API?

Privy adalah platform infrastruktur otentikasi dan dompet. Ini memberikan tiga hal pada aplikasi Anda: UI login, dompet tersemat yang disediakan per pengguna, dan serangkaian endpoint REST untuk pemeriksaan sisi server. Dompet tersemat berada di enklaf yang aman, sehingga Privy tidak pernah melihat kunci pribadi dan backend Anda juga tidak. Pengguna dapat mengekspor kunci mereka nanti jika mereka ingin berpindah ke dompet self-custody; opsi tersebut adalah bagian besar dari daya tariknya.

Platform ini mengenakan biaya per dompet aktif bulanan, yang berarti Anda dapat merilis prototipe secara gratis dan menyesuaikan harga seiring dengan pertumbuhan daya tarik. Paket gratis mencakup 1.000 pengguna aktif bulanan, Pro dimulai dari $149 per bulan, dan Enterprise menangani SLA khusus.

Otentikasi dan Pengaturan

Mulai di privy.io dan buat aplikasi baru dari dasbor. Anda akan mendapatkan dua nilai penting:

Atur metode login yang diizinkan (email, SMS, Google, Apple, Farcaster, dompet), pilih rantai default Anda, dan masukkan domain Anda ke dalam daftar asal yang diizinkan (allowed origins). Untuk React, instal SDK:

npm install @privy-io/react-auth

Bungkus aplikasi Anda di 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>
  );
}

Flag createOnLogin menyediakan dompet tersemat pertama kali pengguna login tanpa satu pun. Anda mengontrol rantai yang didukung; Solana berada di bawah konfigurasi solanaClusters yang terpisah.

Endpoint Inti dan Panggilan SDK

React SDK Privy menangani sebagian besar alur sehingga Anda jarang mengakses REST mentah. Namun, server SDK dan payload webhook menggunakan format token yang sama, jadi mengetahui API dasarnya membantu saat terjadi masalah.

Memicu Login dan Membaca Pengguna

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

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

  if (!ready) return <p>Memuat...</p>;
  if (!authenticated) return <button onClick={login}>Masuk</button>;

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

  return (
    <div>
      <p>Halo {user.email?.address ?? user.id}</p>
      <p>Dompet: {embedded?.address}</p>
      <button onClick={logout}>Keluar</button>
    </div>
  );
}

useWallets mengembalikan setiap dompet yang telah dihubungkan pengguna, dan bidang walletClientType memberi tahu Anda dompet mana yang dibuat oleh Privy. Ini adalah pola yang Anda ikuti untuk dompet tersemat Privy.

Menandatangani Transaksi

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

Untuk Solana, tukar getEthereumProvider dengan getSolanaProvider dan lewati transaksi yang diserialkan. Jika Anda ingin mencerminkan pola akses data dari penyedia seperti Alchemy, Privy berfungsi dengan baik bersama mereka; Privy menangani kunci, Alchemy menangani RPC.

Memverifikasi Token di Server

Instal server SDK:

npm install @privy-io/server-auth

Setiap permintaan terotentikasi dari frontend Anda membawa token akses Privy (JWT). Verifikasi di server sebelum Anda mempercayai ID pengguna apa pun:

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

Anda juga dapat mengambil objek pengguna lengkap (privy.getUser(userId)) untuk memeriksa akun yang terhubung, alamat dompet, dan metadata kustom.

Mengekspor Dompet Tersemat

Privy memungkinkan pengguna mengekspor kunci pribadi mereka kapan saja. UX-nya adalah satu hook:

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

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Ekspor kunci pribadi</button>;

Privy menampilkan modal iframe yang aman; aplikasi Anda tidak pernah menyentuh materi kunci.

Tanda Tangan Otorisasi dan Mesin Kebijakan

Untuk operasi sensitif (transfer besar, login perangkat baru), Privy mendukung tanda tangan otorisasi. Anda menentukan kebijakan di dasbor, melampirkannya ke aplikasi Anda, dan Privy memberlakukan MFA, daftar yang diizinkan (allowlists), atau persetujuan yang ditandatangani server sebelum transaksi berhasil. Detailnya ada di panduan kunci otorisasi Privy. Dikombinasikan dengan opsi MFA (TOTP, SMS, passkey), ini menutup sebagian besar celah pengambilalihan akun yang dibiarkan terbuka oleh dompet biasa.

Webhook

Privy mengirimkan peristiwa JSON ke endpoint Anda pada perubahan siklus hidup pengguna dan dompet:

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

Verifikasi header svix-signature dengan secret webhook dari dasbor sebelum Anda menulis apa pun ke basis data Anda.

Kesalahan Umum dan Batas Kecepatan

Beberapa kesalahan muncul berulang kali:

Gunakan Apidog untuk memutar ulang webhook yang gagal secara lokal. Tempel payload mentah ke dalam permintaan, edit header tanda tangan, dan panggil server pengembangan Anda berulang kali hingga handler berhasil.

Harga Privy

Periksa privy.io/pricing untuk angka-angka terbaru; tingkatan dapat berubah seiring pertumbuhan produk.

Menguji Privy API dengan Apidog

Client SDK Privy menyembunyikan panggilan HTTPS, tetapi setiap verifikasi token, pencarian pengguna, dan webhook yang ditangani backend Anda adalah permintaan REST biasa. Di sinilah Apidog sangat berguna. Buat koleksi Privy di Apidog, masukkan ID aplikasi dan secret Anda sebagai variabel lingkungan, dan akses endpoint seperti GET /api/v1/users/{userId} atau POST /api/v1/users/{userId}/wallets tanpa meninggalkan alat.

Anda juga dapat merekam payload webhook dari dasbor, menyimpannya sebagai permintaan Apidog, dan memutarnya ulang terhadap tunnel lokal. Siapkan tes otomatis yang memverifikasi bahwa JWT yang valid mengembalikan objek pengguna dan yang kedaluwarsa mengembalikan 401; jalankan tes ini di setiap deployment. Unduh Apidog secara gratis dan lewati kerumitan cURL. Jika Anda sudah beralih dari Postman, panduan alur kerja berdampingan mencakup migrasi lengkap.

tombol

FAQ

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh