X402 Python SDK підключення

Python SDK підходить для бекенд-сервісів, даних завдань, автоматизованих агентів та пакетних скриптів. acedatacloud відповідає за виклики API, acedatacloud-x402 відповідає за підписання заголовка запиту PAYMENT-SIGNATURE. Джерела та адреси пакетів:

SDK репозиторій: https://github.com/AceDataCloud/SDK
X402 Client репозиторій: https://github.com/AceDataCloud/X402Client
PyPI SDK: https://pypi.org/project/acedatacloud/
PyPI X402 Client: https://pypi.org/project/acedatacloud-x402/

Встановлення залежностей

pip install acedatacloud acedatacloud-x402

Якщо потрібно використовувати upto, також потрібно одноразово викликати Permit2 approve CLI, цей CLI залежить від web3:

pip install 'acedatacloud-x402[cli]'

Вихід установки та перевірки імпорту чистого 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  One-time ERC-20 approve(Permit2, amount) needed before signing upto payments.

Роз’яснення результатів:

acedatacloud та acedatacloud-x402 можна встановити та імпортувати з PyPI.
pip install 'acedatacloud-x402[cli]' включає approve-permit2 CLI для попереднього авторизації upto.

Base або SKALE приклад

Наступний приклад не потребує API Token. Приватний ключ гаманця підписується лише локально, не буде надісланий до 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"])

Python SDK наразі повертає dict, тому приклад використовує res["choices"][0]["message"]["content"]. Не припускайте, що він обов’язково має атрибут .choices. Результат виконання програми SKALE paid call:

payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 4786
content ADC_PY_SDK_X402_OK
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz

Роз’яснення результатів:

Програма завершила 402 парсинг, підписання PAYMENT-SIGNATURE та повторний запит.
content ADC_PY_SDK_X402_OK є фіксованим рядком, який дійсно повертає модель, що вказує на те, що запит пройшов через платіжний ланцюг X402 до цільового API.
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz є ID відповіді на цей chat completion.

При використанні SKALE потрібно лише змінити назву мережі:

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

Solana приклад

Solana використовує секретний ключ, закодований у 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,
)

Шлях Solana буде побудований та надісланий SPL USDC TransferChecked транзакцію, а потім підписана транзакція буде поміщена в PAYMENT-SIGNATURE envelope. Solana paid retry на виробничому API вже повернув HTTP 200 та ADC_SOLANA_E2E_OK. Цей публічний RPC запит зіткнувся з обмеженнями, не було стабільного підтвердження підпису в ланцюзі; для звірки використовуйте свій власний Solana RPC для перевірки цієї транзакції.

Async клієнт

Той самий payment handler може бути використаний для 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,
)

Використання `upto` для пост-обліку

Справжня вартість API, така як чат-комплітації, виклики моделей тощо, може бути відома лише після завершення відповіді. У цей момент API може одночасно повертати exact та upto. Якщо потрібно віддати перевагу upto:

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

Результат виконання програми Base upto:

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

Підтвердження в ланцюзі:

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

Роз’яснення результатів:

content ADC_BASE_UPTO_OK вказує на те, що запит дійсно потрапив до API моделі.
settled value 3 atomic USDC вказує на те, що upto розраховується за фактичним використанням, а не знімається повна межа.
settlement tx можна відкрити на BaseScan, для звірки зберігайте tx hash, payer, completion id та підсумок запиту.

upto використовує Permit2 для авторизації межі, фактична сума розрахунку не може перевищувати цю межу. Перед першим використанням потрібно зробити один раз approve(Permit2, amount) для USDC на цільовій ланцюзі. CLI спосіб:

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

Програмний спосіб:

from acedatacloud_x402 import EVMAccountSigner, approve_permit2

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

Цей хелпер є ідемпотентним. Якщо allowance вже достатньо, він поверне {"skipped": true}, не повторюючи транзакцію в ланцюзі.

Низькорівневе підписання

Якщо ви не використовуєте SDK, ви також можете безпосередньо викликати низькорівневі функції підпису:

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

Низькорівневі функції підходять для тестування, проксі-слою, інтеграції шлюзу або неофіційного SDK. Звичайний бізнес-код повинен переважно використовувати create_x402_payment_handler.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Coding

Інші посібники

X402 Python SDK підключення

Встановлення залежностей

Base або SKALE приклад

Solana приклад

Async клієнт

Використання `upto` для пост-обліку

Низькорівневе підписання

​Встановлення залежностей

​Base або SKALE приклад

​Solana приклад

​Async клієнт

​Використання upto для пост-обліку

​Низькорівневе підписання

Встановлення залежностей

Base або SKALE приклад

Solana приклад

Async клієнт

Використання `upto` для пост-обліку

Низькорівневе підписання