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(commerce): publish the agent commerce guide and keep the console on the page when a step-up password is wrong

nirholas6ad8a94f57fa
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 07f8e9cc6..8a021ccc7 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -94,6 +94,7 @@ bottom.
| Agent lifecycle, runs and automations over MCP (Runs tab) | MCP tools [api/_mcp/tools/agent-lifecycle.js](api/_mcp/tools/agent-lifecycle.js) (`get_agent`, `update_agent`, `delete_agent`, `start_agent`, `stop_agent`, `upload_agent_avatar`, `create_agent_run`, `update_agent_run`, `cancel_agent_run`, `get_agent_run_steps`, `automation_list`, `automation_get`, `automation_create`, `automation_update`, `automation_delete`, `automation_trigger`) over the REST validators and engines in [api/_lib/agents-v1/](api/_lib/agents-v1) (runs, automations, run receipts), policy rows in [packages/mcp-policy/src/table.js](packages/mcp-policy/src/table.js); replay endpoint [api/agent-run-replay.js](api/agent-run-replay.js) `→ /api/agent-run-replay`; Runs tab [src/agent-run-replay.js](src/agent-run-replay.js), mounted from [src/avatar-page.js](src/avatar-page.js) on `/agents/:id?view=runs` | Built, ships with the next deploy | An MCP client can now edit, start, stop, re-skin and delete an agent, and drive autonomous runs and automations, with create and update validated by the same schemas as the REST path. `delete_agent` and `automation_delete` are destructive: refused without `confirm_delete` and a matching `get_agent` / `automation_get` preview. A run carries two budgets (model turns and dollars), honors cancel between steps, ends with a plain-language summary, and chains a sha256 receipt over every step; `get_agent_run_steps` returns each tool call paired with its result and receipt. The owner-only Runs tab lists every run, replays it step by step with a scrubber, polls a live run, verifies the receipt chain server-side, and cancels. Docs: [docs/mcp.md](docs/mcp.md) `→ /docs/mcp`, [docs/agent-runtime.md](docs/agent-runtime.md#autonomous-runs-budgets-receipts-and-replay). Tests: [tests/mcp-agent-lifecycle.test.js](tests/mcp-agent-lifecycle.test.js), [tests/agent-run-replay-endpoint.test.js](tests/agent-run-replay-endpoint.test.js) |
| Agents REST API (`/api/v1`) and webhooks | Router [api/v1/rest.js](api/v1/rest.js) over [api/_lib/agents-v1/](api/_lib/agents-v1) (http envelope, agents, runs, automations, skills, [webhooks.js](api/_lib/agents-v1/webhooks.js), [run-stream.js](api/_lib/agents-v1/run-stream.js), [agent-export.js](api/_lib/agents-v1/agent-export.js), [openapi.js](api/_lib/agents-v1/openapi.js)), delivery queue [api/_lib/webhook-dispatch.js](api/_lib/webhook-dispatch.js), retry cron [api/cron/webhook-deliveries.js](api/cron/webhook-deliveries.js), dashboard [src/dashboard-next/pages/developers.js](src/dashboard-next/pages/developers.js) `→ /dashboard/developers` | Built, ships with the next deploy | Agent CRUD, start/stop, sync chat and history, runs with resumable SSE, automations with trigger-now, skills, strategies, export/import, and HTTPS webhooks (`run.finished`, `automation.fired`, `message.received`, `approval.needed`) with HMAC signatures, 8-attempt backoff, a delivery log and replay. Cursor pagination, `{data, meta}` envelope, `Idempotency-Key`. Docs: [docs/api-reference.md](docs/api-reference.md#agents-api-v1), [docs/developer-platform.md](docs/developer-platform.md). Tests: [tests/api/v1-rest-router.test.js](tests/api/v1-rest-router.test.js), [tests/api/agent-export.test.js](tests/api/agent-export.test.js), [tests/api/run-stream.test.js](tests/api/run-stream.test.js), [tests/webhook-dispatch-signing.test.js](tests/webhook-dispatch-signing.test.js) |
| Agent mail (inbox, rules, send controls) | Page [pages/agent-mail.html](pages/agent-mail.html) `→ /agents/:id/mail` and `/agent-mail` + [src/agent-mail.js](src/agent-mail.js), REST [api/v1/agent-mail.js](api/v1/agent-mail.js) `→ /api/v1/agents/:id/mail/*`, MCP [api/_mcp/tools/mail.js](api/_mcp/tools/mail.js), service [api/_lib/mail/](api/_lib/mail) (service, controls, untrusted, rules, inbound, content rules, spam, threading), webhook [api/mail/inbound.js](api/mail/inbound.js), migration [api/_lib/migrations/20261010184500_agent_mail_controls.sql](api/_lib/migrations/20261010184500_agent_mail_controls.sql) | Built, ships with the next deploy; outside delivery waits on the `agents.three.ws` DNS records (owner) | Each agent can hold an address on `agents.three.ws`: quote-then-confirm mailbox creation and sends that show the exact recipients and body first, content rules, a per-agent recipient allowlist and daily send cap that only a signed-in owner can change, instant delivery between agent mailboxes, and received mail fenced as untrusted data on every surface. Owner rules turn matching mail into a read-only, zero-budget agent run, either at once or after a yes in /approvals. Docs: [docs/agent-mail.md](docs/agent-mail.md). Tests: [tests/agent-mail-controls.test.js](tests/agent-mail-controls.test.js) |
+| Agent commerce (invoices, sends, offers, limit requests) | Owner console [pages/commerce.html](pages/commerce.html) `→ /commerce` and `/invoices` + [src/commerce-page.js](src/commerce-page.js), public invoice and receipt page [pages/agent-invoice.html](pages/agent-invoice.html) `→ /invoices/:id` + [src/agent-invoice-page.js](src/agent-invoice-page.js), REST [api/agent-commerce/[...route].js](api/agent-commerce/[...route].js) `→ /api/agent-commerce/*`, library [api/_lib/agent-commerce/](api/_lib/agent-commerce), MCP [api/_mcpagent/commerce-tools.js](api/_mcpagent/commerce-tools.js) on `/api/mcp-agent`, watcher cron [api/cron/agent-invoice-watch.js](api/cron/agent-invoice-watch.js), migration [api/_lib/migrations/20261010221500_agent_commerce.sql](api/_lib/migrations/20261010221500_agent_commerce.sql) | Built, ships with the next deploy | Agents and owners issue invoices in USDC, SOL or $THREE, payable by Solana Pay link or QR; a per-minute watcher matches payments by reference key and memo and moves invoices to paid, underpaid or expired, with webhooks, owner notifications and a public receipt. Paid mainnet invoices feed the earnings ledger. `agent_send` is preview-then-confirm and gated by the destination allowlist and approvals; offers sell with a quote and an explicit confirm and release the fulfillment only once the chain shows payment; `spending_setup` proposals need the owner's step-up (password, fresh sign-in or a linked-wallet signature) and can never be approved by the agent. Docs: [docs/agent-commerce.md](docs/agent-commerce.md). Tests: [tests/agent-commerce-invoices.test.js](tests/agent-commerce-invoices.test.js) |
| Agent perps (perpetual futures desk) | Page [pages/agent-perps.html](pages/agent-perps.html) `→ /agents/:id/perps` and `/agent-perps` + [src/agent-perps.js](src/agent-perps.js) + [src/agent-perps.css](src/agent-perps.css), REST [api/v1/agents/[id]/perps/[...path].js](api/v1/agents/[id]/perps/[...path].js) over [api/_lib/perps/routes.js](api/_lib/perps/routes.js) `→ /api/v1/agents/:id/perps/*`, MCP [api/_mcpagent/perps-tools.js](api/_mcpagent/perps-tools.js) (`perps_*` on `/api/mcp-agent`), service [api/_lib/perps/service.js](api/_lib/perps/service.js), venue contract and registry [api/_lib/perps/index.js](api/_lib/perps/index.js), venue module [api/_lib/perps/phoenix.js](api/_lib/perps/phoenix.js), paper ledger [api/_lib/perps/paper.js](api/_lib/perps/paper.js), limits [api/_lib/perps/limits.js](api/_lib/perps/limits.js), alerts [api/_lib/perps/alerts.js](api/_lib/perps/alerts.js), cron [api/cron/perps-tick.js](api/cron/perps-tick.js), migration [api/_lib/migrations/20261010213000_perps_desk.sql](api/_lib/migrations/20261010213000_perps_desk.sql) | Built, ships with the next deploy (paper by default; live per agent once the owner turns it on) | An agent goes long or short with USDC collateral from its own Solana wallet. Every action is a preview then a confirmed, idempotent execute that refuses if the quote moved past tolerance. Mandatory per-agent leverage and per-position margin caps (2x and $25 by default), slippage and quote-move limits, a live tracker stream with PnL, funding and liquidation distance, owner alert thresholds delivered through notifications, and a kill switch that cancels and closes everything. Paper mode fills at live prices; live transactions are simulated before the agent wallet signs. Docs: [docs/perps.md](docs/perps.md). Tests: [tests/perps-desk.test.js](tests/perps-desk.test.js) |
| Papertrade reads (HyperEVM synthetic perps) | REST [api/papertrade.js](api/papertrade.js) `→ /api/papertrade?view=markets, quote, account or protocol`, MCP [api/_mcpagent/papertrade-tools.js](api/_mcpagent/papertrade-tools.js) (`papertrade_*` on `/api/mcp-agent`), client and service [api/_lib/papertrade/index.js](api/_lib/papertrade/index.js), position math [api/_lib/papertrade/math.js](api/_lib/papertrade/math.js) | Built, ships with the next deploy | Read-only window onto Papertrade: live markets priced at the Hyperliquid mid, exact open quotes (hard-bust price, capacity limits, and the payout ladder after the deadband, impact haircut and live win fee), any wallet's positions valued live, and protocol health including the payout queue. Nothing signs or trades. Docs: [docs/papertrade.md](docs/papertrade.md). Tests: [tests/papertrade-math.test.js](tests/papertrade-math.test.js) |
| Solana trading tools (MCP + REST) | registry [api/_lib/trading-tools/registry.js](api/_lib/trading-tools/registry.js), REST [api/v1/trading/[...path].js](api/v1/trading/[...path].js) and [api/v1/trading/index.js](api/v1/trading/index.js) over [api/_lib/trading-tools/routes.js](api/_lib/trading-tools/routes.js) `→ /api/v1/trading/*`, MCP [api/_mcpagent/trading-tools.js](api/_mcpagent/trading-tools.js) (on `/api/mcp-agent`, group `trading`), swap comparison and router transaction check [api/_lib/trading-tools/swap-routes.js](api/_lib/trading-tools/swap-routes.js), quote and guarded fill [api/_lib/trading-tools/swap.js](api/_lib/trading-tools/swap.js) through [api/agents/solana-trade.js](api/agents/solana-trade.js), research [api/_lib/trading-tools/market.js](api/_lib/trading-tools/market.js), ecosystem signals [api/_lib/trading-tools/ecosystem.js](api/_lib/trading-tools/ecosystem.js), arbitrage [api/_lib/trading-tools/arbitrage.js](api/_lib/trading-tools/arbitrage.js), live route check [scripts/check-trading-routes.mjs](scripts/check-trading-routes.mjs) (`npm run check:trading-routes`) | Built, ships with the next deploy | Ten tools an agent trades Solana with, one registry for both surfaces: token search, price, indicators, news, and market signals (one token, or with no mint the ecosystem view: macro readings, top movers and anomalies with their inputs and `as_of`). `swap_quote` compares every aggregator on net output after fees and impact and says why one route won; with `agent_id` it runs the guard chain and issues a five-minute `quote_id`. `swap_simulate` dry-runs it; `swap_execute` fills it only with `confirm_swap: true`, re-priced and refused below the approved minimum, once per quote. `arbitrage_quote` shows the non-atomic risk, a simulated worst case and a verdict, and refuses above $100 unless asked. Docs: [docs/trading-tools.md](docs/trading-tools.md) `→ /docs/trading-tools`. Tests: [tests/trading-tools-swap.test.js](tests/trading-tools-swap.test.js), [tests/trading-tools-arbitrage.test.js](tests/trading-tools-arbitrage.test.js) |
diff --git a/data/changelog.json b/data/changelog.json
index f78f7ee02..931619fb6 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -29624,6 +29624,15 @@
"improvement"
],
"link": "/docs/start-here"
- }
-]
+ },
+ {
+ "date": "2026-10-10",
+ "title": "Agents can now send invoices, sell things, buy from each other and ask for higher limits",
+ "summary": "Your agent can bill anyone in USDC, SOL or $THREE. Each invoice gets a share page, a Solana Pay link and a QR code that any Solana wallet can scan, and three.ws watches the chain to mark it paid, part-paid or expired on its own, with notifications, webhooks and a receipt. Paid invoices show up in your agent's earnings next to skill sales and creator fees. Agents can also list things for sale and buy from each other with a quote first and an explicit confirm, and the goods are only released once the payment is verified. Sending money takes a preview and a confirm, and goes to your approvals unless the address is on your allowlist. An agent can read its own spending limits and propose changes, but only you can approve them, after confirming it is you. Manage it all on the new Commerce page.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/commerce"
+ }
+ ]
}
diff --git a/data/pages.json b/data/pages.json
index 89c3f2ffd..64fd2232f 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -5004,6 +5004,14 @@
"changefreq": "monthly",
"added": "2026-10-10"
},
+ {
+ "path": "/docs/agent-commerce",
+ "title": "Docs: Agent Commerce",
+ "description": "Let an agent invoice in USDC, SOL or $THREE with a Solana Pay link and QR verified on-chain, send money with a preview and confirm, sell and buy offers with fulfillment released on payment, and propose limit changes only the owner can approve. REST, MCP and webhook reference.",
+ "priority": 0.7,
+ "changefreq": "monthly",
+ "added": "2026-10-10"
+ },
{
"path": "/docs/checkout-companion",
"title": "Docs: Checkout companion",
diff --git a/docs/agent-commerce.md b/docs/agent-commerce.md
new file mode 100644
index 000000000..c4673d08c
--- /dev/null
+++ b/docs/agent-commerce.md
@@ -0,0 +1,245 @@
+# Agent Commerce: invoices, sends, offers and spending rules
+
+Agents on three.ws can already pay for things: `pay_quote` and `pay_and_call`
+settle a paid endpoint from an agent's wallet, inside the owner's per-payment
+and daily caps. Agent Commerce adds everything around that. An agent can
+**bill** someone and know when it was paid, **send** money under the owner's
+rules, **sell** something and **buy** from another agent with a quote and an
+explicit confirm. It can also **read its own spending limits and propose
+changes** that only the owner can approve.
+
+Everything settles on Solana. Every payment is verified on-chain before
+anything is marked paid, and paid invoices show up in the agent's earnings next
+to skill sales and creator fees.
+
+| Piece | Where | Source |
+|---|---|---|
+| Owner console | [/commerce](https://three.ws/commerce) (also `/invoices`): Invoices, Offers, Purchases and Limit requests tabs | [pages/commerce.html](../pages/commerce.html), [src/commerce-page.js](../src/commerce-page.js) |
+| Public invoice and receipt page | `/invoices/<id>`: amount, Solana Pay QR and link, status timeline, "I've paid" check, receipt once paid | [pages/agent-invoice.html](../pages/agent-invoice.html), [src/agent-invoice-page.js](../src/agent-invoice-page.js) |
+| REST API | `/api/agent-commerce/*` (v1 envelope, scopes, CSRF, Idempotency-Key) | [api/_lib/agent-commerce/routes.js](../api/_lib/agent-commerce/routes.js) |
+| MCP tools | 13 tools on the agent wallet server, `https://three.ws/api/mcp-agent`, group `commerce` | [api/_mcpagent/commerce-tools.js](../api/_mcpagent/commerce-tools.js) |
+| Invoice watcher | `/api/cron/agent-invoice-watch`, every minute | [api/cron/agent-invoice-watch.js](../api/cron/agent-invoice-watch.js) |
+| Invoices, Solana Pay, verification | server | [invoices.js](../api/_lib/agent-commerce/invoices.js), [solana-pay.js](../api/_lib/agent-commerce/solana-pay.js) |
+| Sends, offers, limit requests, step-up | server | [send.js](../api/_lib/agent-commerce/send.js), [offers.js](../api/_lib/agent-commerce/offers.js), [limit-requests.js](../api/_lib/agent-commerce/limit-requests.js), [step-up.js](../api/_lib/agent-commerce/step-up.js) |
+| Schema | `agent_commerce_invoices`, offers, orders, quotes and limit requests | [api/_lib/migrations/20261010221500_agent_commerce.sql](../api/_lib/migrations/20261010221500_agent_commerce.sql) |
+| Tests | amounts, Solana Pay links, payment matching, status rules, limit diffs, tool policy | [tests/agent-commerce-invoices.test.js](../tests/agent-commerce-invoices.test.js) |
+
+## Invoices
+
+An invoice is a request for a fixed amount of **USDC, SOL or $THREE**, paid
+into the issuing agent's own Solana wallet.
+
+| Field | Meaning |
+|---|---|
+| `amount`, `asset` | What is owed. `asset` is `USDC`, `SOL` or `THREE`. |
+| `network` | `mainnet` (default) or `devnet` for testing. $THREE exists on mainnet only, so a devnet $THREE invoice is refused. |
+| `memo` | What it is for, up to 140 characters. Shown to the payer, written on-chain with the payment. |
+| `description` | Optional longer detail for the receipt page, up to 1000 characters. |
+| `payer`, `payer_label` | Optional. A Solana address and a name for who should pay. Leave `payer` empty for an open invoice anyone can pay. The payer field is informational: the money is matched by the invoice's reference, so a payment from another wallet still counts. |
+| `due_in_hours` or `due_at` | When it expires. Default 72 hours, at least 5 minutes away, at most 90 days. |
+| `status` | `open`, `underpaid`, `paid`, `expired` or `cancelled`. |
+
+Every invoice gets a short number such as `INV-7E1XFEQ6`, a share link
+(`/invoices/<id>`), a Solana Pay link (`/api/agent-commerce/pay/<id>`, which
+redirects to the `solana:` transfer URL) and a QR code
+(`/api/agent-commerce/pay/<id>/qr.svg`). Any Solana wallet that supports
+Solana Pay can scan the QR and pay in one step.
+
+### How a payment is matched
+
+Each invoice carries a unique **reference key**. The Solana Pay link puts that
+key on the transfer, and the watcher finds payments by reading the
+transactions that touch it. A transaction counts toward the invoice only when:
+
+- it succeeded;
+- it carries the invoice's memo;
+- the right asset arrived at the issuing agent's wallet (the right mint and
+ owner for USDC and $THREE, a native transfer for SOL).
+
+Anything else is recorded as ignored with the reason (memo mismatch, wrong
+mint, failed transaction), never counted. Partial payments add up: two
+payments of half the amount make the invoice `paid`.
+
+### Lifecycle
+
+```
+open ──▶ underpaid ──▶ paid
+ │ │
+ ├──────────┴──▶ expired (the due date passed first)
+ └──▶ cancelled (the owner or the agent cancelled it)
+```
+
+- **underpaid**: a verified payment landed but the total is short. The pay
+ link always asks for the *remaining* amount.
+- **expired**: the due date passed before it was paid in full. A payment that
+ arrives later still settles it and is marked paid late. The money has
+ already moved, so an invoice that kept saying "expired" would be wrong. The
+ watcher keeps reading expired invoices for 24 hours for that reason.
+- **cancelled**: only an `open` invoice can be cancelled. Cancelling twice is
+ harmless and returns the same invoice.
+
+Every transition is a guarded update, so the watcher and a payer pressing
+"I've paid" at the same moment fire each webhook and notification exactly once.
+
+### Notifications and webhooks
+
+The owner gets an inbox notification (with a deep link to the invoice) when an
+invoice is paid, underpaid or expired. Webhook subscribers receive
+`invoice.created`, `invoice.paid`, `invoice.underpaid`, `invoice.expired` and
+`invoice.cancelled`, with the invoice in the payload. Subscribe from the
+webhooks panel, as with every other three.ws event.
+
+### Earnings
+
+When an invoice becomes `paid`, its USD value is fixed from the amount actually
+received at the live price of that moment. Paid **mainnet** invoices appear in
+the agent's earnings ledger as invoice income, next to skill sales and creator
+fees. Devnet invoices are test traffic and never count as earnings.
+
+## Sends
+
+`agent_send` moves money out of an agent's wallet to someone else, and it is
+always two steps:
+
+1. `agent_send_preview` pins the recipient, amount, asset and chain, and
+ reports how the send will be gated. The agent shows its user that table.
+2. `agent_send` consumes the preview with `confirm_send: true`. The destination
+ is re-checked at that moment:
+ - **on the owner's destination allowlist** (active and past its cooldown):
+ the agent signs it now, inside every spend cap;
+ - **not on it while the allowlist is off**: it becomes an approval request
+ in the owner's approvals inbox (push and Telegram). It is not sent until
+ the owner approves;
+ - **refused** by an enforced allowlist, a frozen wallet or a cap: it stops
+ with the reason. Approval cannot lift any of those.
+
+A preview runs once, expires, and only works for the agent that asked for it.
+
+## Offers and purchases
+
+An agent lists something for sale with `agent_sell`: a title, a price in USDC,
+SOL or $THREE, optional stock, and the **fulfillment** the buyer receives once
+paid (a download link, a code, instructions). Other agents find it with
+`offer_list`. Anyone can see the active ones at `GET /api/agent-commerce/offers`.
+
+Buying is quote, then confirm:
+
+1. `agent_buy` returns a quote with the seller's wallet, the amount, the asset
+ and the chain. Nothing is reserved or signed.
+2. `agent_buy_confirm` with that `preview_id` and `confirm_payment: true`
+ re-reads the offer (price, stock, still active) and opens an invoice from
+ the seller to the buyer. It pays that invoice from the buyer's wallet inside
+ the buyer's caps, then verifies it on-chain. When the invoice reads `paid`,
+ the order is delivered, the stock goes down, and the fulfillment is returned.
+
+A purchase is an ordinary invoice under the hood, so a sale lands in the
+seller's invoices, webhooks and earnings like any other income. If the
+payment lands before the RPC has indexed it, the order stays `submitted` and
+the watcher finishes it; confirming the same preview again returns the order
+and, once paid, the fulfillment. The owner manages offers (pause, reactivate,
+close) and sees every purchase on the Offers and Purchases tabs of
+[/commerce](https://three.ws/commerce).
+
+## Spending rules
+
+`spending_check` reads an agent's limits and today's usage: per-payment cap,
+daily cap, per-counterparty daily cap, whether the wallet is frozen, and
+whether capabilities are required.
+
+`spending_setup` lets the agent **propose** a change to those keys
+(`daily_usd`, `per_tx_usd`, `per_counterparty_daily_usd`, `frozen`,
+`require_capabilities`) with a reason. A proposal never changes anything:
+
+- It appears on the **Limit requests** tab of `/commerce` as a before/after
+ table, with each row marked as loosening or tightening, and a fingerprint of
+ the exact change.
+- Approving asks the owner to confirm it is them, with one of: their account
+ password; a fresh Google sign-in; or a signature from a Solana wallet linked
+ to their account over a message naming the request and its fingerprint. The
+ confirmation is valid for five minutes.
+- The approve endpoint accepts only a browser session with CSRF, so an agent's
+ API key or OAuth token cannot reach it, and no tool approves. An agent can
+ never approve its own limits.
+- On approval the change is applied through the same owner-only writer as the
+ Limits & Safety panel, and the custody log records it. A request expires
+ after seven days, and an agent can have at most three pending.
+
+The destination allowlist is not proposable. It keeps its own cooldown-gated
+flow.
+
+## MCP tools
+
+All thirteen live on the agent wallet server, `https://three.ws/api/mcp-agent`,
+in the `commerce` group. Financial-tier tools are hidden until a connection
+turns the group on, for example with `X-Three-Tools: default,commerce`.
+
+| Tool | Tier | Scope | What it does |
+|---|---|---|---|
+| `invoice_create(agent_id, amount, asset, memo, network?, description?, payer?, payer_label?, due_in_hours?, due_at?)` | write | `agents:write` | Issue an invoice. Returns the share link, Solana Pay link and QR. |
+| `invoice_details(invoice_id)` | read | `wallet:read` | One invoice with its payments and timeline. |
+| `invoice_list(agent_id?, status?, limit?, before?)` | read | `wallet:read` | Your invoices with totals (outstanding, paid, past due, mainnet income). |
+| `invoice_verify(invoice_id)` | read | `wallet:read` | Read the chain now and settle whatever it shows. |
+| `invoice_cancel(invoice_id)` | write | `agents:write` | Cancel an open invoice. |
+| `agent_send_preview(agent_id, to, amount, asset, network?, memo?)` | read | `wallet:read` | The confirmation table for a send and how it will be gated. Returns a `preview_id`. |
+| `agent_send(agent_id, preview_id, confirm_send)` | **financial** | `wallet:write` | Send, or route to owner approval, per the rules above. |
+| `offer_list(seller_agent_id?, asset?, network?, limit?)` | read | none beyond sign-in | Active offers to buy from. |
+| `agent_sell(agent_id, title, price, asset, fulfillment, description?, network?, stock?)` | write | `agents:write` | List an offer. |
+| `agent_buy(agent_id, offer_id)` | read | `wallet:read` | A purchase quote. Returns a `preview_id`. |
+| `agent_buy_confirm(agent_id, preview_id, confirm_payment)` | **financial** | `wallet:write` | Pay for the quoted offer and return the fulfillment once verified. |
+| `spending_check(agent_id, network?)` | read | `wallet:read` | Current limits and today's usage. |
+| `spending_setup(agent_id, changes, reason?)` | write | `agents:write` | Propose a limit change for the owner to approve. |
+
+The model must show the user the preview table (recipient, amount, asset,
+chain) and get an explicit yes before sending a `confirm_send` or
+`confirm_payment` flag.
+
+## REST API
+
+Base path: `https://three.ws/api/agent-commerce`. Responses use the v1
+envelope (`{ data, meta }` or `{ error: { code, message } }`). Writes from a
+browser session need the `x-csrf-token` header. Creates accept an
+`Idempotency-Key`.
+
+| Method and path | Auth | What it does |
+|---|---|---|
+| `GET /invoices/:id/public` | public | The payer's view: amount, pay link, timeline. |
+| `POST /invoices/:id/verify` | public | Read the chain now and settle what it shows. |
+| `GET /pay/:id` | public | 302 to the invoice's `solana:` transfer link. |
+| `GET /pay/:id/qr.svg` | public | That link as a QR code. |
+| `GET /offers` | public | Active offers. |
+| `GET /invoices`, `POST /invoices` | owner, `wallet:read` / `agents:write` | List with totals; create. |
+| `GET /invoices/:id`, `POST /invoices/:id/cancel` | owner | One invoice in full; cancel. |
+| `GET /offers/mine`, `POST /offers/mine`, `POST /offers/:id/status` | owner | Your offers; list one; set `active`, `paused` or `closed`. |
+| `GET /purchases` | owner, `wallet:read` | What your agents bought. |
+| `GET /requests` | owner, `wallet:read` | Limit proposals from your agents. |
+| `POST /requests/:id/challenge` | owner, browser session only | Step-up options and the wallet message to sign. |
+| `POST /requests/:id` | owner, browser session only | `{ decision: "approve", payload_hash, step_up }` or `{ decision: "deny" }`. |
+
+Create a devnet invoice with an API key:
+
+```bash
+curl -s https://three.ws/api/agent-commerce/invoices \
+ -H "authorization: Bearer $THREE_WS_API_KEY" \
+ -H "content-type: application/json" \
+ -H "idempotency-key: $(uuidgen)" \
+ -d '{"agent_id":"<your agent id>","amount":"0.01","asset":"SOL","network":"devnet","memo":"Logo design, first draft","due_in_hours":48}'
+```
+
+The response carries `invoice.page_url` (the share link to send the payer),
+`invoice.pay_url` (the `solana:` transfer link) and `invoice.qr_url`. The two
+pay fields become `null` once the invoice is paid or cancelled.
+
+## Testing on devnet
+
+Create an invoice with `"network": "devnet"` in USDC or SOL, open its share
+link, and pay it from any devnet wallet by scanning the QR. Press "I've paid"
+on the page, or wait up to a minute for the watcher. To see the other states:
+pay part of the amount and the invoice reads `underpaid` with the remainder on
+the pay link; set `due_in_hours` to `0.1` and let it pass, and it reads
+`expired`.
+
+## Related
+
+- [Agent wallet MCP server](./mcp-agent.md): `pay_quote`, `pay_and_call` and the rest of the wallet tools.
+- [Account linking](./account-linking.md): linking the Solana wallet used for step-up signatures.
+- [STRUCTURE.md](../STRUCTURE.md): where every surface lives.
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 53a768192..dc95f922b 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -10052,6 +10052,20 @@ An execute is refused with `409 quote_moved` when an order's entry or liquidatio
---
+## Agent commerce
+
+Invoices, offers, purchases and limit requests under `/api/agent-commerce/*`, in
+the v1 envelope. Public routes: `GET /invoices/:id/public`,
+`POST /invoices/:id/verify`, `GET /pay/:id` (302 to the `solana:` link),
+`GET /pay/:id/qr.svg`, `GET /offers`. Owner routes (session, API key or OAuth):
+`GET/POST /invoices`, `GET /invoices/:id`, `POST /invoices/:id/cancel`,
+`GET/POST /offers/mine`, `POST /offers/:id/status`, `GET /purchases`,
+`GET /requests`. Approving a limit request (`POST /requests/:id/challenge`,
+then `POST /requests/:id`) takes a browser session and a step-up proof only.
+Webhook events: `invoice.created`, `invoice.paid`, `invoice.underpaid`,
+`invoice.expired`, `invoice.cancelled`. Full reference and examples:
+[Agent Commerce](./agent-commerce.md).
+
## Pagination
Paginated list endpoints use `limit`/`offset` query parameters unless noted otherwise (each endpoint's own parameter table is authoritative; some small per-user lists, like `/api/agents` and `/api/widgets`, return everything with no pagination).
diff --git a/docs/mcp-agent.md b/docs/mcp-agent.md
index 73e87ad17..c9f139cb8 100644
--- a/docs/mcp-agent.md
+++ b/docs/mcp-agent.md
@@ -123,6 +123,25 @@ Full reference with examples: [MCP integration](./mcp.md#agent-wallet-portfolio-
| `duel_details(duel_id or challenge_id)` | read (predictions) | none for a duel, sign-in for a challenge | One duel with its window, phase, standings and crowd calls, or one challenge with its duel. |
| `duel_markets(view?, ...)` | read (predictions) | none, sign-in for `challenges` | Duels by phase, your incoming and outgoing challenges, or the challenge leaderboard plus this season's top predictors. |
+### Agent commerce
+
+Invoices, sends, offers and an agent's own spending rules, as thin adapters over
+`api/_lib/agent-commerce/` (the library behind `/commerce`, `/invoices/:id` and
+`/api/agent-commerce/*`). All thirteen tools are in the `commerce` group; turn
+the financial ones on with `X-Three-Tools: default,commerce`. Full guide:
+[Agent Commerce](./agent-commerce.md).
+
+| Tool | Tier | Scope | What it does |
+|------|------|-------|--------------|
+| `invoice_create`, `invoice_cancel` | write | `agents:write` | Issue an invoice in USDC, SOL or $THREE with a Solana Pay link, QR and receipt page; cancel an open one. |
+| `invoice_details`, `invoice_list`, `invoice_verify` | read | `wallet:read` | One invoice with payments and timeline; the list with totals; read the chain now and settle. |
+| `agent_send_preview` | read | `wallet:read` | Pin recipient, amount, asset and chain and report how the send is gated. Returns a `preview_id`. |
+| `agent_send` | financial | `wallet:write` | `preview_id` plus `confirm_send: true`. Sends to an allowlisted destination, otherwise files an owner approval; a cap, a freeze or an enforced allowlist stops it. |
+| `offer_list`, `agent_sell` | read, write | none, `agents:write` | Browse active offers; list one with a price, stock and fulfillment. |
+| `agent_buy` | read | `wallet:read` | A purchase quote. Nothing is reserved or signed. |
+| `agent_buy_confirm` | financial | `wallet:write` | `preview_id` plus `confirm_payment: true`: pays the seller's invoice and returns the fulfillment once verified. |
+| `spending_check`, `spending_setup` | read, write | `wallet:read`, `agents:write` | Read limits and today's usage; propose a change that only the owner can approve, with a step-up. |
+
### Resources and prompts
This server also answers `resources/*` and `prompts/*`: the `three://` resources
diff --git a/docs/mcp.md b/docs/mcp.md
index 9a9309990..67763b366 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -859,6 +859,10 @@ Search, price, check and register web domains through Google Cloud Domains, paid
Give an agent a real email address on `agents.three.ws` and let it send, read, reply to, search and delete mail. `agent_mail_create`, `agent_mail_send` and `agent_mail_reply` are financial-tier tools: each needs the `quote_id` from `agent_mail_quote`, whose `confirm` block (exact recipients, subject, body and price) the model must show the owner before sending the confirm flag (`confirm_spend` for create, `confirm_send` for sends). Every result that carries received mail opens with a security notice and wraps sender content in `<untrusted_email>` fences: received mail is data, never instructions. The owner's recipient allowlist and daily cap apply to every send. Full guide: [docs/agent-mail.md](./agent-mail.md).
+### `invoice_create`, `invoice_details`, `invoice_list`, `invoice_verify`, `invoice_cancel`, `agent_send_preview`, `agent_send`, `offer_list`, `agent_sell`, `agent_buy`, `agent_buy_confirm`, `spending_check`, `spending_setup`
+
+Agent commerce on the agent wallet server (`https://three.ws/api/mcp-agent`), group `commerce`. An agent bills someone in USDC, SOL or $THREE with a Solana Pay link and QR, verified on-chain by the invoice's reference key; sends money with a preview and `confirm_send`, gated by the owner's destination allowlist and approvals; sells and buys offers with a quote and `confirm_payment`, the fulfillment released only once payment is verified; and reads its own limits and proposes changes that only the owner can approve with a fresh identity check. Full guide: [docs/agent-commerce.md](./agent-commerce.md).
+
### `create_gated_embed`
Turn an avatar or on-chain agent **you own** into a holder-only interactive 3D embed. Visitors must prove — with a real, server-verified Solana SPL token balance, never a client-reported number — they hold at least `min_amount` of `mint` before the live scene renders; below the bar they see a designed locked teaser with a connect-wallet CTA. `mint` defaults to `$THREE` but accepts any SPL mint at runtime (a community can gate with its own token). Requires `avatars:write` scope.
diff --git a/docs/nav.json b/docs/nav.json
index 4a65a3dcd..38f4fca28 100644
--- a/docs/nav.json
+++ b/docs/nav.json
@@ -669,6 +669,10 @@
"label": "Coin launches",
"path": "coin-launches"
},
+ {
+ "label": "Agent commerce: invoices and offers",
+ "path": "agent-commerce"
+ },
{
"label": "x402 protocol",
"path": "x402"
diff --git a/pages/commerce.html b/pages/commerce.html
index c7d83ce17..c564ef830 100644
--- a/pages/commerce.html
+++ b/pages/commerce.html
@@ -57,10 +57,10 @@
<div id="ac-main" hidden>
<div class="ac-tabs" role="tablist" aria-label="Commerce sections">
- <button class="ac-tab" role="tab" id="tab-invoices" aria-controls="panel-invoices" aria-selected="true" data-tab="invoices">Invoices <span class="ac-count" data-count="invoices">0</span></button>
- <button class="ac-tab" role="tab" id="tab-offers" aria-controls="panel-offers" aria-selected="false" tabindex="-1" data-tab="offers">Offers <span class="ac-count" data-count="offers">0</span></button>
- <button class="ac-tab" role="tab" id="tab-purchases" aria-controls="panel-purchases" aria-selected="false" tabindex="-1" data-tab="purchases">Purchases <span class="ac-count" data-count="purchases">0</span></button>
- <button class="ac-tab" role="tab" id="tab-requests" aria-controls="panel-requests" aria-selected="false" tabindex="-1" data-tab="requests">Limit requests <span class="ac-count" data-count="requests">0</span></button>
+ <button class="ac-tab" role="tab" id="tab-invoices" aria-controls="panel-invoices" aria-selected="true" data-tab="invoices">Invoices <span class="ac-count" data-count="invoices" hidden></span></button>
+ <button class="ac-tab" role="tab" id="tab-offers" aria-controls="panel-offers" aria-selected="false" tabindex="-1" data-tab="offers">Offers <span class="ac-count" data-count="offers" hidden></span></button>
+ <button class="ac-tab" role="tab" id="tab-purchases" aria-controls="panel-purchases" aria-selected="false" tabindex="-1" data-tab="purchases">Purchases <span class="ac-count" data-count="purchases" hidden></span></button>
+ <button class="ac-tab" role="tab" id="tab-requests" aria-controls="panel-requests" aria-selected="false" tabindex="-1" data-tab="requests">Limit requests <span class="ac-count" data-count="requests" hidden></span></button>
</div>
<section id="panel-invoices" role="tabpanel" aria-labelledby="tab-invoices">
diff --git a/src/commerce-page.js b/src/commerce-page.js
index 08e5f81bb..a1b7af5d5 100644
--- a/src/commerce-page.js
+++ b/src/commerce-page.js
@@ -53,7 +53,7 @@ async function call(path, { method = 'GET', body, idempotent = false } = {}) {
try {
res = await apiFetch(path.startsWith('/api/') ? path : `${API}${path}`, {
method,
- allowAnonymous: method === 'GET',
+ allowAnonymous: true,
headers,
body: body ? JSON.stringify(body) : undefined,
});
@@ -62,11 +62,15 @@ async function call(path, { method = 'GET', body, idempotent = false } = {}) {
return { ok: false, status: 0, data: null, message: 'Network error. Check your connection and try again.' };
}
const json = await res.json().catch(() => ({}));
+ const code = json?.error?.code || null;
+ // A 401 from a step-up check is a wrong proof the row should explain; any
+ // other 401 means the session ended, so put the sign-in wall up.
+ if (res.status === 401 && method !== 'GET' && !String(code).startsWith('step_up')) showAuthWall();
return {
ok: res.ok,
status: res.status,
data: json?.data ?? json,
- code: json?.error?.code || null,
+ code,
message: json?.error?.message || json?.error_description || (typeof json?.error === 'string' ? json.error : null) || `Request failed (${res.status})`,
};
}
@@ -120,6 +124,7 @@ function setCount(tab, n, hot = false) {
const c = els.main.querySelector(`[data-count="${tab}"]`);
if (!c) return;
c.textContent = String(n);
+ c.hidden = false;
c.classList.toggle('is-hot', hot && n > 0);
}