←Home/Docs
⌕

Thử nghiệm x402 (Agents)

Thử nghiệm, gắn cờ tính năng, chỉ áp dụng testnet. GET /x402/legal/documents/{id} là một bản sao thử nghiệm, không cần API key, trả phí theo từng lượt gọi dựa trên GET /v1/legal/documents/{id} dành cho các AI agent tự hành muốn trả vài phần mười xu cho mỗi lần gọi thay vì giữ một API key của CrawlPipe. Tính năng này mặc định bị tắt trong mọi môi trường (X402_ENABLED=false) và khi bật lên, chỉ thanh toán qua bên trung gian mô phỏng trên mạng testnet (base-sepolia) — không sử dụng tiền mã hóa thực hay tiền thật.

Tại sao có tính năng này

CrawlPipe được bán chủ yếu qua khóa API tính phí theo lượng dùng. Tuy nhiên, "nền kinh tế agent" mới nổi (các LLM agent tự hành khám phá và trả phí cho các công cụ theo thời gian thực theo giao thức x402) không muốn đăng ký tài khoản trước — nó muốn gọi endpoint, nhận báo giá, thanh toán trực tiếp và nhận dữ liệu trong cùng một chu kỳ yêu cầu/phản hồi. Thử nghiệm này là bước chuẩn bị của CrawlPipe: một endpoint, một loại văn bản, $0.002/lượt gọi.

Quy trình

  1. Yêu cầu không có thanh toán. Agent gọi endpoint mà không có header X-PAYMENT. Máy chủ trả về 402 Payment Required với nội dung JSON mô tả chính xác yêu cầu thanh toán (mảng accepts, theo cấu trúc PaymentRequirements của x402).
  2. Agent tạo thanh toán. Ví/client x402 của agent tạo payload thanh toán cho một trong các mục nhập accepts, mã hóa base64 dạng JSON, và thử lại CÙNG yêu cầu đó với header X-PAYMENT: <base64>.
  3. Xác minh, thanh toán, phản hồi. Máy chủ giải mã header, yêu cầu bên trung gian xác minh thanh toán đúng định dạng, kiểm tra văn bản có tồn tại hay không (lỗi 404 không bao giờ tính phí), hoàn tất thanh toán, và trả về 200 với CÙNG nội dung văn bản mà GET /v1/legal/documents/{id} trả về, kèm header X-PAYMENT-RESPONSE chứa biên nhận thanh toán.

Ví dụ: Thử thách 402

GET /x402/legal/documents/vn:tt:2017:31:btc HTTP/1.1
Host: api.crawlpipe.com
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "2000",
      "resource": "https://api.crawlpipe.com/x402/legal/documents/vn:tt:2017:31:btc",
      "description": "CrawlPipe x402 pilot — GET /x402/legal/documents/{id} ($0.002/call)",
      "mimeType": "application/json",
      "payTo": "0x000000000000000000000000000000000000dEaD",
      "maxTimeoutSeconds": 60,
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "extra": { "name": "USDC", "version": "2" }
    }
  ],
  "error": {
    "code": "payment_required",
    "message": "Payment required",
    "details": { "price_usd": 0.002 }
  }
}

maxAmountRequired là giá theo đơn vị nguyên tử của asset (USDC, 6 chữ số thập phân) — "2000" tương đương $0.002. resource luôn lặp lại URL chính xác đã yêu cầu.

Ví dụ: Yêu cầu đã thanh toán

GET /x402/legal/documents/vn:tt:2017:31:btc HTTP/1.1
Host: api.crawlpipe.com
X-PAYMENT: eyJmcm9tIjoiMHhBQkMuLi4iLCJub25jZSI6ImFiYzEyMyIsInNpZ25hdHVyZSI6Ii4uLiJ9
HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0eFJlZiI6InNpbS1hYmMxMjMiLCJuZXR3b3JrIjoiYmFzZS1zZXBvbGlhIn0=

{
  "success": true,
  "data": {
    "document": {
      "id": "019f6ec2-afa9-7baa-bc22-1b8741767e2b",
      "natural_key": "vn:tt:2017:31:btc",
      "doc_number": "31/2017/TT-BTC",
      "...": "— giống hệt cấu trúc của GET /v1/legal/documents/{id}"
    }
  },
  "meta": { "request_id": "..." }
}

X-PAYMENT-RESPONSE cũng là base64(JSON) — giải mã để lấy {success, txRef, network}. Việc phát lại cùng một khoản thanh toán (cùng nonce) sẽ lại trả về 200 với replay: true và không tính phí mới.

Giới hạn tần suất (Rate limit)

10 yêu cầu/phút cho mỗi bên trả phí. Bên trả phí được xác định bởi trường from trong payload thanh toán (hoặc bởi IP client đối với các thử thách 402 trước khi thanh toán). Vượt quá giới hạn sẽ trả về 429 với error.code: "rate_limited" và header Retry-After.

Tách biệt với hệ thống đo lường bằng key

Endpoint này không cần API key và hoàn toàn nằm ngoài hệ thống đo lường được trình bày trong Đo lường & lỗi: không có hàng usage_event/usage_counter nào được ghi cho lưu lượng x402, và GET /v1/usage không bao giờ bị ảnh hưởng bởi nó.

Giới hạn hiện tại của bản thử nghiệm

  • Chỉ lưu trong bộ nhớ (In-process). Bộ giới hạn tần suất và khử trùng lặp thanh toán đều nằm trong bộ nhớ máy chủ và được đặt lại mỗi khi khởi động lại/deploy process.
  • Thanh toán mô phỏng. Mặc định SimulatedFacilitator xác minh hình thức thanh toán và xử lý định hình với mã giao dịch tổng hợp — không có cuộc gọi blockchain thực nào được thực hiện.
  • Mức trần chi tiêu hàng ngày toàn cục. Do endpoint không cần key, mức trần chi tiêu của tổ chức không áp dụng — thay vào đó một hạn mức chi tiêu toàn cục hàng ngày (X402_DAILY_CAP_USD, mặc định $10.00) sẽ bảo vệ hệ thống.
Thử nghiệm x402 (Agents) — CrawlPipe Docs