Öffentlichen Einstiegspunkt prüfen
Facilitator-Fähigkeitserklärung: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:
kinds zurückgegeben wird, funktioniert der Facilitator-Einstiegspunkt normal.
402 accepts prüfen
Senden Sie eine nicht autorisierte Anfrage, die keine Gebühren verursacht:
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)
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- Die 402-Antwort der ersten Anfrage.
- Die ausgewählte payment requirement.
- Die Zusammenfassung der signierten
PAYMENT-SIGNATURE. - HTTP-Status und Antwortkörper nach dem retry.
- Die On-Chain-settlement-Transaktion oder bei einem Fehler den vom Facilitator gemeldeten Fehlergrund.
PAYMENT-SIGNATURE-Werte an Log-Systeme oder Tickets.
Beispiel für Ergebnisse der öffentlichen API-Verifizierung:
- Base
exact, Solanaexactund Baseuptohaben alle den paid retry von HTTP 402 zu HTTP 200 abgeschlossen. - Die On-Chain-Transaktion von Base
exactist auf BaseScan auffindbar, und der Abrechnungsbetrag beträgt95215atomic USDC. - Die Signaturobergrenze von Base
uptobeträgt95215atomic USDC, aber das tatsächliche On-Chain-settlement beträgt3atomic 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: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 vonplatform.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.
- Nach dem Erstellen der Bestellung ist der Bestellstatus
Pending, und der Preis beträgt1.26. - Die erste
pay/-Anfrage gibt HTTP 402 zurück, inacceptsgibt es Baseexactund Solanaexact, die Beträge sind jeweils1200000atomic USDC. - Nach erneutem Versuch mit Base
PAYMENT-SIGNATUREwird HTTP 200 zurückgegeben, der Bestellstatus ändert sich zuFinished, undpay_wayistX402. - Nach dem Dekodieren von
PAYMENT-RESPONSEwerdensuccess=True,network=baseangezeigt und derselbe Transaktions-Hash angegeben. - Auf BaseScan ist der Transaktionsstatus
1, der Überweisungsbetrag beträgt1200000atomic USDC, also1.2USDC. - Der Erstellungspreis
1.26wurde während des alten X402-Zahlungsrabattzeitraums bezahlt, der endgültige Signatur- und Abrechnungsbetrag beträgt1.2USDC.
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.
upto invalid_upto_evm_payload_invalid_signature zurückgibt, zuerst Folgendes prüfen:
extra.chainIdim von der API zurückgegebenen Eintrageip155:8453+upto(sollte8453sein).- Die von der API zurückgegebene
extra.facilitatorAddress. - Die von
https://facilitator.acedata.cloud/supportedzurückgegebene Base-upto-Facilitator-Adresse. - Permit2 domain, spender, USDC-Vertrag und Signaturkonto.
- Ob die Wallet bereits Permit2 für Base USDC approve hat.
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.
PAYMENT-SIGNATURE, keine vollständige EIP-712 signature und keine Seed-Phrase speichern.
Strukturierte Zahlungsfehler
X402-Fehler nach der Signatur geben unterextensions.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_failedbehandeln und den öffentlichen technischen Code für die Suche durch den Kundenservice aufbewahren.

