메인 콘텐츠로 건너뛰기
Facilitator는 X402 흐름의 서버 측 정산 구성 요소입니다. 클라이언트는 서명을 담당하고, Gateway 또는 당신의 서버는 Facilitator의 /verify 및 /settle 호출을 담당합니다. Ace Data Cloud의 프로덕션 Facilitator 주소는 다음과 같습니다:
소스 코드 저장소: https://github.com/AceDataCloud/FacilitatorX402

v2 wire 규약

Ace Data Cloud의 X402 흐름은 공식 x402 v2를 전면 사용하며, 더 이상 v1의 X-Payment 요청 헤더를 허용하지 않습니다. 연동 시 세 가지 사항에 유의해야 합니다:
  • 요청 헤더는 PAYMENT-SIGNATURE이며, 값은 base64로 인코딩된 JSON envelope입니다.
  • envelope 최상위에는 반드시 x402Version: 2가 있어야 하며, accepted 객체를 사용하여 이번에 선택한 scheme 및 network를 선언합니다.
  • network는 CAIP-2 식별자(예: eip155:8453)를 사용하며, base와 같은 약칭을 작성할 수 없습니다.
envelope 구조:
402 응답은 JSON body 외에도 PAYMENT-REQUIRED 응답 헤더를 함께 제공하며, 값은 동일한 challenge 내용의 base64 인코딩입니다. 이를 통해 클라이언트는 body를 파싱하지 않고도 결제 요구 사항을 읽을 수 있습니다.

핵심 인터페이스

GET /supported

지원되는 네트워크와 scheme을 확인합니다:
반환 예시:
결과 설명:
  • network는 CAIP-2 식별자를 사용하며, base, solana와 같은 약칭이 아닙니다.
  • /supported는 Facilitator가 해당 검증 및 정산 기능을 보유하고 있음을 나타냅니다.
  • Base와 Solana는 모두 exact를 지원하며, upto는 현재 Base에서만 제공됩니다.
  • signers는 Facilitator가 정산 트랜잭션을 제출하는 데 사용하는 주소입니다.
  • 특정 API가 이러한 옵션을 허용하는지 여부는 여전히 해당 API의 402 accepts를 기준으로 합니다.

POST /verify

클라이언트가 전달한 PAYMENT-SIGNATURE가 특정 payment requirement를 충족하는지 검증합니다. 요청 body:
v2의 paymentRequirements 필드는 scheme, network, asset, amount, payTo, maxTimeoutSeconds, extra이며, 금액 필드는 amount입니다. API 402 응답의 accepts[]에는 클라이언트가 상한을 읽을 수 있도록 maxAmountRequired도 추가로 반환되지만, 이는 Facilitator 요청 body의 필드에 속하지 않습니다. 성공 응답:
프로덕션 주문 결제의 PAYMENT-RESPONSE 응답 헤더를 디코딩하면 settlement 결과가 포함됩니다. Base 주문 결제의 프로그램 실행 결과:
결과 설명:
  • success=True는 Facilitator settlement가 성공했음을 나타냅니다.
  • transaction은 온체인 트랜잭션 해시이며, 주문의 pay_id에도 동일한 값이 기록됩니다.
  • explorer에서 1200000 atomic USDC의 Base USDC 전송을 확인할 수 있습니다.
  • errorReason=None은 이번 settlement에서 비즈니스 오류가 반환되지 않았음을 나타냅니다.
검증 실패도 일반적으로 HTTP 200을 반환하지만, isValid는 false입니다. 비즈니스 측에서는 HTTP 상태 코드만 보지 말고 invalidReason을 읽어야 합니다.

POST /settle

이미 검증된 승인을 온체인에 정산합니다. 요청 body는 /verify와 기본적으로 동일합니다. upto의 차이점은 다음과 같습니다: paymentRequirements.amount는 settle 시 실제 정산 금액으로 다시 작성됩니다. 서명 상한은 Facilitator가 verify 단계에서 기록하며, settle 시 실제 금액이 해당 상한을 초과하지 않는지 검증합니다. 성공 응답:
upto의 실제 금액이 0인 경우, transaction은 빈 문자열일 수 있으며, 이는 온체인 트랜잭션을 보낼 필요가 없음을 나타냅니다.

Ace Data Cloud Gateway가 Facilitator를 사용하는 방법

Ace Data Cloud API Gateway의 흐름은 다음과 같습니다:
  1. 클라이언트가 처음으로 API를 요청하며, Authorization 및 PAYMENT-SIGNATURE를 포함하지 않습니다.
  2. Gateway가 요청의 예상 가격을 계산하고, 402 및 accepts를 반환합니다.
  3. 클라이언트가 서명 후 PAYMENT-SIGNATURE를 포함하여 재시도합니다.
  4. Gateway가 PAYMENT-SIGNATURE를 디코딩하고, 일치하는 payment requirement를 선택합니다.
  5. Gateway가 Facilitator /verify를 호출합니다.
  6. /verify 성공 후, Gateway가 요청을 대상 API로 통과시킵니다.
  7. 대상 API가 반환된 후, Gateway가 /record 단계에서 Facilitator /settle을 호출합니다.
  8. Gateway가 온체인 트랜잭션 해시를 사용 기록 metadata에 기록합니다.
exact는 단계 7에서 서명 금액을 정산하며, upto는 단계 7에서 실제 사용량에 따라 amount를 기록한 후 실제 금액을 정산합니다.

자신의 API를 연동하는 방법

자신의 API가 X402를 지원하도록 하려면, 이 구조에 따라 구현할 수 있습니다:
  1. 각 유료 엔드포인트에 대해 네트워크, 금액, 수금 주소, 자산 주소 및 서명 domain을 포함하는 paymentRequirements를 준비합니다.
  2. 요청에 PAYMENT-SIGNATURE가 없으면 HTTP 402와 accepts를 반환합니다.
  3. 요청에 PAYMENT-SIGNATURE가 있으면 Base64 디코딩하여 paymentPayload를 얻습니다.
  4. Facilitator /verify를 호출합니다.
  5. 검증 성공 후 비즈니스 로직을 실행합니다.
  6. 비즈니스 성공 후 Facilitator /settle을 호출합니다.
  7. 대사를 위해 payer, transaction, amount, network를 저장합니다.
서버는 자체 생성한 paymentRequirements를 사용하여 /verify와 /settle을 호출해야 하며, 클라이언트가 반환한 금액, 수금 주소 또는 자산 주소를 신뢰하지 마십시오.

재생 방지

Facilitator는 nonce를 기록합니다. 동일한 nonce의 승인은 중복 검증 및 결제할 수 없습니다. 이는 다음을 의미합니다:
  • 클라이언트는 요청할 때마다 새로운 envelope에 서명해야 합니다;
  • /settle이 트랜잭션을 제출했지만 일시적으로 확인되지 않은 경우, 동일한 nonce로 /settle을 재시도하여 멱등성 대사를 수행할 수 있습니다;
  • 동일한 PAYMENT-SIGNATURE를 캐시한 후 여러 API 호출에 사용하지 마십시오.

일반적인 오류