# AgentPay

> The trust layer for AI agents that pay per call. We pay x402 services ourselves and check they deliver, rank them on that evidence, price a plan before the agent spends, and hand back a verifiable receipt — under a session cap enforced before a dollar moves. 17 free tools to start: no API keys, no USDC, no wallet setup. Every call is session-tracked with a full receipt.

AgentPay gives agents a wallet, a budget cap, and the awareness to spend it well. An agent can onboard with zero humans and zero funding in three calls: register, discover, call. Free tools cost $0 and need no funded wallet, yet every call still produces a receipt. Paid tools use x402: a 402 challenge, USDC settlement, retry with proof, verified on-chain. USDC on Base or Stellar — both the standard x402 `exact` scheme, so any standard client can pay (Stellar settles through the Built on Stellar facilitator with fees sponsored; Circle CCTP bridges USDC 1:1 between the two) — or sBTC / STX on Stacks from any Stacks x402 client. The AgentPay SDK adds a classic payment + memo path on Stellar.

## Onboarding (zero human, zero funding)

1. POST /v1/agent/register → { wallet, session_token, free_tools }  (free)
2. GET  /tools → list tools
3. POST /tools/{name}/call → { result, receipt }  (free tools settle $0)

Paid anchors (all $0.01, Bazaar-indexed): POST /v1/session/create (budget-capped session); pre_trade_check (one-call trade verdict — slippage at size, funding carry, OI crowding, security; Stacks tokens price the swap on Bitflow: impact at size, route, pool TVL); verified_route (buyer-side trust oracle — sweeps the x402 marketplace, collapses sybils, returns one vetted, ready-to-pay provider). Each pick carries a typed `evidence[]` (types follow the proposed x402 Trust-Provider evidenceType vocabulary).
Price any multi-tool plan BEFORE spending: POST /v1/plan/estimate (free, no wallet).

## Gateway

- Production: https://agentpay.tools
- Chains: USDC on Base (canonical paid chain; standard x402 `exact`), USDC on Stellar (standard x402 `exact` via the Built on Stellar facilitator, fees sponsored; the AgentPay SDK can also pay classic + memo; CCTP-bridged 1:1), or sBTC on Stacks mainnet, STX too (any Stacks x402 client; AgentPay SDK, sign-don't-broadcast) — live: stacks-mainnet
- Tools: 20 (17 free)
- Protocol: x402-v2 (HTTP 402 → pay → retry)
- SDK: pip install agentpay-x402 — one-liner: `from agentpay import quickstart; s = quickstart(); print(s.call('token_price', {'symbol':'ETH'}).data['price_usd'])`  (Base support: `pip install "agentpay-x402[base]"`; sBTC: `pip install "agentpay-x402[stacks]"` then `quickstart(stacks_key="…", prefer_chain="stacks")`)

## Tools

- crypto_news (Free): Latest crypto news and community sentiment from r/CryptoCurrency for any token
- defi_tvl (Free): DeFi protocol Total Value Locked from DeFiLlama. Returns top 10 or a specific protocol.
- dune_query (Free): Run any Dune Analytics query and return live onchain results by query ID. Use fast_only=True for live bots — returns cached result instantly or raises immediately, never blocks.
- fear_greed_index (Free): Crypto Fear & Greed Index (0=extreme fear, 100=extreme greed) with optional history
- funding_rates (Free): Get perpetual futures funding rates across Binance, Bybit, and OKX
- gas_tracker (Free): Get current Ethereum gas prices (slow, standard, fast)
- market_snapshot (Free): Fed rate, inflation proxy, S&P 500, BTC, ETH, and gas in one call. Replaces three separate API integrations with a single normalized response — the only tool that gives you macro + crypto in one shot.
- open_interest (Free): Get total open interest in perpetual futures for any asset, with 1h and 24h change rates. Pairs with funding_rates to complete the derivatives picture — rising OI with high funding = overcrowded position.
- orderbook_depth (Free): Get real bid/ask depth and slippage estimates at $10k, $50k, and $250k notional from Binance, Bybit and OKX. Use before sizing a position to know if you can execute without moving the market.
- pre_trade_check ($0.01): One-call pre-trade sanity check: 'I want to long $X of SYMBOL — is now sane?' Combines live orderbook slippage at YOUR size, cross-exchange funding (carry cost), open-interest crowding, and contract security (GoPlus) into a single ok/caution/avoid verdict with a per-factor breakdown. Major ERC-20 addresses (LINK, UNI, ARB, OP, AAVE, PEPE, SHIB) resolve automatically; native assets (BTC, ETH, SOL, ...) report security n/a; an unrecognized token without token_address reads 'unknown' and caps the verdict at caution — an unscreened contract can never read 'ok'. Replaces four API integrations and the judgment layer on top of them. Raw component data embedded so you can apply your own thresholds. Stacks tokens (STX, sBTC, USDCx, stSTX, ZEST, LEO, USDh, aeUSDC, stBTC) add the Bitflow DEX venue: price impact at YOUR size from a live route quote, the pools and bins the swap crosses, and their TVL; STX and sBTC keep their CEX perp legs, DEX-only tokens report funding/OI n/a and contract risk unscreened (no GoPlus coverage on Stacks).
- session_create ($0.01): Open a budget-capped agent session on AgentPay. Pay $0.01 USDC once — get a session_id, budget config, and gateway URL. Enforces a hard max_spend cap across all subsequent tool calls via the AgentPay SDK. The entry point for agents discovering AgentPay on Base Bazaar.
- token_market_data (Free): Get market cap, 24h volume, ATH, and price change for any token. Note: does NOT return pool depth or slippage — for pre-trade liquidity estimates, use a dedicated orderbook tool.
- token_price (Free): Get the current USD price of any cryptocurrency token
- token_security (Free): Scan any token contract for honeypot, rug pull, and security risks
- url_reader (Free): Convert any URL to clean, LLM-ready markdown. Strips ads, nav, and boilerplate — returns just the content. No API key needed.
- verified_route ($0.01): Paid buyer-side trust oracle: 'I need X, budget $Y — which x402 tool is real?' Sweeps the WHOLE x402 marketplace across many queries (a single search shows only a slice), collapses sybil/factory clusters (one wallet stamping many fake-distinct listings → one entry), ranks the genuinely-used survivors by real unique-payer usage, and returns ONE vetted recommendation with a ready-to-pay x402 challenge. The credit-bureau check an agent cannot do itself in one query — pay $0.01 to avoid paying a scam or a dead stub.
- wallet_balance (Free): Get the token balances for any Ethereum or Stellar wallet address
- web_search (Free): Search the web and return the top 5 results with their full content as clean markdown. Better than DIY because zero setup and results include page content, not just links.
- whale_activity (Free): Detect recent large wallet movements for a token (whale tracking)
- yield_scanner (Free): Find best DeFi yield opportunities across protocols for a given token

## Integration

POST /tools/{name}/call with {parameters, agent_address}
On 402: free tools ($0.000) authorize without an on-chain tx; paid tools settle USDC on Base or Stellar (standard x402, PAYMENT-SIGNATURE header — pick the `accepts[]` entry for your network), Stellar classic payment + memo (AgentPay SDK / manual, X-Payment header), or sBTC / STX on Stacks (PAYMENT-SIGNATURE from a Stacks x402 client, or the AgentPay SDK's signed `sbtc-token::transfer`; the gateway broadcasts and confirms).
Response: data is in result["result"]

## Recipe — pre-trade guardrail alongside Coinbase for Agents

Coinbase for Agents gives an agent trading (orders_preview / orders_create) and a curated x402 data catalog. AgentPay adds the step that catalog does not have: a one-call risk verdict before the order. Run the two MCPs side by side — AgentPay is not part of Coinbase's catalog and settles its own $0.01 from the small wallet you give it.
Config (claude_desktop_config.json, next to the Coinbase connector): "agentpay": {"command": "npx", "args": ["-y", "@romudille/agentpay-mcp"], "env": {"AGENTPAY_ENABLE_PAID": "1", "AGENTPAY_MAX_SPEND": "0.10"}} — fund the per-install wallet (address printed at startup) with a few cents of USDC on Base, or set AGENTPAY_BASE_KEY. Keyless, pre_trade_check refuses cleanly and says what to set.
Prompt to paste: Trading guardrail: before every Coinbase orders_create, call AgentPay pre_trade_check with {"symbol": <asset>, "side": <long|short>, "size_usd": <notional>}. Proceed only if the verdict is "ok". On "caution" or "avoid", show me the per-factor reasons and ask before doing anything else. For data the Coinbase catalog does not cover, call AgentPay verified_route first and use the provider it picks. Never exceed AGENTPAY_MAX_SPEND.

## Docs

- README: https://agentpay.tools/
- Agent Skills: npx skills add romudille-bit/agentpay — installs the agentpay-route
  (vet + pay the best x402 tool under budget) and agentpay-session (spend cap +
  receipts) skills into Claude Code, Codex, Droid, OpenCode, and other
  skills-CLI-compatible runtimes.
- MCP server: npx @romudille/agentpay-mcp — keyless: 17 free tools + verified_route
  preview. Wallet mode: set AGENTPAY_BASE_KEY (EVM key) + AGENTPAY_MAX_SPEND to
  settle paid tools in-place (gasless EIP-3009 on Base, hard session cap).
- Remote MCP (claude.ai, ChatGPT, Perplexity, Grok custom connectors): https://agentpay.tools/mcp — Streamable HTTP, no auth, the keyless tool set. Install steps per harness: https://agentpay.tools/connect. Priced tools answer an x402 PaymentRequired a wallet-carrying client pays in-band; otherwise local server or SDK.
- npm: https://www.npmjs.com/package/@romudille/agentpay-mcp
- GitHub: https://github.com/romudille-bit/agentpay
- Glama MCP: https://glama.ai/mcp/servers/romudille-bit/agentpay