x402 memungkinkan klien membayar permintaan dengan stablecoin. BazaarLink menerima pembayaran x402 yang diselesaikan melalui x402 facilitator OKX di X Layer untuk mendaftarkan akun agen dan mengisi saldo yang sudah ada. Halaman ini menjelaskan perilaku kedua rute secara tepat.
Alur 402
Kedua rute mengikuti tiga langkah yang sama: minta, tanda tangani, kirim ulang.
Kirim permintaan tanpa pembayaran. Server menjawab 402 Payment Required dengan body JSON berisi x402Version, resource, dan accepts(network, asset, amount, payTo, maxTimeoutSeconds).
Tanda tangani otorisasi pembayaran untuk salah satu entri dalam accepts dengan kunci dompet Anda sendiri.
Kirim kembali permintaan yang sama dengan payload pembayaran berkode base64 di header X-PAYMENT. Nama header payment-signature juga diterima sebagai alias.
Baca persyaratan dari respons
Ambil network, asset, dan amount dari respons 402, jangan menulisnya secara tetap. amount menggunakan unit terkecil aset(6 desimal untuk USDT0). Kirim body JSON yang sama pada kedua permintaan.
POST /api/v1/agents/register/x402 membuat akun agen, API key, dan saldo awal dalam satu permintaan berbayar. API key dan login tidak diperlukan.
Body permintaan
namewajib
string
Nama agen, 1 hingga 100 karakter.
description
string
Deskripsi opsional, hingga 4000 karakter.
amountUsdwajib
number
Jumlah yang dibayar dalam dolar AS, berupa angka positif. Sebelum 402 dibuat, jumlah dibatasi ke rentang yang diizinkan(saat ini $1 hingga $50), jadi gunakan jumlah dari respons.
Field yang tidak dikenal ditolak dengan 400 bad_request.
1. Minta tanpa membayar
Responsnya adalah 402 dengan persyaratan pembayaran. Belum ada apa pun yang dibuat.
Tanda tangani dengan dompet Anda sendiri, lalu kirim permintaan yang sama dengan header X-PAYMENT. Perintah curl menunjukkan permintaannya; contoh TypeScript di bawah menghasilkan nilai header.
Contoh ini menggunakan paket klien @okxweb3/x402 dan viem; Anda dapat menandatangani dengan OKX Wallet atau kunci dompet apa pun. Kunci privat tetap di mesin Anda; hanya otorisasi yang sudah ditandatangani yang dikirim.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { x402Client } from"@okxweb3/x402-core/client";
importtype { Network } from"@okxweb3/x402-core/types";
import { toClientEvmSigner } from"@okxweb3/x402-evm";
import { ExactEvmScheme } from"@okxweb3/x402-evm/exact/client";
import { privateKeyToAccount } from"viem/accounts";
constURL = "https://bazaarlink.ai/api/v1/agents/register/x402";
constHEADERS = { "content-type": "application/json" };
constBODY = JSON.stringify({ name: "my-agent", amountUsd: 1.1 });
// 1. Ask without paying. The 402 body lists what the server accepts.const challenge = awaitfetch(URL, { method: "POST", headers: HEADERS, body: BODY });
if (challenge.status !== 402) thrownewError("unexpected status " + challenge.status);
const paymentRequired = await challenge.json();
// 2. Sign the payment authorization with your own wallet key.const privateKey = readSecret("payer-private-key") as`0x${string}`; // from your own secret store, never from source codeconst signer = toClientEvmSigner(privateKeyToAccount(privateKey));
const client = newx402Client().register(
paymentRequired.accepts[0].networkasNetwork,
newExactEvmScheme(signer),
);
const payload = await client.createPaymentPayload(paymentRequired);
const xPayment = Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
// 3. Send the same request again with the signed payment.const res = awaitfetch(URL, { method: "POST", headers: { ...HEADERS, "x-payment": xPayment }, body: BODY });
const account = await res.json(); // 201: api_key, credits, claim_token, payment ...console.log(res.status, account.credits_usd);
Simpan kunci privat dompet di variabel lingkungan atau penyimpanan rahasia, jangan di kode sumber.
Respons pendaftaran
Pendaftaran yang berhasil mengembalikan 201 dengan field berikut. API key hanya ditampilkan di sini satu kali, jadi segera simpan.
Isi saldo yang berhasil mengembalikan 200 dengan status credited, saldo baru dalam dolar AS, txHash, serta paidUsd, creditedUsd, dan serviceFeeUsd (jumlah yang dibayar, jumlah yang dikreditkan, dan biaya isi saldo platform).
1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1200 OK
Content-Type: application/json
{"status":"credited","balance":12.5,"txHash":"0xTX_HASH","paidUsd":1.1,"creditedUsd":1,"serviceFeeUsd":0.1}
1
2
3
4
5
6
7
8
9
// Same three steps against /api/x402/topup; only the URL, body and auth header change.constURL = "https://bazaarlink.ai/api/x402/topup";
constHEADERS = {
"content-type": "application/json",
authorization: "Bearer " + process.env.BAZAARLINK_API_KEY,
};
constBODY = JSON.stringify({ amountUsd: 1.1 });
// ...reuse the challenge / sign / resend code from the registration example.// 200 -> { "status": "credited", "balance": 12.5, "txHash": "0x...", "paidUsd": 1.1, "creditedUsd": 1, "serviceFeeUsd": 0.1 }
Baca batas saat ini
GEThttps://bazaarlink.ai/api/x402/topup
GET /api/x402/topup mengembalikan minUsd, maxUsd, dan network tanpa autentikasi.
1
curl https://bazaarlink.ai/api/x402/topup
1
{"minUsd":1,"maxUsd":50,"network":"eip155:196"}
Pembayaran duplikat dan berulang
Otorisasi yang ditandatangani hanya dapat digunakan sekali. Server mengenali pembayaran berulang sebelum menghubungi jaringan pembayaran, sehingga percobaan ulang tidak menagih Anda dua kali.
Isi saldo: mengirim ulang pembayaran yang sudah dikreditkan mengembalikan 200 dengan status already_credited.
Pendaftaran: selama 15 menit, pembayaran bertanda tangan yang sama mengembalikan respons 201 yang sama, termasuk API key, sehingga aman dicoba ulang saat terjadi kegagalan jaringan. Setelah itu, responsnya 200 dengan status already_registered dan txHash pembayaran, tanpa menampilkan API key lagi.
Respons error
Rute x402 mengembalikan error sebagai { "error": { "message", "code" } }. Dua respons berbeda: 410 menggunakan { "error", "code" } dan 429 menggunakan { "error" } dengan header Retry-After.
HTTP
Kode
Arti
400bad_request
Body tidak valid: tipe salah, name hilang, atau ada field yang tidak dikenal.
400topup_unavailable
Akun ini tidak dapat diisi saldonya.
401unauthenticated
Khusus isi saldo: tidak ada API key atau session yang valid.
402(payment requirements body)
Belum ada pembayaran yang dapat digunakan. Body berisi persyaratan; tanda tangani dan kirim ulang. Ini juga dikembalikan jika pembayaran tidak cocok dengan persyaratan atau gagal diverifikasi.
402payment_amount_too_low
Jumlah yang diselesaikan lebih rendah daripada jumlah yang diminta.
403geo_blocked
x402 tidak dapat digunakan dari wilayah Anda.
410agent_register_discontinued
Pendaftaran agen sedang dimatikan.
429(Retry-After header)
Terlalu banyak pendaftaran dari sumber jaringan yang sama. Tunggu selama detik yang diberikan dalam Retry-After.
502facilitator_error
Pembayaran tidak dapat diverifikasi atau diselesaikan. Coba lagi nanti.
502settlement_error
Pembayaran sudah diterima tetapi tidak dapat dikreditkan. Kirim ulang pembayaran yang sama, jangan tanda tangani yang baru.
502registration_error
Pembayaran sudah diterima tetapi akun tidak dapat dibuat. Kirim ulang pembayaran yang sama, jangan tanda tangani yang baru.
503disabled / runtime_disabled
x402 sedang dimatikan atau belum dikonfigurasi.
503asset_unavailable / dedup_unavailable
Dependensi(konfigurasi aset, pemeriksaan duplikat, atau pemeriksaan isi saldo)tidak dapat dihubungi. Coba lagi nanti.
503signup_disabled / agent_register_unavailable
Pendaftaran sedang dinonaktifkan sementara atau tidak dapat digunakan.
Serahkan akun kepada seseorang
Kirim upgrade_url dari respons kepada pemilik akun. Setelah mereka masuk dan mengambil alih, API key dan saldo berpindah ke akun mereka. Lakukan sebelum claim_expires.
1
https://bazaarlink.ai/claim?token=<claim_token>
Jaringan dan aset
Saat ini USDT0 di X Layer, diselesaikan melalui x402 facilitator OKX. Berlaku biaya isi saldo platform, sehingga saldo yang Anda terima lebih rendah dari jumlah yang dibayar (lihat harga). Pembayaran diselesaikan on-chain dan tidak dapat dibatalkan, jadi periksa jumlah dan jaringan sebelum menandatangani.