接入文档 · Docs

从接入到收到第一笔 USDC

全文基于我们自己在 Base 主网跑通的链路写成,包含踩过的坑。
x402 v2 · eip155:8453 · Circle USDC · PayAI facilitator

快速开始

五步,把一份能按次卖的数据变成在架商品。前四步在控制台完成,第五步由平台审核。

01

创建资产

进入控制台 → 数据资产 → 新建资产,填写名称、类目与更新频率。

02

接入数据源

选择 API / CSV / Postgres / 爬虫,填连接信息,点「测试取数」确认返回结构与新鲜度。

03

切分工具

在工具工厂里逐个定义工具的名称、描述、入参、返回字段与价格。至少一个设为免费。

04

生成端点 + 发现层

点「生成端点」,平台自动产出 MCP 端点、/.well-known 清单与 llms.txt,并跑一次 402 自检。

05

提交审核

平台审核工具描述与定价合理性(通常 1 个工作日内),通过后进入市场与 Registry 队列。

自证最简单的方法:不付款直接调用付费工具,应该拿到 402 挑战。检查里面的 network、asset、payTo、amount 四个字段全对,配置就是正确的——这一步不花一分钱。

数据源接入

四种接入方式,覆盖大多数可售数据。接入后平台会按你声明的更新频率做缓存,保证 1 秒内返回。

类型适用场景配置要点
HTTP API已有对外接口、第三方数据源URL / method / headers / 轮询间隔(最短 45 秒)
CSV / 文件名单、名录、静态表上传后声明主键列与更新频率,支持覆盖式更新
PostgreSQL业务库直连、实时性强只读账号 + IP 白名单 + 视图而非原表
定时爬虫没有接口的公开页面目标 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 个免费 ping:健康检查,供 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,gas 由 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

控制台里的一切动作都有对应接口,方便你把自己的系统接进来。

方法路径说明
POST/v1/assets创建数据资产与数据源
POST/v1/assets/{id}/tools批量创建 / 更新工具与价目
GET/v1/assets/{id}/verify跑一次 402 自检,返回挑战四要素
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 收录后工具名不可随意变更,切工具名等于换一个商品。