> ## 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 Integrationsanleitung

> Platform API guide - Ace Data Cloud

Das Python SDK eignet sich für Backend-Dienste, Datenaufgaben, automatisierte Agenten und Batch-Skripte. `acedatacloud` ist für API-Aufrufe verantwortlich, `acedatacloud-x402` ist für das Auschecken des `PAYMENT-SIGNATURE` Anfrage-Headers verantwortlich.

Quellcode und Paketadressen:

* SDK-Repository: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* X402 Client Repository: [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/)

## Abhängigkeiten installieren

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

Wenn Sie `upto` verwenden möchten, müssen Sie auch einmalig das Permit2 approve CLI aufrufen, das von `web3` abhängt:

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

Ausgabe der Installation und Importüberprüfung in einer sauberen 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  Einmalige ERC-20 Genehmigung (Permit2, Betrag) erforderlich, bevor Sie `upto` Zahlungen signieren.
```

Erklärung der Ergebnisse:

* `acedatacloud` und `acedatacloud-x402` können beide von PyPI installiert und importiert werden.
* `pip install 'acedatacloud-x402[cli]'` bringt das `approve-permit2` CLI mit, das für die Vorabgenehmigung von `upto` verwendet wird.

## Base oder SKALE Beispiel

Das folgende Beispiel benötigt kein API-Token. Der private Schlüssel der Brieftasche wird nur lokal signiert und nicht an Ace Data Cloud gesendet.

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

Das Python SDK gibt derzeit ein `dict` zurück, daher verwendet das Beispiel `res["choices"][0]["message"]["content"]`. Gehen Sie nicht davon aus, dass es immer das Attribut `.choices` hat.

Ergebnis der SKALE bezahlten Anrufausführung:

```text theme={null}
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 4786
content ADC_PY_SDK_X402_OK
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz
```

Erklärung der Ergebnisse:

* Das Programm hat die 402-Analyse, die `PAYMENT-SIGNATURE`-Signatur und den ursprünglichen Anfrage-Wiederholungsversuch abgeschlossen.
* `content ADC_PY_SDK_X402_OK` ist der feste String, den das Modell tatsächlich zurückgibt, was bedeutet, dass die Anfrage über die X402-Zahlungskette in die Ziel-API eingegangen ist.
* `id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz` ist die ID der Chat-Vervollständigungsantwort.

Wenn Sie SKALE verwenden, müssen Sie nur den Netzwerknamen ändern:

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

## Solana Beispiel

Solana verwendet einen base58-kodierten geheimen Schlüssel:

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

Der Solana-Pfad wird eine SPL USDC `TransferChecked`-Transaktion konstruieren und einreichen und dann die Transaktionssignatur in das `PAYMENT-SIGNATURE`-Envelope einfügen.

Die Solana bezahlte Wiederholung hat auf der Produktions-API HTTP 200 und `ADC_SOLANA_E2E_OK` zurückgegeben. Bei dieser öffentlichen RPC-Abfrage gab es eine Drosselung, die eine stabile Bestätigung der On-Chain-Signatur verhinderte; wenn Sie eine Abrechnung benötigen, verwenden Sie bitte Ihre eigene Solana RPC, um diese Transaktion abzufragen.

## Async-Client

Der gleiche Zahlungs-Handler kann für `AsyncAceDataCloud` verwendet werden:

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

## Verwendung von `upto` für nachträgliche Abrechnung

Die tatsächlichen Kosten von API-Anfragen wie Chat-Vervollständigungen und Modellaufrufen sind möglicherweise erst nach Abschluss der Antwort bekannt. Zu diesem Zeitpunkt kann die API sowohl `exact` als auch `upto` zurückgeben. Wenn Sie `upto` priorisieren möchten:

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

Ergebnis der Base `upto`-Programm-Ausführung:

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

On-Chain-Bestätigung:

```text theme={null}
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
transfer value 3 atomic USDC
```

Erklärung der Ergebnisse:

* `content ADC_BASE_UPTO_OK` zeigt an, dass die Anfrage tatsächlich in die Modell-API eingegangen ist.
* `settled value 3 atomic USDC` zeigt an, dass `upto` nach tatsächlichem Verbrauch abgerechnet wurde und nicht den gesamten Höchstbetrag abgezogen hat.
* `settlement tx` kann auf BaseScan geöffnet werden; speichern Sie beim Abgleichen tx hash, payer, completion id und Anfragezusammenfassung.

`upto` verwendet Permit2, um ein Limit zu genehmigen, der tatsächlich abgerechnete Betrag darf dieses Limit nicht überschreiten. Vor der ersten Verwendung müssen Sie eine `approve(Permit2, amount)` auf USDC auf der Zielkette durchführen.

CLI-Methode:

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

Programmmethode:

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

Dieser Helper ist idempotent. Wenn die Erlaubnis bereits ausreichend ist, wird `{"skipped": true}` zurückgegeben, und es wird keine wiederholte On-Chain-Transaktion gesendet.

## Niedrigere Signatur

Wenn Sie das SDK nicht verwenden, können Sie auch direkt die niedrigstufigen Signaturfunktionen aufrufen:

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

Niedrigstufige Funktionen eignen sich für Tests, Proxy-Schichten, Gateway-Integrationen oder inoffizielle SDKs. Normale Geschäftscodes sollten bevorzugt `create_x402_payment_handler` verwenden.


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