Skip to content

Commit 0930a01

Browse files
up2itnow0822up2itnow0822
committed
feat: add AgentPay x402 payment demo
Adds a WebMCP demo showcasing x402 micropayments (HTTP 402 Payment Required) through navigator.modelContext on Base chain. Demo features: - Both declarative (toolname/tooldescription HTML attributes) and imperative (navigator.modelContext.registerTool) tool registration patterns - Three tools: fetch_paid_api, check_wallet_balance, get_payment_history - Simulated x402 API server (client-side, no backend required) - Clean UI: wallet status, activity log, payment history, API response - Full error handling and agent-active CSS states Tech: agentpay-mcp v4.0.0, agentwallet-sdk v6.0.4, webmcp-sdk v0.5.7 Protocol: x402 (Patent Pending) | Chain: Base | Non-custodial wallet via NFT Also adds entry to AWESOME_WEBMCP.md under Demos section.
1 parent 8944da6 commit 0930a01

5 files changed

Lines changed: 1293 additions & 1 deletion

File tree

‎AWESOME_WEBMCP.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,10 @@ A curated list of awesome WebMCP demos.
4545
- [WebMCP Flow](https://webmcp-flow.vercel.app/) - An AI-controllable architecture diagram builder that lets an AI agent create nodes, connect them with edges, and apply auto-layout in real time via WebMCP tools.
4646
- [Code](https://github.com/ttimur-dev/webmcp-flow)
4747
- **Example Prompt:** "Draw a typical web application architecture with authentication: browser client, API Gateway, Auth Service, User Service, PostgreSQL, Redis. Connect them with edges labeled by protocol and apply auto layout."
48-
48+
- [AgentPay x402 Payment Demo](https://googlechromelabs.github.io/webmcp-tools/demos/x402-payment/) - A WebMCP demo showing an AI agent making x402 micropayments through `navigator.modelContext`. Fetch a paid API endpoint; on HTTP 402 the AgentPay wallet signs a payment on Base and retries automatically. Uses both declarative and imperative tool registration.
49+
- [Code](https://github.com/GoogleChromeLabs/webmcp-tools/tree/main/demos/x402-payment)
50+
- **Example Prompt:** "Buy premium market data from this API using x402 payment"
51+
4952
## Contributing
5053

5154
Contributions are welcome! Please read the [contribution guidelines](CONTRIBUTING.md) first.

‎demos/x402-payment/README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# AgentPay x402 — WebMCP Payment Demo
2+
3+
🚀 **Live Demo:** https://googlechromelabs.github.io/webmcp-tools/demos/x402-payment/
4+
5+
A production-ready WebMCP demo showing an AI agent making **x402 micropayments** through `navigator.modelContext`. When a paid API returns HTTP 402, the AgentPay wallet automatically signs a payment on **Base** and retries — all inside the browser.
6+
7+
## What It Demonstrates
8+
9+
- **Both registration patterns:** declarative (`toolname` / `tooldescription` HTML attributes) AND imperative (`navigator.modelContext.registerTool()`)
10+
- **x402 payment flow:** GET → 402 Payment Required → sign payment → retry → 200 OK
11+
- **Non-custodial wallet UX:** balance, session spend limits, real-time payment log
12+
- **Three WebMCP tools:**
13+
- `fetch_paid_api` — Fetches a URL; handles HTTP 402 automatically
14+
- `check_wallet_balance` — Wallet balance + session spend limits
15+
- `get_payment_history` — Recent x402 payments made in this session
16+
17+
## Example Prompts
18+
19+
Use these with Claude, ChatGPT, or any MCP-compatible AI agent:
20+
21+
> **"Buy premium market data from this API using x402 payment"**
22+
23+
> "Check my wallet balance and spend limits"
24+
25+
> "Show me my payment history for this session"
26+
27+
> "Fetch https://api.agentpay.demo/news/crypto paying up to $0.05"
28+
29+
## How It Works
30+
31+
### 1. Declarative Tool (HTML)
32+
33+
The fetch form is tagged with WebMCP attributes. The browser exposes this as a structured tool to any connected AI agent:
34+
35+
```html
36+
<form
37+
id="fetchForm"
38+
toolname="fetch_paid_api"
39+
tooldescription="Fetch a URL that may require an x402 micropayment..."
40+
>
41+
<input name="url" toolparamdescription="The URL to fetch..." />
42+
<input name="max_payment_usdc" toolparamdescription="Max USDC to pay..." />
43+
</form>
44+
```
45+
46+
### 2. Imperative Tools (JavaScript)
47+
48+
Additional tools registered via `navigator.modelContext.registerTool()`:
49+
50+
```js
51+
if (navigator.modelContext) {
52+
navigator.modelContext.registerTool({
53+
name: 'check_wallet_balance',
54+
description: 'Returns the current AgentPay wallet balance in USDC...',
55+
inputSchema: { type: 'object', properties: {} },
56+
execute: () => JSON.stringify({ balance_usdc: 12.47, ... }),
57+
});
58+
}
59+
```
60+
61+
### 3. x402 Payment Flow
62+
63+
```
64+
Agent → fetch_paid_api(url, max_payment_usdc)
65+
→ GET /api/endpoint → 402 Payment Required
66+
→ AgentPay wallet signs payment on Base
67+
→ GET /api/endpoint + Payment-Authorization header
68+
→ 200 OK + data returned to agent
69+
```
70+
71+
## Tech Stack
72+
73+
| Package | Version | Purpose |
74+
|---|---|---|
75+
| [`agentpay-mcp`](https://www.npmjs.com/package/agentpay-mcp) | 4.0.0 | x402 payment MCP server |
76+
| [`agentwallet-sdk`](https://www.npmjs.com/package/agentwallet-sdk) | 6.0.4 | Non-custodial agent wallet |
77+
| [`webmcp-sdk`](https://github.com/up2itnow0822/webmcp-sdk) | 0.5.7 | WebMCP developer toolkit |
78+
| WebMCP API | Chrome 146+ | `navigator.modelContext` |
79+
| Base | Mainnet | L2 blockchain for payments |
80+
81+
## Running Locally
82+
83+
This is a **static HTML demo** — no build step required.
84+
85+
```bash
86+
# Serve locally (any static server works)
87+
npx serve demos/x402-payment
88+
89+
# Or with Python
90+
python3 -m http.server --directory demos/x402-payment 8080
91+
```
92+
93+
Then open `http://localhost:8080` in **Chrome 146+** with WebMCP enabled:
94+
95+
1. Go to `chrome://flags`
96+
2. Search for **"WebMCP"**
97+
3. Enable **"WebMCP for testing"**
98+
4. Restart Chrome
99+
100+
Install the [Model Context Tool Inspector](https://chromewebstore.google.com/detail/model-context-tool-inspec/gbpdfapgefenggkahomfgkhfehlcenpd) extension to inspect the registered tools.
101+
102+
## Architecture Notes
103+
104+
The demo runs fully client-side — the x402 API server is simulated in JavaScript to make it self-contained. In a real deployment:
105+
106+
- The API server would implement the [x402 spec](https://x402.org) and return `402 Payment Required` with payment requirements in the `X-Payment-Requires` header
107+
- `agentpay-mcp` handles payment signing, broadcasting to Base, and polling for confirmation
108+
- The wallet is a non-custodial ERC-4337 smart contract wallet — the NFT holder is the sole authorized signer
109+
110+
## x402 Protocol
111+
112+
x402 is an open protocol for **HTTP micropayments** using blockchain. A server returns:
113+
114+
```http
115+
HTTP/1.1 402 Payment Required
116+
X-Payment-Requires: {"currency":"USDC","network":"base","amount":"0.001","recipient":"0x..."}
117+
```
118+
119+
The client signs a payment, attaches it as a header, and retries:
120+
121+
```http
122+
GET /api/endpoint
123+
Payment-Authorization: {"signature":"0x...","tx_hash":"0x..."}
124+
```
125+
126+
x402 — Patent Pending. Spec: https://x402.org
127+
128+
---
129+
130+
*Built by [AgentPay](https://www.npmjs.com/package/agentpay-mcp) · x402 Protocol (Patent Pending) · Runs on Base*

‎demos/x402-payment/index.html‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
<!doctype html>
2+
<!--
3+
Copyright 2026 AgentPay / up2itnow0822
4+
SPDX-License-Identifier: Apache-2.0
5+
6+
AgentPay x402 Payment Demo
7+
Shows both declarative AND imperative WebMCP tool registration.
8+
x402 Protocol (HTTP 402 Payment Required) — Patent Pending
9+
Chain: Base (live) | Non-custodial smart contract wallet owned via NFT
10+
-->
11+
<html lang="en">
12+
<head>
13+
<meta charset="UTF-8" />
14+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
15+
<title>AgentPay x402 — WebMCP Payment Demo</title>
16+
<link
17+
rel="icon"
18+
href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>💳</text></svg>"
19+
/>
20+
<link href="style.css" rel="stylesheet" />
21+
</head>
22+
<body>
23+
<header class="site-header">
24+
<div class="logo">
25+
<span class="logo-icon">💳</span>
26+
<div>
27+
<h1>AgentPay <span class="badge">x402</span></h1>
28+
<p class="tagline">WebMCP Payment Demo — Patent Pending</p>
29+
</div>
30+
</div>
31+
<div class="chain-badge">
32+
<span class="dot"></span>
33+
Base Mainnet
34+
</div>
35+
</header>
36+
37+
<main>
38+
<!-- Wallet Status Panel -->
39+
<section class="panel wallet-panel">
40+
<h2>🔑 Agent Wallet</h2>
41+
<div class="wallet-grid">
42+
<div class="stat-card">
43+
<label>Wallet Address</label>
44+
<span id="wallet-address" class="mono truncate">Initializing…</span>
45+
</div>
46+
<div class="stat-card">
47+
<label>USDC Balance</label>
48+
<span id="wallet-balance" class="mono">—</span>
49+
</div>
50+
<div class="stat-card">
51+
<label>Session Spend Limit</label>
52+
<span id="spend-limit" class="mono">—</span>
53+
</div>
54+
<div class="stat-card">
55+
<label>Session Spent</label>
56+
<span id="session-spent" class="mono">—</span>
57+
</div>
58+
</div>
59+
<p class="wallet-note">
60+
Non-custodial · Smart contract wallet · Owned via NFT ·
61+
<a href="https://www.npmjs.com/package/agentpay-mcp" target="_blank" rel="noopener">agentpay-mcp v4.0.0</a>
62+
</p>
63+
</section>
64+
65+
<!-- Declarative tool: quick API fetch via form -->
66+
<section class="panel api-panel">
67+
<h2>📡 Fetch Paid API <span class="tag declarative">Declarative</span></h2>
68+
<p class="panel-desc">
69+
Use the declarative WebMCP tool to fetch premium market data. The agent
70+
will automatically handle HTTP 402 → sign payment → retry.
71+
</p>
72+
<form
73+
id="fetchForm"
74+
toolname="fetch_paid_api"
75+
tooldescription="Fetch a URL that may require an x402 micropayment. On HTTP 402, the agent wallet signs a payment on Base and retries automatically. Returns the JSON response body."
76+
>
77+
<div class="form-group">
78+
<label for="api-url">API Endpoint</label>
79+
<input
80+
type="url"
81+
id="api-url"
82+
name="url"
83+
value="https://api.agentpay.demo/market-data/BTC"
84+
placeholder="https://api.example.com/paid-endpoint"
85+
toolparamdescription="The URL to fetch. If it returns 402, the agent will pay and retry."
86+
/>
87+
</div>
88+
<div class="form-group">
89+
<label for="max-payment">Max Payment (USDC)</label>
90+
<input
91+
type="number"
92+
id="max-payment"
93+
name="max_payment_usdc"
94+
value="0.01"
95+
min="0.001"
96+
max="10"
97+
step="0.001"
98+
toolparamdescription="Maximum USDC to pay for this request. Default 0.01."
99+
/>
100+
</div>
101+
<button type="submit" class="btn-primary">
102+
🚀 Fetch (with x402 payment if needed)
103+
</button>
104+
</form>
105+
</section>
106+
107+
<!-- Activity Log -->
108+
<section class="panel log-panel">
109+
<h2>📋 Activity Log</h2>
110+
<div id="activity-log" class="log-container">
111+
<p class="log-empty">Agent activity will appear here…</p>
112+
</div>
113+
<div class="log-controls">
114+
<button class="btn-secondary" onclick="clearLog()">🗑 Clear</button>
115+
</div>
116+
</section>
117+
118+
<!-- Payment History -->
119+
<section class="panel history-panel">
120+
<h2>💰 Payment History <span class="tag imperative">Imperative</span></h2>
121+
<p class="panel-desc">
122+
Fetched via the <code>get_payment_history</code> imperative tool.
123+
Ask the agent: <em>"Show me my payment history for this session."</em>
124+
</p>
125+
<div id="payment-history" class="history-container">
126+
<p class="log-empty">No payments yet this session.</p>
127+
</div>
128+
</section>
129+
130+
<!-- API Response -->
131+
<section class="panel response-panel" id="response-panel" style="display:none">
132+
<h2>✅ API Response</h2>
133+
<pre id="response-body" class="response-body"></pre>
134+
<div class="payment-proof" id="payment-proof" style="display:none">
135+
<h3>🔗 Payment Receipt</h3>
136+
<div id="receipt-details" class="receipt-grid"></div>
137+
</div>
138+
</section>
139+
140+
<!-- Example prompts -->
141+
<section class="panel prompts-panel">
142+
<h2>💬 Example Prompts</h2>
143+
<ul class="prompt-list">
144+
<li>
145+
<button class="prompt-chip" onclick="copyPrompt(this)">
146+
Buy premium market data from this API using x402 payment
147+
</button>
148+
</li>
149+
<li>
150+
<button class="prompt-chip" onclick="copyPrompt(this)">
151+
Check my wallet balance and spend limits
152+
</button>
153+
</li>
154+
<li>
155+
<button class="prompt-chip" onclick="copyPrompt(this)">
156+
Show me my payment history for this session
157+
</button>
158+
</li>
159+
<li>
160+
<button class="prompt-chip" onclick="copyPrompt(this)">
161+
Fetch https://api.agentpay.demo/news/crypto paying up to $0.05
162+
</button>
163+
</li>
164+
</ul>
165+
<p class="prompt-note">Click a prompt to copy it, then paste into your AI agent.</p>
166+
</section>
167+
168+
<!-- WebMCP not available notice -->
169+
<section class="panel no-webmcp-notice" id="no-webmcp">
170+
<h2>⚠️ WebMCP Not Detected</h2>
171+
<p>
172+
This demo requires Chrome 146+ with WebMCP enabled. Enable it at
173+
<code>chrome://flags/#webmcp-for-testing</code> (or search "WebMCP") and restart Chrome.
174+
</p>
175+
<p>
176+
Install the
177+
<a href="https://chromewebstore.google.com/detail/model-context-tool-inspec/gbpdfapgefenggkahomfgkhfehlcenpd" target="_blank" rel="noopener">Model Context Tool Inspector</a>
178+
extension to debug registered tools.
179+
</p>
180+
</section>
181+
</main>
182+
183+
<footer>
184+
<p>
185+
Powered by
186+
<a href="https://www.npmjs.com/package/agentpay-mcp" target="_blank" rel="noopener">agentpay-mcp</a> ·
187+
<a href="https://github.com/up2itnow0822/webmcp-sdk" target="_blank" rel="noopener">webmcp-sdk</a> ·
188+
x402 Protocol (Patent Pending) · Built on Base
189+
</p>
190+
</footer>
191+
192+
<script type="module" src="script.js"></script>
193+
</body>
194+
</html>

0 commit comments

Comments
 (0)