Thanh toán theo yêu cầu (x402)

Một agent có ví tiền mã hóa có thể sử dụng UberLLM mà không cần tài khoản và không cần API key. Nó thanh toán cho mỗi yêu cầu bằng USDC trên Base, sử dụng tiêu chuẩn thanh toán mở x402 (phiên bản 2).

Tính năng này hoạt động cho chat: POST /v1/chat/completions và POST /v1/messages. Hình ảnh, video, âm nhạc và giọng nói vẫn cần một key.

Để kiểm tra xem tính năng thanh toán theo yêu cầu đã được bật hay chưa, hãy mở api.uberllm.dev/x402. Nó hiển thị network, USDC contract và wallet nhận thanh toán. Nếu nó trả lời "404 not found", thì tính năng thanh toán theo yêu cầu đang tắt. Hãy sử dụng một key thay thế (Quickstart).

Cách hoạt động

1. Gửi yêu cầu mà không có key. Phản hồi là HTTP 402 Payment Required. Header PAYMENT-REQUIRED (JSON base64, cũng có trong body) cho biết yêu cầu có thể tốn tối đa bao nhiêu, và những phương thức thanh toán nào được chấp nhận.
2. Ví của bạn ký một trong các tùy chọn đó. Gửi lại yêu cầu tương tự với chữ ký trong header PAYMENT-SIGNATURE.
3. UberLLM kiểm tra thanh toán, trả lời, sau đó thu tiền thanh toán. Một phản hồi thông thường (không streaming) đi kèm với biên lai trong header PAYMENT-RESPONSE, bao gồm giao dịch on-chain.

Mỗi chữ ký thanh toán cho một yêu cầu. Để thực hiện một yêu cầu khác, hãy ký lại.

Chi phí của bạn

402 báo giá tối đa mà yêu cầu có thể tốn. Đó là lời nhắc (prompt) của bạn cộng với max_tokens đầu ra, theo tuyến đường đắt nhất mà yêu cầu có thể đi. Đặt max_tokens để giữ báo giá thấp.

Có hai cách để thanh toán:

• upto (được đề xuất trước). Bạn ký báo giá như một mức trần. Sau khi có câu trả lời, chỉ chi phí thực tế được tính, làm tròn lên đến một phần triệu đô la tiếp theo. Khoản thanh toán đầu tiên cần một lần chấp thuận USDC. Nếu dịch vụ thanh toán hỗ trợ, việc chấp thuận đó không cần gas.
• exact. Toàn bộ số tiền đã báo giá sẽ được tính, ngay cả khi yêu cầu sử dụng ít hơn. Không có khoản nào được hoàn lại. Chỉ chọn exact nếu ví của bạn không thể thực hiện upto.

Bạn sẽ không bao giờ bị tính phí nhiều hơn số tiền bạn đã ký. Nếu không có gì được phục vụ (không có mô hình nào khả dụng, lỗi trước khi câu trả lời bắt đầu), không có khoản nào được tính.

Thử với curl

curl -i https://api.uberllm.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"deepseek/deepseek-v4-flash","max_tokens":200,"messages":[{"role":"user","content":"Hello"}]}'
# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi…
#
# {"x402Version":2,"error":"PAYMENT-SIGNATURE header is required",
#  "accepts":[{"scheme":"upto","network":"eip155:8453","amount":"…","asset":"0x8335…2913","payTo":"0x…",…},
#             {"scheme":"exact",…}]}

amount tính theo đơn vị cơ sở USDC: 1,000,000 là $1. Ký một mục của accepts bằng ví của bạn. Sau đó gửi lại yêu cầu tương tự với -H 'PAYMENT-SIGNATURE: <base64 payment>'.

Từ code

Một thư viện client x402 thực hiện việc ký 402, và thử lại giúp bạn. Trong JavaScript:

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await pay("https://api.uberllm.dev/v1/chat/completions", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    model: "deepseek/deepseek-v4-flash",
    max_tokens: 200,
    messages: [{ role: "user", content: "Hello" }],
  }),
});
console.log(await res.json());

Để chỉ trả đúng chi phí thực, hãy đăng ký thêm UptoEvmScheme từ @x402/evm/upto/client. Các thư viện cho Go và Python được liệt kê tại x402.org.

Những điều cần biết

• Streaming hoạt động. Với "stream": true, câu trả lời sẽ được streaming như bình thường. Thanh toán sẽ được thu khi luồng streaming kết thúc. Không có header PAYMENT-RESPONSE, vì các header đã được gửi trước đó. Ví của bạn sẽ hiển thị giao dịch chuyển tiền.
• Một ví, tối đa 4 yêu cầu trả phí cùng lúc.
• Nếu không thể thu phí sau khi có câu trả lời (ví dụ, ví đã bị rút hết tiền trong thời gian đó), một câu trả lời thông thường sẽ bị giữ lại và bạn nhận được 402 payment_failed. Ví đó sau đó không thể thanh toán trong 24 giờ.
• Phiên bản 1 x402 (header X-PAYMENT) không được chấp nhận. Hãy sử dụng client phiên bản 2.
• Có nhiều yêu cầu? Một tài khoản với tín dụng trả trước sẽ đơn giản hơn và không có bước on-chain: đăng ký.

Lỗi