يستدعي الوكيل واجهة API المحمية
يصل طلب `GET /v1/intelligence` بدون ترويسة `Authorization: Bearer` لرمز ترخيص ES256 أو إيصال جلسة مدفوعة.
حوّل أي واجهة REST API أو نقطة نهاية MCP إلى جدار دفع ذاتي التحصيل.
تفشل بطاقات الائتمان في المبالغ الأقل من $1.00 وتحجب وكلاء الذكاء الاصطناعي المستقلين الذين لا يملكون بطاقات شركات. تنقل XPayr معيار HTTP `402 Payment Required` إلى بيئة الإنتاج الفعلي: اطلب الدفع من المتصلين غير المصادقين عبر جلسة عملات مستقرة غير وصائية، وسوِّ 99.5% على شبكات Base أو Solana أو Arbitrum أو TRON أو Circle Arc، وتحقق من رموز الوصول غير ذات الحالة ES256 JWT في أقل من جزء من المللي ثانية عبر برمجيات الحافة الوسيطة.
يُصدر الخادم استجابة HTTP 402
تُنشئ البرمجية الوسيطة معرّف منتج دفع/ترخيص SKU في XPayr أو تشير إليه وتُعيد `402 Payment Required` + بيانات `X-Payment-Required` الوصفية.
يسدّد الوكيل بالعملات المستقرة
يتحقق الوكيل من ضوابط الإنفاق عبر `@xpayr/mcp-server` (`POST /api/mcp`)، ويدفع بعملة USDC/USDT (بنسبة 99.5% مباشرةً لمحفظة التاجر)، ويتلقى رمز ES256 JWT.
تحقق JWKS في أقل من مللي ثانية
يعيد الوكيل المحاولة بترويسة `Authorization: Bearer <jwt>`. تتحقق برمجية الحافة الوسيطة من توقيع ES256 مقابل `/.well-known/jwks.json` دون اتصال وتُعيد `200 OK`.
1. حمولة تحدي HTTP `402 Payment Required` القياسية
HTTP/1.1 402 Payment Required
Content-Type: application/json
WWW-Authenticate: XPayr402 realm="api.merchant.example", jwks="https://xpayr.com/.well-known/jwks.json"
X-Payment-Required: protocol="xpayr-x402-v1", amount="5.00", currency="USD", fee_bps="50"
{
"error": "payment_required",
"protocol": "xpayr-x402-v1",
"amount": "5.00",
"currency": "USD",
"accepted_rails": ["base:USDC", "solana:USDC", "arbitrum:USDT", "tron:USDT", "arc-testnet:USDC"],
"checkout_url": "https://xpayr.com/buy/pro-api-pass",
"mcp_endpoint": "https://xpayr.com/api/mcp",
"mcp_tool": "xpayr_create_payment_session",
"jwks_uri": "https://xpayr.com/.well-known/jwks.json"
}
2. برمجية Node.js / Edge الوسيطة (`@xpayr/extension-kit` v0.2.0)
import { createRemoteJWKSet, jwtVerify } from 'jose';
const XPAYR_JWKS = createRemoteJWKSet(
new URL('https://xpayr.com/.well-known/jwks.json')
);
export async function requireXpayr402(req, res, next) {
const token = (req.headers.authorization || '').replace(/^Bearer\s+/i, '');
if (token) {
try {
const { payload } = await jwtVerify(token, XPAYR_JWKS, { algorithms: ['ES256'] });
req.xpayrEntitlement = payload;
return next();
} catch (_) { /* expired or invalid token -> emit 402 below */ }
}
return res.status(402)
.set('WWW-Authenticate', 'XPayr402 jwks="https://xpayr.com/.well-known/jwks.json"')
.json({
error: 'payment_required',
protocol: 'xpayr-x402-v1',
checkout_url: 'https://xpayr.com/buy/api-credits-10k',
mcp_endpoint: 'https://xpayr.com/api/mcp'
});
}
الأسئلة الشائعة — HTTP 402 وجدران الدفع للوكلاء
كيف تطبّق XPayr بروتوكول HTTP 402 Payment Required لواجهات API ووكلاء الذكاء الاصطناعي؟
عندما يستدعي عميل غير مصادق أو وكيل ذكاء اصطناعي نقطة النهاية المحمية دون رمز ترخيص XPayr ES256 صالح أو إثبات جلسة مدفوعة، تُعيد البرمجية الوسيطة لديك استجابة HTTP 402 مرفقة بملف JSON لتحدي الدفع من XPayr (مع ترويسات WWW-Authenticate / X-Payment-Required). وبمجرد السداد على Base أو Solana أو Arbitrum أو TRON أو Circle Arc، يحصل العميل على رمز ES256 JWT موقّع تشفيرياً وقابل للتحقق دون اتصال عبر https://xpayr.com/.well-known/jwks.json.
هل يضيف التحقق من رمز حامل HTTP 402 أي تأخير زمني لكل طلب API؟
لا يلزم إجراء أي اتصال شبكي لكل طلب. إذ يخزّن خادم الحافة (Edge Worker) أو الخلفية لديك مفتاح P-256 العام الخاص بـ XPayr من /.well-known/jwks.json مؤقتاً ويتحقق من توقيع ES256 JWT محلياً في أقل من 0.2 مللي ثانية.
كيف يمكن لوكلاء الذكاء الاصطناعي المستقلين سداد تحدي الدفع HTTP 402 تلقائياً؟
تفحص الوكلاء المتصلة بحزمة @xpayr/mcp-server (أو عبر POST https://xpayr.com/api/mcp) تحدي 402، وتتحقق من سياسة ضوابط وكيل التاجر (/tools/ai-agent-policy-simulator)، وتنفّذ نية الدفع بالعملات المستقرة أو تطلب اعتمادها، ثم تعيد إرسال الطلب مرفقاً بترويسة Authorization: Bearer <es256_license_jwt> الناتجة.
أين يُستضاف بيان اكتشاف x402 المقروء آلياً الخاص بـ XPayr؟
اطّلع على https://xpayr.com/.well-known/x402.json إلى جانب https://xpayr.com/.well-known/agents.json وhttps://xpayr.com/.well-known/mcp.json.