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

> Platform API guide - Ace Data Cloud

Python SDK är lämplig för backend-tjänster, dataprojekt, automatiserade agenter och batch-skript. `acedatacloud` ansvarar för API-anrop, `acedatacloud-x402` ansvarar för att signera `PAYMENT-SIGNATURE` begäran.

Källkod och paketadress:

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

## Installera beroenden

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

Om du vill använda `upto`, behöver du också göra en engångsanrop till Permit2 approve CLI, som är beroende av `web3`:

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

Utskrift av installation och importkontroll för en ren 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  Engångs ERC-20 godkännande (Permit2, belopp) behövs innan signering av upto betalningar.
```

Resultatförklaring:

* `acedatacloud` och `acedatacloud-x402` kan båda installeras och importeras från PyPI.
* `pip install 'acedatacloud-x402[cli]'` kommer att inkludera `approve-permit2` CLI för att hantera förhandsgodkännande för `upto`.

## Base eller SKALE exempel

Nedan exempel kräver ingen API-token. Plånbokens privata nyckel signeras endast lokalt och skickas inte till 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 returnerar för närvarande en `dict`, så exemplet använder `res["choices"][0]["message"]["content"]`. Anta inte direkt att det alltid har `.choices` attributet.

Resultatet av SKALE betald anrop:

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

Resultatförklaring:

* Programmet har genomfört 402-analys, `PAYMENT-SIGNATURE` signering och omförsök av den ursprungliga begäran.
* `content ADC_PY_SDK_X402_OK` är en fast sträng som modellen returnerar, vilket indikerar att begäran har gått igenom X402 betalningskedjan till mål-API:t.
* `id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz` är ID:t för denna chat completion respons.

Vid användning av SKALE behöver du bara ändra nätverksnamnet:

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

## Solana exempel

Solana använder base58-kodad hemlig nyckel:

```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-vägen kommer att konstruera och skicka en SPL USDC `TransferChecked` transaktion, och sedan placera transaktionssignaturen i `PAYMENT-SIGNATURE` kuvertet.

Solana betald omförsök har returnerat HTTP 200 och `ADC_SOLANA_E2E_OK` på produktions-API:t. Denna offentliga RPC-förfrågan har stött på begränsningar och har inte stabilt bekräftat signaturen på kedjan; för avstämning, vänligen använd din egen Solana RPC för att kontrollera denna transaktion.

## Async klient

Samma betalningshanterare kan användas för `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,
)
```

## Använda `upto` efterkalkyl

De verkliga kostnaderna för API:er som chat completion, modellanrop etc. kan behöva vänta tills svaret är klart för att veta. Vid denna tidpunkt kan API:t samtidigt returnera både `exact` och `upto`. Om du vill prioritera användningen av `upto`:

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

Resultatet av Base `upto` programmet:

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

Kedjeverifiering:

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

Resultatförklaring:

* `content ADC_BASE_UPTO_OK` indikerar att begäran verkligen har nått modell-API:t.
* `settled value 3 atomic USDC` indikerar att `upto` har avräknats baserat på faktisk användning, snarare än att dra hela gränsen.
* `settlement tx` kan öppnas på BaseScan, spara tx hash, payer, completion id och begärans sammanfattning för avstämning.

`upto` använder Permit2 för att godkänna en gräns, det faktiska beloppet som avräknas får inte överstiga denna gräns. Vid första användning måste du göra en `approve(Permit2, amount)` på USDC på målkedjan.

CLI-metod:

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

Programmet metod:

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

Denna hjälpare är idempotent. Om tillåtelsen redan är tillräcklig, kommer den att returnera `{"skipped": true}`, och ingen kedjetransaktion kommer att skickas igen.

## Låg nivå signering

Om du inte använder SDK kan du direkt anropa de lågnivåsigneringsfunktionerna:

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

Lågnivåfunktioner är lämpliga för testning, proxylager, gatewayintegration eller icke-officiella SDK. Vanlig affärskod bör prioritera att använda `create_x402_payment_handler`.


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