Hoppa till huvudinnehåll
X402 är ett betalningsprotokoll på kedjan baserat på HTTP 402 Payment Required. Genom Ace Data Clouds X402-funktioner kan anroparen använda USDC för att slutföra betalningar på kedjan direkt i varje API-begäran, utan att skapa en API-token eller förskottsladda kontosaldot. Denna uppsättning dokument är organiserad enligt den faktiska integrationsordningen: kör först igenom en minimal begäran, integrera sedan SDK:n och förstå därefter nätverk, debiteringsmodeller, orderbetalning och Facilitator. Det rekommenderas att läsa från topp till botten enligt tabellen nedan.

Rekommenderad integrationsväg

Om du bara vill anropa Ace Data Cloud API, använd i första hand det officiella SDK:t:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Offentlig källkod och paketadresser: SDK:t slutför automatiskt stegen med den första oautentiserade begäran, tolkar 402 Payment Required, anropar payment handler och försöker igen med PAYMENT-SIGNATURE. Du behöver bara förbereda en plånbok med USDC och välja det nätverk du vill använda. Om du även vill att ditt eget API ska stödja X402-betalningsmottagning behöver du läsa Facilitator-dokumentationen för att förstå sambandet mellan paymentRequirements, paymentPayload, /verify och /settle.

Supportstatus

Ace Data Cloud X402 har verifierats i offentliga API:er, officiella SDK:er, Facilitator och avvecklingsflöden på kedjan. Tabellen nedan sammanfattar den aktuella statusen enligt de funktioner som utvecklare oftast använder vid integrering. Följande utdata används endast för att förklara returformatet för verifierade flöden. Vid faktisk integrering ska du alltid utgå från accepts som returneras av det aktuella API:et.
Förklaring:
  • Både npm- och PyPI-paketen har installerats och importerats framgångsrikt i rena miljöer.
  • Obetalda API-förfrågningar returnerar 402, och accepts innehåller tillgängliga betalningsmetoder för Base och Solana.
  • accepts[].network är en CAIP-2-identifierare, och klienten måste matcha enligt CAIP-2-strängen vid val av nätverk.
  • Både TypeScript SDK och Python SDK kan automatiskt hantera 402 och slutföra ett betalt återförsök.
  • Base exact, Base upto och orderbetalningar har alla explorer-adresser som kan öppnas offentligt.
  • Den signerade gränsen för Base upto är 95215 atomic USDC, och den faktiska settlementen är 3 atomic USDC, vilket återspeglar egenskapen hos efterdebiterad mätning där avräkning sker enligt faktisk användning.
  • Solana exact har verifierat HTTP 402 -> HTTP 200 och modellutdata. Eftersom offentliga RPC-frågor kan hastighetsbegränsas rekommenderas det att använda en egen Solana RPC eller plattformens settlement-register för att bekräfta transaktionssignaturen vid strikt avstämning.

Anslutningsanmärkningar

När utvecklare ansluter bör de prioritera de realtidsbetalningskrav som returneras av den aktuella förfrågan, i stället för att kopiera exempelbelopp eller adresser i dokumentationen:
  • accepts[].maxAmountRequired är det maximala belopp som kan signeras för den aktuella förfrågan.
  • accepts[].asset är det USDC-kontrakt eller den mint som ska användas för denna förfrågan.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress och accepts[].extra.verifyingContract deltar i EVM typed data-signeringen.
  • upto kräver att plånboken först ger Permit2 behörighet för USDC på målkedjan; om behörighet saknas returneras PERMIT2_ALLOWANCE_REQUIRED.
  • Om du uttryckligen vill använda efterdebiterad mätning ska du skicka in preferScheme: 'upto' i TypeScript SDK, annars väljer SDK det första tillgängliga requirement som servern returnerar under det nätverket.

Omfattning som kan verifieras offentligt

Före anslutning kan dessa offentliga ingångar och SDK-beteenden verifieras:
  • API-förfrågningar utan Authorization eller PAYMENT-SIGNATURE returnerar 402 Payment Required, och accepts i svaret är den enda signeringsgrunden för den aktuella förfrågan.
  • Både TypeScript SDK och Python SDK tillhandahåller payment handlers, och SDK:s transportlager anropar handlern och försöker igen en gång efter att ha tagit emot 402.
  • https://facilitator.acedata.cloud/.well-known/x402: returnerar de nätverk, scheme och protokolländpunkter som Facilitator stöder; API-priset baseras fortfarande på 402 som returneras i realtid av målförfrågan.
  • https://facilitator.acedata.cloud/supported: returnerar de nätverk och scheme som Facilitator stöder.
  • X402Client-repositoriet innehåller avancerade verifieringsverktyg på kedjan, som kan användas för att bekräfta signaturer, återförsök och settlement-beteende; verktygens utdata ersätter inte accepts som returneras av online-API:t.
upto tillhör efterdebiterad mätavräkning och lämpar sig för API:er där den faktiska användningen, såsom chattkomplettering och modellanrop, blir känd först efter svaret. För närvarande tillhandahåller endast Base upto; om signaturverifieringen misslyckas, kontrollera om chain id, facilitator-adress, spender, USDC-kontrakt och Permit2 allowance överensstämmer med 402-svaret.