Hoppa till huvudinnehåll
Den här handledningen använder en minimal API-begäran för att beskriva hela flödet för Ace Data Cloud X402. Målet är inte att först skriva komplex kod, utan att först förstå: varför den första begäran returnerar 402, vad som finns i accepts, och hur PAYMENT-SIGNATURE gör samma API-begäran till en betald begäran.

Förberedelser

Du behöver förbereda: X402 kräver ingen API Token vid anrop till Ace Data Cloud API. SDK:ts första begäran innehåller inte Authorization, Gateway returnerar 402 Payment Required och betalningskrav; SDK:t försöker automatiskt igen efter signering.

Installera SDK

Källkod och paketadresser: TypeScript:
Python:
Om du vill använda Solana behöver du även installera motsvarande beroenden:
Python-versionens Solana signer-beroenden ingår redan i acedatacloud-x402. Installations- och importkontrollutdata i en ren temporär miljö:
Resultatbeskrivning:
  • Både npm-paketen och PyPI-paketen är faktiskt publicerade paket, inte platshållarnamn i dokumentationen.
  • acedatacloud-x402[cli] installerar CLI:t, och underkommandot approve-permit2 kan användas för Permit2-auktorisering i upto-scenarier.

Den första begäran returnerar 402

Du kan först använda curl för att se vad en obetald begäran returnerar. Exemplet nedan medför ingen debitering eftersom det inte innehåller PAYMENT-SIGNATURE:
Svarskroppen innehåller en accepts-array, med en vanlig struktur enligt följande:
Samma challenge-innehåll placeras också i base64-format i svarsheadern PAYMENT-REQUIRED, så att klienten kan läsa betalningskraven utan att parsa body. Programutdatasammanfattningen för en obetald begäran till produktions-API:t är följande:
Resultatbeskrivning:
  • Den första begäran innehåller inte Authorization eller PAYMENT-SIGNATURE, så den returnerar HTTP 402 och medför ingen debitering.
  • accepts är den enda tillförlitliga signaturgrunden för den här begäran och innehåller valbara nätverk, scheme, beloppsgräns, mottagaradress och tillgångsadress.
  • network är en CAIP-2-identifierare, klienten måste matcha enligt CAIP-2-strängen när den väljer nätverk.
  • Det maximala beloppet för denna minimala chattbegäran med gpt-4o-mini är 95215 atomic USDC, det vill säga 0.095215 USDC.
  • Varje begäran bör läsa det aktuella 402-svaret, hårdkoda inte exempelbelopp i affärskoden.
Fältens betydelse:

Slutför betalningsförsök igen med SDK

Nedan är ett minimalt TypeScript-exempel. Det anger network: 'base', handlern väljer Base payment requirement från det aktuella 402-svaret; det faktiska beloppet och mottagaradressen baseras fortfarande på accepts:
Fyra steg sker bakom den här koden:
  1. SDK:t skickar en vanlig API-begäran utan Authorization.
  2. Gateway returnerar 402 Payment Required och accepts.
  3. createX402PaymentHandler väljer payment requirement för network = 'base' och signerar PAYMENT-SIGNATURE.
  4. SDK:t försöker igen med samma begärandetext, och Gateway anropar Facilitator för att verifiera och reglera innan den släpper igenom till mål-API:t.

Visa Facilitators funktioner som stöds

X402 API är inte beroende av en resurskatalog. Klienten anropar direkt ett känt API och använder 402 Payment Required och accepts som returneras i realtid av den begäran som enda grund för pris och signatur. Facilitators funktionsdeklaration finns på:
Den beskriver endast /supported, /verify, /settle och de betalningsnätverk som för närvarande är aktiverade, och listar inte API-resurser. Ace Data Clouds produktionsadress för Facilitator är:
Du kan se vilka nätverk och scheman den stöder:
De returnerade kinds listar de nätverk och scheman som Facilitator stöder. Vid faktiska anrop gäller fortfarande det accepts som returneras av API:t. Utdata från Facilitator /supported:
Resultatet innebär:
  • /supported visar att Facilitator har kapacitet att verifiera och reglera dessa nätverk och scheman.
  • Både Base och Solana stöder exact; upto erbjuds för närvarande endast på Base.
  • Huruvida ett specifikt API tillåter ett visst nätverk avgörs fortfarande av API:ts 402 accepts.