AgentPay — trust routing + spend caps for x402 agents

AgentPay

エージェント向け決済ツールの多くはウォレットです。つまり、お金を動かします。AgentPayは、そもそも支出するかどうかを判断するレイヤーです。

AgentPayは、MCP サーバーとAI エージェントのための経済インテリジェンスレイヤーです。

エージェントはお金を使います。しかし、ほとんどの場合、セッションが終わって請求書が届くまで、いくら使ったのか、なぜ使ったのかがわかりません。

AgentPayはエージェントに経済インテリジェンスを提供します。作業後ではなく、作業中にコストについて推論する能力です。

まず、予算を設定します。セッションごとに上限額を設け、決済レイヤーで適用します。モデルが無視できるコード内の制限ではなく、お金が動く場所で適用されるため、エージェントは最初の呼び出しから、使える金額を正確に把握できます。

ツールを呼び出す前に、その呼び出しにかかるコストがわかります。タスクの途中で残額を確認し、計算が合わなければ、より安価な代替手段に切り替えられます。セッションが終わると、すべての呼び出し、コスト、判断を記録したレシートが作成されます。これはデバッグログではなく、経済的な説明責任を証明するものです。

開発者はすべてを確認できます。エージェントごとの支出パターン、ループや急増を検知する異常フラグ、エージェントが使用できるツールと各ツールに使える金額を厳密に適用するポリシー制御です。

その結果、単に予算を持つだけでなく、その使い方を理解したエージェントが実現します。

無料で始められます： 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() はエージェントを登録し、ウォレットを作成して、予算上限付きのすぐに使えるセッションを返します。

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、ガス価格を 1 回の呼び出しで取得
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[]（完全な送信元／送信先＋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	title、url、sentiment、score を含む headlines[]
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、token_address?	1 回の呼び出しで取引を判定（ok/caution/avoid）：指定したサイズでのスリッページ、売買方向を考慮した資金調達コスト、OI の偏り、任意のセキュリティ確認 — $0.01
verified_route	need、budget_usd?、chain?	購入者側の信頼オラクル：x402 マーケットプレイスをくまなく調査し、シビル／ファクトリークラスターを統合し、利用状況 × 提供スコアで実際のプロバイダーをランク付け → 審査済みの推奨 1 件と支払い準備完了の challenge — $0.01

---

セッションインテリジェンス

これは実際の経済インテリジェンスレイヤーです。Session によって、エージェントとあなたは、何が起きたのか、いくらかかったのか、そしてその理由を実際に把握できます。

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"}
    #   ]
    # }

ポリシーパラメーター

エージェントに許可する操作を正確に制御します。

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 が発生します。受取人の許可リスト、1 回あたりの最大額、承認ゲートは、すべての決済レールで 402 自体、つまり実際に署名される受取人と金額に照らして確認され、署名は行われずに PolicyRejected／ApprovalRequired（どちらも BudgetExceeded のサブクラス）が発生します。すべての拒否は spending_summary()["anomalies"] に記録され、同一の有料呼び出しの繰り返し、上限の半分を占める単一の呼び出し、未確認の取引のフラグも併せて記録されます。budget_policy() は、明示的な値、環境変数、ルール（残高に対する割合）、またはプロンプトから上限自体を決定し、ウォレット残高を上限として設定します。sBTC 支払者の場合、wallet.get_sbtc_balance_usd(rate) からその上限を取得できます。

---

例：市場インテリジェンスエージェント

無料ツール 5 個、セッション 1 件、レシートの完全な記録。

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 Skills（あらゆるエージェントにワンコマンドでインストール）

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 スキル（エージェントが予算内で最適な有料 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 上のガスレス 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 自体の内部で強制されます。残高の少ない専用キーを使用してください。

購入者側のルーティング — 予算内で最適なツールを見つけて支払う

エージェントが有料ツールを必要とすると、AgentPay は x402 マーケットプレイス全体から選択肢を見つけ、偽の／空のスタブを除外し、価格ではなく実際の利用状況に基づいて順位付けし、予算内で実際に動作する最安のツールを推奨します。エージェントはプロバイダーに直接支払い（ピアツーピアで、資金の保管は行いません）、検証可能なレシートを保持します。

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

---

有料ツール：session_create、pre_trade_check、verified_route（各 $0.01）

現在、有料のツールは 3 つです。session_create は、厳格な max_spend 上限を設けた予算上限付きセッションを開始します。これは、複数の呼び出しにわたって支出を制限する必要がある自律型エージェント向けです。pre_trade_check は最初の結果バンドルです。1 回の呼び出しで、指定した規模でのライブ注文板スリッページ、売買方向を考慮したファンディングコスト、未決済建玉の集中度、および任意のコントラクトセキュリティスキャンから、ok／caution／avoid の取引判定を返します。要素ごとの内訳と生の構成要素も含まれます。verified_route は購入者側の信頼性オラクルです。「X が必要で、予算は $Y — 本物の x402 ツールはどれですか？」という問いに答えます。マーケットプレイス全体を調査し、Sybil／ファクトリーのクラスターをまとめ、ニーズに関連するプロバイダーだけを残し、実際のユニークな支払者による利用状況とProberの有料提供スコアを掛け合わせて順位付けし、すぐに支払えるチャレンジ付きの審査済み推奨を 1 件返します。17 個のデータツールはすべて引き続き無料です。

1 セントも使う前に、ウォレットなしでプランの価格を見積もれます。POST /v1/plan/estimate、または SDK から session.estimate_plan([...]) を使用してください。

従量課金制の推論が提供開始された場合も、同じ Session インターフェースを通じて利用できます。エージェントがコストを確認し、価値があるかを判断したうえで、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 の主力分析エージェント（agents/analyst/）は、実際の顧客として毎日、まさにこの仕組みを利用しています。estimate_plan でプランの価格を見積もり、無料のインテリジェンスを収集し、厳格な $0.25 の上限内で主要銘柄の pre_trade_check 判定を購入して、オンチェーンで検証可能なレシート付きの市場ノートを公開します。最初の優良顧客は、私たち自身です。

---

アーキテクチャ

AgentPay は x402 決済ゲートウェイであり、経済インテリジェンスレイヤーです。エージェントは厳格な予算上限内でツールを呼び出し、有料ツールの利用時にはオンチェーンで USDC を支払い、作業中にセッション全体のレシートを蓄積します。無料のツールでは決済手順を完全に省略します。セッションの追跡とコストの把握は常に有効です。

チェーンのサポートと x402 の相互運用性

Base では、標準の x402 exact スキーム（CDP ファシリテーター経由のガスレス EIP-3009）で決済します。つまり、標準の x402 クライアントであれば、AgentPay SDK がなくても Base 上で AgentPay に支払えます。

Stellar では、Horizon で直接検証される 従来型の決済＋テキストメモ として決済します。AgentPay SDK（pip install agentpay-x402）に対応しており、402 の指示に従った手動決済も可能ですが、標準の @x402/stellar スキーム（Soroban の null-account テンプレート、署名済み auth エントリー、ファシリテーター決済を使用）には対応していません。標準の @x402/stellar クライアントは、現時点では AgentPay の Stellar 決済レールで支払えません。標準の Soroban スキームへの移行は v2 のロードマップに含まれています。標準クライアントは Base で支払ってください。Circle CCTP により、両チェーン間で USDC を 1:1 でブリッジできます。

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 — インストール → 上限付きのメインネット決済を 1 回実行 → 3 通りの方法でレシートを検証 → 署名前に拒否するルールを実際の出力とともに確認します。
• メインネットのリファレンス： docs/stacks-mainnet.md — 設定、ワンライナー、結果が不確定な決済の引き換え、台帳の検証、パイロットエージェントについて説明します。
• 実行可能なデモ： examples/stacks_m1_demo.py — 上限付きセッション → sBTC 決済 → レシート → 上限超過の拒否。STACKS_NETWORK=mainnet を指定するとメインネットで実行されます。この名前は、作成時のマイルストーンに由来します。
• 支出ルールのデモ： examples/stacks_policy_demo.py — 受取人の許可リスト、呼び出しごとの上限、承認ゲートにより、何も署名する前に sBTC 決済を拒否し、その後、承認された決済を 1 回実行します。拒否内容はレシートに記録されます。
• デモ動画： 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	✅ インデックス登録済み、15 分ごとにヘルスチェック
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 のデフォルトでは表示されません（AGE-125）
Claude Code plugin	✅ /plugin marketplace add romudille-bit/agentpay
MCP Registry	✅ io.github.romudille-bit/agentpay v2.4.3（公式）
402audit	✅ 監査済み — スコア 100、判定「proprietary」
signal402	✅ Bazaar から自動インデックス登録済み（6 時間ごとに更新）
x402.fuchss.app	✅ 掲載済み — AGE-123 後、評価が回復中
xpay.tools	削除 — Bazaar と重複するため（SPA ミラー）

エージェントが読み取り可能なエンドポイント：

エンドポイント	用途
/.well-known/agentpay.json	AgentPay マニフェスト
/.well-known/agent.json	A2A エージェントカード
/llms.txt	LLM が読み取り可能なサービスの説明
/.well-known/l402-services	402index.io のディスカバリー形式