x402 Quick Start Guide#

HTTP 402 ("Payment Required") ist ein Web-Standard für maschinenlesbare Zahlungsanforderungen — ideal für AI Agents, die autonom bezahlen sollen. PayWatcher ist dein Verification Layer: dein Server empfängt USDC-Zahlungen, ruft /v1/payments/verify auf und erhält sofort Bestätigung, ob die Transaktion korrekt ist.

POST /v1/payments/verify#

Verifiziert eine eingehende USDC-Transaktion auf der Base-Chain.

Request#

bash

curl -X POST https://api.paywatcher.dev/v1/payments/verify \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_hash": "0xabc123...",
    "network": "base",
    "amount": "1.00",
    "to": "0xYOUR_DEPOSIT_ADDRESS",
    "tolerance_seconds": 300
  }'

Feld	Typ	Pflicht	Beschreibung
`tx_hash`	string	✓	Transaktions-Hash (0x...)
`network`	string	✓	Netzwerk: `base`
`amount`	string	✓	Erwarteter Betrag in USDC als Dezimalstring (z.B. `"1.00"`) — Währung ist immer USDC
`to`	string	✓	Deine Deposit-Wallet-Adresse
`tolerance_seconds`	number		Zeittoleranz für die Transaktion (Standard: 300)

Response — verified#

json

{
  "data": {
    "verified": true,
    "tx_hash": "0xabc123...",
    "network": "base",
    "amount": "1.00",
    "from": "0xAGENT_ADDRESS",
    "to": "0xYOUR_DEPOSIT_ADDRESS",
    "block_number": 43749345,
    "confirmations": 8,
    "timestamp": "2026-04-04T10:00:00Z"
  }
}

Response — not verified#

json

{
  "data": {
    "verified": false,
    "tx_hash": "0xabc123...",
    "network": "base",
    "amount": null,
    "from": null,
    "to": null,
    "block_number": null,
    "confirmations": null,
    "timestamp": null,
    "reason": "tx_not_found",
    "retry_after_seconds": 2
  }
}

Retry-Logik#

Wenn verified: false, enthält die Antwort einen reason. Manche Gründe sind temporär — dein Agent sollte in diesen Fällen nach retry_after_seconds erneut versuchen:

Reason	`retry_after_seconds`	Bedeutung
`tx_not_found`	`2`	Transaktion noch nicht im Mempool sichtbar
`insufficient_confirmations`	`3`	Zu wenige Block-Confirmations
`amount_mismatch`	`null`	Falscher Betrag — kein Retry sinnvoll
`wrong_recipient`	`null`	Falsche Empfängeradresse
`expired`	`null`	Transaktion außerhalb der Zeittoleranz

Wenn retry_after_seconds den Wert null hat, ist ein Retry nicht sinnvoll — die Zahlung muss neu angefordert werden.

Fehler-Codes#

HTTP Status	Code	Beschreibung
`400`	`VALIDATION_ERROR`	Ungültige oder fehlende Request-Parameter
`401`	`UNAUTHORIZED`	API-Key fehlt oder ungültig
`429`	`RATE_LIMITED`	Zu viele Anfragen — Rate Limit überschritten
`503`	`RPC_UNAVAILABLE`	Blockchain-Node temporär nicht erreichbar

Nächste Schritte#

Quick Start Guide — Payment Intent erstellen und Webhook empfangen
Endpoints — Vollständige API-Referenz
Dashboard — API-Keys verwalten und Verifications einsehen