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
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.
- Både npm- och PyPI-paketen har installerats och importerats framgångsrikt i rena miljöer.
- Obetalda API-förfrågningar returnerar 402, och
acceptsinnehå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, Baseuptooch orderbetalningar har alla explorer-adresser som kan öppnas offentligt. - Den signerade gränsen för Base
uptoär95215atomic USDC, och den faktiska settlementen är3atomic USDC, vilket återspeglar egenskapen hos efterdebiterad mätning där avräkning sker enligt faktisk användning. - Solana
exacthar 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.facilitatorAddressochaccepts[].extra.verifyingContractdeltar i EVM typed data-signeringen.uptokräver att plånboken först ger Permit2 behörighet för USDC på målkedjan; om behörighet saknas returnerasPERMIT2_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
AuthorizationellerPAYMENT-SIGNATUREreturnerar402 Payment Required, ochacceptsi 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
acceptssom 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.
