Integration Docs · Docs

From integration to your first USDC payment

This guide is based on the pipeline we actually ran end to end on Base mainnet, including the pitfalls we hit.
x402 v2 · eip155:8453 · Circle USDC · PayAI facilitator

Quick start

Five steps to turn a per-call sellable dataset into a listed product. The first four happen in the console; the fifth is platform review.

01

Create an asset

Go to Console → Data Assets → New Asset, and fill in the name, category, and update frequency.

02

Connect the data source

Choose API / CSV / Postgres / Crawler, fill in the connection details, and click “Test fetch” to confirm the response structure and freshness.

03

Split into tools

In the tool factory, define each tool’s name, description, input parameters, return fields, and price one by one. Make at least one of them free.

04

Generate endpoint + discovery layer

Click “Generate endpoint” and the platform automatically produces the MCP endpoint, the /.well-known manifest and llms.txt, then runs one 402 self-check.

05

Submit for review

The platform reviews tool descriptions and pricing reasonableness (usually within 1 business day). Once approved, you enter the marketplace and Registry queue.

The simplest way to prove it yourself:Calling a paid tool without paying should return a 402 challenge. Check that all four fields inside — network, asset, payTo, amount — are correct, and the configuration is right; this step costs nothing.

Data source integration

Four integration methods covering most sellable data. After connecting, the platform caches according to the update frequency you declare and guarantees a response within 1 second.

TypeBest forKey configuration
HTTP APIExisting public API, third-party data sourceURL / method / headers / polling interval (minimum 45 seconds)
CSV / FilesLists, directories, static tablesAfter upload, declare the primary key column and update frequency; overwriting updates are supported.
PostgreSQLDirect connection to your business database, high freshnessRead-only account + IP allowlist + views instead of raw tables
Scheduled crawlerPublic pages with no APITarget URL list + CSS selectors + frequency (≥45 minutes recommended)
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"
    }
  }'

In the response, asset_id is used to create tools later. If the data source changes, re-test the fetch, or the tool keeps pointing at the old snapshot.

Splitting into tools

Data can’t be sold as-is; split it into “one question that a single call can answer.”

Criteria:If you can return the answer to a question within 1 second and the buyer can use it right away, it qualifies as a paid unit.

Recommended structure

  • 1 free ping: health check, so an Agent can tell whether the endpoint is alive.
  • 1–2 free listing tools: list the full set of entries as a shop window (list_*)。
  • 3–6 paid tools: single-item lookup, historical series, rankings, ratings, scenario recommendations.
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" }
    }
  ]
}
Tool descriptions are read directly by Agents to judge "should this be called, should this be paid for".Tools with unclear descriptions don’t get bought— platform review rejects tools whose descriptions are vague (such as "query data").

Pricing and the free tier

Price per call — never below settlement cost.

Cost structure
  • facilitator per-settlement fee
    ≈ $0.001
  • Extra on-chain cost
    ≈ $0 (sponsored)
  • Platform commission (tiered by commitment: 50% / 40% / 30%)
    From 50%
Recommended range
$0.01 – $0.50

Default $0.05. A unit price below $0.01 makes no sense in this system: early on we priced at $0.001 and lost money on every single sale.

What the free tier is for

Before an Agent decides to pay, it has to know you have inventory and that the inventory is what it wants. Make "list all entries" and ping free—The free tier is a shop window, not charity, and that is what decides whether paid conversion ever gets a chance.

MCP endpoint

The platform exposes tools with FastMCP and attaches a 402 challenge to paid tools using the x402 SDK payment wrapper. If you self-host, copy these principles exactly.

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
No charge when delivery fails — that is the foundation of trust.A failed query must return isError, and the x402 middleware will not settle. That is the precondition for an Agent to call you again and again.

Discovery layer registration

Make yourself findable by others (and by Agents). The console can generate and validate these three files with one click.

/.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。
The MCP Registry publishing tool must use The binary on GitHub releases——The package with the same name on npm is fake. The platform handles this step for you in the console; be careful when self-hosting.

Settlement and revenue sharing

Collection model: buyer payments go to the platform collection address; after commission they are pooled by calendar month and settled to your payout address on the 10th of the following month.

402

Server returns a payment challenge

Contains scheme, network, asset contract, amount, payout address, and timeout.

Sign

Client signs an EIP-3009 authorization

transferWithAuthorization. The buyer’s wallet only needs USDC; gas is sponsored by the facilitator.No ETH is needed at any point in the process.

Verify

Replay the request with the payment credential → server verifies

facilitator verifies the signature and amount; only after it passes is the tool logic executed.

Settlement

Deliver data → settle on-chain

Settlement happens only after the data is returned successfully. No charge when a failure returns isError.

Only trust on-chain Transfer events for reconciliation

When verifying real money flows:Trust only on-chain Transfer events—balance differences get fooled by RPC sync lag. The console's reconciliation panel aggregates by Transfer events by default, and settlement statements export to CSV.

Collection model (default)

USDC first goes to the platform collection address with a 50% commission, pooled by calendar month and settled on the 10th of the following month. Eligible for marketplace featured slots and joint promotion.

Self-custody model (Enterprise)

USDC goes straight to your wallet, verifiable on-chain; the platform only charges a service fee. You are responsible for choosing and operating the facilitator.

Client integration

Callers don’t need to register or hold an API Key — if the wallet has USDC, they can call per request.

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
Two things you must watch out for:① When writing your own client, pass params["_meta"] through to the server unchanged, or the payment middleware loses the context; ② with a local proxy, set NO_PROXY=127.0.0.1,localhost, or the request gets blocked by the proxy.

Platform API

Every action in the console has a matching API, so you can plug your own systems in.

MethodPathNotes
POST/v1/assetsCreate data assets and data sources
POST/v1/assets/{id}/toolsBulk create / update tools and price list
GET/v1/assets/{id}/verifyRun one 402 self-check and return the four challenge elements
GET/v1/assets/{id}/callsCall details (200 / 402 / settled)
GET/v1/settlementsSettlement statement list and status
POST/v1/assets/{id}/publishSubmit for listing review
GET/v1/market/itemsPublic marketplace catalog (no authentication required)
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"}

Troubleshooting

Every item below is something we actually hit in production — you won’t find them in the official docs.

The official x402.org facilitator only supports testnet, so payments always fail once you switch to mainnet;Mogami only supports v1, and it is incompatible with the 2.25 SDK. In production, use PayAI(no signup, supports x402 v2 mainnet). Getting this choice wrong breaks the entire chain.
At install time, write pip install "mcp<2" "x402==2.25.0". The hooks interface of mcp 2.x is incompatible with x402 2.25: installing 2.x leaves hooks untriggered and payment credentials unattached.
With a local proxy, set NO_PROXY=127.0.0.1,localhost, or local debug requests get swallowed by the proxy. Likewise, disable proxy_buffering, or streaming responses get buffered until they time out.
Some target sites (such as autodl) drop long-lived connections at around 45 seconds, so leave headroom in your crawl interval and timeout settings. We finally settled on a full crawl every 45 minutes.
In production, add your real domain to FastMCP’s DNS rebinding allowlist, otherwise requests are rejected (symptom: fine locally, 403 once deployed).
Balance differences get fooled by RPC sync lag.Trust only on-chain Transfer events, and verify on basescan.org filtered by receiving address + USDC.
The publishing tool must use The binary on GitHub releases; the package with the same name on npm is fake. Also, once Registry has listed the tool, its name cannot be changed at will—changing the name is changing the product.