Hoppa till huvudinnehåll
X402 omfattar HTTP, SDK, signaturer, Facilitator och on-chain-transaktioner. Vid felsökning av signatur- eller avräkningsproblem rekommenderas att bekräfta lager för lager i ordningen ”offentlig ingång -> 402-svar -> SDK payment handler -> on-chain settlement”. Den här guiden beskriver kontrollmetoderna för varje lager och listar vanliga fel.

Kontrollera offentlig ingång

Facilitator-kapacitetsdeklaration:
Om facilitator, supportedKinds och protokolländpunkter returneras betyder det att kapacitetsmetadata är korrekt. API-resursupptäckt har avvecklats; anropa mål-API:t direkt och utgå från det aktuella 402-svaret. Facilitator-stödda kapaciteter:
Om kinds returneras betyder det att Facilitator-ingången fungerar korrekt.

Kontrollera 402 accepts

Skicka en oautentiserad begäran som inte debiteras:
Kontrollera om accepts i svaret innehåller det nätverk du vill använda. network är en CAIP-2-identifierare:
  • eip155:8453 + exact (Base)
  • eip155:8453 + upto (Base, efterföljande mätning)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact (Solana)
Om målnätverket saknas betyder det att detta API eller den aktuella miljön inte har konfigurerats med motsvarande X402-betalningsmetod.

Kör X402Clients avancerade verifieringsverktyg

X402Client-förrådet tillhandahåller avancerade verifieringsverktyg som kan användas för att bekräfta val av 402-svar, signaturgenerering, paid retry och on-chain settlement. De kräver funded wallet, RPC, privata nycklar och utvecklingsberoenden. För vanlig affärsintegration rekommenderas att i första hand använda TypeScript- eller Python-SDK:t; kör dessa verktyg endast när du behöver lokalisera problem med signaturer eller on-chain-avräkning. Förrådsadress: https://github.com/AceDataCloud/X402Client
Base:
Solana:
Verifieringsverktygen skriver normalt ut:
  1. 402-svaret för den första begäran.
  2. Det valda payment requirement.
  3. Sammanfattningen av den signerade PAYMENT-SIGNATURE.
  4. HTTP-status och svarskropp efter återförsöket.
  5. On-chain settlement transaction, eller Facilitator-felorsaken vid misslyckande.
Skicka inte privata nycklar eller fullständiga PAYMENT-SIGNATURE till loggsystem eller supportärenden. Exempel på verifieringsresultat för offentligt API:
Förklaring:
  • Base exact, Solana exact och Base upto har alla slutfört paid retry från HTTP 402 till HTTP 200.
  • On-chain-transaktionen för Base exact kan hittas i BaseScan, och avräkningsbeloppet är 95215 atomic USDC.
  • Signaturgränsen för Base upto är 95215 atomic USDC, men faktisk on-chain settlement är 3 atomic USDC, vilket visar att efterföljande mätning debiterar enligt faktisk användning.
  • Solana-sökvägen har bekräftat paid retry och modellutdata. Offentliga RPC:er kan begränsa trafik; om strikt on-chain-avstämning krävs ska du använda en egen Solana RPC eller bekräfta transaktionssignaturen via plattformens avräkningsregister.

SDK smoke test

Avancerade verifieringsverktyg används för att kontrollera signaturer och on-chain-avräkning. Verksamhetssidan bör även utföra SDK smoke test för att bekräfta att applikationskoden automatiskt kan hantera 402 via payment handler. Nedan visas endast kärnutdragen; komplett kod behöver kompletteras med wallet, provider och import. TypeScript:
Python:
Om modellen returnerar den fasta strängen enligt instruktionerna betyder det att SDK, payment handler, Gateway, Facilitator och mål-API:t är sammankopplade. De två ovanstående smoke testen använder Base exact och avräknas med det fasta belopp som anges i 402-offerten. Chat completions är ett tokenmätt scenario; vid produktionsintegration rekommenderas att ange preferScheme: 'upto' (i Python prefer_scheme="upto") för avräkning enligt faktisk användning. Python SDK:s returobjekt är dict; innehållet kan läsas med res["choices"][0]["message"]["content"].

E2E för orderbetalning

Orderbetalning använder plattforms-API:t för platform.acedata.cloud och kräver en plattformskontotoken. Den fullständiga kedjan är: skapa en Pending-order, utlös 402 med POST /api/v1/orders/{order_id}/pay/, och försök sedan igen med PAYMENT-SIGNATURE. Exempel på verifieringsresultat för betalning av små order:
Följande transaktionsposter är historiska testexempel från tidigare policyer, och belopp samt transaktionshashar har behållits oförändrade. Nya X402-order har inte längre rabatt för betalningsmetoder; använd amount i det aktuella 402-svaret som grund för signering och betalning.
Resultatbeskrivning:
  • Efter att ordern skapats är orderstatusen Pending och priset är 1.26.
  • Den första pay/-begäran returnerar HTTP 402. accepts innehåller Base exact och Solana exact, och beloppen är båda 1200000 atomic USDC.
  • Efter omförsök med Base PAYMENT-SIGNATURE returneras HTTP 200, orderstatusen ändras till Finished och pay_way är X402.
  • Efter avkodning av PAYMENT-RESPONSE visas success=True, network=base, och samma transaktionshash anges.
  • På BaseScan är transaktionsstatusen 1, överföringsbeloppet är 1200000 atomic USDC, alltså 1.2 USDC.
  • Skaparpriset 1.26 betalades under den gamla X402-betalningsrabattpolicyn, och det slutliga signatur- och avräkningsbeloppet är 1.2 USDC.
Om orderbetalningen saknar Authorization: Bearer {platform_token}, eller om ordern inte tillhör det aktuella kontot, misslyckas den i plattformens behörighetslager; detta skiljer sig från det kontolösa X402 API:et som anropar x402.acedata.cloud direkt.

Vanliga fel

Checklista för Base upto

upto tillhandahålls för närvarande endast på Base (eip155:8453). Eftersom upto-signaturen binder fler EVM typed data-parametrar bör man vid integration särskilt bekräfta att realtidsfälten i 402-svaret helt överensstämmer med klientsignaturen.
Om Base upto returnerar invalid_upto_evm_payload_invalid_signature, kontrollera först:
  1. extra.chainId i eip155:8453 + upto-posten som API:et returnerar (ska vara 8453).
  2. extra.facilitatorAddress som API:et returnerar.
  3. Base upto facilitator-adressen som returneras av https://facilitator.acedata.cloud/supported.
  4. Permit2 domain, spender, USDC-kontraktet och signeringskontot.
  5. Om plånboken redan har approve:at Permit2 för Base USDC.
upto-signaturens digest binder samtidigt Permit2 domain, chain ID, spender, mottagaradress, facilitator-adress och validAfter. Om någon av dessa inte stämmer överens återställer Facilitator fel signer och returnerar därmed invalid signature. Om dessa alla stämmer överens men 402 ändå returneras, kontrollera sedan Permit2 allowance; om behörighet saknas returneras PERMIT2_ALLOWANCE_REQUIRED.

Spara verifieringsinformation

En fullständig verifiering sparar åtminstone:
  • API path och sammanfattning av begärandetexten;
  • valt network och scheme;
  • maxAmountRequired;
  • payer-plånboksadress;
  • slutlig HTTP-status;
  • modellutdata eller task ID i svaret;
  • settlement transaction-länk;
  • Gateway trace ID eller plattformens användningspost-ID.
Spara inte privata nycklar, fullständig PAYMENT-SIGNATURE, fullständig EIP-712 signature eller seed phrase.

Strukturerade betalningsfel

Signerade X402-fel returnerar stabil code, säkra interpoleringsparametrar, fas och återförsöksflagga i extensions.acedatacloud.paymentError. Använd i första hand denna struktur för felsökning, parsa inte det engelska error på toppnivå och be inte heller användare att tillhandahålla plånbokssignaturer eller originaltext från simuleringar på kedjan.
  • charged: false: verifieringen avvisades uttryckligen före settlement, och ingen debitering initierades denna gång.
  • Saknar charged: resultatet är okänt eller har redan gått in i settlement-fasen; kontrollera först ordern och statusen på kedjan, och upprepa inte betalningen direkt.
  • settlement_pending: upprepa inte betalningen tills vidare; uppdatera först ordern eller kontakta support.
  • Oigenkänd code: hantera som payment_failed och behåll offentlig teknisk kod för supportens sökning.