X402 빠른 시작

본 튜토리얼은 최소한의 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
X402 Client 저장소: https://github.com/AceDataCloud/X402Client
npm: @acedatacloud/sdk, @acedatacloud/x402-client
PyPI: acedatacloud, acedatacloud-x402

TypeScript:

npm install @acedatacloud/sdk @acedatacloud/x402-client ethers

Python:

pip install acedatacloud acedatacloud-x402

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

npm install @solana/web3.js

Python 버전의 Solana signer 종속성은 이미 acedatacloud-x402에 포함되어 있습니다. 깨끗한 임시 환경의 설치 및 가져오기 확인 출력:

@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를 포함하지 않기 때문에 요금이 부과되지 않습니다:

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 배열이 포함되며, 일반적인 구조는 다음과 같습니다:

{
  "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의 미지급 요청 프로그램 출력 요약은 다음과 같습니다:

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에 따릅니다:

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의 프로그램 실행 결과:

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 호출 방식으로 작성되었습니다.

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

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

Facilitator 지원 능력 확인

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

curl https://facilitator.acedata.cloud/.well-known/x402

이것은 /supported, /verify, /settle 및 현재 활성화된 결제 네트워크만 설명하며, API 리소스는 나열하지 않습니다. Ace Data Cloud의 생산 Facilitator 주소는 다음과 같습니다:

https://facilitator.acedata.cloud

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

curl https://facilitator.acedata.cloud/supported

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

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를 기준으로 합니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

준비 작업

SDK 설치

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

SDK로 결제 재시도 완료

Facilitator 지원 능력 확인

​준비 작업

​SDK 설치

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

​SDK로 결제 재시도 완료

​Facilitator 지원 능력 확인

준비 작업

SDK 설치

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

SDK로 결제 재시도 완료

Facilitator 지원 능력 확인