وثائق التكامل · Docs

من التكامل حتى استلام أول USDC

هذا الدليل مبني على المسار الذي شغّلناه بأنفسنا على شبكة Base الرئيسية، بما في ذلك الأخطاء التي واجهناها.
x402 v2 · eip155:8453 · Circle USDC · PayAI facilitator

البداية السريعة

خمس خطوات لتحويل بيانات قابلة للبيع بالطلب إلى منتج معروض. الخطوات الأربع الأولى تتم في لوحة التحكم، والخامسة مراجعة من المنصة.

01

إنشاء أصل

انتقل إلى لوحة التحكم → أصول البيانات → أصل جديد، واملأ الاسم والفئة وتكرار التحديث.

02

ربط مصدر البيانات

اختر API / CSV / Postgres / Crawler، وأدخل بيانات الاتصال، ثم اضغط «اختبار الجلب» للتأكد من بنية الاستجابة وحداثتها.

03

تقسيم الأدوات

في مصنع الأدوات، حدّد اسم كل أداة ووصفها ومدخلاتها وحقول الإرجاع وسعرها واحدة تلو الأخرى. اجعل واحدة منها مجانية على الأقل.

04

إنشاء نقطة النهاية + طبقة الاكتشاف

اضغط «إنشاء نقطة النهاية»، فتولّد المنصة تلقائيًا نقطة نهاية MCP وملف /.well-known وllms.txt، ثم تُجري فحصًا ذاتيًا واحدًا لـ 402.

05

إرسال للمراجعة

تراجع المنصة أوصاف الأدوات ومعقولية التسعير (خلال يوم عمل واحد عادةً)، وبعد الموافقة تدخل السوق وقائمة انتظار Registry.

أبسط طريقة لإثبات ذلك بنفسك:استدعاء أداة مدفوعة بدون دفع يجب أن يعيد تحدي 402. تحقّق من صحة الحقول الأربعة بداخله: network وasset وpayTo وamount؛ فإن صحّت كان الإعداد سليماً——وهذه الخطوة لا تكلّف شيئاً.

ربط مصادر البيانات

أربع طرق تكامل تغطي معظم البيانات القابلة للبيع. بعد الربط، تخزن المنصة البيانات مؤقتًا حسب تكرار التحديث الذي تحدده، وتضمن الاستجابة خلال ثانية واحدة.

النوعالحالة المناسبةنقاط الإعداد
HTTP APIواجهة خارجية موجودة، مصدر بيانات طرف ثالثURL / method / headers / فاصل الاستقصاء (45 ثانية كحد أدنى)
CSV / ملفاتالقوائم، الأدلة، الجداول الثابتةبعد الرفع، حدّد عمود المفتاح الرئيسي وتكرار التحديث؛ ويتم دعم التحديث بالاستبدال.
PostgreSQLاتصال مباشر بقاعدة بيانات الأعمال، وآنية عاليةحساب للقراءة فقط + قائمة IP مسموح + عروض بدل الجداول الأصلية
زاحف مجدولصفحات عامة بلا واجهةقائمة URL المستهدفة + محددات CSS + التكرار (يُنصح بـ 45 دقيقة أو أكثر)
POST /v1/assets
curl -X POST https://api.feegate.org/v1/assets \
  -H "Authorization: Bearer $RAILS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPU 行情快照",
    "category": "算力",
    "refresh_minutes": 45,
    "source": {
      "type": "http_api",
      "url": "https://rentgpu.link/api/prices",
      "method": "GET",
      "headers": {},
      "response_path": "data.items"
    }
  }'

القيمة asset_id في الاستجابة تُستخدم لإنشاء الأدوات لاحقاً. وبعد تغيّر مصدر البيانات يجب إعادة اختبار الجلب، وإلا بقي الأداة يشير إلى اللقطة القديمة.

تقسيم الأدوات

لا تُباع البيانات كما هي؛ بل تُقسَّم إلى «سؤال واحد يمكن لاستدعاء واحد الإجابة عنه».

معايير الحكم:إذا أمكنك إرجاع إجابة السؤال خلال ثانية واحدة وكان بإمكان المشتري استخدامها فورًا، فهي مؤهلة لتكون وحدة مدفوعة.

البنية المقسَّمة الموصى بها

  • ping مجاني واحد: فحص صحة، ليتحقق Agent مما إذا كانت نقطة النهاية تعمل.
  • أداة أو أداتان مجانيتان للعرض: اعرض المجموعة الكاملة من العناصر كواجهة عرض (list_*)。
  • من 3 إلى 6 أدوات مدفوعة: استعلام عنصر واحد، سلسلة تاريخية، تصنيفات، تقييمات، توصيات حسب السيناريو.
POST /v1/assets/{asset_id}/tools
{
  "tools": [
    {
      "name": "list_gpu_models",
      "price": "0",
      "description": "列出全部在监测的 GPU 卡型,含显存与在售平台数量。免费。",
      "params": {}
    },
    {
      "name": "gpu_price",
      "price": "0.05",
      "description": "指定卡型的当前最低价、中位价与 30 天最低价,附平台名与库存状态。",
      "params": { "gpu": "string" }
    },
    {
      "name": "recommend_for_task",
      "price": "0.05",
      "description": "按任务(如 fine-tune 7B)给出最省钱的租用方案与估算总成本。",
      "params": { "task": "string", "hours": "int" }
    }
  ]
}
يقرأ الـ Agent أوصاف الأدوات مباشرة ليحكم «هل تُستدعى، وهل يُدفع مقابلها».الأدوات ذات الوصف غير الواضح لا تُشترى— وترفض مراجعة المنصة الأدوات التي تكون أوصافها عبارات عامة (مثل «الاستعلام عن البيانات»).

التسعير والطبقة المجانية

التسعير بالطلب، ولا تنزل عن تكلفة التسوية.

هيكل التكلفة
  • رسوم facilitator لكل تسوية
    ≈ $0.001
  • تكلفة إضافية على السلسلة
    ≈ $0 (مدفوعة بالنيابة)
  • عمولة المنصة (متدرجة حسب الالتزام: 50% / 40% / 30%)
    تبدأ من 50%
النطاق الموصى به
$0.01 – $0.50

الافتراضي $0.05. السعر الأقل من $0.01 لا معنى له في هذا النظام: في البداية سعّرنا بـ $0.001 فكانت النتيجة خسارة في كل عملية بيع.

دور الطبقة المجانية

قبل أن يقرر الـ Agent الدفع، عليه أن يعرف أن لديك مخزوناً وأن هذا المخزون هو ما يريده. اجعل «سرد كل العناصر» و ping مجانيين——الطبقة المجانية واجهة عرض، لا صدقة، وهذا هو ما يحدد ما إذا كانت هناك فرصة للتحويل المدفوع.

نقطة نهاية MCP

تعرض المنصة الأدوات عبر FastMCP وتربط تحدي 402 بالأدوات المدفوعة باستخدام غلاف الدفع في x402 SDK. إذا كنت تبنيها بنفسك، التزم بهذه المبادئ كما هي.

server.py
from fastmcp import FastMCP
from x402.mcp import require_payment

mcp = FastMCP("gpu-market")

# 免费层:橱窗
@mcp.tool()
def list_gpu_models() -> dict:
    """列出全部在监测的 GPU 卡型。免费。"""
    return load_models()

# 付费层:$0.05 / 次
@mcp.tool()
@require_payment(price="$0.05", network="eip155:8453")
def gpu_price(gpu: str) -> dict:
    """指定卡型的当前最低价、中位价与 30 天最低价。"""
    r = query_price(gpu)
    if not r:
        # 关键:查询失败返回 isError,x402 中间件就不会结算
        return {"isError": True, "content": "no data"}
    return r
عدم التحصيل عند فشل التسليم هو أساس الثقة.عند فشل الاستعلام يجب إرجاع isError، فلا ينفّذ وسيط x402 التسوية. وهذا شرط أن يعاود الـ Agent استدعاءك مراراً.

التسجيل في طبقة الاكتشاف

اجعل الآخرين (وAgent) قادرين على العثور عليك. يمكن للوحة التحكم إنشاء هذه الملفات الثلاثة والتحقق منها بنقرة واحدة.

/.well-known/mcp.json
{
  "name": "link.rentgpu/gpu-market",
  "transport": "streamable-http",
  "url": "https://api.feegate.org/mcp/gpu-market",
  "tools": [
    {"name": "list_gpu_models", "payment": "free"},
    {"name": "gpu_price",     "payment": "x402"}
  ]
}
/.well-known/x402.json
{
  "network": "eip155:8453",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo": "0x230cd9cd33589bcf33cd32e5aa4f9e0c3994a63b",
  "facilitator": "payai",
  "prices": {
    "gpu_price": "50000",      // USDC 6 位小数 → $0.05
    "gpu_history": "50000",
    "list_gpu_models": "0"
  }
}
/llms.txt
# GPU 算力雷达(rentgpu.link)

> 26 家平台、23 张 GPU 卡型的租赁报价,每 45 分钟全量重抓。

## 免费端点
- GET /api/prices        全量报价 feed,CC BY 4.0,免注册免 key
- GET /api/resolve?gpu=H100&budget=10   按卡型+预算直接给答案

## 付费工具(MCP, x402, $0.05/次)
- gpu_price / gpu_history / market_movers
- platform_reliability / recommend_for_task

## How to cite
数据来源:GPU 算力雷达 https://rentgpu.link ,授权 CC BY 4.0。
أداة النشر في MCP Registry يجب أن تستخدم الملف التنفيذي على GitHub releases——الحزمة بنفس الاسم على npm مزيفة. وتتولّى المنصة هذه الخطوة في لوحة التحكم، فانتبه عند البناء الذاتي.

التسوية وتقاسم الإيرادات

نموذج التحصيل: تذهب مدفوعات المشتري إلى عنوان تجميع المنصة، وبعد خصم العمولة تُجمَّع حسب الشهر الميلادي وتُسوَّى إلى عنوان الاستلام في العاشر من الشهر التالي.

402

يعيد الخادم تحدي الدفع

يتضمن scheme وnetwork وعقد الأصل والمبلغ وعنوان الاستلام والمهلة الزمنية.

التوقيع

يوقّع العميل تفويضًا وفق EIP-3009

transferWithAuthorization. لا تحتاج محفظة المشتري سوى USDC، ويتكفّل facilitator بدفع الغاز.لا حاجة إلى ETH في أي مرحلة من العملية.

التحقق

إعادة إرسال الطلب مع إثبات الدفع → يتحقق الخادم

يتحقق facilitator من التوقيع والمبلغ؛ ولا تُنفَّذ منطقية الأداة إلا بعد النجاح.

التسوية

تسليم البيانات → settle على السلسلة

لا تتم التسوية إلا بعد إرجاع البيانات بنجاح. ولا يُحصَّل أي مبلغ عند إرجاع isError بسبب الفشل.

للمطابقة، ثق فقط بأحداث Transfer على السلسلة

عند التحقق بأموال حقيقية،الثقة فقط بأحداث Transfer على السلسلة— فروق الأرصدة تُخدع بتأخر مزامنة RPC. ولوحة المطابقة تجمع افتراضياً حسب أحداث Transfer، ويمكن تصدير كشوف التسوية بصيغة CSV.

نموذج التحصيل (الافتراضي)

يذهب USDC أولًا إلى عنوان تجميع المنصة بعمولة 50%، ويُجمَّع حسب الشهر الميلادي ويُسوَّى في العاشر من الشهر التالي. ويؤهلك ذلك لمواضع مميزة في السوق وللترويج المشترك.

نموذج الحفظ الذاتي (Enterprise)

يذهب USDC مباشرة إلى محفظتك ويمكن التحقق منه على السلسلة، وتقتصر رسوم المنصة على رسوم الخدمة. وتتحمل أنت مسؤولية اختيار facilitator وتشغيله.

تكامل العميل

لا يحتاج المستدعي إلى التسجيل ولا إلى API Key؛ يكفي وجود USDC في المحفظة للاستدعاء بالطلب.

client.py
# pip install "mcp<2" "x402==2.25.0" web3
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from x402.mcp import create_payment_hook
from eth_account import Account

account  = Account.from_key("你的私钥")    # 只需有 Base 主网 USDC
MCP_URL  = "https://api.feegate.org/mcp/gpu-market"

async with streamablehttp_client(MCP_URL) as (r, w, _):
    async with ClientSession(r, w, hooks=[create_payment_hook(account)]) as s:
        await s.initialize()
        print(await s.call_tool("list_gpu_models", {}))          # 免费
        print(await s.call_tool("gpu_price", {"gpu": "H100"}))  # $0.05
نقطتان يجب الانتباه إليهما:① عند كتابة عميل بنفسك، مرِّر params["_meta"] إلى الخادم كما هو، وإلا فلن يحصل وسيط الدفع على السياق؛ ② وإذا وُجد وكيل محلي، فاضبط في العميل NO_PROXY=127.0.0.1,localhost، وإلا حُجب الطلب بواسطة الوكيل.

API المنصة

لكل إجراء في لوحة التحكم واجهة مقابلة، لتسهيل ربط أنظمتك الخاصة.

الطريقةالمسارملاحظات
POST/v1/assetsإنشاء أصول البيانات ومصادرها
POST/v1/assets/{id}/toolsإنشاء / تحديث الأدوات وقائمة الأسعار بشكل مجمع
GET/v1/assets/{id}/verifyتشغيل فحص ذاتي واحد لـ 402 وإرجاع عناصر التحدي الأربعة
GET/v1/assets/{id}/callsتفاصيل الاستدعاءات (200 / 402 / settled)
GET/v1/settlementsقائمة كشوف التسوية وحالتها
POST/v1/assets/{id}/publishإرسال طلب الإدراج للمراجعة
GET/v1/market/itemsكتالوج السوق العام (بدون مصادقة)
terminal
curl https://api.feegate.org/v1/assets/ast_92f1/verify \
  -H "Authorization: Bearer $RAILS_KEY"

# → {"x402Version":2,"accepts":[{"scheme":"exact",
#     "network":"eip155:8453","amount":"50000",
#     "payTo":"0x230c…a63b","maxTimeoutSeconds":300}],
#    "error":"Payment Required"}

دليل استكشاف الأخطاء

كل بند أدناه واجهناه فعليًا في الإنتاج، ولن تجده في الوثائق الرسمية.

facilitator الرسمي على x402.org يدعم شبكة الاختبار فقط، فتفشل المدفوعات دائماً بعد الانتقال إلى الشبكة الرئيسية؛Mogami يدعم v1 فقط، وغير متوافق مع SDK 2.25. استخدم في الإنتاج PayAI(بلا تسجيل، ويدعم x402 v2 على الشبكة الرئيسية). وخطأ الاختيار هنا يجعل السلسلة كلها معطّلة.
اكتب عند التثبيت pip install "mcp<2" "x402==2.25.0". فواجهة hooks في mcp 2.x غير متوافقة مع x402 2.25، وتثبيت 2.x يسبب عدم تفعيل hook وعدم إرفاق إثبات الدفع.
مع وجود وكيل محلي، اضبط في العميل NO_PROXY=127.0.0.1,localhost، وإلا ابتلع الوكيل طلبات التصحيح المحلية. وبالمثل، عطّل في nginx على الخادم proxy_buffering، وإلا خُزّنت استجابات البث حتى انتهاء المهلة.
بعض المواقع المستهدفة (مثل autodl) تقطع الاتصالات الطويلة بعد نحو 45 ثانية، لذا اترك هامشًا في إعدادات فاصل الجلب والمهلة. استقررنا في النهاية على جلب كامل كل 45 دقيقة.
في بيئة الإنتاج، أضف نطاقك الفعلي إلى قائمة السماح الخاصة بـ DNS rebinding في FastMCP، وإلا ستُرفض الطلبات (العرض: يعمل محليًا ويعيد 403 بعد النشر).
فروق الأرصدة تُخدع بتأخر مزامنة RPC.الثقة فقط بأحداث Transfer على السلسلة، وتحقق على basescan.org بالتصفية حسب عنوان الاستلام + USDC.
أداة النشر يجب أن تستخدم الملف التنفيذي على GitHub releases؛ فالحزمة التي تحمل الاسم نفسه على npm مزيفة. كذلك لا يمكن تغيير اسم الأداة بعد إدراجها في Registry، فتغيير الاسم يعني تغيير المنتج.