Bayar per permintaan (x402)

Agen dengan dompet kripto dapat menggunakan UberLLM tanpa akun dan tanpa API key. Ini membayar untuk setiap permintaan dalam USDC di Base, menggunakan standar pembayaran terbuka x402 (versi 2).

Ini berfungsi untuk chat: POST /v1/chat/completions dan POST /v1/messages. Gambar, video, musik, dan ucapan masih memerlukan key.

Untuk memeriksa apakah pembayaran per permintaan diaktifkan, buka api.uberllm.dev/x402. Ini menunjukkan network, kontrak USDC, dan dompet yang menerima pembayaran. Jika jawabannya "404 not found", pembayaran per permintaan dinonaktifkan. Gunakan key sebagai gantinya (Quickstart).

Cara kerjanya

1. Kirim permintaan tanpa kunci. Jawabannya adalah HTTP 402 Payment Required. Header PAYMENT-REQUIRED (JSON base64, juga di dalam body) menyatakan berapa biaya maksimum permintaan tersebut, dan metode pembayaran apa saja yang diterima.
2. Dompet Anda menandatangani salah satu opsi tersebut. Kirim permintaan yang sama lagi dengan tanda tangan di header PAYMENT-SIGNATURE.
3. UberLLM memeriksa pembayaran, memberikan jawaban, lalu mengumpulkan pembayaran. Jawaban normal (non-streaming) disertai dengan tanda terima di header PAYMENT-RESPONSE, yang mencakup transaksi on-chain.

Setiap tanda tangan membayar untuk satu permintaan. Untuk membuat permintaan lain, tanda tangani lagi.

Apa yang Anda bayar

402 memperkirakan biaya maksimal yang mungkin dikenakan untuk permintaan tersebut. Itu adalah prompt Anda ditambah max_tokens output, pada rute termahal yang mungkin diambil oleh permintaan tersebut. Atur max_tokens untuk menjaga perkiraan biaya tetap rendah.

Ada dua cara untuk membayar:

• upto (ditawarkan pertama kali). Anda menyetujui perkiraan biaya sebagai batas maksimal. Setelah jawaban diberikan, hanya biaya sebenarnya yang dikenakan, dibulatkan ke atas hingga sepersejuta dolar berikutnya. Pembayaran pertama memerlukan persetujuan USDC satu kali. Jika layanan pembayaran mendukungnya, persetujuan tersebut tidak memerlukan gas.
• exact. Jumlah perkiraan penuh dikenakan, meskipun permintaan menghabiskan biaya lebih sedikit. Tidak ada yang dikembalikan. Pilih exact hanya jika dompet Anda tidak dapat melakukan upto.

Anda tidak akan pernah dikenakan biaya lebih dari jumlah yang Anda setujui. Jika tidak ada yang diberikan (tidak ada model yang tersedia, terjadi kesalahan sebelum jawaban dimulai), tidak ada yang dikenakan.

Coba dengan 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 dalam unit dasar USDC: 1,000,000 adalah $1. Tanda tangani satu entri dari accepts dengan dompet Anda. Kemudian kirim permintaan yang sama lagi dengan -H 'PAYMENT-SIGNATURE: <base64 payment>'.

Dari kode

Pustaka klien x402 melakukan penandatanganan 402, dan percobaan ulang untuk Anda. Dalam 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());

Untuk membayar hanya biaya sebenarnya, juga daftarkan UptoEvmScheme dari @x402/evm/upto/client. Pustaka untuk Go dan Python terdaftar di x402.org.

Perlu Diketahui

• Streaming berfungsi. Dengan "stream": true, jawaban akan di-stream seperti biasa. Pembayaran ditagih saat stream berakhir. Tidak ada header PAYMENT-RESPONSE, karena header sudah dikirim. Dompet Anda akan menunjukkan transfer tersebut.
• Satu dompet, maksimal 4 permintaan berbayar dalam satu waktu.
• Jika pembayaran tidak dapat ditagih setelah jawaban (misalnya, dompet dikosongkan sementara itu), jawaban normal akan ditahan dan Anda akan mendapatkan 402 payment_failed. Dompet tersebut kemudian tidak dapat membayar selama 24 jam.
• Versi 1 x402 (header X-PAYMENT) tidak diterima. Gunakan klien versi 2.
• Banyak permintaan? Akun dengan kredit prabayar lebih sederhana dan tidak memiliki langkah on-chain: daftar.

Kesalahan