X402 E2E 검증 및 문제 해결

X402는 HTTP, SDK, 서명, Facilitator 및 온체인 트랜잭션을 포함합니다. 서명 또는 정산 문제를 해결할 때는 “공개 엔드포인트 -> 402 응답 -> SDK payment handler -> 온체인 settlement” 순서로 각 계층을 확인하는 것을 권장합니다. 이 튜토리얼에서는 각 계층의 확인 방법을 설명하고 일반적인 오류를 나열합니다.

공개 엔드포인트 확인

Facilitator 기능 선언:

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

facilitator, supportedKinds 및 프로토콜 엔드포인트가 반환되면 기능 메타데이터가 정상임을 의미합니다. API 리소스 검색은 폐기되었습니다. 대상 API를 직접 호출하고 실시간 402 응답을 기준으로 하십시오. Facilitator 지원 기능:

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

kinds가 반환되면 Facilitator 엔드포인트가 정상임을 의미합니다.

402 `accepts` 확인

요금이 청구되지 않는 인증 없는 요청을 보냅니다:

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에 사용할 네트워크가 포함되어 있는지 확인합니다. network는 CAIP-2 식별자입니다:

eip155:8453 + exact（Base）
eip155:8453 + upto（Base, 사후 계량）
eip155:1187947933 + exact（SKALE）
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact（Solana）

대상 네트워크가 없으면 해당 API 또는 현재 환경에 대응하는 X402 수금 방식이 구성되지 않았음을 의미합니다.

X402Client 고급 검증 도구 실행

X402Client 저장소는 402 응답 선택, 서명 생성, paid retry 및 온체인 settlement를 확인하는 데 사용할 수 있는 고급 검증 도구를 제공합니다. 이 도구들은 funded wallet, RPC, 개인 키 및 개발 의존성이 필요합니다. 일반적인 비즈니스 연동에는 TypeScript 또는 Python SDK를 우선 사용하는 것을 권장합니다. 서명 또는 온체인 정산 문제를 파악해야 할 때만 이 도구를 실행하십시오. 저장소 주소: https://github.com/AceDataCloud/X402Client

git clone https://github.com/AceDataCloud/X402Client.git
cd X402Client/typescript
npm install
npm install --no-save ethers @solana/spl-token bs58 tsx

Base:

export X402B_BASE_PAYER_PRIVATE_KEY=0x...
TEST_API_PATH='/openai/chat/completions' \
TEST_BODY='{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' \
npx tsx scripts/test-real-e2e.ts

SKALE:

export SKALE_BASE_PRIVATE_KEY=0x...
TEST_API_PATH='/openai/chat/completions' \
TEST_BODY='{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' \
npx tsx scripts/test-skale-e2e.ts

Solana:

export X402B_SOLANA_PAYER_PRIVATE_KEY=...
npx tsx scripts/test-solana-e2e.ts

검증 도구는 일반적으로 다음을 출력합니다:

첫 번째 요청의 402 응답.
선택된 payment requirement.
서명된 PAYMENT-SIGNATURE 요약.
재시도 후의 HTTP 상태 및 응답 본문.
온체인 settlement transaction 또는 실패 시 Facilitator 오류 원인.

개인 키 또는 전체 PAYMENT-SIGNATURE를 로그 시스템이나 티켓에 보내지 마십시오. 공개 API 검증 결과 예시:

SKALE exact
HTTP 402 -> HTTP 200
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
block 1969317
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
paid 0.095215 USDC

Base exact
HTTP 402 -> HTTP 200
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
block 46726299
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
transfer value 95215 atomic USDC

Solana exact
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run because public RPC lookup hit 429

Base upto
HTTP 402 -> HTTP 200
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

설명:

SKALE exact, Base exact, Solana exact 및 Base upto 모두 HTTP 402에서 HTTP 200으로의 paid retry를 완료했습니다.
SKALE exact의 온체인 트랜잭션은 SKALE explorer에서 조회할 수 있으며, 정산 금액은 0.095215 USDC입니다.
Base exact의 온체인 트랜잭션은 BaseScan에서 조회할 수 있으며, 정산 금액은 95215 atomic USDC입니다.
Base upto의 서명 한도는 95215 atomic USDC이지만, 실제 온체인 settlement는 3 atomic USDC이므로 사후 계량이 실제 사용량에 따라 청구됨을 의미합니다.
Solana 경로는 paid retry와 모델 출력을 확인했습니다. 공개 RPC는 속도 제한될 수 있습니다. 엄격한 온체인 대조가 필요한 경우 자체 Solana RPC 또는 플랫폼 측 정산 기록을 사용하여 트랜잭션 서명을 확인하십시오.

SDK smoke test

고급 검증 도구는 서명과 온체인 정산을 확인하는 데 사용됩니다. 비즈니스 측에서는 SDK smoke test도 실행하여 애플리케이션 코드가 payment handler를 통해 402를 자동으로 처리할 수 있는지 확인해야 합니다. 아래에는 핵심 코드 조각만 표시하며, 전체 코드에서는 지갑, provider 및 import를 보완해야 합니다. TypeScript:

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

const res = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Reply with exactly ADC_SDK_X402_OK' }],
  max_tokens: 8
});

Python:

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="skale",
        evm_signer=signer,
    )
)

res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply with exactly ADC_PY_X402_OK"}],
    max_tokens=8,
)

모델이 요구대로 고정 문자열을 반환하면 SDK, payment handler, Gateway, Facilitator 및 대상 API가 연결되었음을 의미합니다. 위의 두 smoke test는 SKALE exact를 사용합니다. SKALE은 현재 exact만 제공하며, 402 견적의 고정 금액으로 정산되고 실제 token 사용량에 따라 인하되지 않습니다. 채팅 완성은 token 기준으로 계량되는 시나리오이므로, 정식 연동 시 Base로 변경하고 preferScheme: 'upto'를 전달하여 실제 사용량에 따라 정산하는 것을 권장합니다. SDK smoke test의 프로그램 실행 결과:

TypeScript SDK
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT

Python SDK
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 4786
content ADC_PY_SDK_X402_OK
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz

결과 설명:

TypeScript SDK는 createX402PaymentHandler를 통해 402, 서명 및 재시도를 자동으로 처리하고, 최종적으로 ADC_TS_SDK_X402_OK를 받습니다.
Python SDK는 create_x402_payment_handler를 통해 동일한 흐름을 완료하고, 최종적으로 ADC_PY_SDK_X402_OK를 받습니다.
두 smoke test 모두 SKALE payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C를 사용합니다.
Python SDK의 반환 객체는 dict이며, 예제에서는 res["choices"][0]["message"]["content"]를 사용하여 내용을 읽을 수 있습니다.

주문 결제 E2E

주문 결제는 platform.acedata.cloud의 플랫폼 API를 사용하며, 플랫폼 계정 토큰이 필요합니다. 전체 흐름은 Pending 주문 생성, POST /api/v1/orders/{order_id}/pay/로 402 트리거, 이후 PAYMENT-SIGNATURE를 포함하여 재시도하는 것입니다. 소액 주문 결제 검증 결과 예시:

아래 거래 기록은 이전 정책에 따른 과거 실측 샘플이며, 금액과 거래 해시는 원본 그대로 보존됩니다. 새 X402 주문에는 더 이상 결제 수단 할인이 적용되지 않습니다. 이번 402 응답의 amount를 서명 및 결제의 기준으로 삼으십시오.

created order 78481793-304e-47f7-bc0c-8231aec9cc1e
created state Pending
created price 1.26

http_status=402
x402Version 2
accepts [('eip155:8453', 'exact', '1200000'), ('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'exact', '1200000')]

status 200
order state Finished
pay_way X402
pay_id 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
settle_header {'success': True, 'network': 'base', 'transaction': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151'}

Base tx status 1
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC

결과 설명:

주문 생성 후 주문 상태는 Pending이고 가격은 1.26입니다.
첫 번째 pay/ 요청은 HTTP 402를 반환하며, accepts에는 Base exact와 Solana exact가 있고 금액은 모두 1200000 atomic USDC입니다.
Base PAYMENT-SIGNATURE를 포함하여 재시도한 후 HTTP 200이 반환되고, 주문 상태는 Finished로 변경되며 pay_way는 X402입니다.
PAYMENT-RESPONSE를 디코딩하면 success=True, network=base가 표시되고 동일한 거래 해시가 제공됩니다.
BaseScan에서 거래 상태는 1이고, 전송 금액은 1200000 atomic USDC, 즉 1.2 USDC입니다.
생성 가격 1.26은 이전 X402 결제 할인 정책 기간에 결제되었으며, 최종 서명 및 정산 금액은 1.2 USDC입니다.

주문 결제에 Authorization: Bearer {platform_token}이 없거나 주문이 현재 계정에 속하지 않는 경우, 플랫폼 권한 계층에서 실패합니다. 이는 x402.acedata.cloud의 계정 없는 X402 API를 직접 호출하는 경우와 다릅니다.

일반적인 오류

현상	점검 방향
첫 번째 요청이 402가 아님	실수로 `Authorization`을 포함했는지 또는 해당 API에 아직 X402 pricing이 없는지 확인합니다.
`No payment requirement for network`	대상 네트워크가 `accepts`에 없습니다. 네트워크를 변경하거나 Gateway 구성을 확인합니다.
`invalid_402`	402 응답이 유효한 JSON이 아닙니다. 프록시, 게이트웨이 또는 오류 페이지를 확인합니다.
`Authorization nonce already processed`	동일한 `PAYMENT-SIGNATURE`를 재사용했습니다. 다시 서명합니다.
`invalid_upto_evm_payload_invalid_signature`	`upto`의 chainId, Permit2 domain, facilitator 주소, 서명 계정이 일치하는지 확인합니다.
`PERMIT2_ALLOWANCE_REQUIRED`	대상 체인의 USDC에 대해 `approve-permit2`를 실행합니다.
`Payer has insufficient USDC balance`	결제 지갑의 USDC 잔액이 부족합니다.
HTTP 200이지만 tx hash가 없음	`upto`의 실제 금액이 0일 수 있거나 settlement 기록이 아직 비동기로 작성 중일 수 있습니다.
Solana `Missing transaction payload`	`PAYMENT-SIGNATURE` envelope에 직렬화된 거래 또는 signature가 없습니다. wallet adapter를 확인합니다.

Base `upto` 체크리스트

upto는 현재 Base에서만 제공됩니다(eip155:8453). SKALE은 exact만 제공합니다. upto 서명은 더 많은 EVM typed data 매개변수에 바인딩되므로, 연동 시 402 응답의 실시간 필드와 클라이언트 서명이 완전히 일치하는지 특히 확인해야 합니다.

SKALE exact
HTTP 402 -> HTTP 200
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

Base upto
HTTP 402 -> HTTP 200
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Base upto가 invalid_upto_evm_payload_invalid_signature를 반환하는 경우, 우선 다음을 확인합니다:

API가 반환한 eip155:8453 + upto 항목의 extra.chainId(값은 8453이어야 함).
API가 반환한 extra.facilitatorAddress.
https://facilitator.acedata.cloud/supported가 반환한 Base upto facilitator 주소.
Permit2 domain, spender, USDC 계약 및 서명 계정.
지갑이 이미 Base USDC에 대해 Permit2를 approve했는지 여부.

upto의 서명 digest는 Permit2 domain, chain ID, spender, 수금 주소, facilitator 주소 및 validAfter를 동시에 바인딩합니다. 어느 하나라도 일치하지 않으면 Facilitator는 잘못된 signer를 복구하게 되어 invalid signature를 반환합니다. 이들이 모두 일치하지만 여전히 402가 반환된다면, 다음으로 Permit2 allowance를 확인합니다. 권한이 없으면 PERMIT2_ALLOWANCE_REQUIRED가 반환됩니다.

검증 정보 저장

한 번의 완전한 검증에는 최소한 다음을 저장합니다:

API path 및 요청 본문 요약;
선택된 network 및 scheme;
maxAmountRequired;
payer 지갑 주소;
HTTP 최종 상태;
응답의 모델 출력 또는 작업 ID;
settlement transaction 링크;
Gateway trace ID 또는 플랫폼 사용 기록 ID.

개인 키, 전체 PAYMENT-SIGNATURE, 전체 EIP-712 signature 또는 니모닉은 저장하지 마세요.

구조화된 결제 오류

서명 후 X402 실패는 extensions.acedatacloud.paymentError에 안정적인 code, 안전한 삽입 매개변수, 단계 및 재시도 가능 플래그를 반환합니다. 이 구조를 우선 사용하여 문제를 해결하고, 최상위 영어 error를 파싱하지 말며, 사용자에게 지갑 서명이나 온체인 시뮬레이션 원문을 제공하도록 요구하지 마세요.

charged: false: 검증이 settlement 전에 명확하게 거부되었으며, 이번에는 청구가 시작되지 않았습니다.
charged 없음: 결과를 알 수 없거나 이미 settlement 단계에 진입했으므로, 먼저 주문 및 온체인 상태를 확인하고 직접 재결제하는 것을 금지합니다.
settlement_pending: 당분간 재결제하지 말고, 먼저 주문을 새로고침하거나 지원팀에 문의하세요.
인식되지 않은 code: payment_failed로 처리하고, 고객 서비스 검색을 위해 공개 기술 코드를 보존하세요.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

X402 E2E 검증 및 문제 해결

공개 엔드포인트 확인

402 `accepts` 확인

X402Client 고급 검증 도구 실행

SDK smoke test

주문 결제 E2E

일반적인 오류

Base `upto` 체크리스트

검증 정보 저장

구조화된 결제 오류

​공개 엔드포인트 확인

​402 accepts 확인

​X402Client 고급 검증 도구 실행

​SDK smoke test

​주문 결제 E2E

​일반적인 오류

​Base upto 체크리스트

​검증 정보 저장

​구조화된 결제 오류

공개 엔드포인트 확인

402 `accepts` 확인

X402Client 고급 검증 도구 실행

SDK smoke test

주문 결제 E2E

일반적인 오류

Base `upto` 체크리스트

검증 정보 저장

구조화된 결제 오류