Skip to main content
The Python SDK is suitable for backend services, data tasks, automation Agents, and batch processing scripts. acedatacloud is responsible for API calls, while acedatacloud-x402 is responsible for producing the PAYMENT-SIGNATURE request header. Source code and package URLs:

Install Dependencies

To use upto, you also need to run the Permit2 approve CLI once. This CLI depends on web3:
Installation and import check output in a clean Python venv:
Result description:
  • Both acedatacloud and acedatacloud-x402 can be installed and imported from PyPI.
  • pip install 'acedatacloud-x402[cli]' includes the approve-permit2 CLI, which is used for prerequisite authorization for upto.

Base Example

The example below does not require an API Token. The wallet private key is only used for local signing and will not be sent to Ace Data Cloud.
The Python SDK currently returns a dict, so the example uses res["choices"][0]["message"]["content"]. Do not directly assume that it necessarily has a .choices attribute.

Solana Example

Solana uses a base58-encoded secret key:
The Solana path constructs and submits an SPL USDC TransferChecked transaction, then puts the transaction signature into the PAYMENT-SIGNATURE envelope. The Solana paid retry has returned HTTP 200 and ADC_SOLANA_E2E_OK on the production API. This public RPC query encountered rate limiting and did not reliably confirm the on-chain signature; use your own Solana RPC to query the transaction when reconciliation is needed.

Async Client

The same payment handler can be used with AsyncAceDataCloud:

Using upto Post-Payment Metering

The actual cost of APIs such as chat completions and model invocations may only be known after the response has completed. In this case, the API may return both exact and upto. To prioritize using upto:
Base upto program execution result:
On-chain confirmation:
Result description:
  • content ADC_BASE_UPTO_OK indicates that the request actually reached the model API.
  • settled value 3 atomic USDC indicates that upto settles based on actual usage rather than charging the full limit.
  • settlement tx can be opened in BaseScan. Save the tx hash, payer, completion id, and request summary for reconciliation.
upto uses Permit2 to authorize a limit, and the actual settlement amount cannot exceed this limit. Before first use, you need to perform a one-time approve(Permit2, amount) for USDC on the target chain. CLI method:
Programmatic method:
This helper is idempotent. If the allowance is already sufficient, it returns {"skipped": true} and does not send another on-chain transaction.

Low-Level Signing

If you do not use the SDK, you can also directly call the low-level signing function:
Low-level functions are suitable for testing, proxy layers, gateway integrations, or non-official SDKs. For regular business code, prioritize using create_x402_payment_handler.