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(knock): document the paid door and register the new endpoints and tools

nirholas1cb30bf97bb8
diff --git a/docs/api-reference.md b/docs/api-reference.md
index a2cf12c2d..1d7afcac6 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -7052,6 +7052,97 @@ curl -X POST https://three.ws/api/seeker/verify \
---
+## Herald API: deliver a message in person
+
+The rail behind [@three-ws/herald](./herald.md). Anything that can make an HTTPS
+request posts a line here, and the browser tab the caller has open says it out
+loud through their 3D companion.
+
+An announcement is **always** delivered to the authenticated caller's own
+sessions. There is no recipient field, so a key can never be used to interrupt
+somebody else.
+
+### Announce
+
+```
+POST /api/herald/announce
+```
+
+Auth: a signed-in session, or a Bearer API key carrying the `herald:announce`
+scope (mint one at `/dashboard/developers`). Rate limit: 60 per minute per
+account.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `text` (alias `message`) | string, 1-280 | Required. The line to say. |
+| `from` | string, max 60 | Attribution, spoken with the line. |
+| `importance` | int 0-100 | Default 70. The receiving client applies its own floor. |
+| `url` | string, max 2048 | Same-origin path or absolute `http(s)`; anything else is dropped. |
+| `tone` | `neutral` \| `alert` \| `celebrate` \| `error` | Default `alert`. |
+| `emote` | string, max 40 | `wave`, `dance`, `punch`, `backflip`. |
+| `key` | string, max 120 | Dedupe key; two announcements sharing one are said once. |
+| `meta` | object | Passed through to the client untouched. |
+
+```bash
+curl -X POST https://three.ws/api/herald/announce \
+ -H "Authorization: Bearer $THREE_WS_API_KEY" \
+ -H 'content-type: application/json' \
+ -d '{"text":"Deploy is green","importance":80,"url":"/dashboard","from":"CI"}'
+```
+
+```json
+{
+ "queued": true,
+ "id": "6a293426-8f48-4254-bc14-cef9ada17680",
+ "expires_in": 300,
+ "announcement": {
+ "id": "6a293426-8f48-4254-bc14-cef9ada17680",
+ "text": "Deploy is green",
+ "from": "CI",
+ "importance": 80,
+ "url": "/dashboard",
+ "tone": "alert",
+ "at": 1787888380209
+ }
+}
+```
+
+`202` means the line is queued for a live surface, not that a human heard it.
+
+| Status | Code | Meaning |
+| --- | --- | --- |
+| 400 | `validation_error` | No `text`, or a field outside its bounds. |
+| 401 | `unauthorized` | No session and no bearer credential. |
+| 403 | `insufficient_scope` | A valid key without `herald:announce`. |
+| 429 | `rate_limited` | More than 60 announcements in a minute. |
+| 503 | `service_unavailable` | The rail is not reachable; nothing was queued. |
+
+### Listen
+
+```
+GET /api/herald/stream
+```
+
+Server-sent events, session-cookie auth only (writing is for machines,
+listening is for the person at the browser). Emits `open` once, then one
+`announce` per queued line, with a `ping` every 15 seconds. The queue is
+drained rather than broadcast, so a line is said by exactly one open tab, and
+an undelivered one expires after about five minutes.
+
+```bash
+curl -N https://three.ws/api/herald/stream -b 'session=<your session cookie>'
+```
+
+```
+event: open
+data: {"ts":1787888542255}
+
+event: announce
+data: {"id":"6a29...","text":"Deploy is green","importance":80,"tone":"alert"}
+```
+
+---
+
## 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/knock.md b/docs/knock.md
new file mode 100644
index 000000000..9fecb0a3d
--- /dev/null
+++ b/docs/knock.md
@@ -0,0 +1,294 @@
+# Knock
+
+**A priced door to a person. Pay their price, get one message through, and their
+3D companion delivers it in person.**
+
+Cold outreach is free to send and expensive to receive. That asymmetry is the
+whole problem: the person on the receiving end drowns, and the one message that
+mattered is lost in the pile. Knock inverts it. You publish a door, you set what
+one message from a stranger costs, and the price does the filtering. A stranger
+who genuinely needs you buys thirty seconds of your attention for a nickel. A
+spammer cannot buy a million of them.
+
+The delivery is the other half. A knock is not a badge on a tab you will get to
+later: your [companion](./companion.md) walks on screen wherever you are on
+three.ws, turns to you, and says who is at the door and what they paid.
+
+Open yours at **[three.ws/knock](https://three.ws/knock)**.
+
+- **The money is yours.** The USDC settles directly to the wallet you name.
+ three.ws never takes custody of it and takes no cut of it.
+- **Both kinds of visitor.** A person pays with the wallet in their browser. An
+ agent pays over [x402](./x402.md) with no human in the loop.
+- **Nothing lands for free.** Price, daily cap, message length, and a block list
+ are all yours to set. Every refusal happens before any payment, so a knock
+ that was never going to land is never a knock somebody paid for.
+- **One message, one door.** Knock is not a chat. It is a way in, once.
+
+---
+
+## Opening your door
+
+1. Pick a username, if you have not (your door lives at `/knock/<username>`).
+2. Open [three.ws/knock](https://three.ws/knock) and set:
+ - **Price**: anything from $0.001 to $1,000, or `0` for a free door.
+ - **Solana wallet**: where the USDC lands. Solana is the home chain and the
+ lane an agent settles on by default. A Base address is optional and is only
+ advertised when you set one.
+ - **Headline and greeting**: what a visitor reads before they write. Tell
+ them what you actually want to hear about; it is the cheapest filter you
+ have.
+ - **Daily cap** and **message length**.
+3. Flick **Door open**. Share the link.
+
+A priced door cannot be opened without a payout address. The API refuses the
+save rather than quietly routing a stranger's money into the platform's wallet.
+
+**Listed** is separate from **open**. An unlisted open door is reachable by
+anyone with the link but never appears in the public directory, which is what
+you want if you are handing the link to a specific set of people.
+
+---
+
+## What a visitor sees
+
+`three.ws/knock/<handle>` renders your price, your greeting, and a box. The
+message is capped at the length you set, with a live counter.
+
+A **subject** line is optional and is the only thing spoken aloud. The body is
+shown in full, in the bubble and in your inbox, but it is never read at you by
+your own avatar: a long or hostile paragraph should not be able to hijack your
+companion's mouth.
+
+When the knock lands, the sender gets a **receipt URL**. It carries its own
+proof (an HMAC over the knock id), so they can check on it later without an
+account here, and it exposes exactly two things: the status, and the reply if
+you wrote one.
+
+---
+
+## What you see
+
+Two views of the same thing.
+
+**In person.** The knock becomes a companion event whose importance is derived
+from the amount paid, so your avatar walks on and says, for example, *"Ada paid
+$0.05 to reach you: Your x402 settle path."* Every paid knock scores above the
+default interrupt threshold of 60; a free-door knock lands at 45, which puts it
+in the feed and the bell without stopping your day. Raise your companion's
+threshold if you want only the expensive ones to interrupt.
+
+**In the inbox.** [three.ws/knock](https://three.ws/knock) lists every knock
+with what it was worth, plus totals: waiting, all time, and earned. From a row
+you can reply, mark read, dismiss, or block.
+
+A **reply** is written back to the receipt link the sender already holds. That
+is the whole return path, deliberately: answering someone never hands out your
+email address or opens a thread.
+
+A **block** matches on the wallet that paid when there was one, and on the
+sender's name when the knock was free. A blocked sender gets the same answer a
+shut door gives, so they cannot tell it was them specifically.
+
+---
+
+## For agents
+
+### Read the door first
+
+```bash
+curl -s 'https://three.ws/api/knock/door?handle=nirholas'
+```
+
+```json
+{
+ "door": {
+ "handle": "nirholas",
+ "display_name": "nirholas",
+ "free": false,
+ "price": "$0.05",
+ "price_atomics": "50000",
+ "currency": "USDC",
+ "networks": ["solana"],
+ "max_chars": 600,
+ "headline": "Ask me about x402 on Solana",
+ "endpoint": "https://three.ws/api/x402/knock?to=nirholas",
+ "protocol": "x402"
+ }
+}
+```
+
+Public, cacheable, no credential. A handle nobody has opened a door for and a
+handle that matches nobody both answer 404 with the same body, so this cannot be
+used to enumerate accounts.
+
+`GET /api/knock/directory` returns every open, listed door, cheapest first.
+
+### Knock, and pay for it
+
+The paid lane is a standard x402 endpoint:
+
+```
+POST https://three.ws/api/x402/knock?to=<handle>
+```
+
+```json
+{
+ "from": "Ada (research agent)",
+ "subject": "Your x402 settle path",
+ "message": "I index x402 endpoints and yours is the only one settling on Solana. Two questions about the facilitator.",
+ "url": "https://example.com/ada",
+ "sender_kind": "agent",
+ "request_id": "ada-2026-08-28-001"
+}
+```
+
+The first call answers `402` with the door's real price and the recipient's own
+address as `payTo`. Pay it and retry with the `X-PAYMENT` header, exactly as
+with any other x402 resource. A settled call returns:
+
+```json
+{
+ "ok": true,
+ "knock_id": "c1b0a2d4-…",
+ "delivered_to": "nirholas",
+ "announced": true,
+ "importance": 74,
+ "paid": "$0.05",
+ "receipt_url": "https://three.ws/api/knock/reply?id=c1b0a2d4-…&token=…",
+ "duplicate": false
+}
+```
+
+`request_id` is an idempotency key. A retry after a settled payment returns the
+first knock rather than knocking, and charging, twice.
+
+Free doors take a plain POST instead, with the handle in the body:
+
+```bash
+curl -X POST https://three.ws/api/knock/send \
+ -H 'content-type: application/json' \
+ -d '{"to":"nirholas","from":"Ada","message":"a real message"}'
+```
+
+Posting to the wrong lane is not an error you have to guess at: a priced door
+answers the free lane with `402` and the x402 endpoint to use, and a free door
+answers the x402 lane with `400` and the plain one.
+
+### With the SDK
+
+```bash
+npm install @three-ws/knock
+```
+
+```js
+import { knock, quote } from '@three-ws/knock';
+import { wrapFetchWithPayment } from 'x402-fetch';
+
+const door = await quote('nirholas'); // read the live price first
+
+const result = await knock({
+ to: 'nirholas',
+ from: 'Ada (research agent)',
+ subject: 'Your x402 settle path',
+ message: 'Two questions about the facilitator.',
+ fetchWithPayment: wrapFetchWithPayment(fetch, wallet),
+ maxPriceAtomics: 100_000n, // never spend more than $0.10
+ requestId: 'ada-2026-08-28-001',
+});
+```
+
+The SDK never signs anything itself: you pass the paying `fetch` from the x402
+client and wallet you already trust, so your keys and your chain stay yours.
+`maxPriceAtomics` is checked against the door's live price before any payment is
+attempted, which matters because an owner can raise their price between your
+quote and your call.
+
+From the terminal:
+
+```bash
+npx @three-ws/knock quote nirholas
+npx @three-ws/knock send nirholas "Two questions." --from "Ada" --payer ./payer.mjs
+```
+
+A priced door prints the recipient, the amount, the token and the chain, and
+stops for a yes. With no TTY it refuses rather than assuming consent.
+
+### From an MCP client
+
+```bash
+claude mcp add knock -- npx -y @three-ws/knock-mcp
+```
+
+Six tools: `knock_quote`, `knock_directory`, `knock_send`, `knock_receipt`, and
+(with `THREE_WS_API_KEY`) `knock_inbox` and `knock_act`.
+
+The MCP server holds no wallet and cannot spend. On a priced door `knock_send`
+returns the recipient, amount, token and chain and stops, so the decision to pay
+stays with a human. See
+[@three-ws/knock-mcp](https://www.npmjs.com/package/@three-ws/knock-mcp).
+
+### Read the answer
+
+```bash
+curl -s 'https://three.ws/api/knock/reply?id=<knock id>&token=<receipt token>'
+```
+
+```json
+{ "knock": { "status": "replied", "reply": "Ask away.", "seen": true, "amount": "$0.05" } }
+```
+
+Statuses: `pending`, `read`, `replied`, `dismissed`. A wrong or missing token is
+a 404, not a 403: an id on its own should not confirm that a knock exists.
+
+---
+
+## Endpoints
+
+| Endpoint | Auth | What it does |
+| --- | --- | --- |
+| `GET /api/knock/door?handle=` | none | One door's public terms. |
+| `GET /api/knock/directory` | none | Every open, listed door, cheapest first. |
+| `POST /api/knock/send` | none | Knock on a free door. |
+| `POST /api/x402/knock?to=` | x402 payment | Knock on a priced door. |
+| `GET /api/knock/reply?id=&token=` | receipt token | What became of a knock you sent. |
+| `GET /api/knock/settings` | session | Your door, your totals, your block list. |
+| `PATCH /api/knock/settings` | session | Change any of it. |
+| `GET /api/knock/inbox` | session | The knocks your door has taken. |
+| `PATCH /api/knock/inbox/<id>` | session | Reply, mark read, dismiss, block. |
+
+Error codes are stable and mean what they say: `no_door`, `door_closed`,
+`door_full` (429, retryable tomorrow), `message_too_long`, `message_too_short`,
+`bad_url`, `missing_sender`, `free_door`, `payment_required`.
+
+---
+
+## Why it is built this way
+
+**Refuse before charging.** The message is read and validated against that
+door's limits before the 402 is issued. A knock that is too long, a door that is
+shut, a door that is full for the day, a sender who is blocked: all of them cost
+nothing. The handler that records the knock also runs before settlement, so even
+a payer who skipped the pre-flight gets refused without moving money.
+
+**The price is the ranking.** A mail client guesses at importance from keywords.
+A knock does not have to guess: the sender said what reaching you was worth, in
+money. The companion's importance score is a log-scaled function of the amount,
+so a $50 knock outranks a $0.05 one without a $5,000 knock being able to sit
+permanently at the top of the feed.
+
+**The body is never spoken.** Only the subject line is read aloud. Anything a
+stranger writes is untrusted text, and untrusted text does not get to use your
+avatar as a speaker.
+
+**No custody, no cut.** `payTo` on the 402 challenge is the recipient's own
+address. There is no platform wallet in the path to be drained, reconciled, or
+argued about.
+
+---
+
+## Related
+
+- [The Companion](./companion.md) is what delivers a knock in person.
+- [x402](./x402.md) is the payment protocol the priced lane speaks.
+- [Notifications](./notifications.md) covers the per-category channel matrix; knocks are their own category, and the avatar channel is on for them by default.
diff --git a/docs/mcp.md b/docs/mcp.md
index 64069c772..21732cc64 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -109,6 +109,7 @@ npx -y @three-ws/agent-sniper serve # the same engine as an x402-paid HTTP API (
# Account, inbox & discovery
npx -y @three-ws/notifications-mcp # inbox, read state, delivery prefs & Web Push devices
+npx -y @three-ws/herald-mcp # tell your human in person: your avatar walks on and says it
npx -y @three-ws/billing-mcp # plan quotas, metered usage, invoices & receipts
npx -y @three-ws/activity-mcp # trending agents/coins, $THREE holder board & activity ticker
diff --git a/docs/start-here.md b/docs/start-here.md
index 76c01d834..0f77b5b16 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -141,6 +141,7 @@ Curious what happens between the prompt and the model? [How the Forge works](./h
- **Following Solana traders?** → [KOL Tracker](./kol-tracker.md): KOLs ranked by realized P&L computed from their own wallets' on-chain trades (never self-reported), with the public API behind it
- **Listening to the economy?** → [Agent Symphony](./agent-symphony.md): /symphony plays the live agent economy as generative music; every event type has a voice, and solo mode isolates one agent by ear
- **Catching up on your inbox?** → [Notifications](./notifications.md): the bell, the /notifications center, category filters, and the full inbox API
+- **Something too important for a badge?** → [Herald](./herald.md): the open SDK behind /herald, where a 3D character walks onto the page and says it out loud, with an interrupt budget (importance floor, quiet hours, dedupe, batching), an accessible card for machines with no GPU, a rail so CI or an AI agent can reach the tab you have open, and a CLI that announces when your build finishes
- **About to pay for something?** → [Checkout companion](./checkout-companion.md): the browser extension that reads a payment page before you pay, why the arithmetic is never a model's job, and why it never reads a form field
- **Something broken on a page?** → [Feedback](./feedback.md): telling the corner companion what went wrong, what the browser attaches for you, and the boundary that keeps untrusted text from ever reaching anything with write access
- **Showing off your work?** → [The creator portfolio](./creator-portfolio.md): everything on your public /u/username page, what makes an item public, and how following works from it
diff --git a/packages/agent-glance/src/index.js b/packages/agent-glance/src/index.js
index 47bc9f6b3..a9889f513 100644
--- a/packages/agent-glance/src/index.js
+++ b/packages/agent-glance/src/index.js
@@ -148,7 +148,9 @@ export function glanceEmbedHtml(agentId, opts = {}) {
*/
export function renderGlanceAnsi(card, opts = {}) {
const color = opts.color !== false;
- const width = Math.max(34, Math.min(80, opts.width || 46));
+ // Wide enough that the agent URL fits whole: a card whose last line is a
+ // half-truncated uuid cannot be copied, which is most of why it is there.
+ const width = Math.max(40, Math.min(100, opts.width || 68));
const c = (code, text) => (color ? `\u001b[${code}m${text}\u001b[0m` : String(text));
const dot = { active: '32', idle: '33', new: '90' }[card.status] || '90';
const pad = (text) => {