연동 문서 · Docs

연동부터 첫 USDC 수령까지

본 문서는 저희가 Base 메인넷에서 직접 통과시킨 경로를 바탕으로 작성되었으며, 겪은 시행착오도 담았습니다.
x402 v2 · eip155:8453 · Circle USDC · PayAI facilitator

빠른 시작

건별로 판매할 수 있는 데이터를 등록 상품으로 만드는 5단계. 처음 4단계는 콘솔에서 진행되고, 5단계는 플랫폼 심사입니다.

01

자산 생성

콘솔 → 데이터 자산 → 새 자산으로 이동해 이름, 카테고리, 갱신 주기를 입력합니다.

02

데이터 소스 연결

API / CSV / Postgres / 크롤러 중에서 선택하고 연결 정보를 입력한 뒤 ‘테스트 조회’를 눌러 응답 구조와 신선도를 확인합니다.

03

도구 분할하기

도구 팩토리에서 각 도구의 이름, 설명, 입력 파라미터, 반환 필드, 가격을 하나씩 정의합니다. 최소 하나는 무료로 설정하세요.

04

엔드포인트 + 디스커버리 생성

‘엔드포인트 생성’을 누르면 플랫폼이 MCP 엔드포인트, /.well-known 매니페스트, llms.txt를 자동으로 만들고 402 자체 점검을 한 번 실행합니다.

05

심사 제출

플랫폼이 도구 설명과 가격의 합리성을 심사합니다(보통 영업일 1일 이내). 통과하면 마켓과 Registry 대기열에 들어갑니다.

스스로 증명하는 가장 간단한 방법:결제 없이 유료 도구를 호출하면 402 챌린지를 받아야 합니다. 안의 network, asset, payTo, amount 네 필드가 모두 맞으면 설정이 올바른 것입니다——이 단계에는 비용이 들지 않습니다.

데이터 소스 연동

판매 가능한 데이터 대부분을 포괄하는 4가지 연동 방식입니다. 연결 후 플랫폼은 사용자가 선언한 갱신 주기에 따라 캐싱하여 1초 이내 응답을 보장합니다.

유형적합한 경우설정 요점
HTTP API기존 공개 API, 서드파티 데이터 소스URL / method / headers / 폴링 간격(최소 45초)
CSV / 파일명단, 디렉터리, 정적 테이블업로드 후 기본 키 열과 갱신 주기를 지정하며, 덮어쓰기 갱신을 지원합니다.
PostgreSQL업무 DB 직접 연결, 실시간성 우수읽기 전용 계정 + IP 허용 목록 + 원본 테이블 대신 뷰
정기 크롤러API가 없는 공개 페이지대상 URL 목록 + CSS 선택자 + 주기(45분 이상 권장)
POST /v1/assets
curl -X POST https://api.feegate.org/v1/assets \
  -H "Authorization: Bearer $RAILS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPU 行情快照",
    "category": "算力",
    "refresh_minutes": 45,
    "source": {
      "type": "http_api",
      "url": "https://rentgpu.link/api/prices",
      "method": "GET",
      "headers": {},
      "response_path": "data.items"
    }
  }'

응답의 asset_id 는 이후 도구 생성에 사용합니다. 데이터 소스가 바뀌면 수집을 다시 테스트해야 하며, 그렇지 않으면 도구가 이전 스냅샷을 계속 가리킵니다.

도구 분할

데이터는 그대로 팔 수 없습니다. ‘한 번의 호출로 답할 수 있는 하나의 질문’으로 쪼개야 합니다.

판단 기준:어떤 질문의 답을 1초 안에 반환할 수 있고 구매자가 받자마자 쓸 수 있다면, 그것은 유료 단위가 될 자격이 있습니다.

권장 분할 구조

  • 무료 ping 1개: 헬스 체크. Agent가 엔드포인트가 살아 있는지 판단하는 용도입니다.
  • 무료 목록 도구 1~2개: 전체 항목을 나열해 진열장으로 활용합니다 (list_*)。
  • 유료 도구 3~6개: 단일 조회, 시계열, 랭킹, 등급, 시나리오 추천.
POST /v1/assets/{asset_id}/tools
{
  "tools": [
    {
      "name": "list_gpu_models",
      "price": "0",
      "description": "列出全部在监测的 GPU 卡型,含显存与在售平台数量。免费。",
      "params": {}
    },
    {
      "name": "gpu_price",
      "price": "0.05",
      "description": "指定卡型的当前最低价、中位价与 30 天最低价,附平台名与库存状态。",
      "params": { "gpu": "string" }
    },
    {
      "name": "recommend_for_task",
      "price": "0.05",
      "description": "按任务(如 fine-tune 7B)给出最省钱的租用方案与估算总成本。",
      "params": { "task": "string", "hours": "int" }
    }
  ]
}
도구 설명은 Agent가 직접 읽고 "호출할지, 결제할지"를 판단하는 데 씁니다.설명이 불명확한 도구는 팔리지 않는다——플랫폼 심사에서는 설명이 "데이터 조회" 같은 모호한 표현인 도구를 반려합니다.

가격 및 무료 티어

건별 과금, 정산 비용보다 낮게 잡지 마세요.

비용 구조
  • facilitator 건당 정산 수수료
    ≈ $0.001
  • 온체인 추가 비용
    ≈ $0(대납)
  • 플랫폼 수수료(약정도에 따라 50% / 40% / 30% 계층)
    50%부터
권장 구간
$0.01 – $0.50

기본값은 $0.05입니다. $0.01 미만의 단가는 이 구조에서 의미가 없습니다. 초기에 $0.001로 책정했다가 팔 때마다 손해를 봤습니다.

무료 티어의 역할

Agent는 결제를 결정하기 전에 당신에게 물건이 있고 그것이 자신이 원하는 것인지 먼저 알아야 합니다. "전체 항목 나열"과 ping을 무료로 두세요——무료 티어는 자선이 아니라 쇼윈도입니다, 그것이 유료 전환의 기회를 좌우합니다.

MCP 엔드포인트

플랫폼은 FastMCP로 도구를 노출하고 x402 SDK 결제 래퍼로 유료 도구에 402 챌린지를 부착합니다. 자체 구축 시에는 다음 원칙을 그대로 따르세요.

server.py
from fastmcp import FastMCP
from x402.mcp import require_payment

mcp = FastMCP("gpu-market")

# 免费层:橱窗
@mcp.tool()
def list_gpu_models() -> dict:
    """列出全部在监测的 GPU 卡型。免费。"""
    return load_models()

# 付费层:$0.05 / 次
@mcp.tool()
@require_payment(price="$0.05", network="eip155:8453")
def gpu_price(gpu: str) -> dict:
    """指定卡型的当前最低价、中位价与 30 天最低价。"""
    r = query_price(gpu)
    if not r:
        # 关键:查询失败返回 isError,x402 中间件就不会结算
        return {"isError": True, "content": "no data"}
    return r
전달 실패에는 요금을 부과하지 않습니다. 그것이 신뢰의 기반입니다.조회에 실패하면 isError를 반환해야 하며, 그러면 x402 미들웨어가 정산하지 않습니다. 이것이 Agent가 계속 호출하는 전제입니다.

디스커버리 레이어 등록

다른 사람(그리고 Agent)이 당신을 찾을 수 있게 하세요. 콘솔에서 다음 세 파일을 한 번에 생성하고 검증할 수 있습니다.

/.well-known/mcp.json
{
  "name": "link.rentgpu/gpu-market",
  "transport": "streamable-http",
  "url": "https://api.feegate.org/mcp/gpu-market",
  "tools": [
    {"name": "list_gpu_models", "payment": "free"},
    {"name": "gpu_price",     "payment": "x402"}
  ]
}
/.well-known/x402.json
{
  "network": "eip155:8453",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo": "0x230cd9cd33589bcf33cd32e5aa4f9e0c3994a63b",
  "facilitator": "payai",
  "prices": {
    "gpu_price": "50000",      // USDC 6 位小数 → $0.05
    "gpu_history": "50000",
    "list_gpu_models": "0"
  }
}
/llms.txt
# GPU 算力雷达(rentgpu.link)

> 26 家平台、23 张 GPU 卡型的租赁报价,每 45 分钟全量重抓。

## 免费端点
- GET /api/prices        全量报价 feed,CC BY 4.0,免注册免 key
- GET /api/resolve?gpu=H100&budget=10   按卡型+预算直接给答案

## 付费工具(MCP, x402, $0.05/次)
- gpu_price / gpu_history / market_movers
- platform_reliability / recommend_for_task

## How to cite
数据来源:GPU 算力雷达 https://rentgpu.link ,授权 CC BY 4.0。
MCP Registry 게시 도구는 GitHub releases의 바이너리——npm의 동명 패키지는 가짜입니다를 사용해야 합니다. 이 단계는 콘솔에서 플랫폼이 대신 처리하지만, 직접 구축할 때는 반드시 유의하세요.

정산 및 수익 분배

수금 모델: 구매자 결제금은 플랫폼 집금 주소로 들어가고, 수수료를 제한 뒤 자연월 단위로 집계되어 다음 달 10일에 정산 주소로 지급됩니다.

402

서버가 결제 챌린지를 반환

scheme, network, 자산 컨트랙트, 금액, 수취 주소, 타임아웃을 포함합니다.

서명

클라이언트가 EIP-3009 인증에 서명

transferWithAuthorization. 구매자 지갑에는 USDC만 있으면 되고, 가스비는 facilitator가 대납합니다.전체 과정에 ETH는 필요하지 않습니다.

검증

결제 증빙을 포함해 요청 재전송 → 서버 verify

facilitator가 서명과 금액을 검증하며, 통과한 뒤에야 도구 로직이 실행됩니다.

정산

데이터 전달 → settle 온체인 처리

데이터가 성공적으로 반환된 후에만 정산됩니다. 실패로 isError를 반환하면 요금이 부과되지 않습니다.

대조는 온체인 Transfer 이벤트만 신뢰

실제 자금으로 검증할 때는,온체인 Transfer 이벤트만 신뢰합니다——잔액 차이로 보면 RPC 동기화 지연에 속습니다. 콘솔의 대사 패널은 기본적으로 Transfer 이벤트 기준으로 집계하며, 정산서는 CSV로 내려받을 수 있습니다.

수금 모델(기본)

USDC는 먼저 플랫폼 집금 주소로 들어가고 50% 수수료가 적용되며, 자연월 단위로 집계되어 다음 달 10일에 정산됩니다. 마켓 추천 슬롯과 공동 프로모션에 참여할 수 있습니다.

자가 보관 모델(Enterprise)

USDC가 지갑으로 직접 들어가며 온체인에서 확인할 수 있고, 플랫폼은 서비스 수수료만 받습니다. facilitator 선정과 운영은 직접 책임져야 합니다.

클라이언트 연동

호출자는 가입이나 API Key가 필요 없습니다. 지갑에 USDC만 있으면 건별로 호출할 수 있습니다.

client.py
# pip install "mcp<2" "x402==2.25.0" web3
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from x402.mcp import create_payment_hook
from eth_account import Account

account  = Account.from_key("你的私钥")    # 只需有 Base 主网 USDC
MCP_URL  = "https://api.feegate.org/mcp/gpu-market"

async with streamablehttp_client(MCP_URL) as (r, w, _):
    async with ClientSession(r, w, hooks=[create_payment_hook(account)]) as s:
        await s.initialize()
        print(await s.call_tool("list_gpu_models", {}))          # 免费
        print(await s.call_tool("gpu_price", {"gpu": "H100"}))  # $0.05
꼭 주의해야 할 두 가지:① 클라이언트를 직접 작성할 때는 params["_meta"] 를 서버로 그대로 전달해야 하며, 그러지 않으면 결제 미들웨어가 컨텍스트를 얻지 못합니다; ② 로컬에 프록시가 있으면 클라이언트에서 NO_PROXY=127.0.0.1,localhost, 그렇지 않으면 요청이 프록시에 막힙니다.

플랫폼 API

콘솔의 모든 동작에는 대응하는 API가 있어 자체 시스템을 연결하기 쉽습니다.

메서드경로설명
POST/v1/assets데이터 자산 및 데이터 소스 생성
POST/v1/assets/{id}/tools도구 및 가격표 일괄 생성/수정
GET/v1/assets/{id}/verify402 자체 점검을 한 번 실행하고 챌린지 4요소 반환
GET/v1/assets/{id}/calls호출 상세(200 / 402 / settled)
GET/v1/settlements정산 내역 목록과 상태
POST/v1/assets/{id}/publish등록 심사 제출
GET/v1/market/items공개 마켓 카탈로그(인증 불필요)
terminal
curl https://api.feegate.org/v1/assets/ast_92f1/verify \
  -H "Authorization: Bearer $RAILS_KEY"

# → {"x402Version":2,"accepts":[{"scheme":"exact",
#     "network":"eip155:8453","amount":"50000",
#     "payTo":"0x230c…a63b","maxTimeoutSeconds":300}],
#    "error":"Payment Required"}

문제 해결 가이드

아래 항목은 모두 저희가 실제 운영에서 겪은 것으로, 공식 문서에는 나오지 않는 내용입니다.

x402.org 공식 facilitator는 테스트넷만 지원, 메인넷으로 전환하면 결제가 항상 실패합니다;Mogami는 v1만 지원, 2.25 SDK와 호환되지 않습니다. 프로덕션에서는 PayAI(가입 불필요, x402 v2 메인넷 지원)를 쓰세요. 이 선택을 틀리면 전체 경로가 동작하지 않습니다.
설치할 때는 pip install "mcp<2" "x402==2.25.0"를 적습니다. mcp 2.x와 x402 2.25의 hooks 인터페이스는 호환되지 않아, 2.x를 설치하면 hook이 발동하지 않고 결제 증빙이 실리지 않는 문제가 생깁니다.
로컬에 프록시가 있으면 클라이언트에서 NO_PROXY=127.0.0.1,localhost를 설정해야 하며, 그렇지 않으면 로컬 디버깅 요청이 프록시에 삼켜집니다. 마찬가지로 서버 nginx에서는 proxy_buffering를 꺼야 하며, 그러지 않으면 스트리밍 응답이 타임아웃까지 버퍼링됩니다.
일부 대상 사이트(예: autodl)는 45초 정도에서 장시간 연결을 끊기 때문에 수집 간격과 타임아웃에 여유를 두세요. 저희는 결국 전체 수집을 45분마다 한 번으로 정했습니다.
운영 환경에서는 FastMCP의 DNS rebinding 허용 목록에 실제 도메인을 추가해야 합니다. 그렇지 않으면 요청이 거부됩니다(로컬에서는 정상인데 배포 후 403이 발생하는 증상).
잔액 차이로 보면 RPC 동기화 지연에 속습니다.온체인 Transfer 이벤트만 신뢰합니다. basescan.org에서 수취 주소 + USDC로 필터링해 대조합니다.
게시 도구는 GitHub releases의 바이너리를 사용합니다. npm의 동명 패키지는 가짜입니다. 또한 Registry에 등록된 뒤에는 도구 이름을 함부로 바꿀 수 없습니다. 도구 이름을 바꾸는 것은 상품을 바꾸는 것과 같습니다.