Agentpay MCP Server

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
Settles in: USDC on Base and Stellar, sBTC on Stacks mainnet (walkthrough)

---

Install

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

---

Quickstart — 3 lines, zero setup

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 enforced before any payment is signed.

---

20 Tools (17 Free + 3 Paid)

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

---

Session Intelligence

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

Policy parameters

Control exactly what your agent is allowed to do:

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 fires before any payment goes out if a tool would push you over the cap, isn't on the allowlist, or exceeds its per-tool limit. The recipient allowlist, per-call maximum and approval gate are checked against the 402 itself — the payee and amount that would actually be signed — on every rail, and raise PolicyRejected / ApprovalRequired (both BudgetExceeded subclasses) with nothing signed. Every refusal is listed under spending_summary()["anomalies"], alongside flags for repeated identical paid calls, a single call taking half the cap, and unconfirmed legs. budget_policy() picks the cap itself from an explicit value, an env var, a rule (share of balance) or a prompt, clamped to what the wallet holds — wallet.get_sbtc_balance_usd(rate) gives that ceiling for an sBTC payer.

---

Example: Market intelligence agent

Five free tools, one session, full receipt.

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

---

Use it in your agent

Agent Skills (one command, any agent)

npx skills add romudille-bit/agentpay

Installs the agentpay-route skill (find, judge, and pay for the best paid x402 tool within a budget) and agentpay-session (hard spend cap + verifiable receipts) into Claude Code, Codex, Droid, OpenCode, or any skills-CLI-compatible runtime. Pair with the MCP below for keyless routing out of the box; add AGENTPAY_BASE_KEY + AGENTPAY_MAX_SPEND for capped, in-place paid calls.

Claude Code plugin (one command)

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

Installs the agentpay-route skill — your agent finds, judges, and pays for the best paid x402 tool within a budget — plus the 17 free tools. No keys needed to route.

MCP server (any runtime)

Self-contained — pure Node, no Python, no repo, no keys to start:

npx -y @romudille/agentpay-mcp

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

Exposes the 17 free tools plus verified_route (buyer-side trust oracle — free preview keyless, full paid payload in wallet mode), route (legacy alias) and estimate_plan (price a multi-tool plan before spending). Listed on Glama.

Wallet mode (v2.4.0): add an EVM key and paid tools settle in-place — gasless EIP-3009 on Base (no ETH needed; nothing broadcast client-side, a rejected call moves no USDC) under a hard session cap:

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

Fund the key's address with USDC on Base mainnet; every paid call counts against AGENTPAY_MAX_SPEND and is refused past the cap — the budget story, enforced inside the MCP itself. Use a dedicated small-balance key.

Buyer-side routing — find & pay for the best tool, within a budget

When an agent needs a paid tool, AgentPay discovers the options across the x402 marketplace, drops the fake/empty stubs, ranks by real usage (not price), and recommends the cheapest one that actually works — within a budget. The agent pays the provider directly (peer-to-peer, no custody) and keeps a verifiable receipt.

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

---

Paid tools: session_create, pre_trade_check, verified_route ($0.01 each)

Three tools cost money today. session_create opens a budget-capped session with a hard max_spend limit — for autonomous agents that need spend enforcement across multiple calls. pre_trade_check is the first outcome 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_route is the buyer-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 to your need, ranks them by real unique-payer usage × the Prober's paid 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, or session.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, or sBTC on Stacks (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 for session_create: send USDC to a Stellar wallet (S... key, issuer GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN) or a Base wallet (0x..., contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).

Eating our own dog food

AgentPay's flagship analyst agent (agents/analyst/) runs daily on these exact rails as a real customer: it prices its plan with estimate_plan, gathers free intel, buys pre_trade_check verdicts 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.

---

Architecture

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.

Chain support & x402 interop

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

Stellar settles as a classic payment + text memo verified directly on Horizon. It is supported by the AgentPay SDK (pip install agentpay-x402) and by manual payment per the 402 instructions — but it is not the standard @x402/stellar scheme (which uses Soroban null-account templates, signed auth entries, and facilitator settlement). A standard @x402/stellar client 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

---

Stacks sBTC settlement

AgentPay settles x402 micropayments in sBTC on Stacks mainnet — budget-capped, signed client-side and never broadcast by the client (the gateway broadcasts the signed transaction, so a hostile gateway can settle at most the signed amount). Live on agentpay.tools since agentpay-x402 0.5.0:

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

• Walkthrough (start here): docs/stacks-walkthrough.md — install → one capped mainnet payment → the receipt verified three ways → the rules refusing before signing, with real output.
• Mainnet reference: docs/stacks-mainnet.md — config, the one-liner, redeeming an uncertain settle, ledger verification, the pilot agent.
• Runnable demo: examples/stacks_m1_demo.py — capped session → sBTC payment → receipt → over-cap rejection. STACKS_NETWORK=mainnet runs it on mainnet; the name is from the milestone it was written for.
• Spending rules demo: examples/stacks_policy_demo.py — recipient allowlist, per-call maximum and approval gate refusing sBTC payments before anything is signed, then one approved settlement; refusals on the receipt.
• Demo video: YouTube (~40s)
• Mainnet receipts: 0x30689b5e…, 0xd1de1a79…, 0x59ce7014… — sbtc-token::transfer payer → gateway, each from a $0.05-capped session, chain-verified on agentpay.tools/ledger.
• Milestone-1 (testnet) material, kept as delivered: docs/stacks-m1.md and the testnet proof 0xa5351bad… (PoX-5 testnet, block 82215). The testnet gateway is still up for anyone who wants to try the rail without mainnet sBTC.

---

Discovery

Agent-readable endpoints: