# agenticpay [![CI](https://github.com/agenticpay-dev/agenticpay/actions/workflows/ci.yml/badge.svg)](https://github.com/agenticpay-dev/agenticpay/actions/workflows/ci.yml) [![CodeQL](https://github.com/agenticpay-dev/agenticpay/actions/workflows/codeql.yml/badge.svg)](https://github.com/agenticpay-dev/agenticpay/actions/workflows/codeql.yml) [![gitleaks](https://github.com/agenticpay-dev/agenticpay/actions/workflows/gitleaks.yml/badge.svg)](https://github.com/agenticpay-dev/agenticpay/actions/workflows/gitleaks.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/agenticpay-dev/agenticpay?style=flat&logo=github&color=yellow)](https://github.com/agenticpay-dev/agenticpay/stargazers) [![npm: @agenticpay/sdk](https://img.shields.io/npm/v/@agenticpay/sdk?label=npm%20%40agenticpay%2Fsdk)](https://www.npmjs.com/package/@agenticpay/sdk) [![npm downloads](https://img.shields.io/npm/dm/@agenticpay/sdk?label=downloads)](https://www.npmjs.com/package/@agenticpay/sdk) **[Website](https://agenticpay-dev.github.io/)** · [Spend caps](https://agenticpay-dev.github.io/#spend-caps) · [npm](https://www.npmjs.com/package/@agenticpay/mcp-bridge) **Get paid by AI agents.** Open-source payment infrastructure for the MCP ecosystem - declare a price on any tool, agents pay in USDC over [x402](https://x402.org), settles on Solana in ~1.5 seconds. No Stripe. No accounts. No API keys. The full stack is here - SDK, CLI, paywall middleware, **self-hosted x402 facilitator**, and a live LLM agent demo. All TypeScript, MIT licensed. > **Just want to test it?** Point your `mcp-server` at our hosted devnet > facilitator: `FACILITATOR_URL=https://agentpay-facilitator-e9b20a5fee6a.herokuapp.com` > No setup needed. ## Live demo A real Claude Opus agent receives a task, decides which paid tools to use, pays autonomously via x402 micropayments on Solana, and answers the user. ``` $ pnpm --filter @agenticpay/two-agent-demo agent Agent wallet: 3rHoEumCpH8EGrr6Lq2vBKeyec6h3yPRGj2nGG2FzEfX Server: http://localhost:4021 Facilitator: http://localhost:4022 ← our own Model: claude-opus-4-7 Task: Reverse the string 'agentpay rocks' and tell me how many words are in 'The quick brown fox jumps over the lazy dog'. [turn 1] tool_use: reverse_string({"text":"agenticpay rocks"}) → paying $0.001 USDC ... ✓ paid + got result in 1596ms: {"result":"skcor yaptnega"} [turn 1] tool_use: word_count({"text":"The quick..."}) → paying $0.0005 USDC ... ✓ paid + got result in 1286ms: {"count":9} Agent final answer: 1. Reversed string: skcor yaptnega 2. Word count: 9 words === payments summary === reverse_string $0.0010 USDC 1596ms word_count $0.0005 USDC 1286ms TOTAL $0.0015 USDC 2 calls ``` On-chain proof (Solana devnet): - Settled by our self-hosted facilitator: [`EsqzTG8id...Bnku`](https://explorer.solana.com/tx/EsqzTG8id5CF5yxXmSSictkJnqn1uVC514joHqVBpdfSy4MkzvGzGGdb7Fybkn5ruSGyCQ87jyjmHuSGpU2Bnku?cluster=devnet) - Earlier settle via x402.org: [`2d2HcefgJ...vkqY`](https://explorer.solana.com/tx/2d2HcefgJYmkivWvf4x3TtZENnNEwJ94c9jLHZsHaDbYmEuBGuv3RCojLzsAjsqF2CKHujgX7QaDcApSLSQAvkqY?cluster=devnet) ## Why The current AI agent stack assumes humans hold the credit card. That breaks the moment agents act on their own initiative - calling APIs, hiring sub-agents, paying for compute. You can't OAuth your way through it. Stablecoin micropayments over HTTP fix it. agenticpay packages the missing ergonomics for the MCP ecosystem specifically: any tool can declare a price, any agent can pay it, and the whole pipeline - including the facilitator that actually submits the on-chain settlement - is open source and self-hostable. ## Architecture ``` ┌──────────────┐ 1) HTTP request ┌─────────────┐ │ Claude / │ ────────────────────────────────────▶ │ mcp-server │ │ GPT agent │ 2) HTTP 402 + payment requirements │ (yours) │ │ │ ◀──────────────────────────────────── │ │ │ │ 3) signed USDC payload │ │ │ │ ────────────────────────────────────▶ │ │ └──────────────┘ └─────┬───────┘ │ verify+settle ▼ ┌──────────────────────┐ │ agenticpay facilitator │ │ (also yours, this │ │ repo, port 4022) │ └──────────┬───────────┘ │ submit ▼ Solana (USDC SPL, sub-cent fees) ``` You can also point `mcp-server` at the public `x402.org/facilitator` for testnet/devnet, or at Coinbase CDP for mainnet. We just made the self-hosted route easy. ## Packages | Package | What it does | |---|---| | `packages/sdk` | TypeScript primitives: USDC transfers, wallet management, network config | | `packages/cli` | `agenticpay` command - wallet, balance, send | | `packages/mcp-server` | HTTP server with x402 paywall middleware. Each tool has a price. | | `packages/facilitator` | **Self-hosted x402 facilitator** - verify + settle USDC payments on Solana. Pays SOL fees on behalf of agents. | | `packages/eliza-plugin` | **Eliza plugin** - wraps paid HTTP endpoints as native Eliza Actions. Solana-native AI agents pay per tool call. | | `packages/ai-sdk` | **Vercel AI SDK helpers** - drop paid tools straight into `generateText` / `streamText`. | | `packages/mcp-bridge` | **Real MCP server** (stdio + `@modelcontextprotocol/sdk`) wrapping x402 paid tools. Drop into Claude Desktop / Cursor. | | `examples/two-agent-demo` | Real Claude Opus agent paying for tool calls | ## Install ```bash npm install @agenticpay/sdk # Solana + USDC primitives npm install -g @agenticpay/cli # `agenticpay` command npm install @agenticpay/mcp-server # paywalled HTTP server npm install @agenticpay/facilitator # self-hosted x402 facilitator npm install @agenticpay/eliza-plugin # Eliza plugin (Solana-native agents) npm install @agenticpay/ai-sdk # Vercel AI SDK paid tools npm install -g @agenticpay/mcp-bridge # MCP server for Claude Desktop / Cursor ``` Or clone the monorepo to get the live two-agent demo and edit-friendly templates (recommended for first run - see Quickstart below). ## Use with Claude Code This repo ships an [Anthropic Skill](https://docs.claude.com/en/docs/claude-code/skills) at `.claude/skills/agenticpay/SKILL.md`. Copy it into your `~/.claude/skills/` to give Claude Code first-class context about agenticpay - it'll then walk you through monetizing an MCP server, generating tool routes, and verifying on-chain settlements without re-reading the README every time. ```bash mkdir -p ~/.claude/skills cp -r .claude/skills/agenticpay ~/.claude/skills/ ``` ## Quickstart (devnet, ~5 minutes, free) ```bash # 1. Install pnpm install pnpm -r build # 2. Generate a payer wallet, fund it on devnet node packages/cli/dist/index.js wallet new node packages/cli/dist/index.js wallet show # → fund SOL at https://faucet.solana.com (paste pubkey) # → fund USDC at https://faucet.circle.com (Solana Devnet, same pubkey) # 3. (option A - fastest) Use our hosted devnet facilitator. Skip step 4. export FACILITATOR_URL=https://agentpay-facilitator-e9b20a5fee6a.herokuapp.com # 3. (option B - fully self-hosted) Start your own facilitator (terminal 1) pnpm --filter @agenticpay/facilitator dev # Note the printed feePayer address. It needs ~0.05 SOL devnet to cover fees. # Either airdrop or use the helper: pnpm --filter @agenticpay/facilitator fund export FACILITATOR_URL=http://localhost:4022 # 4. Start the paywalled mcp-server (terminal 2) PAY_TO= pnpm --filter @agenticpay/mcp-server dev # 5. Run the live LLM agent demo (terminal 3, needs ANTHROPIC_API_KEY in .env) pnpm --filter @agenticpay/two-agent-demo agent ``` ## Framework integrations Drop-in templates for the most common AI agent stacks live under `examples/`: | Framework | File | |---|---| | Anthropic SDK (canonical) | `examples/two-agent-demo/src/agent-llm.ts` | | Real-world paid server template (Claude-backed tools) | `examples/research-server/` | | LangChain.js | `examples/langchain-js/agent-with-paid-tools.ts` | | LangChain Python | `examples/langchain-python/agent_with_paid_tools.py` | | Eliza (Solana-native) | `examples/eliza/plugin-agenticpay.ts` | | Mastra | `examples/mastra/paid-tool.ts` | | Vercel AI SDK | `examples/vercel-ai-sdk/paid-tool.ts` | | OpenAI Custom GPT | `examples/openai-gpt/action-schema.json` | See `examples/README.md` for the integration matrix. ## Status Pre-alpha. Devnet validated end-to-end. Mainnet config supported but requires funding the facilitator with real SOL and pointing at a mainnet-capable RPC (Helius, QuickNode, etc.). ## Roadmap - [x] Devnet end-to-end demo (smoke + LLM agent) - [x] Self-hosted x402 facilitator (verify + settle, fee_payer abstraction) - [ ] Real-world MCP server template (search, fetch, summarize, extract - instead of toy `reverse_string`) - [ ] On-chain escrow for long-running tasks (Anchor program) - [ ] Agent reputation registry on-chain - [ ] Hosted facilitator service (`agenticpay.com`) ## What's a facilitator? If you've never seen x402 before: the **facilitator** is the trusted middleman that (1) verifies an agent's signed payment payload, (2) submits the USDC transfer on-chain, and (3) pays the SOL gas fees so the agent doesn't need any SOL - only USDC. Most MCP devs don't want to run their own; they point at a hosted one. This repo ships a complete facilitator implementation. You can self-host it, fork it, audit it, or deploy it as a service for your own users. ## What happens when a paid tool call fails? Short version: **a failed tool call is never charged.** x402 settlement is an irreversible push, so the middleware is careful about *when* it settles: 1. **Verify before execute.** The payment payload (signature, funds, requirements match) is verified before your tool handler runs. Invalid payment → HTTP 402, the tool never executes. 2. **Execute with a buffered response.** The handler runs, but its response is held back - nothing is sent to the agent yet. 3. **Settle only on success.** If the handler responds with status ≥ 400, the middleware skips settlement entirely and just returns the error. The agent pays nothing for a failed call. 4. **No result without payment.** If on-chain settlement itself fails, the buffered tool result is discarded and the agent gets a payment error instead - the server never leaks a result it wasn't paid for. What this doesn't cover: a tool that returns `200 OK` with a junk answer is still charged - the protocol can't judge response quality. That's what keeps per-call prices micro ($0.0005–$0.001 in the demo): the worst case is capped at one call's price, and quality enforcement belongs to a reputation layer (see Roadmap) rather than the payment protocol. ## License MIT