X402 Python SDK Przewodnik po integracji

Python SDK nadaje się do usług backendowych, zadań danych, automatycznych agentów i skryptów wsadowych. acedatacloud odpowiada za wywołania API, a acedatacloud-x402 odpowiada za podpisywanie nagłówka żądania PAYMENT-SIGNATURE. Adresy źródłowe i pakietów:

Repozytorium SDK: https://github.com/AceDataCloud/SDK
Repozytorium klienta X402: https://github.com/AceDataCloud/X402Client
PyPI SDK: https://pypi.org/project/acedatacloud/
PyPI klient X402: https://pypi.org/project/acedatacloud-x402/

Instalacja zależności

pip install acedatacloud acedatacloud-x402

Jeśli chcesz używać upto, musisz również jednorazowo wywołać CLI Permit2 approve, który zależy od web3:

pip install 'acedatacloud-x402[cli]'

Wynik instalacji i sprawdzenia importu w czystym środowisku 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  Jednorazowe zatwierdzenie ERC-20 (Permit2, amount) wymagane przed podpisywaniem płatności upto.

Wyjaśnienie wyników:

acedatacloud i acedatacloud-x402 można zainstalować i zaimportować z PyPI.
pip install 'acedatacloud-x402[cli]' doda CLI approve-permit2, używaną do autoryzacji przed upto.

Przykład Base lub SKALE

Poniższy przykład nie wymaga tokena API. Klucz prywatny portfela jest podpisywany lokalnie i nie jest wysyłany do Ace Data Cloud.

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"])

Aktualnie Python SDK zwraca dict, więc przykład używa res["choices"][0]["message"]["content"]. Nie zakładaj bezpośrednio, że na pewno ma atrybut .choices. Wynik działania programu dla płatności SKALE:

payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 4786
content ADC_PY_SDK_X402_OK
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz

Wyjaśnienie wyników:

Program zakończył 402 analizę, podpisywanie PAYMENT-SIGNATURE i ponowne próby oryginalnego żądania.
content ADC_PY_SDK_X402_OK to stały ciąg zwracany przez model, co oznacza, że żądanie przeszło przez płatności X402 do docelowego API.
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz to identyfikator odpowiedzi dla tego zakończenia czatu.

Podczas korzystania z SKALE wystarczy zmienić nazwę sieci:

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

Przykład Solana

Solana używa klucza tajnego zakodowanego w base58:

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,
)

Ścieżka Solana skonstruuje i złoży transakcję SPL USDC TransferChecked, a następnie umieści podpis transakcji w kopercie PAYMENT-SIGNATURE. Płatność retry Solana na produkcyjnym API zwróciła HTTP 200 i ADC_SOLANA_E2E_OK. Podczas publicznego zapytania RPC wystąpiły ograniczenia, nie potwierdzono stabilnie podpisu na łańcuchu; w przypadku potrzeby rozliczenia użyj własnego RPC Solana, aby sprawdzić tę transakcję.

Klient asynchroniczny

Ten sam handler płatności można używać w AsyncAceDataCloud:

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,
)

Użycie `upto` do pomiaru po zakończeniu

Rzeczywisty koszt API, takiego jak uzupełnienie czatu czy wywołanie modelu, może być znany dopiero po zakończeniu odpowiedzi. W tym momencie API może jednocześnie zwrócić exact i upto. Jeśli chcesz priorytetowo używać upto:

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

Wynik działania programu dla upto w Base:

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

Potwierdzenie na łańcuchu:

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

Wyjaśnienie wyników:

content ADC_BASE_UPTO_OK oznacza, że żądanie rzeczywiście dotarło do API modelu.
settled value 3 atomic USDC oznacza, że upto zostało rozliczone według rzeczywistego zużycia, a nie pełnego limitu.
settlement tx można otworzyć w BaseScan, podczas rozliczenia zapisz hash tx, płatnika, identyfikator zakończenia i podsumowanie żądania.

upto używa Permit2 do autoryzacji limitu, a rzeczywista kwota rozliczenia nie może przekroczyć tego limitu. Przed pierwszym użyciem należy wykonać approve(Permit2, amount) dla USDC na docelowym łańcuchu. Sposób CLI:

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

Sposób programowy:

from acedatacloud_x402 import EVMAccountSigner, approve_permit2

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

Ten helper jest idempotentny. Jeśli allowance jest już wystarczające, zwróci {"skipped": true}, nie wysyłając ponownie transakcji na łańcuchu.

Niskopoziomowe podpisy

Jeśli nie używasz SDK, możesz bezpośrednio wywołać niskopoziomowe funkcje podpisywania:

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()

Niskopoziomowe funkcje są odpowiednie do testowania, warstwy pośredniej, integracji bramki lub nieoficjalnego SDK. Zwykły kod biznesowy powinien priorytetowo korzystać z create_x402_payment_handler.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

X402 Python SDK Przewodnik po integracji

Instalacja zależności

Przykład Base lub SKALE

Przykład Solana

Klient asynchroniczny

Użycie `upto` do pomiaru po zakończeniu

Niskopoziomowe podpisy

​Instalacja zależności

​Przykład Base lub SKALE

​Przykład Solana

​Klient asynchroniczny

​Użycie upto do pomiaru po zakończeniu

​Niskopoziomowe podpisy

Instalacja zależności

Przykład Base lub SKALE

Przykład Solana

Klient asynchroniczny

Użycie `upto` do pomiaru po zakończeniu

Niskopoziomowe podpisy