> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# X402 Python SDK 接入教程

> Platform API guide - Ace Data Cloud

Python SDK はバックエンドサービス、データタスク、自動化エージェント、およびバッチ処理スクリプトに適しています。`acedatacloud` は API 呼び出しを担当し、`acedatacloud-x402` は `PAYMENT-SIGNATURE` リクエストヘッダーのチェックアウトを担当します。

ソースコードとパッケージのアドレス：

* SDK リポジトリ：[https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* X402 Client リポジトリ：[https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client)
* PyPI SDK：[https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/)
* PyPI X402 Client：[https://pypi.org/project/acedatacloud-x402/](https://pypi.org/project/acedatacloud-x402/)

## 依存関係のインストール

```bash theme={null}
pip install acedatacloud acedatacloud-x402
```

`upto` を使用する場合は、Permit2 approve CLI を一度呼び出す必要があります。この CLI は `web3` に依存しています：

```bash theme={null}
pip install 'acedatacloud-x402[cli]'
```

クリーンな Python venv のインストールとインポートチェックの出力：

```text theme={null}
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]'` は `upto` 前置きのための `approve-permit2` CLI を含みます。

## Base または SKALE の例

以下の例では API トークンは必要ありません。ウォレットの秘密鍵はローカルで署名され、Ace Data Cloud に送信されることはありません。

```python theme={null}
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 有料呼び出しのプログラム実行結果：

```text theme={null}
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 です。

SKALE を使用する場合は、ネットワーク名を変更するだけです：

```python theme={null}
client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="skale",
        evm_signer=signer,
    )
)
```

## Solana の例

Solana は base58 エンコードされた秘密鍵を使用します：

```python theme={null}
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` エンベロープに入れます。

Solana 有料再試行は本番 API で HTTP 200 と `ADC_SOLANA_E2E_OK` を返しました。今回の公開 RPC クエリはレート制限に遭遇し、チェーン上の署名を安定して確認できませんでした。照合が必要な場合は、独自の Solana RPC を使用してこのトランザクションをクエリしてください。

## Async クライアント

同じペイメントハンドラーは `AsyncAceDataCloud` にも使用できます：

```python theme={null}
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` を優先して使用する場合：

```python theme={null}
client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="base",
        evm_signer=signer,
        prefer_scheme="upto",
    )
)
```

Base `upto` のプログラム実行結果：

```text theme={null}
payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
elapsed_ms 5104
content ADC_BASE_UPTO_OK
id chatcmpl-DlcbyS4IT8kUAMo4Ri97HiIHc9T8V
settlement tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
settled value 3 atomic USDC
```

チェーン上の確認：

```text theme={null}
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 ハッシュ、payer、completion ID、およびリクエストの要約を保存してください。

`upto` は Permit2 によって上限を承認し、実際の決済金額はその上限を超えることはできません。最初の使用前に、ターゲットチェーン上の USDC に対して一度 `approve(Permit2, amount)` を行う必要があります。

CLI 方式：

```bash theme={null}
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base
```

プログラム方式：

```python theme={null}
from acedatacloud_x402 import EVMAccountSigner, approve_permit2

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

このヘルパーは冪等性があります。もしアローワンスがすでに十分であれば、`{"skipped": true}` が返され、チェーン上のトランザクションは繰り返し発行されません。

## 低レベル署名

SDKを使用しない場合でも、低レベルの署名関数を直接呼び出すことができます：

```python theme={null}
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` を優先して使用してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.