결제(Settlement)는 당신에게 대가를 지불하게 합니다. 발견(Discovery)은 당신이 찾아지게 합니다. 이 둘은 서로 다른 시스템입니다.

우리가 x402 Global Challenge 기간 동안 가장 많이 접한 질문 중 하나는 다음과 같습니다:

"제 엔드포인트(endpoint)가 라이브 상태입니다. 결제도 잘 작동하고 있습니다. 그런데 왜 리더보드(leaderboard)나 Bazaar에는 나타나지 않나요?"

거의 모든 경우에서, 결제 흐름(payment flow)은 완벽하게 작동하고 있습니다.

빠져 있는 조각은 대개 **발견(discovery)**이며, Global Challenge 참가자들의 경우, 자신의 엔드포인트가 챌린지에 맞게 올바르게 태그(tagged)되었는지 확인하는 것입니다.

확인해야 할 사항은 실제로 두 가지가 있습니다:

1. 당신의 엔드포인트에 Bazaar discovery extension이 활성화되어 있는지 확인하십시오.
2. 당신의 리소스(resource)에 x402-global-challenge 태그가 지정되어 있어, 챌린지 활동이 올바르게 식별되고 귀속되는지 확인하십시오.

엔드포인트가 결제를 수락하기 시작하면, 퍼실리테이터(facilitator)가 당신의 API에 대한 모든 것을 자동으로 알게 될 것이라고 가정하기 쉽습니다. 하지만 그렇지 않습니다.

당신은 x402로 보호된 엔드포인트를 출시했습니다. 결제가 검증되고, 결제가 정산(settle)되며, 돈이 도착합니다. 그러고 나서 리더보드(Leaderboard)에서 자신을 찾아보지만, 아무것도 없습니다.

무엇도 고장 나지 않았습니다. 단지 발견 확장 기능(discovery extension)을 선언하지 않았거나, 엔드포인트가 챌린지용으로 태그되지 않았을 뿐입니다. 두 가지 모두 작은 설정 변경 사항이지만, 놓치기 쉽습니다.

30초 체크

더 읽기 전에, 이것이 당신의 상황인지 확인해 보십시오:

curl -s "https://facilitator.goplausible.xyz/discovery/resources?includeTestnets=true&limit=1000" \
  | jq '.items[] | select(.resourceUrl | contains("your-domain"))'

출력이 비어 있는데 결제는 정산되고 있습니까? 계속 읽어보십시오. 그것이 바로 이 포스트가 해결하고자 하는 정확한 격차입니다.

결제와 발견은 두 개의 서로 다른 시스템입니다

이것이 혼란의 근본 원인이므로, 솔직하게 말씀드리는 것이 가치가 있습니다:

퍼실리테이터 (Facilitator)가 당신을 대신해 수천 건의 결제를 처리할 수 있지만, 여전히 게시할 내용이 아무것도 없을 수 있습니다.

결제 (Settlement)는 단순히 특정 주소가 네트워크상에서 일정 금액을 지불했다는 증거일 뿐입니다. 여기에는 _당신의 엔드포인트가 무엇을 하는지_에 대한 설명이 포함되어 있지 않습니다. 즉, 메서드(method), 입력 형태(input shape), 출력 예시(output example) 등이 전혀 없습니다. 카탈로그 항목을 구축할 수 있는 정보가 그 안에는 아무것도 없습니다.

발견 (Discovery) 확장 기능이 바로 그 메타데이터 (metadata)를 제공합니다. 이 기능은 402 Payment Required 응답 내부에 함께 실려 전달되며, 클라이언트가 실제로 해당 결제를 수행할 때 퍼실리테이터가 이를 카탈로그에 등록합니다.

리소스 서버 (Resource Server)의 두 줄 코드

첫 번째 줄, 임포트 (import):

import { declareDiscoveryExtension } from "@x402-avm/extensions";

두 번째 줄, 이미 가지고 있는 라우트 설정 (route config) 내의 키 (key) 하나:

const routes = {
  "GET /api/quote": {
    accepts: {
...

정말로 이게 전부입니다.

빈 설정으로 declareDiscoveryExtension({})를 호출하면 유효한 발견 (discovery) 확장 기능이 생성되며, 엔드포인트를 카탈로그에 등록하기에 충분합니다. 그 이상의 정보를 전달하면 목록의 품질을 높일 수 있지만, 단순히 나타나기 위해서 필수적인 것은 아무것도 없습니다.

또한, 당신이 하지 않아도 되는 작업에도 주목하세요:

registerExtension을 호출할 필요도 없고, x402ResourceServer를 건드릴 필요도 없습니다. 프레임워크 바인딩 (framework binding)이 라우트를 스캔하여 extensions 아래의 bazaar 키를 찾아내고, 첫 번째 유료 요청이 발생할 때 서버 측 확장 기능을 자동으로 등록합니다.

동일한 동작 방식이 @x402-avm/hono, @x402-avm/express, 그리고 @x402-avm/next 전체에 적용됩니다.

리소스 설정의 extra 필드에 필요한 챌린지 태그 (challenge tag)를 추가하세요:

extra: {
  feePayer: FEE_PAYER,
  tag: "x402-global-challenge",
...

이는 귀하의 엔드포인트(endpoint)를 x402 Global Challenge의 일부로 식별하는 데 도움을 주며, 귀하의 활동이 적절히 추적되고 귀속되도록 보장합니다.

이 태그가 없다면:

• 귀하의 엔드포인트는 여전히 결제를 수락할 수 있습니다.
• 디스커버리 (Discovery) 기능도 여전히 작동할 수 있습니다.
• 하지만 귀하의 활동이 Global Challenge의 일부로 인식되지 않을 수 있습니다.

이를 퍼실리테이터 (facilitator)를 위한 메타데이터 (metadata)라고 생각하세요. 이는 플랫폼에 이 엔드포인트가 챌린지에 속해 있으며, 참가자 활동을 추적할 때 포함되어야 함을 알려줍니다.

세 가지 명령어로 확인하기

디스커버리 API (discovery API)를 직접 확인하세요. 이것이 진실의 원천 (source of truth)이며 즉시 업데이트됩니다.

# 1. 귀하의 402 응답에 디스커버리 확장 (discovery extension)이 포함되어 있는지 확인
curl -i https://your-domain/api/quote | grep -i bazaar

...

해당 API의 merchantId는 payTo 주소의 처음 24글자를 Base64 인코딩한 것이므로, 로컬에서 직접 계산하여 검색할 수 있습니다:

echo -n "YOUR_PAYTO_ADDRESS" | cut -c1-24 | tr -d '\n' | base64

1단계와 2단계 사이에는 한 번의 성공적인 결제가 필요합니다.

디스커버리는 결제 활동에 의해 트리거 (trigger)됩니다. 귀하의 402 Payment Required 응답이 하루 종일 디스커버리 확장 (discovery extension)을 광고할 수는 있지만, 퍼실리테이터는 클라이언트가 엔드포인트에 대한 결제를 성공적으로 완료한 후에야 카탈로그 항목을 생성합니다.

다른 누군가가 호출하기를 기다리기보다, 테스트 클라이언트를 사용하여 귀하의 엔드포인트에 직접 한 번 결제해 보세요.

그다음 브랜딩하기

discovery/resources가 귀하의 엔드포인트를 반환하고 귀하의 리소스가 x402-global-challenge로 올바르게 태깅되면, 공식적으로 디스커버리 (discoverable)가 가능해집니다.

이제 Bazaar에서 귀하의 API가 어떻게 보이는지 다듬을 가치가 있습니다.

도메인 루트에 다음 메타데이터를 추가하세요:

• og:site_name
• og:title
• og:description
• og:image

공개적으로 접근 가능한 로고를 사용한 다음, 퍼실리테이터가 메타데이터를 새로고침할 수 있도록 성공적인 결제를 한 번 더 실행하세요.

전체 과정을 확인하려면 이전 기사를 참조하세요:

GoPlausible 대시보드에서 x402 가맹점(Merchant) 브랜딩하기

즐거운 해킹 되세요! 🚀