Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(mcp): document the 17 named commerce tools and spending_report

nirholas16b544a33044
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11fd04b38..5354adc83 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Docs · Forge Workflows** (`/docs/forge-workflows`): How Forge Workflows chains Forge tools into one repeatable run: the visual node editor, the four starter templates (photo to 3D, text to rigged character, batch photos to library, photo to game asset), resuming from a failed node, and how it differs from Workbench.
- **Docs · Squad chat** (`/docs/team-chat`): How squad chat turns a plain-language request into a plan of role-tagged steps for a specialist team or a solo agent: who can see each squad, how the plan is checked against your own words before it runs, and when a step stops for your approval.
- **Docs · Standalone repositories** (`/docs/standalone-repos`): The generated catalog of every publishable package in this monorepo mirrored to its own standalone GitHub repository with its own install command and documentation site, so each one can be found, starred, installed and cited on its own.
+- **17 named commerce tools and a spending report land in the x402 MCP buyer, hosted and self-custodial**: The self-custodial x402 buyer (@three-ws/x402-mcp, npx -y @three-ws/x402-mcp) and the hosted agent wallet (https://three.ws/api/mcp-agent) both gained 17 named tools, one per fixed three.ws x402 service: weather_forecast, weather_go_no_go, carbon_now, carbon_best_window, domain_rdap_check, domain_rdap_check_bulk, research_search, research_paper, research_bibliography, book_search, book_read, news_wire_search, news_wire_poll, transit_plan, transit_delays, places_search and places_detail. Each carries a fixed input schema and states its price in its description, so a model calls it correctly far more often than it composes the equivalent raw pay_and_call(url) call. On the hosted side every named tool has a matching <name>_quote read tool that prices it without paying, and the shared tool-policy runtime (@three-ws/mcp-policy) gates payment on that exact quote (one service's quote can never unlock a different service's payment). The stdio package also gained spending_report, which totals everything pay_and_call and the named tools have paid, by merchant and by day, from a local append-only ledger (X402_MCP_LEDGER_PATH). (`/docs/mcp`) `[feature, sdk]`
- **A generated SKILL-MD 1.0 catalog of every paid HTTP route is now live at /.well-known/skill.md**: Any agent can now load one markdown file, https://three.ws/.well-known/skill.md, and get a conformant SKILL-MD 1.0 document (the x402-skill-md format) listing every priced endpoint on three.ws: method, path, price, parameters, and the Solana and Base payment rails it settles on, plus a sample 402 challenge body. The document is generated straight from the same OpenAPI catalog /openapi.json serves (api/_lib/skill-md.js reads the shared buildOpenApiDoc() builder and the real buildExactRequirements() rail logic, so the catalog and the live 402 challenge can never drift apart), and is linked from /.well-known/x402.json and llms.txt. Validated in tests/skill-md.test.js against the real upstream x402-skill-md npm validator: zero errors other than the EVM rail finding (SM005), which is expected since this is a Solana-first platform and Base settles only when a facilitator is configured. Distinct from the pre-existing https://three.ws/skill.md (no .well-known), the Agent Skills connector file for installing three.ws MCP servers; both now cross-link to the other. (`/.well-known/skill.md`) `[feature, docs]`
- **A spend call above an agent's approval threshold now pauses for the owner instead of failing**: The requires_approval verdict agent payment sessions and agent-to-agent hires can already produce now actually does something: both /api/pay/execute and /api/agents/a2a-hire create a request on the existing approval inbox the moment a call crosses the caller's approval_threshold_usd, answer with 202 and a poll link to /approvals/<id> instead of failing the call, and resume automatically the moment the owner taps Approve there, re-probing or re-running the exact same reserve-then-settle path the call would have taken inline, with no re-entry point for a double-spend. A denied request answers 403 on the next poll, an expired one answers 410, and retrying with the same idempotency key before the owner answers just re-polls instead of parking a second request. Nothing new to build on the approval page itself: it already renders any venue generically from the request's summary, amount, and risk notes, so the two new venues (payment_session_execute, a2a_hire) show up with the right Approve/Decline card for free. Covered by 21 new handler tests across create, approve, decline, expire, and the executor's own idempotent re-run. (`/approvals`) `[feature, security]`
- **Payment sessions gain blocked hosts, an approval threshold, and a per-rail daily cap, all with tamper-evident verdicts**: Agent payment sessions get three new governance knobs, settable at creation and editable while a session is active: blocked_hosts (a denylist checked after the allowlist, so an explicit block always wins over a broad allow, even with no allowlist set), approval_threshold_usd (a call priced above this amount now gets a distinct requires_approval verdict instead of either settling or silently failing), and per_rail_daily_usd (a rolling 24h spend cap per settlement network, reserved atomically the same way the session budget already is, closing the race a naive sum-of-past-executions check would leave open). Every governance verdict, allow or reject, now carries a policy_digest (a sha256 hash of the exact policy it was judged against) and an HMAC signature over the verdict, digest, request, and timestamp, stored with the execution: editing a session's policy after the fact changes the digest and breaks the signature on every verdict that preceded the edit, so a verdict record can be trusted even after the policy it was judged against has since moved. The dry-run simulator at /api/pay/simulate now predicts all three new rules through the exact same shared policy module the real enforcer calls, so a simulated verdict and an enforced one can never disagree; that parity is pinned by a new test running both over identical scenarios. The payments page gained matching fields in both the session creation and edit modals, with inline validation and a collapsed 'Advanced spend policy' section so the common case (budget, expiry, host allowlist) stays uncluttered. (`/docs/payment-sessions`) `[feature, security]`
diff --git a/data/changelog.json b/data/changelog.json
index 4268a922c..415a0a9ef 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-15",
+ "title": "17 named commerce tools and a spending report land in the x402 MCP buyer, hosted and self-custodial",
+ "summary": "The self-custodial x402 buyer (@three-ws/x402-mcp, npx -y @three-ws/x402-mcp) and the hosted agent wallet (https://three.ws/api/mcp-agent) both gained 17 named tools, one per fixed three.ws x402 service: weather_forecast, weather_go_no_go, carbon_now, carbon_best_window, domain_rdap_check, domain_rdap_check_bulk, research_search, research_paper, research_bibliography, book_search, book_read, news_wire_search, news_wire_poll, transit_plan, transit_delays, places_search and places_detail. Each carries a fixed input schema and states its price in its description, so a model calls it correctly far more often than it composes the equivalent raw pay_and_call(url) call. On the hosted side every named tool has a matching <name>_quote read tool that prices it without paying, and the shared tool-policy runtime (@three-ws/mcp-policy) gates payment on that exact quote (one service's quote can never unlock a different service's payment). The stdio package also gained spending_report, which totals everything pay_and_call and the named tools have paid, by merchant and by day, from a local append-only ledger (X402_MCP_LEDGER_PATH).",
+ "tags": ["feature", "sdk"],
+ "link": "/docs/mcp"
+ },
{
"date": "2026-10-15",
"title": "A generated SKILL-MD 1.0 catalog of every paid HTTP route is now live at /.well-known/skill.md",
diff --git a/docs/mcp.md b/docs/mcp.md
index 213f84b20..718dce133 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1377,6 +1377,45 @@ winning close actually pays across eight price moves after Papertrade's deadband
win fee. `papertrade_account` values any wallet's open positions at the live mid. The same data is on
`GET /api/papertrade`. Full guide: [Papertrade](./papertrade.md).
+### Named commerce tools: pay a fixed three.ws service
+
+Seventeen named tools, each wired to one fixed three.ws x402 endpoint, exist on two servers so the
+same tool names, prices and schemas are available whether an agent talks to the self-custodial
+stdio package or the hosted agent wallet:
+
+- **Hosted** (`https://three.ws/api/mcp-agent`): pays from the signed-in user's own three.ws agent
+ wallet, the same rail `pay_and_call` uses. Each service gets a `<name>_quote` read tool (prices it,
+ never pays) and a `<name>` financial tool, gated by the shared policy runtime on that service's own
+ `quote_id` plus `confirm_payment: true`. A quote from one service can never unlock a different
+ service's payment: every financial tool's preview tool name is unique to it.
+- **Stdio** (`npx -y @three-ws/x402-mcp`): pays with the local `SOLANA_SECRET_KEY` (or a Payment
+ Session token), the same settlement modes as that package's `pay_and_call`. See
+ [its README](../packages/x402-mcp/README.md#tools) for the full tool-to-endpoint table.
+
+| Tool | Price | What it pays for |
+|------|-------|-------------------|
+| `weather_forecast` | $0.001 | 24h hourly forecast at a lat/lon (Open-Meteo, NWS fallback) |
+| `weather_go_no_go` | $0.002 | go/caution/no-go verdict for an activity from the next 6h forecast |
+| `carbon_now` | $0.001 | current UK grid carbon intensity, national or by postcode |
+| `carbon_best_window` | $0.002 | lowest-carbon window in the next 48h |
+| `domain_rdap_check` | $0.001 | one domain's live RDAP registration status |
+| `domain_rdap_check_bulk` | $0.005 | up to 50 domains' RDAP status in one call |
+| `research_search` | $0.002 | merged arXiv + Crossref + Semantic Scholar paper search |
+| `research_paper` | $0.003 | one paper's metadata plus its two-sided citation graph |
+| `research_bibliography` | $0.005 | BibTeX / APA 7 for up to 25 DOIs |
+| `book_search` | $0.001 | OpenLibrary edition search, flagged for a Gutenberg full text |
+| `book_read` | $0.01 | a public-domain book's complete text, split into chapters |
+| `news_wire_search` | $0.003 | GDELT worldwide news search with a coverage timeline |
+| `news_wire_poll` | $0.002 | GDELT articles since a cursor, for an ongoing monitor loop |
+| `transit_plan` | $0.002 | an MBTA trip plan between two stops, with realtime overlays |
+| `transit_delays` | $0.001 | realtime vs. scheduled MBTA arrivals at one stop |
+| `places_search` | $0.002 | OpenStreetMap points of interest near a coordinate |
+| `places_detail` | $0.002 | one place's full OpenStreetMap record |
+
+`spending_report` (stdio package only, read-only) totals everything paid through that key, by
+merchant and by day, from the package's local append-only ledger
+(`X402_MCP_LEDGER_PATH`, default `~/.three-ws/x402-mcp-ledger.jsonl`).
+
---
## Resources
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 45ae4083a..57fcc8f58 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-15T06:13:31.758Z",
+ "generated_at": "2026-10-15T06:54:02.716Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4103,
+ "total": 4104,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -49,6 +49,17 @@
"launch"
]
},
+ {
+ "date": "2026-10-15",
+ "type": "update",
+ "title": "17 named commerce tools and a spending report land in the x402 MCP buyer, hosted and self-custodial",
+ "summary": "The self-custodial x402 buyer (@three-ws/x402-mcp, npx -y @three-ws/x402-mcp) and the hosted agent wallet (https://three.ws/api/mcp-agent) both gained 17 named tools, one per fixed three.ws x402 service: weather_forecast, weather_go_no_go, carbon_now, carbon_best_window, domain_rdap_check, domain_rdap_check_bulk, research_search, research_paper, research_bibliography, book_search, book_read, news_wire_search, news_wire_poll, transit_plan, transit_delays, places_search and places_detail. Each carries a fixed input schema and states its price in its description, so a model calls it correctly far more often than it composes the equivalent raw pay_and_call(url) call. On the hosted side every named tool has a matching <name>_quote read tool that prices it without paying, and the shared tool-policy runtime (@three-ws/mcp-policy) gates payment on that exact quote (one service's quote can never unlock a different service's payment). The stdio package also gained spending_report, which totals everything pay_and_call and the named tools have paid, by merchant and by day, from a local append-only ledger (X402_MCP_LEDGER_PATH).",
+ "link": "/docs/mcp",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-10-15",
"type": "update",
@@ -1548,16 +1559,6 @@
"tags": [
"launch"
]
- },
- {
- "date": "2026-10-10",
- "type": "launch",
- "title": "Launch a Uniswap Pool Coin",
- "summary": "Have your agent launch a fixed-supply coin with a Uniswap V3 pool on Base: pick the pool fee, lock the liquidity, route the fees, see every cost in a confirmation table, and follow the launch to completion. Retries are safe with an Idempotency-Key.",
- "link": "/launch/uniswap",
- "tags": [
- "launch"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index 388f956fb..cf360693a 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-15T06:13:31.737Z",
+ "generated_at": "2026-10-15T06:54:02.696Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -46,6 +46,17 @@
"launch"
]
},
+ {
+ "date": "2026-10-15",
+ "type": "update",
+ "title": "17 named commerce tools and a spending report land in the x402 MCP buyer, hosted and self-custodial",
+ "summary": "The self-custodial x402 buyer (@three-ws/x402-mcp, npx -y @three-ws/x402-mcp) and the hosted agent wallet (https://three.ws/api/mcp-agent) both gained 17 named tools, one per fixed three.ws x402 service: weather_forecast, weather_go_no_go, carbon_now, carbon_best_window, domain_rdap_check, domain_rdap_check_bulk, research_search, research_paper, research_bibliography, book_search, book_read, news_wire_search, news_wire_poll, transit_plan, transit_delays, places_search and places_detail. Each carries a fixed input schema and states its price in its description, so a model calls it correctly far more often than it composes the equivalent raw pay_and_call(url) call. On the hosted side every named tool has a matching <name>_quote read tool that prices it without paying, and the shared tool-policy runtime (@three-ws/mcp-policy) gates payment on that exact quote (one service's quote can never unlock a different service's payment). The stdio package also gained spending_report, which totals everything pay_and_call and the named tools have paid, by merchant and by day, from a local append-only ledger (X402_MCP_LEDGER_PATH).",
+ "link": "/docs/mcp",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-10-15",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index cd683cc22..f0ececc30 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -38,6 +38,14 @@
<category>launch</category>
<description>The generated catalog of every publishable package in this monorepo mirrored to its own standalone GitHub repository with its own install command and documentation site, so each one can be found, starred, installed and cited on its own.</description>
</item>
+ <item>
+ <title>17 named commerce tools and a spending report land in the x402 MCP buyer, hosted and self-custodial</title>
+ <link>https://three.ws/docs/mcp</link>
+ <guid isPermaLink="false">2026-10-15:17 named commerce tools and a spending report land in the x402 MCP buyer, hosted and self-custodial</guid>
+ <pubDate>Thu, 15 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>The self-custodial x402 buyer (@three-ws/x402-mcp, npx -y @three-ws/x402-mcp) and the hosted agent wallet (https://three.ws/api/mcp-agent) both gained 17 named tools, one per fixed three.ws x402 service: weather_forecast, weather_go_no_go, carbon_now, carbon_best_window, domain_rdap_check, domain_rdap_check_bulk, research_search, research_paper, research_bibliography, book_search, book_read, news_wire_search, news_wire_poll, transit_plan, transit_delays, places_search and places_detail. Each carries a fixed input schema and states its price in its description, so a model calls it correctly far more often than it composes the equivalent raw pay_and_call(url) call. On the hosted side every named tool has a matching &lt;name&gt;_quote read tool that prices it without paying, and the shared tool-policy runtime (@three-ws/mcp-policy) gates payment on that exact quote (one service's quote can never unlock a different service's payment). The stdio package also gained spending_report, which totals everything pay_and_call and the named tools have paid, by merchant and by day, from a local append-only ledger (X402_MCP_LEDGER_PATH).</description>
+ </item>
<item>
<title>A generated SKILL-MD 1.0 catalog of every paid HTTP route is now live at /.well-known/skill.md</title>
<link>https://three.ws/.well-known/skill.md</link>
diff --git a/public/features.json b/public/features.json
index aaddd2330..d95521c56 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-15T06:13:31.723Z",
+ "generated_at": "2026-10-15T06:54:02.683Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",