x402, HTTP 402 Payment Required kodunu temel alan, web servisleri ve API’ler için “kullan-ödeme” (pay-per-use) modeli sağlayan bir açık protokoldür. Amaç, uygulamalara, içeriklere veya API’lara erişim için hafif, zincir-agnostik bir ödeme katmanı sunmaktır; kayıt, token, API anahtarı veya merkezi abonelik gerektirmeden. x402; HTTP, on-chain ödemeler, facilitator/relayer modelleri ve mikro-ödeme akışlarını birleştirir.
İçindekiler
- Giriş — Neden x402?
- Temel Fikir ve Hedefler
- Teknik Mimarinin Genel Hatları
- İstek / Yanıt Akışı (Adım Adım)
- Bileşenler — Sunucu, Facilitator, Cüzdan, Ağ
- Protokol Detayları — HTTP Başlıkları, Mesaj Şemaları
- Ödeme Onayı, Zaman Aşımı ve Hata Senaryoları
- Zincir / Token Agnostikliği ve Örnek Paraleşme Akışları
- Güvenlik Modeli ve Saldırı Yüzeyleri
- Uygulama Örnekleri ve Entegrasyon Rehberi
- İş Modeli, Ücretlendirme ve Ekonomik Tasarım
- Yönetişim, Standardizasyon ve Ekosistem
- İzleme, Telemetri ve Başarı Metrikleri
- Zorluklar, Eleştiriler ve Riskler
- Sonuç ve Tavsiyeler
- Sıkça Sorulan Sorular (FAQ)
1) Giriş — Neden x402?
Geleneksel web hizmetleri için ödeme veya abonelik genelde:
- Hesap oluşturma,
- API anahtarı yönetimi,
- Kredi kartı/abonelik altyapısı,
- KYC/AML süreçleri gerektirir.
Bu süreçler hem kullanıcı deneyiminde sürtünme yaratır hem de makine-makine (M2M) kullanımını zorlaştırır. x402, özellikle mikro-ödeme senaryoları (API çağrıları başına ücret, içerik başına ödeme) ve otomasyon (AI ajanları, IoT) için düşük sürtünmeli, açık bir protokol sunmayı hedefler.
2) Temel Fikir ve Hedefler
- HTTP native: Mevcut web istek/yanıt akışına ek minimal başlıklarla entegre edilir.
- On-chain ödeme ile erişim: Ödeme kanıtı (transaction hash veya facilitator imzası) HTTP başlığıyla taşınır.
- Facilitator modeli: Sunucu kendi on-chain altyapısını kurmak zorunda değildir; doğrulama bir facilitator/relayer üzerinden yapılabilir.
- Zincir agnostik: Protokol herhangi bir token/chain ile çalışacak şekilde tasarlanmıştır.
- Mikro-ödeme ve M2M odaklı: Hızlı, küçük değerli işlemler için uygundur.
3) Teknik Mimarinin Genel Hatları
- Client (Kullanıcı/Agent): Ödemeyi başlatan taraf; cüzdan entegrasyonu veya programatik ajan.
- Origin Server (İçerik sağlayıcı): İçeriği barındıran HTTP sunucu. Ödeme gerektiren kaynaklar
402döndürebilir. - Facilitator / Relayer: Ödeme doğrulaması, işlem toplama, on-chain etkileşim ve karşı tarafla uzlaşma işini yapar.
- Blockchain / Settlement Layer: Ödemenin gerçekleştiği yer (herhangi bir chain / stablecoin).
- Optional Gateway (API Aggregator): Çok sayıda küçük ödeme için paketleme veya ön ödeme işlevleri sağlayabilir.
Mimari açısından facilitator kritik: sunucu karmaşık on-chain doğrulamayı ona devreder ve basit HTTP işleyişiyle devam eder.
4) İstek / Yanıt Akışı (Basit Örnek)
- Client
GET /paywalled-resourceisteği gönderir. - Origin Server
402 Payment Requiredile yanıt verir; body veya header içinde ödeme koşulları (fiyat, token, facilitator adresi, ödeme geçerlilik süresi) döner. - Client ödeme işlemini tetikler (cüzdandan transfer veya facilitator aracılığı).
- Ödeme tamamlandığında client yeni istekte
X-PAYMENT: <payment-proof>başlığını ekler. - Origin Server veya facilitator ödeme kanıtını doğrular, başarılıysa 200 OK + içerik döner.
Örnek akış:
→ GET /article/123 HTTP/1.1
Host: api.example.com
← HTTP/1.1 402 Payment Required
X-402-Price: 0.0005 USDC
X-402-Currency: USDC
X-402-Facilitator: 0xFacilitatorAddr
X-402-Expires: 1698507600
Content-Type: application/json
Body: { "message": "Payment required", "instructions": "..." }
→ POST /article/123 HTTP/1.1
Host: api.example.com
X-PAYMENT: txhash_or_facilitator_signature
5) Bileşenler — Roller ve Sorumluluklar
Origin Server
402koşullarını belirler (fiyat, geçerlilik, accepted token listesi).- Facilitator’ı kabul eder veya kendi on-chain doğrulamasını yapar.
Facilitator / Relayer
- Ödemeyi toplar, doğrular, gerekirse off-chain kayıt tutar.
- Sunucuya ödeme onayı dönerek erişim sağlar.
- Güvenilir facilitator çok kritik; decentralize facilitator ağları önerilir.
Client
- Ödeme yapar, proof üretir.
- Akıllı cüzdan veya programatik ödeme ajanı ile çalışabilir.
Blockchain / Settlement Layer
- Ödeme kayıtları; gas/settlement burada gerçekleşir.
6) Protokol Detayları — HTTP Başlıkları ve Mesaj Formatları
Tipik x402 başlık seti :
X-402-Price: Fiyat miktarı (örn. 0.0005)X-402-Currency: Ödeme birimi (örn. USDC, WETH)X-402-Facilitator: Facilitator adresi veya endpointX-402-Expires: Ödeme teklifinin sona ereceği UNIX timestampX-402-Invoice: Benzersiz ödeme kimliği (UUID)X-PAYMENT: İkinci istekte gönderilecek payment proof (tx hash veya facilitator imzası)X-402-Signature(opsiyonel): Sunucu veya facilitator tarafından imzalanmış ödeme talebi
Payment Proof:
- Basit: on-chain transaction hash (örn.
0xabc...123) - Gelişmiş: facilitator tarafından üretilmiş, sunucuya doğrulanabilir imzalı JSON (örnek:
{ invoice, txhash, payer, signature })
7) Ödeme Onayı, Zaman Aşımı ve Hata Senaryoları
- Zaman aşımı:
X-402-Expiressüresi geçince isteğin yenilenmesi gerekir. - Double-spend / Re-org: On-chain ödemelerde chain reorg riskine karşı yeterli confirmations beklenebilir veya facilitator bir süzgeç sağlar.
- Facilitator unreachable: Sunucu, alternatif facilitator listesi veya kendi on-chain doğrulamasına fallback yapabilir.
- Partial payment: Eğer fiyat değişir veya kısmi ödeme kabul ediliyorsa protocol extension gerekir (ör.
X-402-Partially-Accepted).
8) Zincir / Token Agnostikliği ve Örnek Para Akışları
x402’nin avantajı zincir agnostik olmasıdır — USDC (stablecoin), ETH, WETH, veya proje token’ı kullanılabilir. Ödeme akışı senaryoları:
- Direct on-chain transfer: Kullanıcı cüzdanından provider wallet’a transfer.
txhashproof. - Facilitator mediated: Kullanıcı facilitator’a küçük ödeme yapar; facilitator toplu on-chain işlem yapar ve sunucuya imzalı proof ile geri döner.
- Off-chain crediting: Kullanıcı ödeme yaptığını facilitator panelinde gösterir, facilitator API üzerinden sunucuya doğrulama yapar.
Bu modeller trade-off içerir: doğrudan on-chain şeffaf ama maliyetli; facilitator ekonomik ama güvene ihtiyaç duyar.
9) Güvenlik Modeli ve Saldırı Yüzeyleri
Potansiyel Saldırı Türleri
- Facilitator compromise: Facilitator ele geçirilirse ödeme doğrulamaları manipüle edilebilir.
- Replay / Forgery: Payment proof başlıklarının tekrar kullanılması (nonce ve expiry gereklidir).
- Front-running / MEV: On-chain micropaymentlerin frontrun edilmesi; facilitator toplu işlemleri korumalı.
- Denial of Service: Çok sayıda sahte ödeme talepleriyle facilitator/sunucu baskılanabilir.
Korunma Yöntemleri
- Zaman damgası (timestamp) ve nonce ile replay engelleme.
- Facilitator signature verification (public key ile imza doğrulama).
- Minimum confirmations veya facilitator on-chain settlement logic.
- Rate limiting ve otomatik bot-tespit (captcha/require KYC for high volume).
10) Uygulama Örnekleri ve Entegrasyon Rehberi
Basit Bir API için Entegrasyon Adımları
- Sunucu tarafı: Belirli endpoint’leri
protectedolarak işaretle, dönen402body/headers’i üret. - Facilitator seçimi: Güvenilir bir facilitator (veya kendi doğrulama) belirle.
- Client kütüphanesi: Ödeme tetikleyen ve
X-PAYMENTheader’ını ekleyen küçük bir SDK yaz. - Proof doğrulama: Sunucu facilitator API veya on-chain explorer ile tx doğrulaması yapar.
- Caching / Short-lived tokens: Ödeme sonrası kısa süreli erişim token’ı çıkartarak sunucunun tekrarlı on-chain doğrulamalardan kaçınmasını sağla.
(pseudocode)
# server: returns 402
if not has_valid_payment(request):
return Response(402, headers={
"X-402-Price": "0.0005",
"X-402-Currency": "USDC",
"X-402-Facilitator": "https://fac.example/verify",
"X-402-Expires": str(expiry_ts),
"Content-Type": "application/json"
}, body={"message":"Payment required"})
# client: after payment
request.headers["X-PAYMENT"] = payment_proof
resp = http.post("/resource", headers=request.headers)
11) İş Modeli, Ücretlendirme ve Ekonomik Tasarım
- Fiyatlama stratejileri: sabit ücret, dinamik ücret (talebe göre), freemium (ilk X istek ücretsiz).
- Facilitator fee: Facilitator küçük bir servis ücreti alabilir (maker / taker split).
- Revenue share: İçerik sağlayıcı ve facilitator arasında gelir paylaşım modeli.
- Microbilling aggregation: Çok küçük işlemleri facilitator toplar ve tek on-chain işlemle settle eder (gas optimizasyonu).
12) Yönetişim, Standardizasyon ve Ekosistem
- Açık protokoller için governance (foundation veya DAO) önemlidir. Protokol parametreleri (standart başlıklar, invoice şeması, facilitator onay kuralları) ortak kabul görmelidir.
- Facilitator ağları, multiple independent facilitator ile merkezi risk azaltılabilir.
13) İzleme, Telemetri ve Başarı Metrikleri
İzlenmesi gereken ana metrikler:
- Başarılı ödeme sayısı / zaman dilimi
- Ortalama ödeme onay süresi
- Facilitator uptime ve doğrulama latency
- Bot / failed payment oranı
- Gelir / gas maliyeti oranı (facilitator toplu settlement toplamı)
Bu metrikler hem ekonomik modelin sağlığını hem UX kalitesini gösterir.
14) Zorluklar, Eleştiriler ve Riskler
- Adoption problem: Geniş kabul için hem içerik sağlayıcıların hem de client tarafının SDK/altyapı kurması gerekir.
- Centralization of facilitators: İlk aşamada birkaç büyük facilitator hakimiyeti oluşabilir.
- Regulatory concerns: Mikro-ödeme / para transferi regülasyonları ülkelere göre farklılık gösterir.
- UX tradeoffs: Kullanıcıların cüzdan etkileşimi veya gas fee yönetimi dikkatli tasarlanmalı.
15) Sonuç ve Tavsiyeler
x402, web üzerinde anında, hafif ve zincir-agnostik ödeme deneyimi yaratma potansiyeli olan güçlü bir protokoldür.
Uygulama önerileri:
- Küçükilk adımlar: Beta programı, tek bir facilitator ile başlayıp sonra ağ genişlet.
- Kullanıcı deneyimi odaklı SDK: Cüzdan entegrasyonunu basitleştir (wallet connect, embedded signing).
- Güvenlik: Facilitator imza doğrulaması, nonce/expiry zorunlu, rate limiting.
- Ölçek: Mikro-ödeme toplama için aggregation pattern kullan.
16) Sıkça Sorulan Sorular
S: x402 sadece kripto bilen geliştiriciler için mi?
C: Hayır — facilitator ve SDK’lar geliştirildikçe son kullanıcı için transparan hale gelir; geliştiriciler minimal entegrasyon yapar.
S: Gas ücretleri kullanıcının mı olacak?
C: Model seçimine bağlı; doğrudan on-chain ödemede kullanıcı gas öder; facilitator modeliyle kullanıcı gas ücreti maskelenebilir.
S: Hangi kullanım senaryosu için ideal?
C: Pay-per-request API’lar, AI agent ücretlendirme, içerik mikro-ödeme, IoT kullanım senaryoları.
