> ## 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 E2E 검증 및 문제 해결

> Platform API guide - Ace Data Cloud

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

## 공개 엔드포인트 확인

Facilitator 기능 선언:

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

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

Facilitator 지원 기능:

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

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

## 402 `accepts` 확인

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

```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`에 사용할 네트워크가 포함되어 있는지 확인합니다. `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](https://github.com/AceDataCloud/X402Client)

```bash theme={null}
git clone https://github.com/AceDataCloud/X402Client.git
cd X402Client/typescript
npm install
npm install --no-save ethers @solana/spl-token bs58 tsx
```

Base:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
export X402B_SOLANA_PAYER_PRIVATE_KEY=...
npx tsx scripts/test-solana-e2e.ts
```

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

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

개인 키 또는 전체 `PAYMENT-SIGNATURE`를 로그 시스템이나 티켓에 보내지 마십시오.

공개 API 검증 결과 예시:

```text theme={null}
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:

```ts theme={null}
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:

```python theme={null}
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의 프로그램 실행 결과:

```text theme={null}
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`를 서명 및 결제의 기준으로 삼으십시오.

```text theme={null}
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 응답의 실시간 필드와 클라이언트 서명이 완전히 일치하는지 특히 확인해야 합니다.

```text theme={null}
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`를 반환하는 경우, 우선 다음을 확인합니다:

1. API가 반환한 `eip155:8453` + `upto` 항목의 `extra.chainId`(값은 `8453`이어야 함).
2. API가 반환한 `extra.facilitatorAddress`.
3. `https://facilitator.acedata.cloud/supported`가 반환한 Base `upto` facilitator 주소.
4. Permit2 domain, spender, USDC 계약 및 서명 계정.
5. 지갑이 이미 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`로 처리하고, 고객 서비스 검색을 위해 공개 기술 코드를 보존하세요.


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