Zum Hauptinhalt springen
X402 umfasst HTTP, SDK, Signaturen, Facilitator und On-Chain-Transaktionen. Bei der Untersuchung von Signatur- oder Abrechnungsproblemen wird empfohlen, schrittweise in der Reihenfolge „öffentlicher Einstiegspunkt -> 402-Antwort -> SDK payment handler -> On-Chain-settlement“ zu prüfen. Dieses Tutorial erläutert die Prüfmethoden für jede Ebene und führt häufige Fehler auf.

Öffentlichen Einstiegspunkt prüfen

Facilitator-Fähigkeitserklärung:
Wenn facilitator, supportedKinds und die Protokollendpunkte zurückgegeben werden, sind die Fähigkeitsmetadaten normal. Die API-Ressourcenerkennung wurde eingestellt; rufen Sie die Ziel-API direkt auf und orientieren Sie sich an der Echtzeit-402-Antwort. Vom Facilitator unterstützte Fähigkeiten:
Wenn kinds zurückgegeben wird, funktioniert der Facilitator-Einstiegspunkt normal.

402 accepts prüfen

Senden Sie eine nicht autorisierte Anfrage, die keine Gebühren verursacht:
Prüfen Sie, ob accepts in der Antwort das Netzwerk enthält, das Sie verwenden möchten. network ist eine CAIP-2-Kennung:
  • eip155:8453 + exact (Base)
  • eip155:8453 + upto (Base, nachgelagerte Verbrauchsmessung)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact (Solana)
Wenn das Zielnetzwerk nicht vorhanden ist, ist für diese API oder die aktuelle Umgebung keine entsprechende X402-Zahlungsmethode konfiguriert.

Erweiterte Verifizierungstools von X402Client ausführen

Das X402Client-Repository stellt erweiterte Verifizierungstools bereit, mit denen die Auswahl der 402-Antwort, die Signaturerstellung, paid retry und On-Chain-settlement bestätigt werden können. Sie benötigen eine funded wallet, RPC, einen privaten Schlüssel und Entwicklungsabhängigkeiten. Für die gewöhnliche Geschäftsintegration wird empfohlen, vorrangig das TypeScript- oder Python-SDK zu verwenden; führen Sie diese Tools nur aus, wenn Signatur- oder On-Chain-Abrechnungsprobleme lokalisiert werden müssen. Repository-Adresse: https://github.com/AceDataCloud/X402Client
Base:
Solana:
Die Verifizierungstools geben normalerweise Folgendes aus:
  1. Die 402-Antwort der ersten Anfrage.
  2. Die ausgewählte payment requirement.
  3. Die Zusammenfassung der signierten PAYMENT-SIGNATURE.
  4. HTTP-Status und Antwortkörper nach dem retry.
  5. Die On-Chain-settlement-Transaktion oder bei einem Fehler den vom Facilitator gemeldeten Fehlergrund.
Senden Sie keine privaten Schlüssel oder vollständigen PAYMENT-SIGNATURE-Werte an Log-Systeme oder Tickets. Beispiel für Ergebnisse der öffentlichen API-Verifizierung:
Erläuterung:
  • Base exact, Solana exact und Base upto haben alle den paid retry von HTTP 402 zu HTTP 200 abgeschlossen.
  • Die On-Chain-Transaktion von Base exact ist auf BaseScan auffindbar, und der Abrechnungsbetrag beträgt 95215 atomic USDC.
  • Die Signaturobergrenze von Base upto beträgt 95215 atomic USDC, aber das tatsächliche On-Chain-settlement beträgt 3 atomic USDC, was zeigt, dass bei der nachgelagerten Verbrauchsmessung gemäß dem tatsächlichen Verbrauch abgerechnet wird.
  • Der Solana-Pfad hat paid retry und Modellausgabe bestätigt. Öffentliche RPCs können gedrosselt werden; wenn eine strikte On-Chain-Abstimmung erforderlich ist, verwenden Sie bitte Ihren eigenen Solana-RPC oder bestätigen Sie die Transaktionssignatur anhand der Abrechnungsaufzeichnungen der Plattform.

SDK smoke test

Die erweiterten Verifizierungstools werden zur Prüfung von Signaturen und On-Chain-Abrechnungen verwendet. Auf Geschäftsseite sollte außerdem ein SDK smoke test durchgeführt werden, um zu bestätigen, dass der Anwendungscode 402 automatisch über den payment handler verarbeiten kann. Nachfolgend werden nur die Kernfragmente gezeigt; der vollständige Code muss wallet, provider und import ergänzen. TypeScript:
Python:
Wenn das Modell wie gefordert die feste Zeichenfolge zurückgibt, sind SDK, payment handler, Gateway, Facilitator und Ziel-API miteinander verbunden. Die beiden obigen smoke tests verwenden Base exact und rechnen zum in der 402-Preisangabe festgelegten Betrag ab. Chat-Vervollständigungen sind ein nach Tokens abgerechnetes Szenario; bei der produktiven Integration wird empfohlen, preferScheme: 'upto' zu übergeben (in Python prefer_scheme="upto"), um gemäß dem tatsächlichen Verbrauch abzurechnen. Das Rückgabeobjekt des Python SDK ist ein dict; Inhalte können mit res["choices"][0]["message"]["content"] gelesen werden.

E2E für Bestellzahlungen

Bestellzahlungen verwenden die Plattform-API von platform.acedata.cloud und benötigen ein Plattformkonto-Token. Die vollständige Kette lautet: Eine Pending-Bestellung erstellen, mit POST /api/v1/orders/{order_id}/pay/ 402 auslösen und dann mit PAYMENT-SIGNATURE wiederholen. Beispiel für Verifizierungsergebnisse einer Kleinbestellungszahlung:
Die folgenden Transaktionsaufzeichnungen sind historische Testbeispiele unter der alten Richtlinie; Beträge und Transaktions-Hashes bleiben unverändert erhalten. Neue X402-Bestellungen bieten keine Rabatte für Zahlungsmethoden mehr; verwenden Sie bitte den amount in der jeweiligen 402-Antwort als Grundlage für Signatur und Zahlung.
Ergebniserklärung:
  • Nach dem Erstellen der Bestellung ist der Bestellstatus Pending, und der Preis beträgt 1.26.
  • Die erste pay/-Anfrage gibt HTTP 402 zurück, in accepts gibt es Base exact und Solana exact, die Beträge sind jeweils 1200000 atomic USDC.
  • Nach erneutem Versuch mit Base PAYMENT-SIGNATURE wird HTTP 200 zurückgegeben, der Bestellstatus ändert sich zu Finished, und pay_way ist X402.
  • Nach dem Dekodieren von PAYMENT-RESPONSE werden success=True, network=base angezeigt und derselbe Transaktions-Hash angegeben.
  • Auf BaseScan ist der Transaktionsstatus 1, der Überweisungsbetrag beträgt 1200000 atomic USDC, also 1.2 USDC.
  • Der Erstellungspreis 1.26 wurde während des alten X402-Zahlungsrabattzeitraums bezahlt, der endgültige Signatur- und Abrechnungsbetrag beträgt 1.2 USDC.
Wenn die Bestellzahlung kein Authorization: Bearer {platform_token} hat oder die Bestellung nicht zum aktuellen Konto gehört, schlägt sie auf der Plattformberechtigungsebene fehl; dies unterscheidet sich von der kontolosen X402-API beim direkten Aufruf von x402.acedata.cloud.

Häufige Fehler

Base-upto-Checkliste

upto wird derzeit nur auf Base bereitgestellt (eip155:8453). Da die upto-Signatur an mehr EVM typed data-Parameter gebunden wird, sollten bei der Integration besonders die Echtzeitfelder in der 402-Antwort und die Client-Signatur auf vollständige Übereinstimmung geprüft werden.
Wenn Base upto invalid_upto_evm_payload_invalid_signature zurückgibt, zuerst Folgendes prüfen:
  1. extra.chainId im von der API zurückgegebenen Eintrag eip155:8453 + upto (sollte 8453 sein).
  2. Die von der API zurückgegebene extra.facilitatorAddress.
  3. Die von https://facilitator.acedata.cloud/supported zurückgegebene Base-upto-Facilitator-Adresse.
  4. Permit2 domain, spender, USDC-Vertrag und Signaturkonto.
  5. Ob die Wallet bereits Permit2 für Base USDC approve hat.
Der Signatur-digest von upto bindet gleichzeitig Permit2 domain, chain ID, spender, Empfängeradresse, Facilitator-Adresse und validAfter. Bei Inkonsistenz eines beliebigen Elements stellt der Facilitator den falschen signer wieder her und gibt dadurch invalid signature zurück. Wenn all diese übereinstimmen, aber weiterhin 402 zurückgegeben wird, im nächsten Schritt Permit2 allowance prüfen; bei fehlender Autorisierung wird PERMIT2_ALLOWANCE_REQUIRED zurückgegeben.

Verifizierungsinformationen speichern

Bei einer vollständigen Verifizierung mindestens speichern:
  • API path und Anfragekörper-Zusammenfassung;
  • das ausgewählte network und scheme;
  • maxAmountRequired;
  • die payer-Wallet-Adresse;
  • den endgültigen HTTP-Status;
  • die Modellausgabe oder Aufgaben-ID in der Antwort;
  • den settlement transaction-Link;
  • Gateway trace ID oder Plattformnutzungsdatensatz-ID.
Keine privaten Schlüssel, keine vollständige PAYMENT-SIGNATURE, keine vollständige EIP-712 signature und keine Seed-Phrase speichern.

Strukturierte Zahlungsfehler

X402-Fehler nach der Signatur geben unter extensions.acedatacloud.paymentError einen stabilen code, sichere Interpolationsparameter, Phase und Wiederholbarkeitskennzeichen zurück. Zur Fehlerbehebung vorrangig diese Struktur verwenden, nicht den englischen error der obersten Ebene parsen und Benutzer nicht auffordern, Wallet-Signaturen oder Originaltexte von On-Chain-Simulationen bereitzustellen.
  • charged: false: Die Verifizierung wurde vor dem settlement eindeutig abgelehnt, bei diesem Vorgang wurde keine Belastung ausgelöst.
  • Ohne charged: Das Ergebnis ist unbekannt oder hat bereits die settlement-Phase erreicht, zuerst Bestellung und On-Chain-Status prüfen, direkte Wiederholungszahlung ist verboten.
  • settlement_pending: Zahlung vorerst nicht wiederholen, zuerst Bestellung aktualisieren oder den Support kontaktieren.
  • Nicht erkannter code: Als payment_failed behandeln und den öffentlichen technischen Code für die Suche durch den Kundenservice aufbewahren.