X402 Python SDK Integrationsanleitung

Das Python SDK eignet sich für Backend-Dienste, Datenaufgaben, automatisierte Agenten und Batch-Skripte. acedatacloud ist für API-Aufrufe verantwortlich, acedatacloud-x402 ist für das Auschecken des PAYMENT-SIGNATURE Anfrage-Headers verantwortlich. Quellcode und Paketadressen:

SDK-Repository: https://github.com/AceDataCloud/SDK
X402 Client Repository: https://github.com/AceDataCloud/X402Client
PyPI SDK: https://pypi.org/project/acedatacloud/
PyPI X402 Client: https://pypi.org/project/acedatacloud-x402/

Abhängigkeiten installieren

pip install acedatacloud acedatacloud-x402

Wenn Sie upto verwenden möchten, müssen Sie auch einmalig das Permit2 approve CLI aufrufen, das von web3 abhängt:

pip install 'acedatacloud-x402[cli]'

Ausgabe der Installation und Importüberprüfung in einer sauberen Python venv:

acedatacloud 2026.4.26.1
acedatacloud-x402 2026.5.31.3
imports_ok True True True True True True
usage: acedatacloud-x402 [-h] {approve-permit2} ...
approve-permit2  Einmalige ERC-20 Genehmigung (Permit2, Betrag) erforderlich, bevor Sie `upto` Zahlungen signieren.

Erklärung der Ergebnisse:

acedatacloud und acedatacloud-x402 können beide von PyPI installiert und importiert werden.
pip install 'acedatacloud-x402[cli]' bringt das approve-permit2 CLI mit, das für die Vorabgenehmigung von upto verwendet wird.

Base oder SKALE Beispiel

Das folgende Beispiel benötigt kein API-Token. Der private Schlüssel der Brieftasche wird nur lokal signiert und nicht an Ace Data Cloud gesendet.

import os

from acedatacloud import AceDataCloud
from acedatacloud_x402 import EVMAccountSigner, create_x402_payment_handler

signer = EVMAccountSigner.from_private_key(os.environ["EVM_PRIVATE_KEY"])

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="base",
        evm_signer=signer,
    )
)

res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hi in 3 words"}],
    max_tokens=10,
)

print(res["choices"][0]["message"]["content"])

Das Python SDK gibt derzeit ein dict zurück, daher verwendet das Beispiel res["choices"][0]["message"]["content"]. Gehen Sie nicht davon aus, dass es immer das Attribut .choices hat. Ergebnis der SKALE bezahlten Anrufausführung:

payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 4786
content ADC_PY_SDK_X402_OK
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz

Erklärung der Ergebnisse:

Das Programm hat die 402-Analyse, die PAYMENT-SIGNATURE-Signatur und den ursprünglichen Anfrage-Wiederholungsversuch abgeschlossen.
content ADC_PY_SDK_X402_OK ist der feste String, den das Modell tatsächlich zurückgibt, was bedeutet, dass die Anfrage über die X402-Zahlungskette in die Ziel-API eingegangen ist.
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz ist die ID der Chat-Vervollständigungsantwort.

Wenn Sie SKALE verwenden, müssen Sie nur den Netzwerknamen ändern:

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="skale",
        evm_signer=signer,
    )
)

Solana Beispiel

Solana verwendet einen base58-kodierten geheimen Schlüssel:

import os

from acedatacloud import AceDataCloud
from acedatacloud_x402 import SolanaKeypairSigner, create_x402_payment_handler

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="solana",
        solana_signer=SolanaKeypairSigner.from_base58(os.environ["SOLANA_SECRET_KEY"]),
    )
)

res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hi in 3 words"}],
    max_tokens=10,
)

Der Solana-Pfad wird eine SPL USDC TransferChecked-Transaktion konstruieren und einreichen und dann die Transaktionssignatur in das PAYMENT-SIGNATURE-Envelope einfügen. Die Solana bezahlte Wiederholung hat auf der Produktions-API HTTP 200 und ADC_SOLANA_E2E_OK zurückgegeben. Bei dieser öffentlichen RPC-Abfrage gab es eine Drosselung, die eine stabile Bestätigung der On-Chain-Signatur verhinderte; wenn Sie eine Abrechnung benötigen, verwenden Sie bitte Ihre eigene Solana RPC, um diese Transaktion abzufragen.

Async-Client

Der gleiche Zahlungs-Handler kann für AsyncAceDataCloud verwendet werden:

import os

from acedatacloud import AsyncAceDataCloud
from acedatacloud_x402 import EVMAccountSigner, create_x402_payment_handler

signer = EVMAccountSigner.from_private_key(os.environ["EVM_PRIVATE_KEY"])

client = AsyncAceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="base",
        evm_signer=signer,
    )
)

res = await client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hi in 3 words"}],
    max_tokens=10,
)

Verwendung von `upto` für nachträgliche Abrechnung

Die tatsächlichen Kosten von API-Anfragen wie Chat-Vervollständigungen und Modellaufrufen sind möglicherweise erst nach Abschluss der Antwort bekannt. Zu diesem Zeitpunkt kann die API sowohl exact als auch upto zurückgeben. Wenn Sie upto priorisieren möchten:

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="base",
        evm_signer=signer,
        prefer_scheme="upto",
    )
)

Ergebnis der Base upto-Programm-Ausführung:

payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
elapsed_ms 5104
content ADC_BASE_UPTO_OK
id chatcmpl-DlcbyS4IT8kUAMo4Ri97HiIHc9T8V
settlement tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
settled value 3 atomic USDC

On-Chain-Bestätigung:

explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
transfer value 3 atomic USDC

Erklärung der Ergebnisse:

content ADC_BASE_UPTO_OK zeigt an, dass die Anfrage tatsächlich in die Modell-API eingegangen ist.
settled value 3 atomic USDC zeigt an, dass upto nach tatsächlichem Verbrauch abgerechnet wurde und nicht den gesamten Höchstbetrag abgezogen hat.
settlement tx kann auf BaseScan geöffnet werden; speichern Sie beim Abgleichen tx hash, payer, completion id und Anfragezusammenfassung.

upto verwendet Permit2, um ein Limit zu genehmigen, der tatsächlich abgerechnete Betrag darf dieses Limit nicht überschreiten. Vor der ersten Verwendung müssen Sie eine approve(Permit2, amount) auf USDC auf der Zielkette durchführen. CLI-Methode:

X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base

Programmmethode:

from acedatacloud_x402 import EVMAccountSigner, approve_permit2

approve_permit2(
    rpc_url="https://mainnet.base.org",
    signer=EVMAccountSigner.from_private_key("0x..."),
    token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
)

Dieser Helper ist idempotent. Wenn die Erlaubnis bereits ausreichend ist, wird {"skipped": true} zurückgegeben, und es wird keine wiederholte On-Chain-Transaktion gesendet.

Niedrigere Signatur

Wenn Sie das SDK nicht verwenden, können Sie auch direkt die niedrigstufigen Signaturfunktionen aufrufen:

import base64
import json

from acedatacloud_x402 import EVMAccountSigner, sign_evm_payment

envelope = sign_evm_payment(requirement, EVMAccountSigner.from_private_key("0x..."))
x_payment = base64.b64encode(json.dumps(envelope, separators=(",", ":")).encode()).decode()

Niedrigstufige Funktionen eignen sich für Tests, Proxy-Schichten, Gateway-Integrationen oder inoffizielle SDKs. Normale Geschäftscodes sollten bevorzugt create_x402_payment_handler verwenden.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

X402 Python SDK Integrationsanleitung

Abhängigkeiten installieren

Base oder SKALE Beispiel

Solana Beispiel

Async-Client

Verwendung von `upto` für nachträgliche Abrechnung

Niedrigere Signatur

​Abhängigkeiten installieren

​Base oder SKALE Beispiel

​Solana Beispiel

​Async-Client

​Verwendung von upto für nachträgliche Abrechnung

​Niedrigere Signatur

Abhängigkeiten installieren

Base oder SKALE Beispiel

Solana Beispiel

Async-Client

Verwendung von `upto` für nachträgliche Abrechnung

Niedrigere Signatur