Skip to main content
SDK wallet-kit berjalan di browser, sehingga apiKey Helius Anda tersedia di sisi klien: penyedia mengirimkannya ke bootstrap dompet (/waas/config) saat aplikasi Anda dimuat. Hal ini wajar untuk SDK sisi klien. Halaman ini menjelaskan secara persis apa yang dapat dan tidak dapat dilakukan oleh kunci tersebut, serta cara mengamankannya.

​
Apa yang dapat — dan tidak dapat — dilakukan oleh kunci

Mulailah dari sini karena bagian ini mudah disalahpahami: kunci API Helius adalah kredensial RPC/kredit, bukan kunci dompet. Kunci yang bocor tidak dapat:
  • menandatangani transaksi atau pesan,
  • memindahkan atau mengakses dana, atau
  • mengakses dompet tersemat milik pengguna mana pun.
Penandatanganan dompet diotorisasi oleh passkey atau sesi milik pengguna akhir, dan kunci privat disimpan di enklave aman milik Turnkey — tidak pernah berada di aplikasi Anda, server Anda, atau apa pun yang dapat dijangkau oleh kunci API. Mengekspos kunci tidak mengekspos dompet. Yang dapat dilakukan oleh kunci yang bocor adalah menghabiskan kredit Helius Anda (kuota RPC). Hanya itu cakupan dampaknya — masalah penagihan, bukan kustodian — dan lapisan di bawah ini akan membatasi dan menutupnya.
Eksposur juga bukan cara untuk melewati penagihan. Tanda tangan WaaS dihitung saat dompet tersemat melakukan penandatanganan, bukan pada lapisan kunci API — kunci yang bocor tidak dapat menghasilkan tanda tangan gratis atau menagihkan tanda tangan dari situs milik orang lain. Penghitungan tidak bergantung pada kerahasiaan kunci.

​
Amankan kunci

Lapisan berikut diurutkan dari upaya paling rendah hingga batas perlindungan paling kuat. Lapisan pertama adalah perlindungan dasar yang wajib; tambahkan lapisan lainnya sesuai toleransi risiko Anda.

​
1. Batasi kunci berdasarkan domain (wajib)

Batasi kunci ke origin tempat aplikasi Anda berjalan agar kunci yang diambil dari bundle Anda tidak dapat digunakan dari tempat lain.
1

Open RPC Access Control

Di dasbor, buka kunci Anda pada bagian RPCs, lalu buka Access Control.
2

Add your domains to Allowed Domains

Tambahkan setiap origin yang melayani aplikasi Anda — produksi, staging, dan pratinjau:
3

Use a separate key per environment

Gunakan kunci yang berbeda untuk lingkungan lokal, staging, dan produksi agar Anda dapat merotasi satu kunci tanpa menghentikan lingkungan lainnya.
Daftar domain yang diizinkan mencegah penyalahgunaan berbasis browser, bukan skrip yang disengaja. Pemeriksaan membaca header Origin/Referer permintaan — browser mengaturnya secara jujur, tetapi klien non-browser (misalnya curl -H "Origin: yourdapp.com") dapat memalsukannya. Hal ini berlaku untuk setiap kunci API sisi klien, bukan hanya Helius. Pembatasan domain secara andal mencegah kasus umum — kunci Anda muncul di situs milik orang lain — tetapi untuk batas perlindungan yang tidak dapat dipalsukan, gunakan kunci sisi server yang dibatasi ke IP/CIDR Anda (langkah 4).

​
2. URL RPC Aman tanpa kunci (otomatis)

Lalu lintas RPC sama sekali tidak membawa kunci Anda. SDK mendapatkan URL RPC Aman tanpa kunci milik proyek Anda saat bootstrap dan menggunakannya secara otomatis untuk panggilan connection — tidak ada yang perlu dikonfigurasi. Karena URL ini tidak berisi kunci, tidak ada kunci dalam permintaan RPC yang dapat diekstrak. URL ini juga dibatasi hingga 5 RPS per IP, sehingga perlindungannya tidak bergantung pada pemeriksaan Origin. (Tersedia pada paket berbayar; jika proyek tidak memiliki URL RPC Aman, RPC akan menggunakan pengendali rute same-origin pada langkah 3.)

​
3. Pindahkan kunci ke sisi server — serverless

Agar kunci tidak berada di browser untuk panggilan RPC, pengiriman, dan riwayat transaksi, arahkan panggilan tersebut melalui endpoint Anda sendiri yang menyisipkan kunci dari rahasia sisi server. Dengan cara ini, Anda juga dapat menggunakan pendaratan yang dioptimalkan Sender dan riwayat transaksi. Kedua opsi ini 100% serverless — tidak ada server yang perlu dijalankan:
  • Pengendali rute Next.js — diterapkan sebagai fungsi serverless (Vercel, Netlify, Cloudflare). Membaca HELIUS_API_KEY dari lingkungan server.
    app/api/helius/[...path]/route.ts
  • Proksi Cloudflare Worker — opsi serverless sepenuhnya yang paling sederhana: kunci disimpan dalam rahasia Worker dan tidak pernah mencapai browser.

    Helius RPC Proxy

    Proksi RPC sumber terbuka yang dapat Anda terapkan ke Cloudflare dengan satu klik.

​
4. Tambahkan batas IP/CIDR yang tidak dapat dipalsukan

Untuk membuat batas yang tidak dapat dipalsukan oleh penyerang, batasi kunci sisi server ke alamat IP atau rentang CIDR backend Anda. Tidak seperti header Origin, IP sumber tidak dapat dipalsukan pada koneksi normal — sehingga curl dari mana pun selain server Anda akan langsung ditolak. Hal ini hanya berlaku untuk kunci sisi server — Anda tidak dapat membatasi kunci browser berdasarkan IP karena pengguna Anda terhubung dari IP yang tidak dapat diprediksi. Pola yang tepat menggunakan dua kunci:
Fungsi serverless memiliki IP keluar yang dinamis, sehingga penetapan CIDR memerlukan jalur keluar yang stabil — Cloudflare Worker dengan IP keluar khusus, Vercel Secure Compute, atau NAT ber-IP tetap di depannya. Tanpa salah satunya, Anda tetap memperoleh manfaat utama (kunci berada di sisi server dan tidak pernah berada di browser); Anda hanya tidak menambahkan batas IP sebagai lapisan tambahan.
Lihat Lindungi kunci Anda untuk referensi lengkap aturan kontrol akses.

​
Perbandingan setiap lapisan

Apa pun lapisan yang Anda pilih, tidak satu pun merupakan kunci dompet pengguna Anda — kunci tersebut tidak pernah terlibat.

​
Bootstrap dompet

Dalam penyiapan pengendali rute (produksi), bootstrap dompet (/waas/config) juga melewati pengendali rute Anda dengan kunci sisi server sehingga tidak ada kunci Helius yang dikirim ke browser. Dalam penyiapan prototipe, browser mengirimkan kunci untuk bootstrap; batasi berdasarkan domain (langkah 1). Dalam kedua kasus, kunci tersebut memiliki cakupan RPC — kunci tersebut tidak dapat mengakses dompet atau dana.

​
Daftar periksa

Sebelum merilis aplikasi:
  • Kunci klien dibatasi berdasarkan domain ke origin Anda secara tepat
  • Kunci terpisah untuk lingkungan lokal/staging/produksi
  • Kunci dibaca dari variabel lingkungan dan tidak pernah ditulis langsung dalam kode
  • (Opsional) RPC, pengiriman, dan riwayat diarahkan melalui pengendali rute serverless atau Cloudflare Worker
  • (Opsional) Kunci sisi server dibatasi ke IP/CIDR Anda untuk membuat batas yang tidak dapat dipalsukan

​
Langkah berikutnya

Protect your keys

Referensi lengkap kontrol akses: domain, IP, CIDR, dan proksi.

Configuration

Konfigurasi penyedia dan metode masuk dasbor.