x402 엔드포인트가 Bazaar에 표시되지 않는 경우? 10가지 원인과 해결책

원래 unlisted.sh/guide에서 게시되었습니다. 저는 언급된 유료 검사기인 Unlisted를 구축했지만, 여기의 모든 것은 무료로 수동으로 작동합니다.

사용자의 x402 엔드포인트가 402 응답을 반환하고 결제를 받아 정상적으로 작동합니다. 하지만 CDP Bazaar에 등록되어 있지 않아 카탈로그에서 검색하는 에이전트들이 이를 찾지 못하는 경우입니다. 저는 제 자체 API에서 이러한 문제들을 여러 번 겪었기 때문에, 제가 아는 모든 원인과 각각의 증상 및 해결책을 공유합니다.

경로가 목록에 등록되는 방법

Bazaar는 x402 엔드포인트를 위해 웹을 크롤링하지 않습니다. 어떤 경로가 목록에 등록되려면 CDP의 결제 처리자(facilitator)를 통해 결제가 정산되어야 하며, 402 도전 응답(challenge)에는 유효한 extensions.bazaar 선언이 포함되어야 합니다. 그 후에 CDP가 주기적으로 재크롤링을 수행합니다. 따라서 다음 세 가지가 필요합니다: 잘 구성된 도전 응답, 결제 처리자로서의 CDP, 그리고 최소 한 건의 정산된 결제.

첫 번째 무료 단계: Bazaar에 직접 문의하기

CDP의 디스커버리 API는 공개적입니다. 받는 지갑 주소와 함께 브라우저에서 이것을 열어보세요:

만약 사용자의 경로가 여기에 있다면, 등록된 것입니다. 그렇지 않다면 계속 읽어보세요.

빠른 진단

1. CDP를 통해 아직 결제가 정산되지 않음

증상: 도전 응답 자체는 올바르게 보이지만, 해당 경로에 대한 결제가 한 번도 이루어지지 않은 경우입니다. 이는 완전히 새로운 엔드포인트에서 가장 흔한 원인입니다.

해결책: CDP의 결제 처리자를 통해 정산되는 실제 유료 호출을 이 경로로 한 번 해보세요. 1센트만으로 충분합니다. 그런 다음 Bazaar가 크롤링할 시간을 주세요.

2. 다른 결제 처리자를 통해 결제가 이루어지는 경우

증상: 실제로 정산된 결제가 있었음에도 불구하고, 경로가 여전히 목록에 등록되지 않은 경우입니다.

해결책: CDP Bazaar는 오직 CDP의 결제 처리자를 통해 발생하는 정산을 통해서만 경로를 알게 됩니다. 만약 사용자의 서버가 다른 결제 처리자를 사용한다면, CDP는 그 결제를 볼 수 없습니다. 해당 경로를 CDP의 결제 처리자(CDP API 키가 필요함)로 지정한 다음, 유료 호출을 한 번 더 해보세요.

3. extensions.bazaar가 누락되었거나 잘못된 경우

3. extensions.bazaar가 누락되었거나 잘못된 경우

증상(Symptom): 결제는 이루어지지만, Bazaar가 인덱싱할 내용이 없습니다. 402 챌린지를 디코드했을 때, extensions.bazaar가 없거나 불완전합니다.

해결책(Fix): 라우트(route)에 발견 메타데이터(discovery metadata)를 선언하세요. Python SDK에서는 declare_discovery_extension(...)을 사용하여 해당 함수를 라우트의 extensions로 전달하고, 리소스 서버(resource server)에서 bazaar_resource_server_extension을 등록해야 합니다. 최소한 extensions.bazaar.info.input.type은 `

해결책: resource.url 포함: 결제 경로의 전체 공개 HTTPS URL을 포함해야 합니다. 현재 x402 SDK가 이 값을 자동으로 채워줍니다. 직접 구현한 402 응답은 종종 이를 누락합니다.

7. 402 본문이 비어 있거나 accepts 필드가 잘못된 경우

증상: x402 v2는 챌린지를 base64로 인코딩된 PAYMENT-REQUIRED 헤더에 담아 보내고, 일부 서버는 본문을 {}로 전송합니다. 본문을 읽는 클라이언트와 크롤러는 결제 옵션을 찾을 수 없습니다.

해결책: 해당 헤더를 유지하고, 402 본문과 동일한 디코딩된 JSON을 반환해야 합니다. accepts가 scheme, network, asset, amount, payTo를 각각 가진 객체들의 비어 있지 않은 배열인지 확인하십시오.

8. POST 경로가 GET으로 설명되는 경우

증상: 해당 경로는 JSON 본문을 받지만, 목록(또는 검증)이 이를 GET으로 처리하여 본문 없이 오류를 반환합니다. (402 대신)

해결책: 발견 메타데이터에 본문을 선언해야 합니다. Python SDK에서는 declare_discovery_extension에 `body_type=

직접 챌린지를 디코딩하기 번거롭다면, Unlisted가 이러한 모든 검사를 귀하의 엔드포인트에 대해 실행하고 CDP에게 라이브 인덱스 상태를 요청합니다. 여기에는 아직 목록에 올라가지 않은 경로라도 CDP가 수락할지 여부가 포함됩니다. 이는 x402 (Base의 USDC) 기반의 호출당 결제 방식이며, 가입 절차 없이 이용 가능하며, 검사가 완료될 때만 요금이 부과됩니다:

• 검사, $0.02: 귀하의 402 챌린지, Bazaar 선언, 그리고 CDP의 라이브 인덱스 상태.
• 검사 + 실제 결제, $0.10: 위 모든 것과 더불어, 귀하의 경로에 대한 실제 테스트 결제 한 건이 포함되어 있어 원인 1을 해결해 드립니다.

POST https://unlisted.sh/diagnose
Content-Type: application/json

...

최신 정보를 담은 전체 가이드는 unlisted.sh/guide에서 확인할 수 있습니다. 여기에 목록에 없는 원인을 발견하셨다면 댓글로 알려주세요. 제가 추가하겠습니다.

Unlisted는 Coinbase와 제휴 관계가 아닙니다.