Library JavaScript

Panduan lengkap @transx402/client — instalasi, konfigurasi, komponen paywall, dan referensi API untuk integrasi pembayaran IDRX.

Ringkasan

@transx402/client adalah library browser/Node untuk pembayaran x402 IDRX. Untuk integrasi full-stack (direkomendasikan), pasangkan dengan @transx402/server: client menandatangani; backend Anda memanggil POST /facilitate.

Mode settlement	Siapa memanggil `/facilitate`	Default untuk	API key
`server` (kanonis)	Backend merchant (`@transx402/server`)	`fetch()`	Env server
`direct`	Browser / agent	`pay()` / paywall	`ipk_` di client

Instalasi

NPM (untuk aplikasi yang di-bundle)

npm install @transx402/client
npm install @transx402/server

CDN (untuk WordPress, situs statis, halaman HTML biasa)

Untuk integrasi tanpa proses build, lihat panduan khusus Penggunaan CDN. Versi singkatnya:

<script src="https://cdn.transx402.com/v1/transx402.min.js"></script>

Script CDN mengekspos objek global TransX402 dengan API yang sama seperti yang dijelaskan di bawah. Alur CDN/paywall memakai settlement direct.

Inisialisasi

`TransX402.create(options)`

Buat instance client TransX402:

// Sandbox (CAMP testnet di fasilitator hosted)
const client = TransX402.create({
  apiKey: 'ipk_sandbox_abc123...',
});
 
// Production (Base mainnet di fasilitator hosted yang sama)
const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',
});

Chain (sandbox/production) ditentukan dari prefix API key — keduanya memakai https://api.transx402.com. Anda tidak perlu mengatur URL fasilitator secara manual untuk integrasi hosted.

Opsi Konfigurasi

Opsi	Tipe	Default	Deskripsi
`apiKey`	`string`	wajib	API key dari dashboard TransX402
`token`	`string`	`'IDRX'`	Simbol token yang digunakan
`network`	`string`	`'base'`	Jaringan blockchain
`onPaymentStart`	`function`	—	Callback saat pembayaran dimulai
`onPaymentSuccess`	`function`	—	Callback saat pembayaran berhasil
`onPaymentError`	`function`	—	Callback saat pembayaran gagal
`onWalletConnect`	`function`	—	Callback saat wallet terhubung
`onApprovalRequired`	`function`	—	Callback opsional untuk alur manual `requestApproval()`

API Utama

`client.fetch(url, options)`

Drop-in replacement untuk fetch(). Otomatis menangani respons 402.

const response = await client.fetch('https://example.com/artikel-premium');
const content = await response.json();

Alur internal (settlement: "server", default fetch()):

Mengirim request fetch() biasa
Jika respons 402, mem-parse persyaratan pembayaran
Menghubungkan wallet (jika belum)
Menandatangani payload pembayaran x402 (Exact EVM + Permit2 witness)
Mencoba ulang request asli dengan PAYMENT-SIGNATURE / X-PAYMENT
API merchant settle via @transx402/server → POST /facilitate
Mengembalikan respons final

Alur internal (settlement: "direct"): 1–4 di atas, lalu client memanggil POST /facilitate sendiri sebelum retry. Dipakai oleh pay() dan paywall.

`client.connectWallet()`

Hubungkan wallet secara eksplisit. Mendukung:

MetaMask / wallet ekstensi browser (EIP-1193)
WalletConnect v2
Coinbase Wallet

const address = await client.connectWallet();
console.log('Wallet terhubung:', address);

`client.checkApproval()` (opsional)

Periksa apakah wallet yang terhubung sudah menyetujui Permit2 untuk IDRX.

const { approved, allowance } = await client.checkApproval();
 
if (!approved) {
  console.log('Perlu approval Permit2');
}

`client.requestApproval()` (opsional)

Helper manual untuk meminta approval Permit2. Sebagian besar integrasi sebaiknya mengandalkan alur x402 standar dan sponsorship extension.

const tx = await client.requestApproval();
console.log('Approval berhasil, tx hash:', tx);

`client.pay(paymentRequirements)`

Trigger pembayaran secara manual tanpa membungkus fetch.

const result = await client.pay({
  to: '0xWalletMerchant',
  amount: '150000',    // dalam IDR (library mengonversi ke unit IDRX)
  currency: 'IDR',
  resource: 'https://example.com/artikel/123',
});
 
console.log('Pembayaran berhasil:', result.txHash);

Komponen Paywall

Komponen paywall siap pakai untuk content gating.

Vanilla JavaScript

TransX402.paywall({
  selector: '#konten-premium',    // elemen yang di-gate
  price: 5000,                     // harga dalam IDR
  currency: 'IDR',
  merchantWallet: '0xMerchant...',
  title: 'Artikel Premium',
  description: 'Bayar Rp 5.000 untuk membaca artikel ini',
});

React

import { Paywall } from '@transx402/client/browser';
 
function ArtikelPage() {
  return (
    <Paywall
      price={5000}
      currency="IDR"
      merchantWallet="0xMerchant..."
    >
      <KontenPremium />
    </Paywall>
  );
}

Tampilan Paywall

Overlay paywall default menampilkan:

Harga dalam IDR (contoh: "Rp 5.000")
Tombol "Pay with IDRX"
Alur koneksi wallet (jika belum terhubung)
Langkah konfirmasi tanda tangan
Konfirmasi pembayaran dengan link transaksi
Dapat dikustomisasi melalui CSS variables

Kustomisasi

CSS Variables

:root {
  --transx402-primary: #2563eb;
  --transx402-bg: #ffffff;
  --transx402-text: #1a1a1a;
  --transx402-radius: 12px;
  --transx402-font: 'Inter', system-ui, sans-serif;
}

Event Hooks

const client = TransX402.create({
  apiKey: 'ipk_sandbox_abc123...',
  onPaymentStart: (details) => {
    console.log('Pembayaran dimulai:', details);
    // Tracking analytics
  },
  onPaymentSuccess: (result) => {
    console.log('Pembayaran berhasil:', result.txHash);
    // Unlock konten
  },
  onPaymentError: (error) => {
    console.error('Pembayaran gagal:', error.message);
    // Tampilkan pesan error
  },
  onWalletConnect: (address) => {
    console.log('Wallet terhubung:', address);
    // Update UI
  },
  onApprovalRequired: () => {
    console.log('Alur approval Permit2 manual (opsional)');
  },
});

Dukungan Multi-Currency

Library dirancang untuk IDRX terlebih dahulu tetapi mendukung token tambahan:

const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',
  token: 'USDC',       // override token default
  network: 'base',
});

Konfigurasi token (alamat, desimal, metode) diambil dari endpoint /tokens fasilitator, sehingga penambahan token baru tidak memerlukan update library client.

Target Ukuran Bundle

Varian	Target
Core (fetch wrapper saja)	< 15 KB gzipped
Dengan paywall UI	< 30 KB gzipped
Dengan wallet connectors	< 50 KB gzipped
CDN full bundle	< 60 KB gzipped

Kompatibilitas

Browser

Chrome 90+
Firefox 90+
Safari 15+
Edge 90+
Mobile: Chrome Android, Safari iOS

Node.js

Node.js 18+ (membutuhkan Fetch API)
Bisa digunakan server-side untuk pembayaran programatik (AI agent, backend)

Contoh Lengkap

Paywall Artikel Blog

<!DOCTYPE html>
<html>
<head>
  <title>Blog Saya</title>
  <script src="https://cdn.transx402.com/v1/transx402.min.js"></script>
</head>
<body>
  <h1>Panduan Investasi Crypto 2026</h1>
 
  <p>Berikut adalah preview artikel...</p>
 
  <div id="konten-premium">
    <p>Ini adalah konten premium yang akan terbuka setelah pembayaran.</p>
    <!-- Konten lengkap di sini -->
  </div>
 
  <script>
    const client = TransX402.create({
      apiKey: 'ipk_sandbox_abc123...',
    });
 
    TransX402.paywall({
      selector: '#konten-premium',
      price: 5000,
      currency: 'IDR',
      title: 'Konten Premium',
      description: 'Bayar Rp 5.000 untuk membaca artikel lengkap',
    });
  </script>
</body>
</html>

Fetch API dengan Error Handling

import { TransX402 } from '@transx402/client';
 
const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',
  onPaymentError: (error) => {
    if (error.code === 'insufficient_balance') {
      alert('Saldo IDRX Anda tidak mencukupi');
    } else if (error.code === 'user_rejected') {
      console.log('Pengguna membatalkan pembayaran');
    }
  },
});
 
try {
  const response = await client.fetch('https://api.mysite.com/premium-data');
  const data = await response.json();
  renderContent(data);
} catch (error) {
  console.error('Gagal mengambil konten:', error);
}

Library JavaScript

On this page