BazaarLinkBazaarLink
Masuk
DokumentasiReferensi APIReferensi SDKPenggunaan AgentikSkill AI

Pembayaran OKX x402: daftarkan agen dan isi saldo

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.

  1. Kirim permintaan tanpa pembayaran. Server menjawab 402 Payment Required dengan body JSON berisi x402Version, resource, dan accepts(network, asset, amount, payTo, maxTimeoutSeconds).
  2. Tanda tangani otorisasi pembayaran untuk salah satu entri dalam accepts dengan kunci dompet Anda sendiri.
  3. 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.

Daftarkan agen

POSThttps://bazaarlink.ai/api/v1/agents/register/x402

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.

curl -i -X POST https://bazaarlink.ai/api/v1/agents/register/x402 \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","amountUsd":1.1}'
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 2,
  "resource": {
    "url": "https://bazaarlink.ai/api/v1/agents/register/x402",
    "description": "BazaarLink paid agent registration",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:196",
      "payTo": "0xPAY_TO_ADDRESS",
      "asset": "0xASSET_CONTRACT",
      "amount": "1100000",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD₮0", "version": "1" }
    }
  ]
}

2. Tanda tangani dan kirim ulang

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.

curl -i -X POST https://bazaarlink.ai/api/v1/agents/register/x402 \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64 payment payload>" \
  -d '{"name":"my-agent","amountUsd":1.1}'

Contoh TypeScript

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.

import { x402Client } from "@okxweb3/x402-core/client";
import type { 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";

const URL = "https://bazaarlink.ai/api/v1/agents/register/x402";
const HEADERS = { "content-type": "application/json" };
const BODY = JSON.stringify({ name: "my-agent", amountUsd: 1.1 });

// 1. Ask without paying. The 402 body lists what the server accepts.
const challenge = await fetch(URL, { method: "POST", headers: HEADERS, body: BODY });
if (challenge.status !== 402) throw new Error("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 code
const signer = toClientEvmSigner(privateKeyToAccount(privateKey));
const client = new x402Client().register(
  paymentRequired.accepts[0].network as Network,
  new ExactEvmScheme(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 = await fetch(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.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "api_key": "sk-bl-...",
  "credits": 1,
  "credits_usd": "$1.0000",
  "claim_token": "...",
  "claim_expires": "2026-10-08T00:00:00.000Z",
  "upgrade_url": "https://bazaarlink.ai/claim?token=...",
  "referral_code": "...",
  "free_model": "auto:free",
  "message": "...",
  "referral_message": "...",
  "base_url": "https://bazaarlink.ai/api/v1",
  "docs": "https://bazaarlink.ai/llms.txt",
  "payment": {
    "txHash": "0xTX_HASH",
    "network": "eip155:196",
    "amountUsd": 1.1,
    "paidUsd": 1.1,
    "creditedUsd": 1,
    "serviceFeeUsd": 0.1
  }
}
api_key
string
API key baru.
credits
number
Saldo yang ditambahkan, dalam dolar AS: jumlah yang dibayar dikurangi biaya isi saldo platform.
credits_usd
string
Saldo yang sama sebagai string berformat.
claim_token
string
Token yang dapat digunakan seseorang untuk mengambil alih akun.
claim_expires
string
Batas waktu pengambilalihan akun dalam ISO 8601.
upgrade_url
string
Tautan pengambilalihan untuk seseorang, diakhiri dengan /claim?token=.
referral_code
string
Kode rujukan akun agen baru.
free_model
string
Selalu auto:free, model yang dapat digunakan tanpa saldo.
message
string
Teks siap pakai yang dapat ditampilkan agen kepada pemiliknya.
referral_message
string
Teks tentang kode rujukan.
base_url
string
API base URL untuk digunakan dengan key baru.
docs
string
Titik masuk dokumentasi yang dapat dibaca mesin.
payment
object
Objek berisi txHash, network, dan amountUsd dari pembayaran yang diselesaikan, ditambah paidUsd, creditedUsd, dan serviceFeeUsd.

Isi saldo yang sudah ada

POSThttps://bazaarlink.ai/api/x402/topup

POST /api/x402/topup mengisi akun yang memiliki API key atau session yang sedang masuk. Alur 402 sama dan body hanya berisi amountUsd.

Autentikasi dengan Authorization: Bearer dan API key Anda, atau gunakan session browser yang sedang masuk.

curl -i -X POST https://bazaarlink.ai/api/x402/topup \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64 payment payload>" \
  -d '{"amountUsd":1.1}'

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).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "credited",
  "balance": 12.5,
  "txHash": "0xTX_HASH",
  "paidUsd": 1.1,
  "creditedUsd": 1,
  "serviceFeeUsd": 0.1
}
// Same three steps against /api/x402/topup; only the URL, body and auth header change.
const URL = "https://bazaarlink.ai/api/x402/topup";
const HEADERS = {
  "content-type": "application/json",
  authorization: "Bearer " + process.env.BAZAARLINK_API_KEY,
};
const BODY = 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.

curl https://bazaarlink.ai/api/x402/topup
{ "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.

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.

Lihat halaman pembayaran agen x402 untuk ringkasannya.

Support
Support
Hi! How can we help you?
Send a message and we'll get back to you soon.