AgentPay

Most agent-payment tools are a wallet — they move money. AgentPay is the layer that decides whether to spend it at all.

AgentPay is the economic intelligence layer for MCP servers and AI agents.

Agents spend money. Most don't know how much, or why, until the session ends and the bill arrives.

AgentPay gives agents economic intelligence — the ability to reason about cost while they work, not after.

It starts with a budget. Every session opens with a hard cap enforced at the payment layer — not in code a model can ignore, but at the point where money moves. The agent knows from the first call exactly what it has to spend.

Before calling a tool, it knows what that call costs. Mid-task, it can check what's left and route to a cheaper alternative if the math doesn't work. When the session ends, a receipt captures every call, every cost, every decision — not a debug log, but proof of economic accountability.

The developer sees all of it: spending patterns per agent, anomaly flags when something loops or spikes, policy controls that enforce exactly which tools an agent can use and how much it can spend on each.

The result is an agent that doesn't just have a budget. It knows how to use one.

Start free:20 tools (17 free), no USDC needed, no wallet setup required.
Live gateway:https://agentpay.tools

pip install agentpay-x402 # core (Stellar) pip install "agentpay-x402[base]" # + pay tools that settle on Base

17 free tools. No USDC, no wallet, no API keys, no human.quickstart()registers an agent, mints a wallet, and returns a ready, budget-capped session.

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

Set a hard budget, or bring your own funded wallet to pay for tools:

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

Every call is session-tracked, and the cap is enforcedbeforeany payment is signed.

Every call is session-tracked — you get a receipt showing every tool called, every cost, and every timestamp.

This is the economic intelligence layer in practice. The Session gives your agent — and you — real visibility into what happened, what it cost, and why.

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") as session: # Base is the default; pass "stellar" to override ...

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())

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

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

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

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

Three tools cost money today.session_createopens a budget-capped session with a hardmax_spendlimit — for autonomous agents that need spend enforcement across multiple calls.pre_trade_checkis the firstoutcome bundle: one call returns an ok/caution/avoid trade verdict from live orderbook slippage at your size, side-aware funding carry, open-interest crowding, and an optional contract security scan — with the per-factor breakdown and raw components embedded.verified_routeis thebuyer-side trust oracle: "I need X, budget $Y — which x402 tool is real?" It sweeps the whole marketplace, collapses sybil/factory clusters, keeps only providers relevant toyour need*, ranks them by real unique-payer usage × theProber'spaid delivery scores, and returns one vetted recommendation with a ready-to-pay challenge. All 17 data tools remain free.

Price any plan before spending a cent (free, no wallet):POST /v1/plan/estimate, orsession.estimate_plan([...])from the SDK.

When metered inference ships, it works through the same Session interface — your agent checks cost, decides if it's worth it, and pays in USDC on Base or Stellar (via the SDK).

# 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

To fund a wallet forsession_create: send USDC to a Stellar wallet (S...key, issuerGA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN) or a Base wallet (0x..., contract0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).

AgentPay'sflagship analyst agent(agents/analyst/) runs daily on these exact rails as a real customer: it prices its plan withestimate_plan, gathers free intel, buyspre_trade_checkverdicts on the majors under a hard $0.25 cap, and publishes a market note with an on-chain-verifiable receipt. The first best customer is the house.

AgentPay is an x402 payment gateway and economic intelligence layer — agents call tools within a hard budget cap, pay USDC on-chain when tools cost money, and accumulate a full session receipt as they work. Free tools skip the payment step entirely; the session tracking and cost awareness are always on.

Basesettles via the standard x402exactscheme (gasless EIP-3009 through the CDP facilitator) —any standard x402 client can pay AgentPay on Base, no AgentPay SDK required.

Stellarsettles as aclassic payment + text memoverified directly on Horizon. It is supported by the AgentPay SDK (pip install agentpay-x402) and by manual payment per the 402 instructions — but it isnotthe standard@x402/stellarscheme (which uses Soroban null-account templates, signed auth entries, and facilitator settlement). A standard@x402/stellarclient cannot pay AgentPay's Stellar rail today; migrating to the standard Soroban scheme is on the v2 roadmap. Standard clients should pay on Base — Circle CCTP bridges USDC 1:1 between the two.

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

AgentPay settles x402 micropayments insBTC on Stacks— budget-capped, signed sign-don't-broadcast, broadcast by the gateway. Milestone 1 of the Stacks Endowment grant is demonstrated live on testnet:

- Developer guide:docs/stacks-m1.md— setup, known limitations, dependencies.
- Runnable demo:examples/stacks_m1_demo.py— capped session → sBTC payment → receipt → over-cap rejection.
- Demo video:YouTube (~40s)
- On-chain proof:0xa5351bad…—sbtc-token::transfer, payer → gateway, statussuccess(PoX-5 testnet, block 82215).

Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.