agentpay

# AgentPay

[![Tests](https://github.com/romudille-bit/agentpay/actions/workflows/test.yml/badge.svg)](https://github.com/romudille-bit/agentpay/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/agentpay-x402?color=blue)](https://pypi.org/project/agentpay-x402/)
[![Python](https://img.shields.io/pypi/pyversions/agentpay-x402)](https://pypi.org/project/agentpay-x402/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/npm/v/%40romudille%2Fagentpay-mcp?label=mcp&color=orange)](https://www.npmjs.com/package/@romudille/agentpay-mcp)
[![Live gateway](https://img.shields.io/badge/gateway-agentpay.tools-black)](https://agentpay.tools)
[![x402-list](https://x402-list.com/badge/agentpay.svg)](https://x402-list.com/services/agentpay?utm_source=badge&utm_medium=referral&utm_campaign=embed)

*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](docs/stacks-walkthrough.md))

---

## Install

```bash
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.

```python
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:

```python
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.

| Tool | Parameters | Returns |
|------|-----------|---------|
| `url_reader` | `url` | Clean markdown content of any web page |
| `web_search` | `query` | Top 5 results with full content |
| `market_snapshot` | — | S&P 500, Treasury yield, BTC, ETH, gas in one call |
| `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` (days of history, default 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` (default 100k) | large_transfers[] with direction, total_volume_usd |
| `defi_tvl` | `protocol` (optional, e.g. "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` (e.g. ETHUSDT) | best_bid/ask, spread_pct, slippage at $10k/$50k/$250k |
| `funding_rates` | `asset` (optional) | funding_rate_pct, annualized_rate_pct, sentiment per exchange |
| `crypto_news` | `currencies` (e.g. "ETH,BTC"), `filter` | headlines[] with title, url, sentiment, score |
| `yield_scanner` | `token`, `chain` (optional), `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** |
| `verified_route` | `need`, `budget_usd?`, `chain?` | buyer-side trust oracle: sweeps the x402 marketplace, collapses sybil/factory clusters, ranks real providers by usage × delivery scores → one vetted recommendation + ready_to_pay challenge — **$0.01** |

---

## 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.

```python
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:

```python
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.

```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_