اگر برای سرویس هوش مصنوعی خود مدل پرداخت مستقیم پیاده کرده‌اید، احتمالاً متوجه شده‌اید که حتی با وجود عملکرد صحیح، اندپوینت x402 شما ممکن است خطای ۴۰۲ را برگرداند و پرداخت‌ها را به‌طور کامل پردازش کند، اما همچنان در CDP Bazaar برای عامل‌های هوش مصنوعی جستجوکننده کاملاً نامرئی باشد. این شکاف شناسایی به این دلیل رخ می‌دهد که بازار CDP به‌صورت کورکورانه وب را خزش نمی‌کند؛ بلکه تنها مسیرهایی را فهرست می‌کند که پرداخت آن‌ها از طریق تسهیل‌گر Coinbase Developer Platform (CDP) تسویه شده و چالش (Challenge) مربوطه حاوی یک اعلان معتبر extensions.bazaar باشد.
برای توسعه‌دهندگانی که نسل بعدی ابزارهای پولی هوش مصنوعی را می‌سازند، این بدان معناست که داشتن یک API فعال و کاربردی کافی نیست. شما به یک مثلث حیاتی نیاز دارید: یک چالش خوش‌ساخت، استفاده از CDP به‌عنوان تسهیل‌گر پرداخت و حداقل یک تراکنش تسویه شده. بدون این سه مورد، سرویس شما برای اکوسیستم عامل‌محور (Agentic) عملاً وجود ندارد.
سازوکار شناسایی
فرآیند فهرست‌بندی در بازار CDP به‌جای پیش‌کنشی، واکنشی است. یک مسیر تنها زمانی لیست می‌شود که پرداختی به آن از طریق تسهیل‌گر CDP نهایی شود و چالش ۴۰۲ حاوی اعلان مورد نیاز extensions.bazaar باشد. پس از برآورده شدن این شرایط، CDP به‌صورت دوره‌ای اندپوینت را بازخزش می‌کند تا اطلاعات فهرست به‌روز بماند.
برای بررسی اینکه آیا مسیر شما در حال حاضر ایندکس شده است یا خیر، می‌توانید از API عمومی شناسایی CDP استفاده کنید. با وارد کردن آدرس کیف پول دریافت‌کننده خود در URL زیر در مرورگر، می‌توانید وضعیت خود را مستقیماً چک کنید:https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0xYOUR_PAY_TO_ADDRESS
به نقل از راهنمای فنی منتشر شده در unlisted.sh/guide، رایج‌ترین دلیل نامرئی بودن، صرفاً این است که هنوز هیچ پرداخت واقعی از طریق CDP تسویه نشده است. حتی تراکنشی به مبلغ یک سنت برای فعال کردن خزشگر بازار کافی است. اگر از تسهیل‌گر دیگری استفاده کنید، CDP هرگز تسویه را نمی‌بیند و مسیر شما فهرست‌نشده باقی می‌ماند. برای رفع این مشکل، مسیر را به تسهیل‌گر CDP (که نیازمند کلید API مربوط به CDP است) متصل کنید و یک فراخوانی پولی دیگر انجام دهید.
تله‌های پیکربندی فنی
علاوه بر تسویه پرداخت، چندین خطای متادیتا و زیرساختی می‌توانند مانع فهرست‌بندی شوند:
- متادیتای ناقص: فیلد
extensions.bazaarباید حضور داشته باشد و کامل باشد. به‌طور مشخص،extensions.bazaar.info.input.typeباید روی یکی از مقادیر "http" یا "mcp" تنظیم شود. اگرinfo.outputگنجانده شده باشد، آن هم به یک نوع (type) نیاز دارد. در SDK پایتون، این مورد از طریقdeclare_discovery_extension(...)در افزونه‌های مسیر و ثبتbazaar_resource_server_extensionروی سرور منبع مدیریت می‌شود. توجه داشته باشید که اگر کلاینت در حین پرداخت، افزونه را حذف کند، CDP چیزی برای فهرست کردن نخواهد داشت (x402 #3557). - طول توضیحات: توصیفاتی که بیش از ۵۰۰ کاراکتر باشند، می‌توانند بدون ایجاد خطای صریح، فرآیند فهرست‌بندی را مختل کنند (x402 #2993). یک یا دو جمله که توضیح دهد مسیر چه چیزی برمی‌گرداند و هزینه آن چقدر است، کافی است.
- تضاد در پروکسی: اگر اپلیکیشن شما پشت Render، Railway، Fly، Heroku یا nginx اجرا می‌شود، ممکن است
resource.urlبه‌جایhttps://مقدارhttp://را تبلیغ کند، زیرا میزبان TLS را می‌بندد و HTTP ساده را فوروارد می‌کند. اعتبارسنجی CDP به‌شدت به HTTPS نیاز دارد. برای uvicorn، از--proxy-headers --forwarded-allow-ips='*'استفاده کنید یا متغیر محیطیFORWARDED_ALLOW_IPS=*را تنظیم کنید. کاربران Express باید ازapp.set("trust proxy", true)استفاده کنند. - فقدان فیلد Resource: در پاسخ‌های دستی ۴۰۲، اغلب فیلد
resource.urlفراموش می‌شود. بدون URL عمومی و کامل HTTPS از مسیر پولی، بازار نمی‌تواند اندپوینت را کاتالوگ کند. - بدنه خالی: در حالی که x402 v2 از هدر base64
PAYMENT-REQUIREDاستفاده می‌کند، برخی خزشگرها همچنان نیاز دارند که JSON رمزگشایی‌شده در بدنه پاسخ ۴۰۲ حضور داشته باشد. اطمینان حاصل کنید که بدنه حاوی یک آرایه غیرخالی از اشیاءacceptsباشد که هر کدام scheme، network، asset، amount وpayToرا مشخص می‌کنند.
خطاهای مسیریابی و طرح‌واره
تعریف نادرست مسیرها نیز منجر به شکست عامل‌ها می‌شود:
- تضاد متد: یک اشتباه رایج، توصیف یک مسیر POST به‌عنوان GET است. این باعث می‌شود عامل‌ها هیچ بدنه‌ای ارسال نکنند و به‌جای چالش پرداخت، خطا دریافت کنند. برای رفع این مشکل در SDK پایتون،
body_type="json"را به همراه یک ورودی نمونه وinput_schemaبهdeclare_discovery_extensionپاس دهید و مطمئن شوید کلید مسیر روی POST تنظیم شده است. - استفاده از Wildcardهای ساده: استفاده از Wildcardهای بدون نام (مثلاً
/prices/*) مانع از درک پارامترهای مسیر توسط بازار می‌شود. توسعه‌دهندگان باید به‌جای آن از پارامترهای نام‌گذاری شده مانندGET /prices/:symbolاستفاده کنند تا متادیتای شناسایی بتواند نام پارامتر مسیر را به‌درستی تعیین کند.
اگر قیمت‌ها یا متادیتای خود را به‌روز کرده‌اید، ممکن است بازار همچنان اطلاعات قدیمی را نشان دهد (cdp-sdk #813). ایندکس تنها در طول یک بازخزش به‌روز می‌شود که معمولاً توسط یک فراخوانی پولی جدید به مسیر تحریک می‌گردد.
این تغییر در شناسایی API، صنعت را از مستندات استاتیک به سمت مدل «پرداخت برای دیده شدن» می‌برد. برای توسعه‌دهنده، لایه‌ی پرداخت اکنون مکانیسم اصلی توزیع است و هر خطای کوچک در دست‌دادن (Handshake) پرداخت، توزیع را به صفر می‌رساند.
این وضعیت دسته‌ای جدید از «بدهی شناسایی» ایجاد می‌کند که در آن بدهی فنی در هدر پرداخت، مستقیماً رشد ورودی (Top-of-funnel) را هدف قرار می‌دهد. توسعه‌دهندگان دیگر نمی‌توانند با پاسخ ۴۰۲ به‌عنوان یک کد خطای ساده برخورد کنند؛ این پاسخ اکنون یک قطعه حیاتی از سئو (SEO) برای عامل‌های هوش مصنوعی است.
برای تأیید وضعیت خود، می‌توانید از API عمومی شناسایی CDP استفاده کنید. برای کسانی که رویکرد خودکار را ترجیح می‌دهند، ابزار Unlisted یک سرویس تشخیصی ارائه می‌دهد. این ابزار بر اساس مدل پرداخت-به-ازای-فراخوانی با استفاده از USDC روی شبکه Base از طریق x402 و بدون نیاز به ثبت‌نام عمل می‌کند:
- بررسی ساده (۰.۰۲ دلار): اعتبارسنجی چالش ۴۰۲، اعلان بازار و وضعیت زنده ایندکس CDP.
- بررسی + پرداخت واقعی (۰.۱۰ دلار): شامل بررسی کامل به‌علاوه یک پرداخت تست واقعی به مسیر برای حل مشکلات تسویه.
تشخیص‌ها را می‌توان از طریق POST https://unlisted.sh/diagnose با یک بدنه JSON حاوی url مسیر پولی تحریک کرد.
گام بعدی شما
- آدرس کیف پول خود را در API عمومی CDP تست کنید تا ببینید آیا در حال حاضر ایندکس شده‌اید یا خیر.
- اگر از پروکسی استفاده می‌کنید، تنظیمات
trust proxyرا در Express یا--proxy-headersرا در uvicorn فعال کنید. - یک تراکنش کوچک (حتی یک سنت) را از طریق تسهیل‌گر CDP اجرا کنید تا خزشگر بازار فعال شود.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو