Skip to main content

@acedatacloud/x402-client — Python

X402 payment protocol client for AceDataCloud APIs. Plug-in for the acedatacloud SDK.

Pay-per-request with USDC — no API key, no account, no session. When an AceDataCloud API returns 402 Payment Required, this package signs the payment envelope and returns it as a PAYMENT-SIGNATURE header; the SDK retries transparently.

  • 🟦 Base — USDC (ERC-20) via EIP-3009 TransferWithAuthorization
  • 🟪 Solana — USDC (SPL) via signed TransferChecked
  • 🟨 SKALE — USDC (bridged) via EIP-3009

Standards compliance (official x402 v2)

This client speaks the current x402 v2 wire protocol — the same one the official x402 SDK implements:

  • payment is sent in the PAYMENT-SIGNATURE header (v2), not the legacy v1 payment header;
  • the envelope is { "x402Version": 2, "accepted": <requirement>, "payload": … };
  • networks are canonical CAIP-2 ids (eip155:8453, eip155:1187947933, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp);
  • EVM exact signs an EIP-3009 TransferWithAuthorization with validAfter=0 and a validBefore default of 3600s, matching the official SDK.

A CI parity guard (tests/test_official_sdk_parity.py) pins the emitted envelope against the official SDK v2.16: it asserts the envelope shape, the authorization field set, and that the EIP-712 signature recovers to the signer — so any drift from the spec fails the build. The @acedatacloud/x402-client TypeScript package emits the identical v2 envelope.

Install

pip install acedatacloud acedatacloud-x402

Quick start

Base or SKALE (EVM)

from acedatacloud import AceDataCloud
from acedatacloud_x402 import create_x402_payment_handler, EVMAccountSigner

client = AceDataCloud(
    base_url="https://x402.acedata.cloud",
    payment_handler=create_x402_payment_handler(
        network="base",                         # or "skale"
        evm_signer=EVMAccountSigner.from_private_key("0x..."),
    ),
)

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)

The handler accepts base, skale, and solana as configuration aliases. Wire requirements use canonical CAIP-2 IDs: eip155:8453, eip155:1187947933, and solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp.

Solana

Solana payments use a recent blockhash and must reach facilitator broadcast within 60 seconds. Use this network only for APIs expected to complete inside that window; long-running protected calls require a future durable-nonce settlement flow.

from acedatacloud import AceDataCloud
from acedatacloud_x402 import create_x402_payment_handler, SolanaKeypairSigner

client = AceDataCloud(
    base_url="https://x402.acedata.cloud",
    payment_handler=create_x402_payment_handler(
        network="solana",
        solana_signer=SolanaKeypairSigner.from_base58("..."),
    ),
)

task = client.images.generate(
    provider="nano-banana",
    prompt="a yellow banana on a white background",
)
result = task.wait()

The same handler works with AsyncAceDataCloud:

from acedatacloud import AsyncAceDataCloud

client = AsyncAceDataCloud(
    base_url="https://x402.acedata.cloud",
    payment_handler=create_x402_payment_handler(network="base", evm_signer=signer),
)

Low-level signing

If you need to produce a PAYMENT-SIGNATURE envelope without going through the SDK:

from acedatacloud_x402 import sign_evm_payment, sign_solana_payment

envelope = sign_evm_payment(requirement, evm_signer)          # dict
envelope = sign_solana_payment(requirement, solana_signer)    # dict
# base64-encode json(envelope) → PAYMENT-SIGNATURE header value

The signers already return the canonical v2 { "x402Version": 2, "accepted": requirement, "payload": ... } envelope.

Metered billing — the upto scheme

For APIs whose true cost is only known after the response (chat completions, image edits, etc.) AceDataCloud advertises an extra upto accept entry alongside exact. upto uses Uniswap Permit2 to authorize a ceiling; the server settles the actual amount at /record time (which may be 0).

from acedatacloud_x402 import (
    EVMAccountSigner,
    create_x402_payment_handler,
)

client = AceDataCloud(
    base_url="https://x402.acedata.cloud",
    payment_handler=create_x402_payment_handler(
        network="base",
        evm_signer=EVMAccountSigner.from_private_key("0x..."),
        prefer_scheme="upto",   # opt-in; defaults to whatever the server lists first
    ),
)

A one-time on-chain ERC20.approve(Permit2, ∞) is required before the first upto payment. Use the bundled CLI:

pip install 'acedatacloud-x402[cli]'
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base

or programmatically:

from acedatacloud_x402 import EVMAccountSigner, approve_permit2

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

The helper is idempotent — re-running it after the allowance is already at or above the requested amount returns {"skipped": true} without sending a transaction.

Verified live on Base mainnet (2026-05-31)

End-to-end runs through https://facilitator.acedata.cloud against three metered chat endpoints, payer wallet 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105:

API Model Credits charged USDC settled Tx
POST /v1/chat/completions claude-sonnet-4-5 0.001587893 0.000151 0xc1f90cc6…b093dd8
POST /openai/chat/completions gpt-5.5 0.001427432 0.000135 0xda8f0ff0…fcca57
POST /glm/chat/completions glm-4.7 0.002753977 0.000262 0xae9bba18…7c5dda

Each call advertised both exact and upto; the handler picked upto, the worker emitted an X-Usage-Exempt placeholder on the first /record, and the facilitator settled at the actual measured cost on the worker's later /record. Each settled amount matches the per-model JSONLogic cost rule in the gateway DB (within ±1 atomic for rounding).

Development

cd python
pip install -e ".[dev]"
pytest
ruff check .

License

MIT © AceDataCloud

Metadata

Release files for acedatacloud-x402 2026.10.19.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for acedatacloud-x402 2026.10.19.1
File Size Uploaded Provenance Actions
acedatacloud_x402-2026.10.19.1.tar.gz 14.1 kB Without provenance Details for acedatacloud_x402-2026.10.19.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for acedatacloud-x402 2026.10.19.1
File Interpreter ABI Platform Actions
acedatacloud_x402-2026.10.19.1-py3-none-any.whl Python 3 none any Details for acedatacloud_x402-2026.10.19.1-py3-none-any.whl

Total release size: 31.5 kB

Release files / acedatacloud_x402-2026.10.19.1.tar.gz

Download URL acedatacloud_x402-2026.10.19.1.tar.gz
Size 14.1 kB
Tags Source
SHA-256 checksum
How to use checksums
0bc55abb512bbfd8e1c06857704cd448acabe21d629b8e32ebe2bffb0436f4db
BLAKE2b-256 checksum
How to use checksums
f3fbd0b5645b00af5431650f8989503b3a55d4dd9c03fad4a7c33febf524c918
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Release files / acedatacloud_x402-2026.10.19.1-py3-none-any.whl

Download URL acedatacloud_x402-2026.10.19.1-py3-none-any.whl
Size 17.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a1737c0820ad63fa98bc0bfe89c5a604bcb15225f251f548045b4e6f886f710
BLAKE2b-256 checksum
How to use checksums
6d0e6fc41ae2e87e7aca8cddc850ce46d54a9d4eb39cb7813a1183541ff9e1f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for acedatacloud-x402 2026.10.19.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page