> ## 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 빠른 시작

> Platform API guide - Ace Data Cloud

본 튜토리얼은 최소한의 API 요청을 통해 Ace Data Cloud X402의 전체 프로세스를 설명합니다. 목표는 복잡한 코드를 먼저 작성하는 것이 아니라, 첫 번째 요청이 왜 402를 반환하는지, `accepts`에 무엇이 있는지, `PAYMENT-SIGNATURE`가 어떻게 동일한 API 요청을 결제된 요청으로 변환하는지를 이해하는 것입니다.

## 준비 작업

다음과 같은 준비가 필요합니다:

| 항목 | 설명 |
| - | - |
| 지갑 | 목표 네트워크를 지원하는 지갑. Base / SKALE은 EVM 지갑을 사용하고, Solana는 Solana 지갑을 사용합니다. |
| USDC | 지갑에 충분한 USDC가 있어야 합니다. 실제 금액은 402 응답의 `maxAmountRequired`에 따릅니다. |
| 개발 환경 | TypeScript는 Node.js 18+를 추천하며, Python은 Python 3.10+를 추천합니다. |
| SDK | 공식 SDK 사용을 권장하며, 서명 세부 사항을 수동으로 작성하는 것은 권장하지 않습니다. |

X402가 Ace Data Cloud API를 호출할 때 API Token이 필요하지 않습니다. SDK의 첫 번째 요청은 `Authorization` 없이 이루어지며, Gateway는 `402 Payment Required`와 결제 요구 사항을 반환합니다; SDK는 서명 후 자동으로 재시도합니다.

## SDK 설치

소스 코드 및 패키지 주소:

* SDK 저장소: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* X402 Client 저장소: [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client)
* npm: `@acedatacloud/sdk`, `@acedatacloud/x402-client`
* PyPI: `acedatacloud`, `acedatacloud-x402`

TypeScript:

```bash theme={null}
npm install @acedatacloud/sdk @acedatacloud/x402-client ethers
```

Python:

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

Solana를 사용하려면 해당 종속성도 설치해야 합니다:

```bash theme={null}
npm install @solana/web3.js
```

Python 버전의 Solana signer 종속성은 이미 `acedatacloud-x402`에 포함되어 있습니다.

깨끗한 임시 환경의 설치 및 가져오기 확인 출력:

```text theme={null}
@acedatacloud/sdk@2026.504.2
@acedatacloud/x402-client@2026.531.3
ethers@6.16.0
@solana/web3.js@1.98.4

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} ...
```

결과 설명:

* npm 패키지와 PyPI 패키지는 실제로 배포된 패키지이며, 문서의 자리 표시자 이름이 아닙니다.
* `acedatacloud-x402[cli]`는 CLI를 설치하며, `approve-permit2` 하위 명령은 `upto` 시나리오의 Permit2 권한 부여에 사용할 수 있습니다.

## 첫 번째 요청은 402를 반환합니다

먼저 `curl`을 사용하여 미지급 요청이 무엇을 반환하는지 확인할 수 있습니다. 아래 예시는 `PAYMENT-SIGNATURE`를 포함하지 않기 때문에 요금이 부과되지 않습니다:

```bash theme={null}
curl -sS -X POST https://x402.acedata.cloud/openai/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "hi"}],
    "max_tokens": 1
  }'
```

반환 본문에는 `accepts` 배열이 포함되며, 일반적인 구조는 다음과 같습니다:

```json theme={null}
{
  "x402Version": 2,
  "resource": {
    "url": "/openai/chat/completions",
    "description": "AceDataCloud API call",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "95215",
      "amount": "95215",
      "maxTimeoutSeconds": 3600,
      "resource": "/openai/chat/completions",
      "description": "...",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "chainId": 8453,
        "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      }
    }
  ],
  "error": "PAYMENT-SIGNATURE header is required"
}
```

동일한 챌린지 내용은 `PAYMENT-REQUIRED` 응답 헤더에 base64 형식으로 포함되어 있어, 클라이언트가 본문을 파싱하지 않고도 결제 요구 사항을 읽을 수 있습니다.

생산 API의 미지급 요청 프로그램 출력 요약은 다음과 같습니다:

```text theme={null}
status=402
x402Version 2
accepts [
  ('eip155:8453', 'exact', '95215'),
  ('eip155:8453', 'upto', '95215'),
  ('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'exact', '95215'),
  ('eip155:1187947933', 'exact', '95215')
]
```

결과 설명:

* 첫 번째 요청은 `Authorization` 또는 `PAYMENT-SIGNATURE`를 포함하지 않았기 때문에 HTTP 402를 반환하며, 요금이 부과되지 않습니다.
* `accepts`는 이번 요청의 유일한 신뢰할 수 있는 서명 근거로, 선택 가능한 네트워크, 스킴, 금액 한도, 수취 주소 및 자산 주소를 포함합니다.
* `network`는 CAIP-2 식별자로, 클라이언트가 네트워크를 선택할 때 CAIP-2 문자열에 따라 일치해야 합니다.
* 이번 `gpt-4o-mini` 최소 채팅 요청의 한도 금액은 `95215` atomic USDC, 즉 `0.095215` USDC입니다.
* 매 요청마다 이번 402 응답을 읽어야 하며, 예제 금액을 비즈니스 코드에 하드코딩하지 않아야 합니다.

필드 의미:

| 필드 | 설명 |
| - | - |
| `scheme` | 결제 방식. `exact`는 고정 금액을 의미하고, `upto`는 승인 한도, 실제 사용량에 따라 결제합니다. |
| `network` | 결제 네트워크의 CAIP-2 식별자, 예: `eip155:8453`, `eip155:1187947933`, `solana:5eykt4...`입니다. |
| `maxAmountRequired` | 최대 결제 금액, 단위는 USDC atomic units이며, `95215`는 `0.095215` USDC를 의미합니다. |
| `amount` | 이번에 결제할 금액; `exact`는 `maxAmountRequired`와 동일하며, `upto`는 결제 단계에서 실제 사용량에 따라 수정됩니다. |
| `payTo` | 수취 주소입니다. |
| `asset` | USDC 계약 주소 또는 Solana 민트 주소입니다. |
| `extra` | 서명에 필요한 체인 ID, EIP-712 도메인, Permit2 주소 등의 확장 정보입니다. |

## SDK로 결제 재시도 완료

다음은 최소 TypeScript 예제입니다. `network: 'skale'`를 지정하며, 핸들러는 이번 402 응답에서 SKALE의 결제 요구 사항을 선택합니다; 실제 금액과 수취 주소는 여전히 `accepts`에 따릅니다:

```ts theme={null}
import { Wallet } from 'ethers';
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const wallet = new Wallet(process.env.SKALE_PRIVATE_KEY!);

const evmProvider = {
  async request({ method, params }: { method: string; params?: unknown[] }) {
    if (method !== 'eth_signTypedData_v4') {
      throw new Error(`지원하지 않는 메서드: ${method}`);
    }
    const [, typedDataJson] = params as [string, string];
    const typedData = JSON.parse(typedDataJson);
    return wallet.signTypedData(typedData.domain, typedData.types, typedData.message);
  }
};

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'skale',
    evmProvider,
    evmAddress: wallet.address
  })
});

const response = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: '정확히 다음과 같이 답변하세요: hello' }],
  max_tokens: 8
});

console.log(response.choices[0].message.content);
```

동일한 링크를 사용한 TypeScript SDK의 프로그램 실행 결과:

```text theme={null}
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT
```

결과 설명:

* `content ADC_TS_SDK_X402_OK`는 모델이 프롬프트에 따라 반환한 고정 문자열로, 유료 재시도 후 요청이 실제로 모델 API에 들어갔음을 나타냅니다.
* `payer`는 로컬 서명 지갑 주소이며, 개인 키는 Ace Data Cloud에 전송되지 않았습니다.
* SDK는 402 파싱, `PAYMENT-SIGNATURE` 서명 및 원래 요청 재시도를 완료했습니다; 비즈니스 코드는 여전히 일반 SDK 호출 방식으로 작성되었습니다.

이 코드 뒤에서 발생한 네 단계:

1. SDK는 `Authorization` 없이 일반 API 요청을 한 번 보냅니다.
2. Gateway는 `402 Payment Required`와 `accepts`를 반환합니다.
3. `createX402PaymentHandler`는 `network = 'skale'`의 결제 요구 사항을 선택하고 `PAYMENT-SIGNATURE`를 서명합니다.
4. SDK는 동일한 요청 본문으로 재시도하며, Gateway는 Facilitator를 호출하여 검증 및 정산 후 목표 API로 전달합니다.

## Facilitator 지원 능력 확인

X402 API는 리소스 디렉토리에 의존하지 않습니다. 클라이언트는 알려진 API를 직접 호출하고, 해당 요청의 실시간 반환인 `402 Payment Required`와 `accepts`를 유일한 가격 및 서명 근거로 사용합니다.

Facilitator의 능력 선언은 다음 위치에 있습니다:

```bash theme={null}
curl https://facilitator.acedata.cloud/.well-known/x402
```

이것은 `/supported`, `/verify`, `/settle` 및 현재 활성화된 결제 네트워크만 설명하며, API 리소스는 나열하지 않습니다.

Ace Data Cloud의 생산 Facilitator 주소는 다음과 같습니다:

```text theme={null}
https://facilitator.acedata.cloud
```

어떤 네트워크와 스킴을 지원하는지 확인할 수 있습니다:

```bash theme={null}
curl https://facilitator.acedata.cloud/supported
```

반환된 `kinds`는 Facilitator가 지원하는 네트워크와 스킴을 나열합니다. 실제 호출 시에는 여전히 API가 반환한 `accepts`를 기준으로 합니다.

Facilitator `/supported` 출력:

```text theme={null}
kinds [
  ('eip155:8453', 'exact'),
  ('eip155:8453', 'upto', {'facilitatorAddress': '0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708'}),
  ('eip155:1187947933', 'exact'),
  ('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'exact')
]
```

결과 설명:

* `/supported`는 Facilitator가 이러한 네트워크와 스킴의 검증 및 정산 능력을 갖추고 있음을 설명합니다.
* Base, SKALE 및 Solana는 모두 `exact`를 지원합니다; `upto`는 현재 Base에서만 제공됩니다.
* 특정 API가 특정 네트워크를 허용하는지는 여전히 해당 API의 402 `accepts`를 기준으로 합니다.


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