x402: HTTP 402 ile Ajan Ödeme Akışı

x402, 1997'den beri "rezervlenmiş ama kullanılmamış" HTTP 402 Payment Required durum kodunu Coinbase 2025'te canlı kullanılır hale getirdi. Bir ajan API'nizi çağırdığında, anında — kredi kartı veya invoice olmadan — USDC ile ödeme yapabiliyor. AIDE'nin commerce-x402 ve x402-pass kontrolleri bu altyapının doğru kurulduğunu doğruluyor.

Bağlam: AIDE bu kontrolde tam olarak neye bakıyor?

commerce-x402 üç adımı kontrol eder:

Korumalı bir endpoint'e auth'suz istek 402 dönüyor mu?
402 cevabında WWW-Authenticate: x402 header'ı var mı?
Body içinde valid x402 paywall objesi (scheme: exact, network, maxAmountRequired, payTo, asset) var mı?

x402-pass ek olarak ödeme akışının uçtan uca çalıştığını test eder — yani facilitator + settlement.

Neden x402?

Geleneksel API monetizasyonu (Stripe + API key) ajan-tarafı için zor:

API key işlemi insan kontrolü gerektiriyor
Fatura döngüsü 30 gün; agent on saniye sonra başka şey yapacak
Kart numarası paylaşmak agent için risk

x402 bunu çözüyor: HTTP 402 alan ajan, cüzdanından USDC ile (saniyeler içinde, on-chain) ödeyip aynı request'i tekrar gönderiyor. Mikro-ödeme (1 cent altı) ekonomik.

Minimum sunucu

Express + x402-express middleware ile başlangıç:

// server.js
import express from "express"
import { x402Middleware } from "x402-express"

const app = express()

app.use(
  "/api/scan",
  x402Middleware({
    network: "base",
    payTo: "0xYourReceiverAddress",
    asset: {
      address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC on Base
      decimals: 6,
      symbol: "USDC"
    },
    pricing: {
      "/api/scan": "0.05"  // 5 cent per scan
    },
    facilitator: "https://x402.org/facilitator"
  })
)

app.post("/api/scan", async (req, res) => {
  // Buraya geldiyse ödeme verified — gerçek scan'i çalıştır
  const result = await runScan(req.body.url)
  res.json(result)
})

app.listen(3000)

Middleware şunu yapar:

İstek geldiğinde Authorization: x402 ... header arar.
Yoksa veya geçersizse 402 + paywall payload döndürür.
Varsa imzayı facilitator'a doğrulatır.
Settlement gerçekleştikten sonra request'i handler'a geçirir.

402 cevabının yapısı

HTTP/1.1 402 Payment Required
WWW-Authenticate: x402
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "50000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xYourReceiverAddress",
    "resource": "/api/scan",
    "description": "AIDE site tarama, sonuç başına 0.05 USDC",
    "mimeType": "application/json",
    "maxTimeoutSeconds": 60
  }],
  "error": "X-PAYMENT header is required"
}

Önemli alanlar:

| Alan | Anlam | AIDE etkisi | |---|---|---| | scheme: exact | Tam-tutarlı ödeme; "tip", "üyelik" gibi varyantlar yok | Diğer scheme'ler henüz spec dışı | | network | Hangi blockchain (base, base-sepolia, polygon) | Mainnet olmazsa AIDE WARNING — testnet ödemeleri "gerçek" sayılmıyor | | maxAmountRequired | İzin verilen tavan, atomik birim (USDC için 6 decimal) | Aşırı yüksek (>$1) → WARNING | | payTo | Alıcı cüzdan | Sıfır adres veya kontrat değilse FAIL | | maxTimeoutSeconds | İmzanın geçerlilik süresi | <30s → ajanlar yetişemiyor |

İkinci request: ödeme imzası

Ajan 402'yi alır, facilitator üzerinden bir EIP-3009 imzası üretir, aynı endpoint'i tekrar çağırır:

POST /api/scan HTTP/1.1
Authorization: x402 eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZSIsInBheWxvYWQiOiJ7XCJzaWduYXR1cmVcIjoiMHguLi4ifSJ9

{"url": "https://stripe.com"}

Authorization: x402 <base64> payload'u içinde imzalı transferWithAuthorization çağrısı. Sunucu facilitator'ı çağırır:

const verification = await fetch("https://x402.org/facilitator/verify", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({ paymentPayload, paymentRequirements })
})

isValid: true dönerse settlement tetiklenir, sonra /api/scan handler çağrılır.

Yaygın hatalar

| Hata | Belirti | Çözüm | |---|---|---| | Korumalı endpoint hâlâ 200 dönüyor | Middleware route'a takmamış | Route ordering — app.use(x402Middleware) sıra olarak handler'lardan önce olmalı | | Facilitator verify her zaman fail | Network mismatch (testnet vs mainnet) | Manifest'te network: "base" ama facilitator URL base-sepolia için olabilir; ikisini eşleştir | | 402 cevabı CORS engelleniyor | Browser-tabanlı agent çağıramıyor | Access-Control-Expose-Headers: WWW-Authenticate ekle | | maxAmountRequired çok düşük | Gas cost > ödeme | Base mainnet'te <0.001 USDC ekonomik değil; minimum 0.01 |

Test: AIDE'nin yaptığı şey

Manuel test için curl:

# 1. Auth'suz çağrı — 402 beklenmeli
curl -i https://api.siteniz.com/api/scan \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

Beklenen:

HTTP/1.1 402 Payment Required
WWW-Authenticate: x402

Yoksa: commerce-x402 FAIL. Sonra:

# 2. Tam taramayı tetikle
curl -X POST https://api.aide.tr/v1/scans \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://siteniz.com","profile":"ai_ready"}'

commerce-x402 PASS, x402-pass warning olabilir (E2E ödeme test edilmez varsayılan olarak).

Production için

Replay protection: Her imzanın nonce alanı olmalı; aynı imza iki kez kullanılmasın. Facilitator default olarak takip etmiyor — kendi DB'nizde seen_nonces tablosu tutun.
Refund yok: x402'de geri ödeme protokol seviyesinde yok. İşlem fail olursa içerik servis edilmemiş demektir; ajan başka request'le tekrar dener. Bunu tasarımdan garantilemen gerek (idempotent handler).
Pricing dynamic: Ajan başına farklı fiyat verebilirsiniz. priceModifier callback'i middleware'e geçer.
Audit log: Her başarılı settlement'ı ClickHouse/Postgres'e yazın — vergi raporlaması için tx hash ve amount lazım.

İlgili kaynaklar

x402 Spec
x402-express
x402.org Facilitator
AIDE check detayları: /learn/commerce-x402, /learn/x402-pass
Genel ticaret ekosistemi: /learn/agentic-commerce-mimari