AgentPay — trust routing + spend caps for x402 agents

AgentPay

大多数 Agent 付款工具只是一个钱包——它们负责转钱。AgentPay 则是决定是否要花钱的那一层。

AgentPay 是 MCP 服务和 AI Agent 的经济智能层。

Agent 会花钱。大多数 Agent 不知道花了多少，也不知道为什么，直到会话结束、账单送达。

AgentPay 为 Agent 提供经济智能——让它们能在工作过程中，而不是事后，推理成本。

一切始于预算。每个会话都会设定一个硬性上限，并在支付层强制执行——不是写在模型可以忽略的代码里，而是在资金实际流动的环节。Agent 从第一次调用起就清楚自己可以花多少钱。

调用工具之前，它就知道该调用的成本。任务进行期间，它可以检查剩余预算；如果计算结果不理想，就切换到更便宜的替代工具。会话结束时，收据会记录每次调用、每笔成本和每个决策——这不是调试日志，而是经济责任的证明。

开发者可以看到这一切：每个 Agent 的支出模式、发现循环调用或支出激增时的异常标记，以及用于精确限制 Agent 可使用哪些工具、每种工具可花多少钱的策略控制。

最终得到的 Agent 不只是拥有预算，还知道如何使用预算。

免费开始： 20 个工具（17 个免费），无需 USDC，无需设置钱包。
在线网关： https://agentpay.tools
结算方式： Base 和 Stellar 上的 USDC，以及 Stacks 主网上的 sBTC（操作演示）

---

安装

pip install agentpay-x402            # core (Stellar + Stacks/sBTC)
pip install "agentpay-x402[base]"    # + pay tools that settle on Base
pip install "agentpay-x402[stacks]"  # same as core, spelled out — pay in sBTC on Stacks

---

快速入门——3 行代码，零配置

17 个免费工具。无需 USDC、钱包、API 密钥或人工参与。quickstart() 会注册 一个 Agent，铸造一个钱包，并返回一个已准备就绪且设有预算上限的会话。

from agentpay import quickstart

s = quickstart()                                   # registers + mints a wallet
print(s.call("token_price", {"symbol": "ETH"})["result"]["price_usd"])
print(s.spending_summary())                        # receipt: every call, cost, tx

设置硬性预算，或使用你自己的已充值钱包支付工具费用：

s = quickstart(max_spend="0.50")                   # cap this run at $0.50
s = quickstart(secret_key="S...", base_key="0x...")  # your wallet (Stellar + Base)

每次调用都会纳入会话跟踪，并且支付签署前会先强制检查预算上限。

---

20 个工具（17 个免费 + 3 个付费）

每次调用都会进行会话跟踪——你会收到一份回执，列出调用的每个工具、每项费用和每个时间戳。

工具	参数	返回值
url_reader	url	任意网页的纯净 Markdown 内容
web_search	query	前 5 条结果及其完整内容
market_snapshot	—	一次调用获取 S&P 500、国债收益率、BTC、ETH 和 gas
token_price	symbol（BTC、ETH、SOL……）	price_usd、change_24h_pct、market_cap_usd
gas_tracker	—	慢速/标准/快速 gwei、base_fee_gwei
fear_greed_index	limit（历史天数，默认值为 1）	value 0–100、value_classification、history[]
token_market_data	token_a、token_b	volume_24h_usd、market_cap_usd、price_usd
wallet_balance	address、chain（ethereum/stellar）	代币余额
whale_activity	token、min_usd（默认值为 100k）	large_transfers[]（完整的 from/to + tx_hash）、total_volume_usd
defi_tvl	protocol（可选，例如 "uniswap"）	tvl、change_1d、change_7d、chains[]
token_security	contract_address、chain	risk_level、is_honeypot、buy_tax、sell_tax
open_interest	symbol（BTC、ETH……）	total_oi_usd、oi_change_1h/24h_pct、long_short_ratio
orderbook_depth	symbol（例如 ETHUSDT）	best_bid/ask、spread_pct、$10k/$50k/$250k 规模下的滑点
funding_rates	asset（可选）	funding_rate_pct、annualized_rate_pct、各交易所的市场情绪
crypto_news	currencies（例如 "ETH,BTC"）、filter	headlines[]，包含 title、url、sentiment、score
yield_scanner	token、chain（可选）、min_tvl	按 APY 排名前 10 的资金池，包含 protocol、tvl_usd、risk_level
dune_query	query_id、limit、fast_only	来自 Dune Analytics 的 rows[]、columns[]、row_count
session_create	agent_address、max_spend、label	session_id、预算配置、gateway_url、回执 — $0.01
pre_trade_check	symbol、size_usd、side、venue?、token_address?	一次调用即可获得交易结论（ok/caution/avoid）：按你的交易规模计算滑点、结合交易方向的资金费率成本、OI 拥挤度，以及可选的安全检查；Stacks 代币还会添加 Bitflow 交易场所（按规模计算价格影响、路由、池 TVL）— $0.01
verified_route	need、budget_usd?、chain?	买方信任预言机：扫描 x402 市场，合并女巫攻击/工厂账号集群，按使用量 × 交付评分排列真实服务提供方 → 给出一条经过审核的推荐，以及可直接付款的 challenge — $0.01

---

会话智能

这是经济智能层的实际运作方式。会话让你的 Agent——也让你——清楚了解发生了什么、花费了多少，以及原因。

from agentpay import quickstart, BudgetExceeded

# quickstart() registers + mints a wallet; the returned session is also a
# context manager, so you can `with` it for a printed receipt on exit.
# Budget caps are exact: max_spend=0.10 (float) == "0.10" (str).
with quickstart(max_spend=0.10) as session:

    # Price an entire multi-tool plan BEFORE spending anything (free, no wallet)
    plan = session.estimate_plan(["token_price", "pre_trade_check", "session_create"])
    plan["total_usdc"], plan["fits_budget"]   # per-step costs + cheaper alternatives inside

    # Reason about cost before committing (use the *_usd Decimals for comparisons)
    if session.would_exceed(session.tool_cost_usd("dune_query")):
        alt = session.suggest_cheaper("dune_query")   # {"name": ..., "price": ...}

    # Call a tool — budget enforced before any payment is signed
    r = session.call("token_price", {"symbol": "ETH"})
    r.data["price_usd"]    # inner tool output  (r["result"]["price_usd"] still works)
    r.cost                 # payment amount, e.g. "0"
    r.network              # settlement chain, e.g. "stellar-mainnet" / "base"

    session.remaining_usd()   # Decimal('0.10')

    # For an external x402 tool that offers several chains, pick one:
    # session.call("https://some-x402-tool/endpoint", {}, chain="base")

    # Full receipt — every call, cost, tx hash, and settlement chain
    print(session.spending_summary())
    # {
    #   "calls": 1, "spent": "$0", "remaining": "$0.1", "budget": "$0.1",
    #   "breakdown": [
    #     {"tool": "token_price", "cost": "Free", "tx_hash": "", "network": "stellar-mainnet"}
    #   ]
    # }

策略参数

精确控制 Agent 可以执行的操作：

from agentpay import AgentWallet, Session

wallet = AgentWallet(secret_key="S...", network="mainnet")   # or quickstart()'s minted wallet
with Session(wallet,
             gateway_url="https://agentpay.tools",
             max_spend=0.10,
             allowed_tools=["token_price", "gas_tracker", "web_search"],
             max_per_tool={"dune_query": 0.02},
             rate_limit=10,                # max 10 calls/min
             prefer_chain="base",          # Base is the default; "stellar" or "stacks" to override
             allowed_recipients=["0x…", "SP…"],   # only these payees may be paid (any rail)
             max_per_call="0.02",          # no single payment above this
             approve_above="0.01",         # payments above this need the approver's yes
             approver=lambda req: ask_human(req)) as session:
    ...

如果某个工具会导致你超出上限、不在允许列表中，或超过该工具的单独限额，BudgetExceeded 会在任何付款发出前触发。每个支付通道都会针对 402 本身检查收款方允许列表、单次调用最高金额和审批关卡——也就是实际将要签署的收款方和金额，并在未签署任何内容的情况下抛出 PolicyRejected / ApprovalRequired（两者均为 BudgetExceeded 的子类）。每次拒绝都会列在 spending_summary()["anomalies"] 中，该列表还会标记重复的相同付费调用、单次调用花费上限一半的预算，以及未确认的支付环节。budget_policy() 会根据显式指定的值、环境变量、规则（余额占比）或提示词确定预算上限，并将上限限制在钱包持有的金额范围内——对于 sBTC 付款方，wallet.get_sbtc_balance_usd(rate) 会提供该上限。

---

示例：市场情报 Agent

五个免费工具、一个会话、完整回执。

from agentpay import quickstart

with quickstart() as session:

    snapshot = session.call("market_snapshot", {})
    rates    = session.call("funding_rates",    {"asset": "ETH"})
    oi       = session.call("open_interest",    {"symbol": "ETH"})
    fg       = session.call("fear_greed_index", {})
    whales   = session.call("whale_activity",   {"token": "ETH", "min_usd": 500_000})

    m = snapshot["result"]
    print(f"S&P:       {m['sp500_price']:,.0f}  ({m['sp500_change_pct']:+.2f}%)")
    print(f"ETH:       ${m['eth_price_usd']:,.0f}")
    print(f"Gas:       {m['gas_standard_gwei']} gwei")

    avg_rate = sum(e["funding_rate_pct"] for e in rates["result"]["rates"]) / len(rates["result"]["rates"])
    print(f"Funding:   {avg_rate:+.4f}%/8h")
    print(f"OI 24h:    {oi['result']['oi_change_24h_pct']:+.2f}%")
    print(f"Sentiment: {fg['result']['value_classification']}")
    print(f"Whale vol: ${whales['result']['total_volume_usd']:,.0f}")

    print(session.spending_summary())

---

在你的 Agent 中使用

Agent Skills（一个命令，适用于任何 Agent）

npx skills add romudille-bit/agentpay

将 agentpay-route 技能（在预算范围内查找、评估并支付最佳付费 x402 工具）和 agentpay-session（严格支出上限 + 可验证收据）安装到 Claude Code、Codex、Droid、OpenCode 或任何兼容 skills-CLI 的运行时中。与下方的 MCP 配合使用，即可开箱实现无密钥路由；添加 AGENTPAY_BASE_KEY + AGENTPAY_MAX_SPEND，即可在原位执行有上限的付费调用。

Claude Code 插件（一个命令）

/plugin marketplace add romudille-bit/agentpay
/plugin install agentpay@agentpay

安装 agentpay-route 技能——让你的 Agent 在预算范围内查找、评估并支付最佳付费 x402 工具——以及 17 个免费工具。路由无需密钥。

MCP 服务（适用于任何运行时）

独立运行——纯 Node，无需 Python、代码仓库或密钥即可启动：

npx -y @romudille/agentpay-mcp

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "@romudille/agentpay-mcp"]
    }
  }
}

提供 17 个免费工具，另有 verified_route（买方侧信任判定工具——免费预览无需密钥，钱包模式下可获取完整付费内容）、route（旧版别名）和 estimate_plan（在支出前为多工具计划估价）。已列入 Glama。

钱包模式（v2.4.0）：添加 EVM 密钥后，付费工具即可原位结算——在 Base 上使用免 Gas 的 EIP-3009（无需 ETH；客户端不会广播任何内容，拒绝的调用不会转移 USDC），并受严格的会话上限约束：

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "@romudille/agentpay-mcp"],
      "env": {
        "AGENTPAY_BASE_KEY": "0x<EVM private key>",
        "AGENTPAY_MAX_SPEND": "0.10"
      }
    }
  }
}

向该密钥对应地址充值 Base 主网上的 USDC；每次付费调用都会计入 AGENTPAY_MAX_SPEND，超过上限后将被拒绝——预算约束直接在 MCP 内执行。请使用余额较少的专用密钥。

买方侧路由——在预算范围内查找并支付最佳工具

当 Agent 需要付费工具时，AgentPay 会在 x402 市场中发现各种选项，剔除虚假或空壳服务，按实际使用情况（而非价格）排序，并在预算范围内推荐真正可用的最便宜工具。Agent 直接向提供方付款（点对点，不托管资金），并保留可验证的收据。

agentpay-route "funding rates" --budget 0.01   # ranked candidates + a recommendation

---

付费工具：session_create、pre_trade_check、verified_route（每项 $0.01）

目前有三种工具需要付费。session_create 会开启一个有预算上限的会话，并设置严格的 max_spend 限额——适用于需要在多次调用中强制执行支出限制的自主 Agent。pre_trade_check 是首个结果组合包：一次调用即可根据你指定规模的实时订单簿滑点、考虑买卖方向的资金费率、未平仓合约拥挤度，以及可选的合约安全扫描，返回 ok/caution/avoid 交易判定——并附带各因素明细和原始数据。对于 Stacks 代币，它会通过 Bitflow 为兑换报价，而非使用 CEX 订单簿：根据实时路由报价计算你指定规模的价格影响，并列出经过的资金池及其 TVL（参见 docs/bitflow-venue.md）。verified_route 是买方侧信任判定工具：“我需要 X，预算为 $Y——哪个 x402 工具是真正可用的？”它会扫描整个市场，合并女巫攻击者/工厂集群，仅保留与你的需求相关的提供方，按实际独立付款方使用情况 × Prober 的付费交付评分进行排序，并返回一条经过审核的推荐及可直接用于付款的 challenge。全部 17 个数据工具仍然免费。

在支出一分钱之前为任何计划估价（免费，无需钱包）：POST /v1/plan/estimate，或通过 SDK 调用 session.estimate_plan([...])。

计量推理功能上线后，也将使用同一个 Session 接口——你的 Agent 会先检查成本、判断是否值得，再通过 SDK 使用 Base 或 Stellar 上的 USDC，或 Stacks 上的 sBTC 付款。

# Future — inference as a Session tool
remaining = session.remaining()
infer_cost = session.tool_cost("inference")   # e.g. "$0.02"

if remaining >= infer_cost:
    result = session.call("inference", {"prompt": "...", "model": "claude-haiku"})
else:
    result = session.call("url_reader", {"url": summary_url})  # cheaper path

为 session_create 的钱包充值：向 Stellar 钱包（S... 密钥，发行方 GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN）或 Base 钱包（0x...，合约 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913）发送 USDC。

自己先用起来

AgentPay 的旗舰分析师 Agent（agents/analyst/）每天都会作为真实客户，严格按照这些规则运行：用 estimate_plan 为计划定价，收集免费情报，在严格的 0.25 美元上限内购买主要资产的 pre_trade_check 评估，并发布附带可在链上验证的收据的市场简报。第一个最佳客户，就是我们自己。

---

架构

AgentPay 是一个 x402 支付网关和经济情报层：Agent 在严格的预算上限内调用工具；如果工具需要付费，则通过链上 USDC 支付；并在工作过程中累积完整的会话收据。免费工具完全跳过支付步骤；会话跟踪和成本意识始终开启。

链支持与 x402 互操作

Base 通过标准 x402 exact 方案结算（经 CDP facilitator 使用免 Gas 的 EIP-3009）——任何标准 x402 客户端都能在 Base 上向 AgentPay 付款，无需 AgentPay SDK。

Stellar 也通过标准 x402 exact 方案结算：使用 Soroban USDC，由付款方签署授权条目，再由 Built on Stellar (OpenZeppelin) facilitator 验证并提交，网络费用由其代付——任何标准 @x402/stellar 客户端都能在 Stellar 上向 AgentPay 付款（参见 docs/stellar-standard-scheme.md）。AgentPay SDK（pip install agentpay-x402）和手动付款方也可以使用经典的付款 + 文本备注方式，并直接通过 Horizon 验证。Circle CCTP 可在 Stellar 和 Base 之间按 1:1 比例桥接 USDC。

agent (Python SDK)
    │
    │  POST /tools/{name}/call
    │  ← 200 {result: ...}              ← free tools return directly
    │  ← 402 {payment_id, amount, ...}  ← paid tools (session_create, pre_trade_check, verified_route)
    │  → USDC on Base (~2s, standard x402) or Stellar (~3–5s, SDK classic+memo)
    │  → retry with X-Payment header
    │  ← 200 {result: ...}
    ▼
gateway (FastAPI on Railway)
    │
    ├── registry/registry.py   — 20-tool catalog (17 free; session_create, pre_trade_check, verified_route — $0.01 each)
    ├── gateway/routes/plan.py — POST /v1/plan/estimate (free pre-flight plan pricing)
    ├── gateway/radar.py       — Arbitrum x402 Radar discovery + settlement verify (see RADAR.md)
    ├── gateway/stellar.py     — Stellar payment verification via Horizon
    ├── gateway/base.py        — Base payment verification via JSON-RPC
    └── gateway/services/tools_runtime.py — real API dispatchers
            ├── Jina Reader       url_reader
            ├── Jina Search       web_search
            ├── Yahoo+CoinGecko   market_snapshot
            ├── CoinGecko         token_price, token_market_data
            ├── Etherscan V2      gas_tracker, whale_activity, wallet_balance
            ├── DeFiLlama         defi_tvl, yield_scanner
            ├── alternative.me    fear_greed_index
            ├── Reddit            crypto_news
            ├── Dune Analytics    dune_query
            ├── GoPlus            token_security
            └── Binance+Bybit+OKX funding_rates, open_interest, orderbook_depth

---

Stacks sBTC 结算

AgentPay 在 Stacks 主网上使用 sBTC 结算 x402 小额支付——受预算上限约束，在客户端本地签名，客户端绝不广播交易（由网关广播已签名的交易，因此恶意网关最多只能结算签名金额）。自 agentpay-x402 0.5.0 起，已在 agentpay.tools 上线：

from agentpay import quickstart

s = quickstart(stacks_key="<64-hex>", prefer_chain="stacks", max_spend="0.05")
r = s.call("pre_trade_check", {"symbol": "BTC", "size_usd": 25000, "side": "long"})
print(r.data["verdict"], r.tx)      # verdict + the sbtc-token::transfer txid

• 操作指南（从这里开始）： docs/stacks-walkthrough.md — 安装 → 一笔设有上限的主网支付 → 用三种方式验证收据 → 签名前拒绝的规则，附真实输出。
• 主网参考： docs/stacks-mainnet.md — 配置、单行命令、赎回结算状态不明的款项、账本验证、试点 Agent。
• 可运行演示： examples/stacks_m1_demo.py — 受限会话 → sBTC 支付 → 收据 → 超限拒绝。设置 STACKS_NETWORK=mainnet 可在主网上运行；文件名源自编写该文件时对应的里程碑。
• 三段式演示： examples/stacks_bff_demo.py — 免费调用、在签名前拒绝付费调用的额度上限、通过 Bitflow 场所完成一笔真实的 0.01 美元 sBTC 支付，以及收据（BFF ARMY 训练营脚本，西班牙语注释）。
• 支出规则演示： examples/stacks_policy_demo.py — 收款方允许列表、单次调用最高额度和审批关卡在签署任何内容前拒绝 sBTC 支付，随后完成一笔已批准的结算；拒绝记录在收据中。
• 演示视频： YouTube（约 40 秒）
• 主网收据： 0x30689b5e…、0xd1de1a79…、0x59ce7014… — sbtc-token::transfer 从付款方转至网关；每笔均来自上限为 $0.05 的会话，并已在链上通过 agentpay.tools/ledger 验证。
• 里程碑 1（测试网）材料，按交付内容保留： docs/stacks-m1.md 和测试网证明 0xa5351bad…（PoX-5 测试网，区块 82215）。测试网网关仍在运行，任何人都可以在不使用主网 sBTC 的情况下体验这条支付通道。

---

发现

目录	状态
PyPI	✅ agentpay-x402
x402scout	✅ 已收录，每 15min 检查一次运行状况
Glama MCP	✅ 已列出
xpaysh/awesome-x402	✅ 已列出（列表自 2025 年 11 月起未更新）
Merit-Systems/awesome-agentic-commerce	⏳ PR #712 自 2026-09-16 起开放
npm	✅ @romudille/agentpay-mcp
skills CLI	✅ npx skills add romudille-bit/agentpay
402index.io	✅ 域名已验证，已同步 17 个工具
x402-list.com	✅ 于 2026-09-07 收录——3 个付费端点，x402 合规性 14/14，评分经测量得出（从不由自身声明）
Coinbase Bazaar	✅ 通过 REST 收录——session_create、pre_trade_check、verified_route（Base）。⚠️ 不在精选集合中：在 MCP search_resources 默认结果中不可见
Claude Code 插件	✅ /plugin marketplace add romudille-bit/agentpay
MCP Registry	✅ io.github.romudille-bit/agentpay v2.4.3（官方）
402audit	✅ 已审计——评分 100，判定为“专有”
signal402	✅ 从 Bazaar 自动收录（每 6h 刷新）
x402.fuchss.app	✅ 已列出——自 402 响应正文修复后等级逐步恢复
xpay.tools	已移除——与 Bazaar 重复（SPA 镜像）

Agent 可读取的端点：

端点	用途
/.well-known/agentpay.json	AgentPay 清单
/.well-known/agent.json	A2A Agent 卡片
/llms.txt	大模型可读的服务说明
/.well-known/l402-services	402index.io 发现格式