API đã settle thành công nhưng không ai tìm thấy: vấn đề "drift" trong x402 và MCP

Bối cảnh

Ngày càng nhiều lập trình viên thử nghiệm mô hình thu phí API bằng x402, hoặc biến MCP server của mình thành một dịch vụ có trả phí. Nhưng không ít người vấp phải một vấn đề khá đau đầu: Thanh toán đã settle thành công, nhưng API vẫn không xuất hiện trong catalog (Bazaar), và agent của người mua không bao giờ tìm thấy nó. Nguyên nhân thường không nằm ở một chỗ duy nhất, mà nằm ở sự "lệch" (drift) giữa hai nguồn thông tin được coi là chuẩn (source of truth):

1. Phản hồi 402 trực tiếp của API (route, giá, payTo)
2. Manifest tại /.well-known/x402 Chỉ cần hai nơi này không khớp nhau, hệ thống discovery sẽ lặng lẽ bỏ qua API của bạn. Thanh toán vẫn chạy bình thường, nhưng sẽ không có thêm người mua mới nào tìm đến. Cách kiểm tra phía người bán (phần bạn kiểm soát được) Từ các issue công khai trên repo x402-foundation/x402 (ví dụ #3677), quy trình debug hiệu quả là:
3. Giải mã header EXTENSION-RESPONSES trong phản hồi /verify và /settle (đây là JSON được mã hóa base64). Nếu header trống, nghĩa là facilitator chưa nhận được khai báo Bazaar hợp lệ từ payload của người mua. Nếu giá trị là rejected, lý do đi kèm chính là điểm nghẽn thực sự.
4. Giữ resource.description dưới 500 ký tự — vượt quá giới hạn này đã từng khiến facilitator từ chối thanh toán.
5. Không cần thêm một lần settle tốn phí để kiểm tra lại việc index — chỉ cần gửi một payload /verify (không settle) từ ví của chính bạn, kèm theo extension, là đủ để kiểm tra lại đường đi mà không phải động đến tiền thật.
6. Tự động kiểm tra drift giữa manifest và phản hồi 402 trực tiếp ngay trong CI, thay vì kiểm tra thủ công sau mỗi lần deploy. Công cụ miễn phí cho bước 4 Chúng tôi có duy trì một GitHub Action miễn phí tên là x402 Manifest Check. Action này validate manifest tại /.well-known/x402 và gửi thử một request tới endpoint 402 (không thanh toán) để đối chiếu hai nguồn thông tin với nhau. Nó không thực hiện thanh toán và không lưu giữ credentials. • GitHub Marketplace: https://github.com/marketplace/actions/x402-manifest-check • callx402 (npm) — thư viện chẩn đoán lỗi settle và phân loại lỗi (invalid signature hay lỗi hạ tầng): https://www.npmjs.com/package/callx402 Giới hạn cần nói thẳng Công cụ phía người bán không thể ép facilitator index API của bạn. Nếu EXTENSION-RESPONSES cứ trả về processing mãi mà API vẫn không xuất hiện trong catalog, đó là vấn đề nằm ở hàng đợi của facilitator — và bản ghi header chính là bằng chứng bạn cần mang đến khi làm việc với họ. Disclosure (minh bạch về liên kết) Tác giả thuộc nhóm Payload — nhóm phát triển callx402 và Veyline (lớp authorization thanh toán non-custodial dành cho agent). Bài viết này chia sẻ kinh nghiệm vận hành x402; các công cụ được nhắc tới ở trên là của chúng tôi.