दस्तावेज़API संदर्भ SDK संदर्भ एजेंटिक उपयोग AI स्किल्स

OKX x402 भुगतान: एजेंट पंजीकरण और बैलेंस जोड़ना

x402 क्लाइंट को stablecoins से अनुरोध का भुगतान करने देता है। BazaarLink X Layer पर OKX के x402 facilitator के माध्यम से निपटाए गए x402 भुगतानों से agent खाता पंजीकृत करने और मौजूदा बैलेंस जोड़ने की सुविधा देता है। यह पृष्ठ दोनों रूट के वास्तविक व्यवहार को बताता है।

402 प्रवाह

दोनों रूट में वही तीन चरण हैं: अनुरोध, हस्ताक्षर, फिर भेजना।

बिना भुगतान अनुरोध भेजें। सर्वर 402 Payment Required के साथ x402Version, resource और accepts（network, asset, amount, payTo, maxTimeoutSeconds）वाला JSON लौटाता है।
अपने वॉलेट key से accepts की किसी एक प्रविष्टि के लिए भुगतान प्राधिकरण पर हस्ताक्षर करें।
वही अनुरोध फिर भेजें और base64-encoded भुगतान payload को X-PAYMENT header में रखें। payment-signature नाम वाला header भी alias के रूप में स्वीकार किया जाता है।

उत्तर से आवश्यकताएँ पढ़ें

network, asset और amount को hard-code न करें; उन्हें 402 उत्तर से लें। amount asset की सबसे छोटी इकाई में है（USDT0 के लिए 6 दशमलव）। दोनों अनुरोधों में वही JSON body भेजें।

agent पंजीकृत करें

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

POST /api/v1/agents/register/x402 एक भुगतान वाले अनुरोध में agent खाता, API key और शुरुआती बैलेंस बनाता है। API key या login की जरूरत नहीं है।

अनुरोध body

nameआवश्यक

string

agent नाम, 1 से 100 वर्ण।

description

string

वैकल्पिक विवरण, अधिकतम 4000 वर्ण।

amountUsdआवश्यक

number

अमेरिकी डॉलर में भुगतान राशि, एक धनात्मक संख्या। 402 बनाने से पहले इसे अनुमत सीमा（वर्तमान में $1 से $50）में सीमित किया जाता है, इसलिए उत्तर की राशि लें।

अज्ञात fields को 400 bad_request के साथ अस्वीकार किया जाता है।

1. भुगतान के बिना पूछें

उत्तर भुगतान आवश्यकताओं के साथ 402 है। अभी कुछ भी नहीं बनाया जाता।

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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. हस्ताक्षर करें और फिर भेजें

अपने वॉलेट से हस्ताक्षर करें, फिर X-PAYMENT header के साथ वही अनुरोध भेजें। curl command अनुरोध दिखाती है; नीचे का TypeScript उदाहरण header value बनाता है।

1
2
3
4
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}'

TypeScript उदाहरण

यह उदाहरण @okxweb3/x402 client packages और viem का उपयोग करता है। आप OKX Wallet या किसी भी wallet key से sign कर सकते हैं। private key आपकी मशीन पर रहती है; केवल signed authorization भेजा जाता है।

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";
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);

वॉलेट private key को environment variable या secret store में रखें, source code में कभी नहीं।

पंजीकरण उत्तर

सफल पंजीकरण इन fields के साथ 201 लौटाता है। API key केवल यहीं एक बार दिखाई जाती है, इसलिए इसे तुरंत सहेजें।

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
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।

credits

number

जुड़ने वाला बैलेंस, अमेरिकी डॉलर में: भुगतान की गई राशि में से प्लेटफ़ॉर्म टॉप-अप शुल्क घटाकर।

credits_usd

string

उसी बैलेंस का formatted string।

claim_token

string

खाता लेने के लिए व्यक्ति द्वारा उपयोग किया जाने वाला token।

claim_expires

string

खाता लेने की ISO 8601 समय-सीमा।

upgrade_url

string

व्यक्ति के लिए claim link, जिसका अंत /claim?token= है।

referral_code

string

नए agent खाते का referral code।

free_model

string

हमेशा auto:free, यानी बिना बैलेंस उपलब्ध model।

message

string

ऐसा तैयार text जिसे agent अपने owner को दिखा सके।

referral_message

string

referral code के बारे में text।

base_url

string

नई key के साथ उपयोग करने वाला API base URL।

docs

string

मशीन-पठनीय documentation entry point।

payment

object

ऑब्जेक्ट, जिसमें सेटल हुए भुगतान का txHash, network और amountUsd, साथ में paidUsd, creditedUsd और serviceFeeUsd होते हैं।

मौजूदा बैलेंस जोड़ें

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

POST /api/x402/topup उस खाते में बैलेंस जोड़ता है जिसके पास API key है या जिसकी session में sign-in है। 402 flow वही है और body में केवल amountUsd है।

Authorization: Bearer और अपनी API key से authenticate करें, या signed-in browser session का उपयोग करें।

1
2
3
4
5
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}'

सफल टॉप-अप पर 200 लौटता है, जिसमें status credited, अमेरिकी डॉलर में नया बैलेंस, txHash, और paidUsd, creditedUsd तथा serviceFeeUsd (भुगतान की गई राशि, जमा की गई राशि और प्लेटफ़ॉर्म टॉप-अप शुल्क) होते हैं।

1
2
3
4
5
6
7
8
9
10
11
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
}

1
2
3
4
5
6
7
8
9
// 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 }

वर्तमान सीमाएँ पढ़ें

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

GET /api/x402/topup बिना authentication के minUsd, maxUsd और network लौटाता है।

1
curl https://bazaarlink.ai/api/x402/topup

1
{ "minUsd": 1, "maxUsd": 50, "network": "eip155:196" }

डुप्लिकेट और दोहराए गए भुगतान

Signed authorization केवल एक बार उपयोग किया जा सकता है। Server payment network से संपर्क करने से पहले दोहराए गए भुगतान को पहचान लेता है, इसलिए retry पर आपसे दो बार शुल्क नहीं लिया जाता।

Top-up: पहले से credited payment को फिर भेजने पर status already_credited वाला 200 मिलता है।

Registration: 15 मिनट तक वही signed payment API key सहित वही 201 response लौटाता है, इसलिए network failure पर सुरक्षित retry किया जा सकता है। उसके बाद status already_registered वाला 200 और payment txHash मिलता है, API key फिर नहीं दिखाई जाती।

Error responses

x402 routes errors को { "error": { "message", "code" } } के रूप में लौटाते हैं। दो responses अलग हैं: 410 में { "error", "code" } और 429 में Retry-After header के साथ { "error" } होता है।

HTTP

कोड

अर्थ

400bad_request

Body मान्य नहीं है: गलत type, name अनुपस्थित, या अज्ञात field।

400topup_unavailable

इस खाते के लिए top-up नहीं किया जा सकता।

401unauthenticated

केवल top-up: कोई valid API key या session नहीं है।

402(payment requirements body)

अभी कोई उपयोग योग्य payment नहीं है। Body में requirements हैं, इसलिए sign करके resend करें। Payment requirements से मेल न खाने या verification विफल होने पर भी यह लौटता है।

402payment_amount_too_low

Settled amount requested amount से कम है।

403geo_blocked

आपके region से x402 उपयोग नहीं किया जा सकता।

410agent_register_discontinued

Agent registration बंद है।

429(Retry-After header)

उसी network source से बहुत अधिक registrations हैं। Retry-After में दिए seconds तक प्रतीक्षा करें।

502facilitator_error

Payment verify या settle नहीं किया जा सका। बाद में फिर प्रयास करें।

502settlement_error

Payment मिल गया, लेकिन credit नहीं किया जा सका। नया payment sign करने के बजाय वही payment resend करें।

502registration_error

Payment मिल गया, लेकिन account बनाया नहीं जा सका। नया payment sign करने के बजाय वही payment resend करें।

503disabled / runtime_disabled

x402 अभी बंद है या configured नहीं है।

503asset_unavailable / dedup_unavailable

Dependency（asset configuration, duplicate check या top-up check）तक पहुँचा नहीं जा सकता। बाद में फिर प्रयास करें।

503signup_disabled / agent_register_unavailable

Registration अस्थायी रूप से disabled है या उपयोग नहीं किया जा सकता।

खाता किसी व्यक्ति को सौंपें

Response का upgrade_url account owner को भेजें। उनके sign in करके claim करने के बाद API key और balance उनके account में चले जाते हैं। claim_expires से पहले claim करें।

1
https://bazaarlink.ai/claim?token=<claim_token>

Network और asset

अभी यह X Layer पर USDT0 है, जो OKX के x402 facilitator से सेटल होता है। प्लेटफ़ॉर्म टॉप-अप शुल्क लगता है, इसलिए मिलने वाला बैलेंस भुगतान की गई राशि से कम होता है (कीमत देखें)। भुगतान ऑन-चेन सेटल होते हैं और वापस नहीं किए जा सकते, इसलिए साइन करने से पहले राशि और नेटवर्क जाँच लें।

Overview के लिए x402 agent payments page देखें।