> ## 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 클라이언트 저장소: [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client)
* PyPI SDK: [https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/)
* PyPI X402 클라이언트: [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` envelope에 넣습니다.

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 해시, 지불자, 완성 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.