agentpay

# AgentPay [](https://github.com/romudille-bit/agentpay/actions/workflows/test.yml) [](https://pypi.org/project/agentpay-x402/) [](https://pypi.org/project/agentpay-x402/) [](LICENSE) [](https://www.npmjs.com/package/@romudille/agentpay-mcp) [](https://agentpay.tools) *大多数代理支付工具都是钱包——它们转移资金。AgentPay 是决定是否花费资金的经济智能层。* **AgentPay 是 MCP 服务器和 AI 代理的经济智能层。** 代理花费资金。大多数代理不知道自己花费了多少或为什么，直到会话结束，账单才出来。 AgentPay 为代理提供经济智能——在工作过程中而不是之后推理成本的能力。 它从预算开始。每个会话都以支付层强制执行的硬上限开启——不是代码中模型可以忽略的，而是资金转移时的硬上限。代理从第一次调用开始就确切知道自己可以花费多少。 在调用工具之前，它知道调用该工具的成本。在任务中途，它可以检查还剩多少，并根据数学计算选择更便宜的替代方案。当会话结束时，收据记录了每次调用、每次成本和每次决策——不是调试日志，而是经济责任证明。 开发者可以看到所有信息：每个代理的消费模式、异常标志（当出现循环或激增时）、策略控制，强制执行代理可以使用的工具以及每个工具可以花费的金额。 结果是代理不仅有预算，还知道如何使用预算。 **免费开始：** 19 个工具（17 个免费），不需要 USDC，不需要钱包设置。 **实时网关：** `https://agentpay.tools` --- ## 安装 ```bash pip install agentpay-x402 # 核心（Stellar） pip install "agentpay-x402[base]" # + 支付工具，在 Base 上结算 ``` --- ## 快速开始 — 3 行代码，零设置 17 个免费工具。不需要 USDC，不需要钱包，不需要 API 密钥，也不需要人类。`quickstart()` 注册了一个代理，创建了一个钱包，并返回一个准备好的、预算上限的会话。 ```python from agentpay import quickstart s = quickstart() # 注册并创建钱包 print(s.call("token_price", {"symbol": "ETH"})["result"]["price_usd"]) print(s.spending_summary()) # 收据：每次调用、成本、交易 ``` 设置硬预算，或带上您自己的已资助钱包支付工具： ```python s = quickstart(max_spend="0.50") # 将此运行上限设为 0.50 美元 s = quickstart(secret_key="S...", base_key="0x...") # 您的钱包（Stellar + Base） ``` 每次调用都跟踪会话，强制执行上限 **在** 支付签名 **之前**。 --- ## 19 个工具（17 个免费 + 2 个付费） 每次调用都跟踪会话——您会收到一份收据，显示每个工具的调用、成本和时间戳。 | 工具 | 参数 | 返回 | |------|-----------|---------| | `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` | — | slow/standard/fast 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) | token balances | | `whale_activity` | `token`, `min_usd` (默认为 100k) | large_transfers[] with direction, 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, slippage at $10k/$50k/$250k | | `funding_rates` | `asset` (可选) | funding_rate_pct, annualized_rate_pct, sentiment per exchange | | `crypto_news` | `currencies` (例如 "ETH,BTC"), `filter` | headlines[] with title, url, sentiment, score | | `yield_scanner` | `token`, `chain` (可选), `min_tvl` | top 10 pools by APY with protocol, tvl_usd, risk_level | | `dune_query` | `query_id`, `limit`, `fast_only` | rows[], columns[], row_count from Dune Analytics | | `session_create` | `agent_address`, `max_spend`, `label` | session_id, budget config, gateway_url, receipt — **$0.01** | | `pre_trade_check` | `symbol`, `size_usd`, `side`, `token_address?` | one-call trade verdict (ok/caution/avoid): slippage at YOUR size, side-aware funding carry, OI crowding, optional security — **$0.01** | --- ## 会话智能 这是经济智能层的实践。会话为您和您的代理提供真正的可见性，了解发生了什么、花费了多少以及为什么。 ```python from agentpay import quickstart, BudgetExceeded # quickstart() 注册并创建钱包；返回的会话也是一个上下文管理器，因此您可以 `with` 它以打印退出时的收据。 # 预算上限是精确的：max_spend=0.10（float）== "0.10"（str）。 with quickstart(max_spend=0.10) as session: # 在花费任何费用之前，估算整个多工具计划的成本（免费，无需钱包） plan = session.estimate_plan(["token_price", "pre_trade_check", "session_create"]) plan["total_usdc"], plan["fits_budget"] # 每步成本 + 更便宜的替代方案 # 在承诺之前考虑成本（使用 *_usd Decimals 进行比较） if session.would_exceed(session.tool_cost_usd("dune_query")): alt = session.suggest_cheaper("dune_query") # {"name": ..., "price": ...} # 调用工具 — 在签署任何付款之前强制执行预算 r = session.call("token_price", {"symbol": "ETH"}) r.data["price_usd"] # 内部工具输出（r["result"]["price_usd"] 仍然有效） r.cost # 支付金额，例如 "0" r.network # 结算链，例如 "stellar-mainnet" / "base" session.remaining_usd() # Decimal('0.10') # 对于提供多个链的外部 x402 工具，选择一个： # session.call("https://some-x402-tool/endpoint", {}, chain="base") # 完整的收据 — 每次调用、成本、交易哈希和结算链 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"} # ] # } ``` ### 策略参数 控制代理的允许行为： ```python from agentpay import AgentWallet, Session wallet = AgentWallet(secret_key="S...", network="mainnet") # 或 quickstart() 创建的钱包 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, # 最大 10 次调用/分钟 prefer_chain="base") as session: # Base 是默认链；传递 "stellar" 以覆盖 ... ``` `BudgetExceeded` 在工具超出上限、未在允许列表中或超过每个工具的限制时触发 **在** 支付发出 **之前**。 --- ## 示例：市场智能代理 五个免费工具，一个会话，完整的收据。 ```python 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()) ``` --- ## 在您的代理中使用 ### Claude Code 插件（一键安装） ``` /plugin marketplace add romudille-bit/agentpay /plugin install agentpay@agentpay ``` 安装 **`agentpay-route`** 技能 — 您的代理在预算内查找、评估并支付最佳付费 x402 工具 + 17 个免费工具。无需密钥即可路由。 ### MCP 服务器（任意运行时） 自包含 — 纯 Node，无需 Python，无需仓库，无需钱包： ```bash npx -y @romudille/agentpay-mcp ``` ```json { "mcpServers": { "agentpay": { "command": "npx", "args": ["-y", "@romudille/agentpay-mcp"] } } } ``` 暴露 17 个免费工具 **以及** `route`（买方路由）和 `estimate_plan`（估算多工具计划的成本）。在 [Glama](https://glama.ai/mcp/servers/romudille-bit/agentpay) 上列出。 ### 买方路由 — 在预算内查找和支付最佳工具 当代理需要付费工具时，AgentPay 会发现 x402 市场上的选项，丢弃假/空占位符，按 **实际使用**（而非价格）排名，并推荐在预算内实际有效的最便宜工具。代理直接向提供者支付（点对点，无托管）并保留可验证的收据。 ```bash agentpay-route "funding rates" --budget 0.01 # 排名候选 + 推荐 ``` --- ## 付费工具：session_create + pre_trade_check（每个 $0.01） 两个工具目前需要付费。`session_create` 在多个调用中开启具有硬 `max_spend` 限制的预算上限会话。`pre_trade_check` 是第一个 **结果包**：一次调用返回 ok/caution/avoid 交易判决，从实时订单簿滑移率按您的规模计算，侧感知资金携带，开仓兴趣，以及可选的合约安全扫描 — 具有每个因素的分解和嵌入的原始组件。所有 17 个数据工具仍然免费。 使用 `POST /v1/plan/estimate` 或 `session.estimate_plan([...])` 从 SDK 估算任何计划的成本（免费，无需钱包）。 当计量推理发货时，它通过相同的会话接口工作 — 您的代理检查成本，决定是否值得，并使用 USDC 在 Stellar 或 Base 上支付。 ```python # 未来 - 会话工具中的推理 remaining = session.remaining() infer_cost = session.tool_cost("inference") # 例如 "$0.02" if remaining >= infer_cost: result = session.call("inference", {"prompt": "...", "model": "claude-haiku"}) else: result = session.call("url_reader", {"url": summary_url}) # 更便宜的路径 ``` 要资助 `session_create` 的钱包：发送 USDC 到 Stellar 钱包（`S...` 密钥，发行人 `GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN`）或 Base 钱包（`0x...`，合约 `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`）。 ### 吃自己的狗粮 AgentPay 的**旗舰分析代理**（`agents/analyst/`) 每天运行在这些确切的轨道上，作为真正的客户：它使用 `estimate_plan` 估算计划，收集免费情报，购买 `pre_trade_check` 判决，并在硬 $0.25 上限下购买主要货币，并发布具有链上可验证收据的市场笔记。第一个最佳客户是房子。 --- ## 架构 AgentPay 是一个 x402 支付网关和经济智能层 — 代理在硬预算上限内调用工具，当工具成本时支付 USDC，并累积完整的会话收据。 ``` 代理（Python SDK） │ │ POST /tools/{name}/call │ ← 200 {result: ...} ← 免费工具直接返回 │ ← 402 {payment_id, amount, ...} ← 付费工具（session_create, pre_trade_check） │ → Stellar 上的 USDC（~3–5s）或 Base（~2s） │ → 带有 X-Payment 头部的重试 │ ← 200 {result: ...} ▼ 网关（FastAPI on Railway） │ ├── registry/registry.py — 19 个工具目录（17 个免费；session_create + pre_trade_check，每个 $0.01） ├── gateway/routes/plan.py — POST /v1/plan/estimate（免费预飞行计划定价） ├── gateway/radar.py — Arbitrum x402 雷达发现 + 结算验证（参见 RADAR.md） ├── gateway/stellar.py — 通过 Horizon 的 Stellar 支付验证 ├── gateway/base.py — 通过 JSON-RPC 的 Base 支付验证 └── gateway/services/tools_runtime.py — 真实的 API 调度器 ├── 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 ``` --- ## 发现 | 目录 | 状态 | |-----------|--------| | [PyPI](https://pypi.org/project/agentpay-x402/) | ✅ agentpay-x402 | | [x402scout](https://x402scout.com) | ✅ indexed, health-checked every 15min | | [Glama MCP](https://glama.ai/mcp/servers/romudille-bit/agentpay) | ✅ listed | | [awesome-x402](https://github.com/xpaysh/awesome-x402) | ✅ listed | | [npm](https://www.npmjs.com/package/@romudille/agentpay-mcp) | ✅ @romudille/agentpay-mcp | | [402index.io](https://402index.io) | ✅ domain verified, 17 tools synced | | Coinbase Bazaar | ✅ indexed (`session_create`, Base) | | Claude Code 插件 | ✅ `/plugin marketplace add romudille-bit/agentpay` | | [xpay.tools](https://xpay.tools) | 🔜 submission in progress | **代理可读端点： | 端点 | 目的 | |----------|---------| | `/.well-known/agentpay.json` | AgentPay 声明 | | `/.well-known/agent.json` | A2A 代理卡 | | `/llms.txt` | LLM 可读服务描述 | | `/.well-known/l402-services` | 402index.io 发现格式 |