Library JavaScript

Panduan lengkap @transx402/client — impor subpath, createBrowserClient, createPaywall, agen, dan mode settlement untuk x402 IDRX.

Ringkasan

@transx402/client adalah library browser dan Node.js untuk pembayaran x402 IDRX. Impor client dari subpath — root paket hanya mengekspor tipe dan error.

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()`	Hanya env server — jangan di browser
`direct`	Browser / agen	`pay()` / `createPaywall()`	Publishable `ipk_pub_sandbox_` / `ipk_pub_live_` (daftarkan Allowed Origins dulu)

Instalasi

npm install @transx402/client
# Settlement full-stack kanonis:
npm install @transx402/server

Membutuhkan Node.js 20.19+. Untuk HTML tanpa build, lihat Penggunaan CDN. Situs WordPress memakai Plugin WordPress, bukan paket npm ini di browser.

Path impor	Peran
`@transx402/client`	Tipe, `FacilitationError`, helper — tanpa `createBrowserClient`
`@transx402/client/browser`	Path 4: `createBrowserClient`, `createPaywall`, CDN `TransX402`
`@transx402/client/agent`	Path 3: `createAgentClient` (Node, private key)

import type { PaymentResult, SettlementMode } from "@transx402/client";
import { FacilitationError, formatFacilitationError } from "@transx402/client";
import { createBrowserClient, createPaywall } from "@transx402/client/browser";
import { createAgentClient } from "@transx402/client/agent";

Kanonis: `createBrowserClient` + `fetch()`

import { createBrowserClient } from "@transx402/client/browser";
 
const client = createBrowserClient({
  environment: "camp", // "local" | "camp" | "base"
  settlement: "server", // default untuk fetch()
  configProxyPath: "/api/transx402", // → GET /api/transx402/config
});
 
const response = await client.fetch("/api/premium");

TypeScript melarang apiKey jika environment di-set dan settlement "server". Hubungkan proxy dengan tx402.config.handleRequest.

Anda boleh set facilitatorUrl untuk menimpa host preset; section config tetap mengikuti environment. Chain / RPC / IDRX / Permit2 hanya dari GET /config.

`client.fetch(url, init?)`

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

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

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"): langkah 1–4, lalu client memanggil POST /facilitate sendiri sebelum retry. Dipakai oleh pay() dan paywall.

Settlement langsung: `pay()`

Pembayaran tanpa backend. Membutuhkan API key publishable.

const direct = createBrowserClient({
  apiKey: "ipk_pub_sandbox_...",
  environment: "camp",
  settlement: "direct",
});
 
const result = await direct.pay({
  to: "0xWalletMerchant",
  amount: "5000", // IDR utuh; library ×100 → unit dasar IDRX
  currency: "IDR",
  resource: "https://example.com/artikel/123",
});
 
console.log("Pembayaran berhasil:", result.txHash);

Paywall: `createPaywall()`

Overlay imperatif — bukan komponen React. Selalu memakai settlement direct.

import { createPaywall } from "@transx402/client/browser";
 
createPaywall({
  apiKey: "ipk_pub_sandbox_...",
  environment: "camp",
  selector: "#konten-premium",
  price: 5000,
  currency: "IDR",
  merchantWallet: "0xMerchant...",
  title: "Artikel Premium",
  description: "Bayar Rp 5.000 untuk membaca artikel ini",
});

Setara CDN: TransX402.paywall({ ... }) dari browser bundle.

Overlay menampilkan harga IDR, Pay with IDRX, koneksi wallet, approve Permit2, tanda tangan, dan tautan transaksi.

Tema

createPaywall({
  apiKey: "ipk_pub_sandbox_...",
  environment: "camp",
  selector: "#konten-premium",
  price: 5000,
  merchantWallet: "0xMerchant...",
  theme: {
    primary: "#2563eb",
    background: "#ffffff",
    text: "#0f172a",
    borderRadius: "12px",
  },
});

Agen: `createAgentClient`

Path 3 — private key Node. Approve Permit2 disponsori via signTransaction. Jangan dipakai di MetaMask (browser tidak bisa eth_signTransaction).

import { createAgentClient } from "@transx402/client/agent";
 
const agent = createAgentClient({
  environment: "camp",
  privateKey: "0x...",
  settlement: "server", // API merchant harus memanggil @transx402/server
  configProxyPath: "http://localhost:3420/api/transx402", // URL absolut di Node
});
 
await agent.fetch("http://localhost:3420/api/premium");
console.log("Alamat agen:", agent.address);

Untuk settlement: "direct", berikan apiKey publishable. configProxyPath relatif hanya untuk browser.

Metode browser lain

const address = await client.connectWallet(); // EIP-1193 / window.ethereum
await client.isWalletConnected();
await client.getNetworkConfig(); // dari GET /config (atau proxy)
 
const { approved, allowance } = await client.checkApproval();
if (!approved) {
  await client.requestApproval(); // biasanya ditangani otomatis
}

Opsi konfigurasi

Opsi	Tipe	Catatan
`environment`	`"local"` \| `"camp"` \| `"base"`	Memilih section config + host preset
`facilitatorUrl`	`string`	Override host opsional; section tetap mengikuti `environment`
`configProxyPath`	`string`	Basis proxy same-origin untuk `GET …/config` (settlement server). Default `/api/transx402`
`settlement`	`"server"` \| `"direct"`	Default `"server"` untuk `fetch()`
`apiKey`	`string`	Wajib untuk `direct` / `pay()` / paywall; dihilangkan untuk `fetch()` server
`onPaymentStart`	`function`	Pembayaran dimulai
`onPaymentSuccess`	`function`	Pembayaran berhasil
`onPaymentError`	`function`	Pembayaran gagal
`onWalletConnect`	`function`	Wallet terhubung
`onApprovalRequired`	`function`	Hook opsional `requestApproval()` manual

Jangan mengirim token atau network — itu bukan opsi client. Config berasal dari GET /config.

Error

import { FacilitationError, formatFacilitationError } from "@transx402/client";
 
try {
  await client.fetch("/api/premium");
} catch (error) {
  if (error instanceof FacilitationError) {
    console.error(error.code, formatFacilitationError(error));
    // insufficient_balance, no_permit2_approval, ...
  }
}

Juga: WalletConnectionError, Permit2Error. Setelah settlement server, gate gagal bisa mengembalikan HTTP 402/500 dengan { code, error, details } — bentuk ulang FacilitationError dari body jika butuh UX yang sama.

Kompatibilitas

Browser

Chrome 90+, Firefox 90+, Safari 15+, Edge 90+
Mobile: Chrome Android, Safari iOS
Wallet: MetaMask / EIP-1193 (window.ethereum) saja

Node.js

Node.js 20.19+ (fetch bawaan)
Agen: @transx402/client/agent dengan private key

Contoh lengkap (settlement server)

import { FacilitationError, formatFacilitationError } from "@transx402/client";
import { createBrowserClient } from "@transx402/client/browser";
 
const client = createBrowserClient({
  environment: "camp",
  settlement: "server",
  configProxyPath: "/api/transx402",
  onPaymentError: (error) => {
    if (error instanceof FacilitationError && error.code === "insufficient_balance") {
      alert("Saldo IDRX Anda tidak mencukupi");
    }
  },
});
 
try {
  const response = await client.fetch("/api/premium");
  const data = await response.json();
  renderContent(data);
} catch (error) {
  console.error("Gagal mengambil konten:", formatFacilitationError(error as FacilitationError));
}

Library JavaScript

On this page