> ## 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 X402는 HTTP `402 Payment Required`를 기반으로 한 온체인 결제 프로토콜입니다. Ace Data Cloud의 X402 기능을 통해 호출자는 API 토큰을 생성하거나 계좌 잔액을 미리 충전하지 않고도 매 API 요청마다 USDC로 직접 온체인 결제를 완료할 수 있습니다. 이 문서 세트는 실제 통합 순서에 따라 구성되어 있습니다: 먼저 최소 요청을 실행한 후 SDK를 통합하고, 그 다음 네트워크, 요금제, 주문 결제 및 Facilitator를 이해합니다. 아래 표에 따라 위에서 아래로 읽는 것을 권장합니다. | 튜토리얼 | 적합한 상황 | 링크 | | - | - | - | | 빠른 시작 | 최소 요청을 통해 402, `accepts` 및 `PAYMENT-SIGNATURE` 프로세스를 이해하기 | [X402 빠른 시작](https://platform.acedata.cloud/documents/x402-quickstart) | | TypeScript SDK | 브라우저, Node.js 또는 프론트엔드 애플리케이션에서 Ace Data Cloud API 호출 | [TypeScript SDK 통합](https://platform.acedata.cloud/documents/x402-typescript-sdk) | | Python SDK | Python 서비스, 스크립트, 에이전트 또는 데이터 파이프라인에서 API 호출 | [Python SDK 통합](https://platform.acedata.cloud/documents/x402-python-sdk) | | 주문 결제 | X402를 사용하여 Ace Data Cloud 콘솔 주문 결제 | [주문 결제 튜토리얼](https://platform.acedata.cloud/documents/x402-order-payment) | | 네트워크 및 결제 방법 | Base, SKALE, Solana의 자산, 서명 및 적합한 상황 이해 | [네트워크 및 결제 방법](https://platform.acedata.cloud/documents/x402-networks) | | `exact` 및 `upto` | 고정 가격 API와 사용량 후속 정산 API 구분 | [요금제 설명](https://platform.acedata.cloud/documents/x402-metered-upto) | | 가격 설명 | X402 가격과 크레딧 단가의 관계 및 각 서비스의 실제 가격 이해 | [X402 가격 설명](https://platform.acedata.cloud/documents/x402-pricing) | | Facilitator | `verify`, `settle` 및 자체 수금 API의 서버 측 링크 이해 | [Facilitator 통합](https://platform.acedata.cloud/documents/x402-facilitator) | | E2E 및 문제 해결 | 공개 엔드포인트 확인, 고급 검증 도구 실행, 일반적인 402, 서명 및 정산 문제 위치 지정 | [E2E 검증 및 문제 해결](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting) | ## 추천 통합 경로 Ace Data Cloud API를 호출하려는 경우, 공식 SDK를 우선적으로 사용하세요: * TypeScript: `@acedatacloud/sdk` + `@acedatacloud/x402-client` * Python: `acedatacloud` + `acedatacloud-x402` 공식 소스 코드 및 패키지 주소: | 프로젝트 | 주소 | | - | - | | Ace Data Cloud SDK | [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) | | X402 클라이언트 | [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client) | | X402 Facilitator | [https://github.com/AceDataCloud/FacilitatorX402](https://github.com/AceDataCloud/FacilitatorX402) | | npm SDK | [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk) | | npm X402 클라이언트 | [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client) | | 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/) | SDK는 첫 번째 인증 없는 요청을 자동으로 처리하고, `402 Payment Required`를 해석하며, 결제 핸들러를 호출하고, `PAYMENT-SIGNATURE`를 포함하여 이러한 단계를 재시도합니다. 당신은 USDC가 있는 지갑을 준비하고 사용하고자 하는 네트워크를 선택하기만 하면 됩니다. 자신의 API도 X402 수금을 지원하게 하려면 Facilitator 문서를 읽고 `paymentRequirements`, `paymentPayload`, `/verify` 및 `/settle`의 관계를 이해해야 합니다. ## 지원 상태 Ace Data Cloud X402는 공개 API, 공식 SDK, Facilitator 및 온체인 정산 경로에서 검증을 완료했습니다. 아래 표는 개발자가 통합할 때 가장 자주 사용하는 기능 차원에 따라 현재 상태를 요약합니다. | 기능 | 상태 | 설명 | | - | - | - | | Facilitator 기능 | 사용 가능 | `https://facilitator.acedata.cloud/.well-known/x402`가 결제 네트워크 및 프로토콜 엔드포인트를 반환합니다. | | API 402 `accepts` | 사용 가능 | 미결제 요청은 Base, SKALE 및 Solana의 사용 가능한 결제 요구 사항을 반환합니다. | | TypeScript SDK | 사용 가능 | `@acedatacloud/sdk`와 `@acedatacloud/x402-client`가 402, 서명 및 재시도를 자동으로 처리합니다. | | Python SDK | 사용 가능 | `acedatacloud`와 `acedatacloud-x402`가 402, 서명 및 재시도를 자동으로 처리합니다. | | Base `exact` | 온체인 검증 완료 | 고정 금액 API 및 주문 결제에 적합합니다. | | Base `upto` | 온체인 검증 완료 | 채팅 보완 등 후속 계량 API에 적합하며, 현재 유일하게 `upto`를 제공하는 네트워크입니다. | | SKALE `exact` | 온체인 검증 완료 | 낮은 가스 비용의 EVM 결제 상황에 적합합니다. | | Solana `exact` | HTTP 유료 재시도 검증 완료 | 검증된 API 유료 재시도 및 모델 응답; 온체인 서명 확인은 자체 Solana RPC 대조를 사용하는 것이 좋습니다. | | 주문 결제 | 온체인 검증 완료 | Base `exact` 주문 결제가 온체인 정산을 완료하고 주문 상태를 업데이트했습니다. | 다음 출력은 검증된 경로의 반환 형태를 설명하기 위한 것입니다. 실제 통합 시에는 항상 현재 API에서 반환된 `accepts`를 기준으로 하십시오. ```text theme={null} 패키지 @acedatacloud/sdk@2026.504.2 가져오기 ok @acedatacloud/x402-client@2026.531.3 가져오기 ok acedatacloud==2026.4.26.1 가져오기 ok acedatacloud-x402==2026.5.31.3 가져오기 ok API 402 상태 402 수락 eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact TypeScript SDK 내용 ADC_TS_SDK_X402_OK Python SDK 내용 ADC_PY_SDK_X402_OK Base exact 내용 ADC_BASE_E2E_OK tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 탐색기 https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 SKALE exact 내용 ADC_SKALE_E2E_OK tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f 탐색기 https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f Base upto 내용 ADC_BASE_UPTO_OK tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 탐색기 https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 서명된 한도 95215 atomic USDC 전송 값 3 atomic USDC Solana exact HTTP 402 -> HTTP 200 내용 ADC_SOLANA_E2E_OK 체인 서명 이 실행에서 확인되지 않음 주문 결제 주문 78481793-304e-47f7-bc0c-8231aec9cc1e 상태 완료 결제 방법 X402 tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 탐색기 https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 ``` 설명： * npm 및 PyPI 패키지가 모두 깨끗한 환경에 설치되어 성공적으로 가져왔습니다. * 미지급 API 요청은 402를 반환하며, `accepts`에는 Base, SKALE 및 Solana의 사용 가능한 결제 방법이 포함되어 있습니다. * `accepts[].network`는 CAIP-2 식별자로, 클라이언트가 네트워크를 선택할 때 CAIP-2 문자열 일치를 따라야 합니다. * TypeScript SDK와 Python SDK는 모두 402를 자동으로 처리하고 유료 재시도를 완료할 수 있습니다. * Base `exact`, SKALE `exact`, Base `upto` 및 주문 결제에는 공개적으로 열 수 있는 탐색기 주소가 있습니다. * Base `upto`의 서명 한도는 `95215` atomic USDC이며, 실제 정산은 `3` atomic USDC로, 후속 측정이 실제 사용량에 따라 정산되는 특성을 반영합니다. * Solana `exact`는 HTTP 402 -> HTTP 200 및 모델 출력을 검증했습니다. 공개 RPC 쿼리가 속도 제한을 받을 수 있으므로, 엄격한 정산 시에는 자체 Solana RPC 또는 플랫폼 측 정산 기록을 사용하여 거래 서명을 확인하는 것이 좋습니다. ## 접속 주의 사항 개발자가 접속할 때는 문서의 예제 금액이나 주소를 복사하기보다는 현재 요청에서 반환된 실시간 결제 요구 사항에 우선적으로 주목해 주십시오: * `accepts[].maxAmountRequired`는 현재 요청에서 서명할 수 있는 최대 금액입니다. * `accepts[].asset`는 이번 요청에서 사용할 USDC 계약 또는 민트입니다. * `accepts[].extra.chainId`, `accepts[].extra.facilitatorAddress` 및 `accepts[].extra.verifyingContract`는 EVM 타입 데이터 서명에 참여합니다. * `upto`는 지갑이 먼저 목표 체인 USDC에 대한 Permit2를 승인해야 합니다; 승인되지 않은 경우 `PERMIT2_ALLOWANCE_REQUIRED`가 반환됩니다. * 후속 측정을 명확히 원하신다면 TypeScript SDK에 `preferScheme: 'upto'`를 전달해 주십시오. 그렇지 않으면 SDK는 해당 네트워크에서 서버가 반환한 첫 번째 사용 가능한 요구 사항을 선택합니다. ## 공개 검증 가능한 범위 접속 전에 이러한 공개 엔트리와 SDK 동작을 먼저 검증할 수 있습니다: * `Authorization` 또는 `PAYMENT-SIGNATURE`가 없는 API 요청은 `402 Payment Required`를 반환하며, 응답의 `accepts`는 이번 요청의 유일한 서명 근거입니다. * TypeScript SDK와 Python SDK는 모두 결제 핸들러를 제공하며, SDK 전송 계층은 402를 수신한 후 핸들러를 호출하고 한 번 재시도합니다. * `https://facilitator.acedata.cloud/.well-known/x402`: Facilitator가 지원하는 네트워크, 스킴 및 프로토콜 엔드포인트를 반환합니다; API 가격은 여전히 목표 요청에서 실시간으로 반환된 402를 기준으로 합니다. * `https://facilitator.acedata.cloud/supported`: Facilitator가 지원하는 네트워크와 스킴을 반환합니다. * X402Client 저장소에는 서명 확인, 재시도 및 정산 동작을 위한 고급 체인 상 검증 도구가 포함되어 있습니다; 도구 출력은 온라인 API에서 반환된 `accepts`를 대체하지 않습니다. `upto`는 후속 측정 정산에 해당하며, 채팅 완성, 모델 호출 등 실제 사용량이 응답 후에야 알려지는 API에 적합합니다. 현재 Base만 `upto`를 제공하며, 서명 검증이 실패하면 체인 ID, facilitator 주소, spender, USDC 계약 및 Permit2 허용량이 402 응답과 일치하는지 확인하십시오. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.