導入ドキュメント · Docs

導入から最初の USDC 受け取りまで

本ドキュメントは私たち自身が Base メインネットで実際に通した構成に基づいて書かれており、踏んだ落とし穴も含まれています。
x402 v2 · eip155:8453 · Circle USDC · PayAI facilitator

クイックスタート

5 ステップで、都度売りできるデータを出品済みの商品にします。最初の 4 ステップはコンソールで完結し、5 番目はプラットフォームの審査です。

01

アセットを作成

コンソール → データアセット → 新規アセット に進み、名称・カテゴリ・更新頻度を入力します。

02

データソースに接続

API / CSV / Postgres / クローラー から選択し、接続情報を入力して「テスト取得」をクリックし、戻り値の構造と鮮度を確認します。

03

ツールを分割

ツールファクトリで、各ツールの名前・説明・入力パラメータ・戻り値フィールド・価格を 1 つずつ定義します。最低 1 つは無料に設定してください。

04

エンドポイント + ディスカバリ層を生成

「エンドポイント生成」をクリックすると、プラットフォームが MCP エンドポイント、/.well-known マニフェスト、llms.txt を自動生成し、402 セルフチェックを 1 回実行します。

05

審査に提出

プラットフォームがツールの説明と価格設定の妥当性を審査します(通常 1 営業日以内)。通過するとマーケットと Registry のキューに入ります。

自分で確かめる最短の方法:支払わずに有料ツールを呼び出すと、402 チャレンジが返るはずです。中の network、asset、payTo、amount の 4 フィールドがすべて正しければ設定は正しい——この確認に費用はかかりません。

データソース接続

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 回の呼び出しで答えられる 1 つの質問」に分割してください。

判断基準:ある質問の答えを 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 の 1 件あたり決済手数料
    ≈ $0.001
  • オンチェーンの追加費用
    ≈ $0(代払い)
  • プラットフォームの取り分(コミット度に応じて 50% / 40% / 30% の階層)
    50% から
推奨レンジ
$0.01 – $0.50

デフォルトは $0.05 です。$0.01 未満の単価はこの仕組みでは意味がありません。初期に $0.001 で設定した結果、1 件売るたびに赤字になりました。

無料枠の役割

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 ミドルウェアは settle しません。これが Agent に何度も呼ばれる前提です。

ディスカバリ層への登録

他の人(と Agent)から見つけてもらえるようにします。コンソールでは以下の 3 ファイルをワンクリックで生成・検証できます。

/.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
必ず注意すべき 2 点:① クライアントを自作するときは params["_meta"] をそのままサーバーへ渡してください。そうしないと決済ミドルウェアがコンテキストを取得できません;② ローカルにプロキシがある場合は NO_PROXY=127.0.0.1,localhostを設定してください。そうしないとリクエストはプロキシに遮られます。

プラットフォーム API

コンソールのすべての操作に対応する API があり、自社システムを接続しやすくなっています。

メソッドパス説明
POST/v1/assetsデータアセットとデータソースを作成
POST/v1/assets/{id}/toolsツールと価格表を一括作成 / 更新
GET/v1/assets/{id}/verify402 セルフチェックを 1 回実行し、チャレンジの 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"}

トラブルシューティング

以下の 1 件 1 件はすべて私たちが本番で実際に踏んだもので、公式ドキュメントには書かれていません。

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 に収録された後はツール名を気軽に変えられません。ツール名を変えることは商品を替えることと同じです。