x402 v2, X-PAYMENT yerine PAYMENT-SIGNATURE'a geçiyor ve 402 ödeme gövdesini yeniden şekillendiriyor

x402 ödeme protokolünün 2. sürümü yayımlandı ve v1'e göre yazılmış istemciler, yükseltilen sunuculara karşı sıradan bir 402 hatası gibi görünen biçimde başarısız olmaya başlayabilir. dev.to'da yayımlanan bir geçiş kılavuzuna göre genel akış değişmedi — istemci bir kaynak ister, 402 alır, bir ödemeyi imzalar ve yeniden dener — ama o 402 içindeki neredeyse tüm alan adları ve çevresindeki HTTP header'ları yeniden adlandırıldı.

Gönderi, yayımlanmış v1 ve v2 spesifikasyon belgelerinden yola çıkarak, yazarın işlettiği canlı bir v2 uç noktasına karşı doğrulanarak yazıldı; yazan, otonom bir yapay zekâ operatörü olan Penny'ydi. Kendi beyanında, kod örneklerinin yalnızca açıklayıcı olduğu ve uçtan uca çalıştırılmadığı belirtiliyor.

Üç header yeniden adlandırıldı

dev.to kılavuzu header değişikliklerini doğrudan eşleştiriyor:

Amaç	v1	v2
Sunucu ödeme gerektiğini bildirir	402 yanıtının JSON gövdesi	PAYMENT-REQUIRED yanıt header'ı (base64 JSON); birçok sunucu bunu gövdede de tutuyor
İstemci ödemesini gönderir	X-PAYMENT istek header'ı	PAYMENT-SIGNATURE istek header'ı
Sunucu mutabakat sonucunu döner	X-PAYMENT-RESPONSE	PAYMENT-RESPONSE

Dağıtımlar geçiş aşamasında olduğu için sunucular sıklıkla iki mutabakat header'ını da yayıyor ve kılavuz istemcilerin herhangi birini okumasını öneriyor.

402 belgesinin içinde ne değişti

PaymentRequired JSON'u yeniden adlandırmaların büyük kısmını taşıyor:

• accepts[].maxAmountRequired, accepts[].amount oluyor. Hâlâ atomik birimlerde bir string — USDC'nin altı basamağıyla "10000" değeri bir sente denk geliyor.
• Ağ tanımlayıcıları CAIP-2 biçimine geçiyor: "base-sepolia" eip155:84532 oluyor ve Base mainnet eip155:8453.
• Her accept seçeneğinin içinde duran kaynak string'i, url, mimeType ve description alanlarını tutan tek bir üst düzey resource nesnesine yükseltildi; böylece kaynak metadata'sı seçenek başına değil bir kez bildiriliyor.
• Yeni, isteğe bağlı bir extensions nesnesi ortaya çıkıyor ve istemcilerin bunu ödemeleriyle birlikte geri döndürmeleri bekleniyor.
• x402Version alanı 1'den 2'ye taşınıyor — her iki sürümü destekleyen istemciler için öngörülen dallanma noktası bu.

İmzalanan payload özünü koruyor

İstemcinin geri gönderdiği base64 belge de biçim değiştirdi. v1, ödeme header'ının üst düzeyinde scheme ve network alanlarını yineliyordu; v2 ise bunun yerine seçilen accepts[] girdisinin aynısını, üst düzeydeki resource ve extensions ile birlikte accepted anahtarı altında yineliyor.

Kılavuza göre önemli sabit şu: payload.authorization; tam EVM şeması için EIP-712 typed data olarak imzalanan bir EIP-3009 TransferWithAuthorization olmaya devam ediyor. Mevcut imzalama kodunun değişmesi gerekmiyor — yalnızca imzayı çevreleyen yapının değişmesi gerekiyor. CAIP-2 geçişinin bir yan etkisi de, EIP-712 chain ID'sinin artık bir ağ-adı arama tablosunda tutulmak yerine tanımlayıcının sayısal bölümünden doğrudan ayrıştırılabilmesi.

Bir uyumluluk kontrol listesi

Her iki sürümle de konuşması gereken istemciler için kılavuzun listesi şöyle:

• Önce PAYMENT-REQUIRED header'ını okuyun, yoksa yanıt gövdesine geri dönün.
• amount alanını okuyun, yoksa maxAmountRequired'a geri dönün.
• Ağ adları yerine CAIP-2 ağ tanımlayıcılarını ayrıştırın.
• x402Version'a göre PAYMENT-SIGNATURE ya da X-PAYMENT seçin.
• Seçilen seçeneği, resource ve extensions ile birlikte accepted olarak döndürün.
• PAYMENT-RESPONSE ya da X-PAYMENT-RESPONSE'tan herhangi birini kabul edin.

Yazar ayrıca test için düşük maliyetli canlı v2 uç noktalarına işaret ediyor; bunlar 402index'te "pennyagent" altında listeleniyor ve Base üzerinde USDC ile her biri birkaç sent tutuyor.

Neden önemli

Sürüm kayması buradaki başlıca pratik risk. Yalnızca v1 destekleyen bir istemci yükseltilmiş bir sunucuya çarptığında dostane bir hata almaz — ayrıştıramayabileceği bir 402 alır (v2 sunucular header ile öne geçiyor) ve adını bilmediği bir ödeme header'ı görür. Bu başarısızlık biçimi genel bir "ödeme gerekli" sorunu gibi görünür ve yanlış teşhis edilmesi kolaydır; alan alan yapılan bir karşılaştırmanın önlediği hasar tam olarak budur.

Yeniden adlandırmalar x402'yi ayrıca ortak zincirlerarası geleneklere yaklaştırıyor: CAIP-2 tanımlayıcıları, protokolün ağ referanslarını geçici adlara bağlı olmaktan çıkarıp daha geniş ekosistemle birlikte çalışabilir hale getiriyor. Entegrasyon yapanlar için çıkarım, sürüm algılamayı birinci sınıf bir konu olarak görmek — x402Version'a göre dallanın, geçiş süresince iki header yazımına da tahammül edin ve kılavuzun kendisinin de uyardığı gibi, göndermeden önce güncel spesifikasyona karşı doğrulayın; çünkü kılavuzun kod örnekleri hiçbir zaman uçtan uca çalıştırılmadı.