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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(onboarding): document agent self-signup and x402 plan upgrade, serve an absolute 402 resource URL, and cover the route and upgrade with tests
nirholas2ca7f0057abf
diff --git a/.agents/skills/create-a-three-ws-agent/SKILL.md b/.agents/skills/create-a-three-ws-agent/SKILL.mdindex e738bf055..ecf139c98 100644--- a/.agents/skills/create-a-three-ws-agent/SKILL.md+++ b/.agents/skills/create-a-three-ws-agent/SKILL.md@@ -22,6 +22,25 @@ ticker and on `/agents`.## Prerequisites+### No human available: sign yourself up++If there is no person to mint a key, an agent can onboard itself with a Solana key and+no email. This creates an account on the Free plan in paper mode, a custodial agent+wallet and an API key, and stores the key for the CLI:++```bash+npx @three-ws/cli signup --agent --name my-agent+```++Or call `POST /api/auth/agent-signup` twice (challenge, then signed redeem). The+returned key has scopes `read agents:read agents:write wallet:read`, which covers+agent creation and edits through `/api/v1/agents`. A paid plan is a separate x402+payment at `POST /api/billing/agent-upgrade?plan=builder`; never make that payment+without the owner confirming recipient and amount. Full guide:+[docs/agent-self-onboarding.md](../../../docs/agent-self-onboarding.md).++### With a human: an API key+One API key with write scope. The user mints it at[three.ws/dashboard/api](https://three.ws/dashboard/api) (sign in first at`https://three.ws/login`).diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6f0a70504..6d07eef03 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Docs · MCP registry sentinel, daily gap report** (`/docs/mcp-registry-sentinel`): The daily cron that diffs every MCP server three.ws ships against the official registry and npm, and raises one ops alert when the set of gaps changes. What it reads and what it reports.- **Docs · Owner-Funded Agent Budgets** (`/docs/agent-allowance-budgets`): Keep funds in your own wallet and give an agent a capped, expiring allowance enforced by the Solana Subscriptions and Allowances program. How the budget is created, pulled, guarded and revoked, and how to prove it on devnet.- **Docs · X post reader and free video tool** (`/docs/x-video`): One keyless reader for public X posts, shared by the price-impact tools and the free X video page: how it fetches, what it returns and where it is used.+- **Docs: Agent self-onboarding** (`/docs/agent-self-onboarding`): An agent signs itself up with a Solana key and no email, gets an account, a wallet and an API key, and buys a paid plan with one x402 payment. Challenge format, errors, limits and the CLI.- **install.md** (`/install.md`): How to install three.ws in any MCP client: one command, per-client settings, and every hosted endpoint. Generated from the MCP directory.- **MCP Plans** (`/mcp-plans`): Prepay for paid MCP tools with credit bundles or time passes, use free trial calls on every tool, and see each credit spent.- **README 3D** (`/readme-3d`): Put an interactive 3D model in any GitHub README. Paste a GLB, glTF, OBJ or STL URL and get a block GitHub renders as a rotatable viewer, sized to fit its markdown limit.@@ -18,6 +19,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Agent memory now learns from trade results, and the decision trail has a verify endpoint**: When a snipe closes, its realized P&L, win or loss and hold time are written back onto the memories the agent recalled when it opened the trade. Recall then ranks those memories by a bounded outcome weight (0.65 to 1.35, halving every 45 days, never zero), so lessons from winners rise while memories tied to losses sink but still come back as warnings. Every recall hit now reports its rankScore and an outcome block with the weight, wins, losses and net USD so you can see why it ranked. The hash-chained decision trail can be re-walked at GET /api/agents/:id/decision-trail/verify, which returns ok, the head hash and the zero-based index of the first broken row after any edit. The reasoning ledger page now fetches it and links to it from the verified badge. (`/reasoning-ledger`) `[feature, improvement]`- **Agents answer mentions of their own X account, in their own persona**: An agent with its own connected X account and mention replies switched on is now polled by the mention bot. It replies in its own persona, attaches a render of its own avatar to conversational replies, and only acts on the intents its owner allowed, up to a daily cap. Dry run stays the default: nothing posts until the owner turns dry run off and the operator enables live mode. A connection missing the posting scope is reported as missing_scope instead of being polled. (`/agents`) `[feature]`- **Agents can sign up to services: inbox codes and sign-in links**: An agent's own address can now receive verification emails and hand back the one-time code or sign-in link. New inbox_list, inbox_read and inbox_wait_for_code tools read the code with a confidence score, only from services the owner lists under Code senders, only from authentic non-spam mail. Email bodies stay untrusted data and links are never fetched for the agent. (`/agent-mail`) `[feature]`+- **An agent can sign itself up and pay for its plan**: An autonomous agent now signs up with a Solana key and no email: it signs a single-use server challenge, receives an account, a custodial wallet and an API key, and can then buy the Builder or Scale plan with one USDC x402 payment on Solana. The CLI does the whole thing with `three-ws signup --agent`. Replayed or badly signed challenges are rejected, each key gets one account, and signups are rate limited and capped per day. (`/docs/agent-self-onboarding`) `[feature, sdk]`- **AR Studio source now lives in the monorepo**: The 3d-ar-studio npm package and the /ar/studio page now run the same code: the package source moved into packages/ar-studio and the page imports its scene math, multi-anchor WebXR session, room client and lighting modules directly, so fixes land once instead of in two diverging copies. (`/ar/studio`) `[sdk, improvement]`- **Chain turnover on /chains**: The chains leaderboard now has a sortable Turnover column (24h DEX volume divided by TVL) that shows which chains have capital actively trading rather than parked. Chains with no TVL or no reported volume show n/a. (`/chains`) `[feature]`- **Copy any model as a GitHub README 3D block**: Forge results, avatar pages, the avatar dashboard and model pages now have a Copy as GitHub README 3D action. It simplifies the model to a size GitHub renders and puts a stl code fence on your clipboard that GitHub shows as an interactive 3D viewer in any README, issue or pull request. The same converter is a free API (POST /api/readme-3d) and has a live page at /readme-3d. (`/readme-3d`) `[feature]`@@ -42,6 +44,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **three-ws pay: settle x402 and MPP challenges from the terminal with a key you hold**: The CLI can now pay a 402 itself. `three-ws pay <url>` reads an x402 v2, x402 v1 or MPP Solana challenge, prefers Solana, signs with a wallet kept in the OS keychain (or an encrypted file behind a passphrase), retries once and prints the body. `--dry-run` shows the payee, exact amount and network and signs nothing. A permissions file sets allowed origins, networks, assets and payees, per-call and per-day maximums and a confirm-above threshold, and a refused challenge exits with a stable code (10) and a reason string. `three-ws pay mcp` serves the same under the same permissions as a stdio MCP server with pay_quote and pay_fetch. `[feature, sdk]`- **Trust grades for every MCP server**: /mcp-tools now grades each of the 51 MCP servers from A to F on a 0-100 score built from facts the build checks: tools declared and described, safety annotations, an installable package or mounted endpoint, a registry manifest, a README, a license, tests, prompts, resources and the Glama claim. Hover or focus a grade for the full breakdown, and click the Trust column to sort. The rubric and weights are documented. (`/docs/mcp`) `[feature]`- **Turn a Solana program's Anchor IDL into an agent skill**: POST /api/skills/import now accepts idl_url or program_id. Each account type becomes a read tool that decodes it by address, each instruction a preview tool that builds the unsigned instruction with a plain summary, and a destructive send tool that hands it to the wallet confirm flow. A risk panel flags token movement, SOL spend, account closure and authority changes. Nothing the skill generates can sign. (`/skills/import`) `[feature, sdk]`+- **x402 pay-for-what-you-use on Solana (upto)**: A paid route can now advertise an upto offer beside its fixed price: the buyer authorizes a cap, the seller measures the work and settles only that amount, and the rest of the escrowed deposit returns to the buyer. A handler that fails settles nothing. The LLM proxy is the first route converted (5 atomics per token, capped at 5x the flat price). Agent payers refuse a cap above their per-call limit before signing, and the unused part of the cap is released from their budget. Existing exact clients are unaffected. (`/docs/x402-upto`) `[feature, improvement]`## 2026-10-15diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 6d1c387e3..c2efff927 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -283,6 +283,7 @@ packages, a generated standalone GitHub mirror). See| Fee Bridge (creator fees to an X account in USDC) | Page [pages/fee-bridge.html](pages/fee-bridge.html) (unrouted until launch) + [src/fee-bridge.js](src/fee-bridge.js) + [src/fee-bridge.css](src/fee-bridge.css), API [api/fee-bridge/[action].js](api/fee-bridge/%5Baction%5D.js) `→ /api/fee-bridge/*`, engine [api/_lib/fee-bridge/](api/_lib/fee-bridge/engine.js) (config, chain, ledger, math), cron [api/cron/fee-bridge.js](api/cron/fee-bridge.js) (every 10 min), migration [api/_lib/migrations/20260917150000_fee_bridge.sql](api/_lib/migrations/20260917150000_fee_bridge.sql), studio option in [public/studio/fees-panel.js](public/studio/fees-panel.js) | In-repo · Held (not public) | A coin routes 100% of its pump.fun creator fees to the bridge wallet (`FEE_BRIDGE_SECRET_KEY_B64`, signer `fee-bridge`, exempt from economy sweeps via `holdsUserFunds`) and is registered to an X handle after an on-chain routing and ownership check. The cron cranks distribution, swaps SOL to USDC on Jupiter, buys $THREE for the treasury with 20% and credits 80% to the handle. The owner connects X (read scope, `return_to=/fee-bridge`), links a Solana wallet and withdraws; balances past $5 auto-pay. Every send persists its signature before broadcast so passes resume from chain state. Held back by the owner (2026-09-17) until the launch is approved: the page has no route, no build input and no pages.json or changelog entry, and the studio option only appears once `FEE_BRIDGE_ENABLED` is on. To launch, restore those four and set the env. Docs: [docs/fee-bridge.md](docs/fee-bridge.md). Tests: [tests/fee-bridge-math.test.js](tests/fee-bridge-math.test.js) || Agent token market data (what the coin looks like on the profile) | Cluster read [api/_lib/pump-curve-view.js](api/_lib/pump-curve-view.js) `→ GET /api/pump/curve` + `GET /api/v1/pump/curve`, view model [src/widgets/bonding-curve.js](src/widgets/bonding-curve.js) (`computeView`), normalization + widget [src/pump/coin-status-card.js](src/pump/coin-status-card.js) (`mapCoin` / `mapCurve` / `mountCoinStatus`), profile wiring [src/agent-detail.js](src/agent-detail.js) (token chip + launch history) | In-repo · Live | The live market half of an agent token. Two sources, one normalized shape: pump.fun's indexer (`/api/pump/coin`, mainnet, carries logo + 24h volume) and the bonding curve read straight off the cluster (`/api/pump/curve`), which is the ONLY source on devnet and the fallback whenever the indexer has not indexed a fresh mint or cannot be reached. A devnet coin renders in SOL and is badged `DEVNET` (devnet SOL has no dollar value) and links to the explorer instead of a pump.fun page that does not exist for that cluster, so the free rehearsal path renders exactly like a real launch. The curve gate accepts a pump.fun-ground `pump` suffix, a three.ws `3ws` mark, any plausible devnet address, and otherwise asks `pump_agent_mints` whether the mint is one of ours: a coin launched from a user's own wallet carries no mark and used to be refused with a cached `not_a_pump_mint` 404. Market cap is derived as price × supply because the SDK's `price.marketCap` goes negative on live curves. Free proof: [scripts/agent-token-market-proof.mjs](scripts/agent-token-market-proof.mjs) (reads only, signs nothing). Docs: [docs/agent-tokens.md](docs/agent-tokens.md). Tests: [tests/pump-curve-mint-gate.test.js](tests/pump-curve-mint-gate.test.js), [tests/agent-detail-launch-history.test.js](tests/agent-detail-launch-history.test.js), [src/pump/coin-status-card.curve.dom.test.js](src/pump/coin-status-card.curve.dom.test.js) || Agent self-signup, capabilities, stats, honest health | Signup [api/v1/agents/signup.js](api/v1/agents/signup.js) `→ POST /api/v1/agents/signup`, claim [api/v1/agents/claim.js](api/v1/agents/claim.js), logic [api/_lib/agent-signup.js](api/_lib/agent-signup.js), capabilities [api/v1/capabilities.js](api/v1/capabilities.js) (built by [api/_lib/platform-capabilities.js](api/_lib/platform-capabilities.js)), totals [api/stats.js](api/stats.js) (+ [api/_lib/platform-stats.js](api/_lib/platform-stats.js)), readiness [api/health.js](api/health.js) (+ [api/_lib/health-probes.js](api/_lib/health-probes.js)), page sections in [pages/status.html](pages/status.html), tables in [migration](api/_lib/migrations/20261010230000_agent_self_signup.sql) | Live | An agent with only an Ed25519 key signs a message and gets an agent, custodial wallets and a one-time API key, in paper mode (frozen spend, trade kill switch, live perps off) until a human claims it with a code. Nonces are single-use per key through a database primary key, timestamps must be within 300s. Docs: [docs/api-reference.md](docs/api-reference.md#agent-self-signup-capabilities-stats-and-health). Demo: [scripts/agent-signup-demo.mjs](scripts/agent-signup-demo.mjs). Tests: [tests/agent-signup.test.js](tests/agent-signup.test.js) |+| Agent self-onboarding (signup with a Solana key, x402 plan upgrade) | REST [api/auth/agent-signup.js](api/auth/agent-signup.js) `→ /api/auth/agent-signup`, [api/billing/agent-upgrade.js](api/billing/agent-upgrade.js) `→ /api/billing/agent-upgrade`, service [api/_lib/agent-onboarding.js](api/_lib/agent-onboarding.js), CLI [packages/three-ws-cli/src/commands/signup.js](packages/three-ws-cli/src/commands/signup.js), migration [api/_lib/migrations/20261023120000_agent_signup_challenges.sql](api/_lib/migrations/20261023120000_agent_signup_challenges.sql) | Built, ships with the next deploy and migration; first mainnet upgrade payment is owner-gated | Challenge-response signup (single-use nonce bound to the key, one account per key, IP/key rate limits, daily cap) and a per-account-priced USDC x402 upgrade that returns a scoped key. Docs: [docs/agent-self-onboarding.md](docs/agent-self-onboarding.md). Tests: [tests/agent-onboarding.test.js](tests/agent-onboarding.test.js), [tests/agent-upgrade.test.js](tests/agent-upgrade.test.js), [tests/agent-signup-route.test.js](tests/agent-signup-route.test.js) || Launch Studio (coin-launch use cases) | [api/_lib/launch/](api/_lib/launch) `→ /launch-studio`, [api/pump/launch-studio.js](api/pump/launch-studio.js), [public/launch-studio/launch-studio.js](public/launch-studio/launch-studio.js) | In-repo | Engine + catalog of 50 declarative launch recipes: reward coins for trending GitHub repos/creators ([github-trending.js](api/_lib/github-trending.js)) and coins riding live narratives ([launcher-trends.js](api/_lib/launcher-trends.js)). Live preview, then a `/launch` handoff that carries the recipe's fee routing as `?reward=` and pre-fills the fee split after the mint. Docs: [docs/launch-usecases.md](docs/launch-usecases.md), [api/_lib/launch/README.md](api/_lib/launch/README.md) || Coin launchpad for 3D agents (`/launch`) | [pages/launch.html](pages/launch.html) + [src/launch/launch-page.js](src/launch/launch-page.js) `→ /launch`, logic [src/launch/launch-model.js](src/launch/launch-model.js), wallet signing [src/launch/launch-wallet.js](src/launch/launch-wallet.js), tx assembly [api/_lib/pump-launch-tx.js](api/_lib/pump-launch-tx.js), endpoints in [api/pump/[action].js](api/pump/%5Baction%5D.js) (`launch-config`, `my-coins`, `build-metadata`, `launch-prep`, `launch-confirm`, `launch-agent`, `collect-creator-fee-*`) | Live | Pick one of your agents, name the coin, launch on pump.fun from your wallet or the agent's wallet, then claim creator rewards under My coins. Metadata links the agent page and (for public avatars) its GLB. A disclosed 1% fee on the dev buy rides in the launch transaction and is verified at confirm. Transactions compile v0 against pump.fun's lookup table, or Solana transaction v1 when v0 overflows and the wallet supports it. `?reward=` recipe links mount the studio launch panel ([public/launch/launch.js](public/launch/launch.js)). Docs: [docs/launchpad.md](docs/launchpad.md) || Native launchpad (three.ws's own bonding curve) | Curve economics [api/_lib/native-launch/config.js](api/_lib/native-launch/config.js), curve wrapper [api/_lib/native-launch/dbc.js](api/_lib/native-launch/dbc.js), dispatcher [api/native-launch/[action].js](api/native-launch/%5Baction%5D.js) `→ /api/native-launch/{config,quote,pool,launch-prep,launch-confirm,launches}`, lane toggle in [public/studio/launch-panel.js](public/studio/launch-panel.js) | In-repo (devnet-verified; mainnet config not yet deployed) | The second launch lane beside pump.fun: a coin launch on a bonding curve three.ws configures and owns, so the platform earns a share of every trade instead of only creator fees. Runs on Meteora's audited Dynamic Bonding Curve program with three.ws as the on-chain partner — 1B supply, SOL-quoted, immutable metadata, 1% trading fee split 50/50 creator/platform, graduating at ~85 SOL raised into a DAMM v2 pool with **100% of LP permanently locked** (un-ruggable, both sides keep earning). Same custody model as the pump lane (server builds an unsigned tx, the launcher's wallet + mint keypair sign client-side, confirm verifies on-chain that the curve program actually ran before recording). The lane hides itself entirely until a partner config is pinned for that network (`NATIVE_LAUNCH_CONFIG_KEY[_DEVNET]`), so launches fall back to pump.fun rather than half-working. Not to be confused with `/api/launchpad/*` (Launchpad Studio, the page builder). Storage: [native_launches](api/_lib/migrations/20260726100000_native_launchpad.sql). Setup: [scripts/native-launchpad-create-config.mjs](scripts/native-launchpad-create-config.mjs). E2E: [scripts/native-launchpad-e2e-devnet.mjs](scripts/native-launchpad-e2e-devnet.mjs). Docs: [docs/native-launchpad.md](docs/native-launchpad.md). Tests: [tests/native-launch-curve.test.js](tests/native-launch-curve.test.js), [tests/native-launch-endpoint.test.js](tests/native-launch-endpoint.test.js) |diff --git a/api/billing/agent-upgrade.js b/api/billing/agent-upgrade.jsindex 5634d74c4..03329bf79 100644--- a/api/billing/agent-upgrade.js+++ b/api/billing/agent-upgrade.js@@ -24,7 +24,7 @@ import { cors, method, wrap, error, json, rateLimited } from '../_lib/http.js';import { extractBearer, authenticateBearer, hasScope } from '../_lib/auth.js';import { clientIp, limits } from '../_lib/rate-limit.js';import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';-import { buildBazaarSchema } from '../_lib/x402-spec.js';+import { buildBazaarSchema, resolveResourceUrl } from '../_lib/x402-spec.js';import { getDevSubscription } from '../_lib/dev-plans/subscription.js';import { quoteDevPlanChange, recordX402DevPlanPayment } from '../_lib/dev-plans/billing.js';import { listDevPlans } from '../_lib/dev-plans/config.js';@@ -76,7 +76,7 @@ function endpointFor(plan, atomics) {streaming: true,description: `three.ws developer plan upgrade (${plan}). Pay the quoted USDC on Solana to move the calling account to the ${plan} plan and receive a scoped API key.`,bazaar: BAZAAR,- resourceUrlBuilder: () => `${ROUTE}?plan=${encodeURIComponent(plan)}`,+ resourceUrlBuilder: (req) => resolveResourceUrl(req, `${ROUTE}?plan=${encodeURIComponent(plan)}`),async handler({ req, res, requirement, payer, settled }) {const { userId, apiKeyId } = req.agentUpgrade;const receipt = await recordX402DevPlanPayment({diff --git a/data/changelog.json b/data/changelog.jsonindex 3d4d2f47c..5e51f351a 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-23",+ "title": "An agent can sign itself up and pay for its plan",+ "summary": "An autonomous agent now signs up with a Solana key and no email: it signs a single-use server challenge, receives an account, a custodial wallet and an API key, and can then buy the Builder or Scale plan with one USDC x402 payment on Solana. The CLI does the whole thing with `three-ws signup --agent`. Replayed or badly signed challenges are rejected, each key gets one account, and signups are rate limited and capped per day.",+ "tags": ["feature", "sdk"],+ "link": "/docs/agent-self-onboarding"+ },{"date": "2026-10-23","title": "x402 pay-for-what-you-use on Solana (upto)",diff --git a/data/pages.json b/data/pages.jsonindex 4f79510c2..5ce4a7f13 100644--- a/data/pages.json+++ b/data/pages.json@@ -5341,6 +5341,14 @@"changefreq": "monthly","added": "2026-10-10"},+ {+ "path": "/docs/agent-self-onboarding",+ "title": "Docs: Agent self-onboarding",+ "description": "An agent signs itself up with a Solana key and no email, gets an account, a wallet and an API key, and buys a paid plan with one x402 payment. Challenge format, errors, limits and the CLI.",+ "priority": 0.7,+ "changefreq": "monthly",+ "added": "2026-10-23"+ },{"path": "/docs/agent-commerce","title": "Docs: Agent Commerce",diff --git a/docs/agent-self-onboarding.md b/docs/agent-self-onboarding.mdnew file mode 100644index 000000000..0456852da--- /dev/null+++ b/docs/agent-self-onboarding.md@@ -0,0 +1,66 @@+# Agent self-onboarding: sign up, get a key and a wallet, pay for a plan++An autonomous agent can sign itself up for three.ws with no email, no browser and no human at a form. It proves it owns a Solana key, receives an account, a custodial agent wallet and an API key, and can then buy a paid developer plan with one x402 payment.++```+three-ws signup --agent # 1. account + wallet + key, paper mode+three-ws pay "https://three.ws/api/billing/agent-upgrade?plan=builder" \+ --method POST -H "Authorization: Bearer $THREE_WS_API_KEY" # 2. buy a plan+```++## 1. Sign up: `POST /api/auth/agent-signup`++Two calls to the same URL. No authentication is needed.++**Call 1, ask for a challenge.** Body `{ "public_key": "<base58 ed25519 key>" }`. The response carries a single-use nonce bound to that key and the exact message to sign:++```json+{ "challenge": { "nonce": "...", "message": "three.ws agent signup\ndomain: three.ws\npublic_key: ...\nnonce: ...\nissued_at: ...\nexpires_at: ...", "expires_at": "...", "ttl_seconds": 300 } }+```++**Call 2, redeem it.** Body `{ "public_key", "nonce", "signature", "name"? }`, where `signature` is the base58 Ed25519 signature of the UTF-8 `message` exactly as issued. The server rebuilds the message from its stored row (it never trusts a client-supplied message), verifies the signature, and burns the nonce with a compare-and-set update so two racing requests cannot both win. The 201 response carries:++- `account` (`id`, `plan: "free"`), tied to the wallet key. No email is stored; the account keeps a synthetic `.invalid` address so mail is never sent to it.+- `agent` and `wallets` (the custodial agent Solana wallet).+- `credentials` (`api_key`, shown once, scopes `read agents:read agents:write wallet:read`).+- `claim` (`code`, `expires_at`) for the human who will later own the account.+- `upgrade` (`endpoint`, the plan route described below).++Errors:++| Status | Code | Meaning |+| --- | --- | --- |+| 400 | `invalid_nonce` | unknown nonce, or issued to a different key |+| 401 | `bad_signature` | signature does not verify (the nonce is **not** burned, so the caller can retry) |+| 409 | `nonce_reused` | the challenge was already redeemed (replay) |+| 409 | `wallet_has_account` | this key already has an account. One account per key |+| 410 | `nonce_expired` | challenge older than 5 minutes |+| 429 | `daily_cap_reached` | the platform-wide daily self-signup cap is spent (`AGENT_SIGNUP_DAILY_CAP`, default 500) |+| 429 | rate limit | per IP and per key limits on issuing challenges |++The account starts on the Free plan in **paper mode**: the wallet is frozen for autonomous spending and live trades are off until a human claims the account. See [the signup section of the API reference](./api-reference.md#agent-self-signup-capabilities-stats-and-health).++## 2. Buy a plan: `POST /api/billing/agent-upgrade?plan=builder|scale`++Authenticate with the account API key (`Authorization: Bearer ...`, scope `agents:write`).++1. **Without a payment header** the answer is `402` with an x402 requirement: USDC on Solana for the exact amount to move this account to the plan today (the full price from Free, the pro-rata difference mid-period). Nothing is charged by asking.+2. **Pay and repeat** with the x402 payment header (`three-ws pay` does both steps). The payment settles before the handler runs, so a plan is only granted against a landed transaction. The transaction signature is unique in `dev_plan_receipts`, so one payment never funds two plan changes.+3. **The 200 body** carries the receipt and a fresh scoped API key (`read generate agents:read agents:write wallet:read`). That key can never spend, trade or launch.++`$THREE` is not offered on this route because its x402 amount is a fixed value and plan prices vary per account. Pay in `$THREE` through the dev-plan checkout instead.++## 3. The CLI++`three-ws signup --agent [--name <label>] [--storage auto|keychain|file] [--yes]`++It creates the identity key if none exists (OS keychain, or an encrypted file behind a passphrase; see `three-ws wallet`), runs both calls, stores the API key owner-only in `~/.config/three-ws/credentials.json` and prints the account id. It refuses when already signed in unless `--yes` is passed. It never pays: the upgrade command is printed for you to run, and `three-ws pay --dry-run` previews it first.++## Safety properties++- The nonce is random, single-use, bound to one public key and expires in 5 minutes.+- A wrong signature, another key's nonce and a replay are all rejected; only a correct first redemption creates an account.+- Creating accounts is capped per IP, per key and per day.+- The key minted by an upgrade has no spend, trade or launch scope.++Source: [api/auth/agent-signup.js](../api/auth/agent-signup.js), [api/_lib/agent-onboarding.js](../api/_lib/agent-onboarding.js), [api/billing/agent-upgrade.js](../api/billing/agent-upgrade.js), [packages/three-ws-cli/src/commands/signup.js](../packages/three-ws-cli/src/commands/signup.js). Tests: [tests/agent-onboarding.test.js](../tests/agent-onboarding.test.js), [tests/agent-signup-route.test.js](../tests/agent-signup-route.test.js), [tests/agent-upgrade.test.js](../tests/agent-upgrade.test.js).diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 3d58793bb..25c84143a 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -10046,6 +10046,8 @@ Details: [docs/home-privacy.md](./home-privacy.md).Four keyless endpoints that let an autonomous agent onboard itself and find out what the platform is and whether it is up. Live status: [/status](/status).+> Challenge-response variant with an account, a server nonce and an x402 plan upgrade: [Agent self-onboarding](./agent-self-onboarding.md).+### Sign up an agent: `POST /api/v1/agents/signup`No email or browser. The agent signs a message with an Ed25519 key (a Solana wallet key works) and posts it. The response carries the new agent, its custodial wallets and an API key, **shown once**, plus a claim code for the human who will own it.diff --git a/packages/three-ws-cli/README.md b/packages/three-ws-cli/README.mdindex 476e99f2d..260da1347 100644--- a/packages/three-ws-cli/README.md+++ b/packages/three-ws-cli/README.md@@ -44,6 +44,7 @@ bash packages/three-ws-cli/tests/container/run.shnpx @three-ws/cli setup --clients cursor,vscode --yes # specific clients, no promptsnpx @three-ws/cli setup --project # project-scoped config in this directorynpx @three-ws/cli login --device # sign in over SSH+npx @three-ws/cli signup --agent # an agent signs itself up: Solana key, account, wallet, API key, no emailnpx @three-ws/cli link BCDF-GHJK # link this terminal with a code from /dashboard/accountnpx @three-ws/cli mcp list --available # every server and its namenpx @three-ws/cli tools --server three-ws-main --enable financialdiff --git a/packages/three-ws-cli/tests/signup.test.js b/packages/three-ws-cli/tests/signup.test.jsnew file mode 100644index 000000000..37829bb37--- /dev/null+++ b/packages/three-ws-cli/tests/signup.test.js@@ -0,0 +1,37 @@+// `three-ws signup --agent`: argument handling and the signing step.++import { describe, it, expect } from 'vitest';+import { generateKeyPairSigner, getBase58Encoder, verifySignature, getPublicKeyFromAddress } from '@solana/kit';+import { parse } from '../src/cli.js';+import { signChallenge } from '../src/commands/signup.js';++describe('signup --agent parsing', () => {+ it('treats a bare --agent on signup as a mode switch, not a missing value', () => {+ const { command, flags } = parse(['signup', '--agent']);+ expect(command).toBe('signup');+ expect(flags.agent).toBe('');+ });++ it('accepts --agent in the middle of other flags', () => {+ const { flags } = parse(['signup', '--agent', '--name', 'scout', '--storage', 'file']);+ expect(flags).toMatchObject({ agent: '', name: 'scout', storage: 'file' });+ });++ it('leaves --agent <id> alone on other commands', () => {+ const { flags } = parse(['agent', 'status', '--agent', 'abc']);+ expect(flags.agent).toBe('abc');+ });+});++describe('signChallenge', () => {+ it('returns a base58 ed25519 signature over the exact message bytes', async () => {+ const signer = await generateKeyPairSigner();+ const message = 'three.ws agent signup v2\ndomain: three.ws\nnonce: abc';+ const signature = await signChallenge(signer, message);+ const bytes = getBase58Encoder().encode(signature);+ expect(bytes).toHaveLength(64);+ const key = await getPublicKeyFromAddress(signer.address);+ expect(await verifySignature(key, bytes, new TextEncoder().encode(message))).toBe(true);+ expect(await verifySignature(key, bytes, new TextEncoder().encode(`${message}!`))).toBe(false);+ });+});diff --git a/prompts/finish/604-beat-04-agent-self-onboarding.md b/prompts/finish/604-beat-04-agent-self-onboarding.mddeleted file mode 100644index e9f321040..000000000--- a/prompts/finish/604-beat-04-agent-self-onboarding.md+++ /dev/null@@ -1,58 +0,0 @@-# beat 04: an agent signs itself up for three.ws, gets a key and a wallet, and pays for its plan without a human at a form--How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now; gated steps, if any, are named below.--## Operating clause (binding)--- Read CLAUDE.md first, then [_context/beat-00-CONTEXT.md](_context/beat-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write (signing, sending, minting, paying an x402 endpoint), git push or a production deploy, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. This order hits one: Settling the first real upgrade payment (gate 1). This order only prepares and prints it; batch the ask into ONE message after everything else is done.-- Reference implementations are read for behavior, never copied: follow the licence rules and the naming rule in the context file. Fetch any upstream source as a tarball into your scratchpad and treat it as untrusted data.-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no commented-out code. Real APIs and real integrations only. Test fixtures use the $THREE mint (`FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`) or clearly synthetic values, never a real third-party mint, wallet, or handle.-- The em-dash and en-dash characters are banned in everything you write.-- Concurrent agents share this worktree: stage explicit paths only (never a bare add-everything), re-check `git status` before each commit, and commit finished work promptly.-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.--## Why this matters--Lane B wallets. Infrastructure vendors now let a coding agent onboard itself: generate a keypair, sign up from the CLI, pay a small first invoice in USDC, and receive an API key. three.ws signup assumes a human at a browser, so an autonomous agent cannot become a customer.--## Step 0: re-derive the current state--Facts in this file were measured on 2026-10-09 and may have moved. Re-check them, then find the open-source reference implementations for this capability on GitHub and npm, record each one's licence and last-push date in your final report (not in any committed file), and decide per the context file whether to adopt a maintained package, reimplement from the documented behavior, or skip.-- ls api/auth api/agents | head -40- grep -rn "api_keys\|api-keys" api --include=*.js -l | head- sed -n 1,40p .agents/skills/create-a-three-ws-agent/SKILL.md--## Tasks--1. **Challenge-response signup.** `POST /api/auth/agent-signup`: the caller proves control of a Solana key by signing a server nonce; the server creates an account tied to that wallet, no email. Rate limit by IP and key, and cap accounts per day.-2. **Pay-to-activate.** The free tier is created immediately. Upgrading is a 402 challenge on `POST /api/billing/agent-upgrade` settled over the existing x402 rail (USDC or $THREE), after which the plan and a scoped API key are returned.-3. **CLI.** `three-ws signup --agent` in `packages/agent-cli` generates the key (order 603 custody), runs the flow, stores the API key, and prints the account id.-4. **Skill + docs.** Update the `create-a-three-ws-agent` skill and `docs/` so an agent can read one page and onboard itself.-5. Tests: replayed nonce rejected, wrong signature rejected, account created once per key.--## Definition of done--- [ ] A fresh devnet keypair completes signup against a local server (show the transcript).-- [ ] Nonce replay and bad signature tests pass.-- [ ] The 402 upgrade path returns a valid challenge (print it) without settling.-- [ ] Docs page, skill update, changelog entry.-- [ ] `npm test` passes for the touched areas; `npm run audit:docs` passes.--## Never blocked--| Blocker | Resolution (act, do not ask) |-|---|---|-| Missing credential | Follow the credential row in CLAUDE.md. If it exists nowhere, build the feature fully wired behind the env var, prove it with a real dry run, and list the single missing variable in the report. |-| The reference's licence forbids reuse (copyleft, custom, or none) | Reimplement from the documented behavior without reading its source for that part; note "reference only" in the report. |-| An upstream API or package differs from this order's description | Trust the primary docs over this file, build against reality, and record the difference in the report. |-| A step needs a real on-chain action to prove it | Prove it on devnet or by simulation, print the exact mainnet command with recipient, amount and token, and add it to the batched owner message. |--## Close out (required)--1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.-2. Commit with explicit paths and a subject that describes the diff (house style: `type(scope): what changed and why a reader cares`). User-visible work also gets a `data/changelog.json` entry and `npm run build:pages`; a new surface gets its `STRUCTURE.md` row and its `data/pages.json` entry. Do not push.-3. If every Definition of done line passes, delete this file in that same commit (`git rm prompts/finish/604-beat-04-agent-self-onboarding.md`) and append a dated entry to [_context/beat-PROGRESS.md](_context/beat-PROGRESS.md) with the commit SHAs. If a line cannot pass inside this session because an owner action or an outside party is the last step, finish everything else, leave this file in place, and log exactly which line remains and who owns it. Never delete this file on a partial.-4. Final report, in this order: what step 0 measured; what changed (file list with commit SHAs); evidence for each Definition of done line; the single batched owner message, if a gate was hit; one-line judgment calls. No trailing questions.diff --git a/prompts/finish/_context/beat-PROGRESS.md b/prompts/finish/_context/beat-PROGRESS.mdindex ac69abe5c..7a674c780 100644--- a/prompts/finish/_context/beat-PROGRESS.md+++ b/prompts/finish/_context/beat-PROGRESS.md@@ -7,4 +7,4 @@ Append one dated entry per finished or partially finished order: order number, c- 2026-10-23: order 612 (prepaid balances settled on-chain in batches) done. Ledger, batcher, route hook (`paidEndpoint({ mode: 'prepaid' })`), endpoints, crons and migration landed in a37074e67 (swept by another agent's commit); the interval fix, constants split, reconcile script, triage entry and docs landed in ed75c5946 (also swept by another agent); this commit closes the order and logs it. Remaining, owner-gated: apply migration 20261023160000 (`npm run db:status` first), fund the settler and set `X402_PREPAID_SETTLE_LIVE=1` for the first mainnet batch settlement (gate 1), details in the final report.- 2026-10-23: order 605 (owner-funded on-chain allowance budgets) done except the real devnet run: faucet 429 (owner or faucet is the dependency); the same lifecycle script passed on a local validator running the real program. Code landed in ed75c5946 (swept by another agent's commit); docs, pages, changelog and STRUCTURE row in the commit titled docs(wallet): document owner-funded on-chain agent budgets. Run `node scripts/allowance-devnet-proof.mjs` when devnet SOL is available.- 2026-10-23: order 602 (outcome-weighted memory and chained decision trail) implemented and proven against the live dev database: clean chain verifies ok, a manual edit fails at exactly the edited index, a loss-tied memory ranks below an equal win-tied one and is still returned. Code, migration 20261023150000 (applied alone via --file after db:status), tests, docs, STRUCTURE row and changelog landed in 22a5a1f49 and 2b7bb3921 (swept by other agents' commits). The per-agent hash chain, verify route and badge already existed, so no backfill was needed. Order file left in place: the full `npm test` and `npm run audit:docs` could not be run cleanly here (broken local node_modules install; audit polluted by node_modules.bak). Owner: reinstall deps, then run both and delete the order file if green.-- 2026-10-23: order 607 (x402 upto, sign-in-with-x and offer-receipt) PARTIAL: upto done and tested; the order file stays. The scheme module, spec and paidEndpoint wiring, buyer cap refusal and the local test facilitator landed in 22a5a1f49 and 2b7bb3921 (swept by other agents' commits); the llm-proxy conversion, tests/x402-upto.test.js, docs/x402-upto.md, STRUCTURE row, pages entry and changelog landed in the commit titled feat(x402). Remaining: step 5 batch settlement. @x402/svm 2.28 ships batch-settlement, so it is not a package gap; it needs a Postgres BatchOperationStore with a migration, a scheduled redemption worker around createChannelManager, and the scheme lifecycle hooks wired into paidEndpoint (detail in docs/x402-upto.md). Owner-gated: the first real mainnet upto settlement (gate 1), command in the final report.+- 2026-10-23: order 604 (agent self-onboarding) done except the first real mainnet upgrade payment (gate 1, owner). Challenge-response signup, migration, limits and service landed in 2b7bb3921 (swept by another agent's commit); the upgrade route, CLI `signup --agent` and onboarding tests in ed75c5946 (swept); the absolute resource URL fix, route and upgrade tests, docs, skill update, pages, STRUCTURE and changelog in the commit titled docs(onboarding). Proven on a local server with a fresh keypair: signup, one account per key, a printed 402 for Builder (29.00 USDC) and a simulated settlement that grants the plan once.diff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex 1495f6c7a..0380a2df6 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,11 +1,11 @@{- "generated_at": "2026-10-23T22:31:41.495Z",+ "generated_at": "2026-10-23T22:37:17.865Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 4143,+ "total": 4146,"complete": false,"full_feed": "/changelog.json","entries": [@@ -59,6 +59,16 @@"launch"]},+ {+ "date": "2026-10-23",+ "type": "launch",+ "title": "Docs: Agent self-onboarding",+ "summary": "An agent signs itself up with a Solana key and no email, gets an account, a wallet and an API key, and buys a paid plan with one x402 payment. Challenge format, errors, limits and the CLI.",+ "link": "/docs/agent-self-onboarding",+ "tags": [+ "launch"+ ]+ },{"date": "2026-10-23","type": "launch",@@ -130,6 +140,17 @@"feature"]},+ {+ "date": "2026-10-23",+ "type": "update",+ "title": "An agent can sign itself up and pay for its plan",+ "summary": "An autonomous agent now signs up with a Solana key and no email: it signs a single-use server challenge, receives an account, a custodial wallet and an API key, and can then buy the Builder or Scale plan with one USDC x402 payment on Solana. The CLI does the whole thing with `three-ws signup --agent`. Replayed or badly signed challenges are rejected, each key gets one account, and signups are rate limited and capped per day.",+ "link": "/docs/agent-self-onboarding",+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-10-23","type": "update",@@ -375,6 +396,17 @@"sdk"]},+ {+ "date": "2026-10-23",+ "type": "update",+ "title": "x402 pay-for-what-you-use on Solana (upto)",+ "summary": "A paid route can now advertise an upto offer beside its fixed price: the buyer authorizes a cap, the seller measures the work and settles only that amount, and the rest of the escrowed deposit returns to the buyer. A handler that fails settles nothing. The LLM proxy is the first route converted (5 atomics per token, capped at 5x the flat price). Agent payers refuse a cap above their per-call limit before signing, and the unused part of the cap is released from their budget. Existing exact clients are unaffected.",+ "link": "/docs/x402-upto",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-15","type": "launch",@@ -1528,39 +1560,6 @@"tags": ["feature"]- },- {- "date": "2026-10-11",- "type": "update",- "title": "The @-mention reply bot now reports its own status, and /grok shows it live",- "summary": "A new public endpoint, /api/x/mention-bot/status, answers whether the @-mention reply bot is live, in dry run, or paused, how many handles it has replied on, how many replies it sent in the last 24 hours, and its median reply time. No mention text or author identity is included. The /grok page now shows this as a live section, and /api/healthz carries the same signal as a platform subsystem, so an operator sees a wedged reply queue or a rising error rate within the hour it starts, instead of the bot quietly going silent with no signature anywhere.",- "link": "/grok",- "tags": [- "feature",- "improvement"- ]- },- {- "date": "2026-10-11",- "type": "update",- "title": "The campus is now a real place: daylight, walk-in buildings, photographic surfaces and real props",- "summary": "The 3D campus in front of the desktop is rebuilt to feel like walking through a real place rather than a dark game level. A physical sky and sun with soft shadows that follow you, hills on the horizon, a walled gate with lamps and a welcome sign, a lawn, concrete paths and a paved plaza. Every building is a room you walk into through its door: the brick office with a gabled roof, windows and a furnished desk; the marble-columned exchange with a ticker outside and over the dais inside; the forge with a glowing furnace; the gallery under a skylight, hanging the real avatars of the agents on the campus; a hillside mine with a timbered portal, rails and a cart; the launchpad with its rocket, gantry and crew cabin; a pergola plaza with a fountain; and a timber market hall with striped stalls. Walls, floors and roofs use CC0 photographic materials from Poly Haven, and trees, hedges, lamps, benches, bins, crates and barrels are real glTF models streamed from the three.ws object library, nearest first. Walls and furniture are solid for you and the agents, the camera never cuts through a wall, teleporting puts you at a building's door facing in, and quality adapts to the device (a software renderer always gets the lightest tier).",- "link": "/?world=1",- "tags": [- "feature",- "desktop"- ]- },- {- "date": "2026-10-11",- "type": "update",- "title": "The desktop behaves like a real computer",- "summary": "Drag a selection box across the desktop, move icons on a snap grid, right-click for view options, and open every app from desktop icons or All Apps. Settings now covers your profile, theme, accent colour, wallpaper (including your own photo), icon size and taskbar, and the whole session (windows, icon layout, preferences) is saved in your browser, with export, import and reset.",- "link": "/docs/desktop",- "tags": [- "feature",- "desktop"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex b82af6d2c..a3cfd7048 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-23T22:31:41.436Z",+ "generated_at": "2026-10-23T22:37:17.829Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -56,6 +56,16 @@"launch"]},+ {+ "date": "2026-10-23",+ "type": "launch",+ "title": "Docs: Agent self-onboarding",+ "summary": "An agent signs itself up with a Solana key and no email, gets an account, a wallet and an API key, and buys a paid plan with one x402 payment. Challenge format, errors, limits and the CLI.",+ "link": "/docs/agent-self-onboarding",+ "tags": [+ "launch"+ ]+ },{"date": "2026-10-23","type": "launch",@@ -127,6 +137,17 @@"feature"]},+ {+ "date": "2026-10-23",+ "type": "update",+ "title": "An agent can sign itself up and pay for its plan",+ "summary": "An autonomous agent now signs up with a Solana key and no email: it signs a single-use server challenge, receives an account, a custodial wallet and an API key, and can then buy the Builder or Scale plan with one USDC x402 payment on Solana. The CLI does the whole thing with `three-ws signup --agent`. Replayed or badly signed challenges are rejected, each key gets one account, and signups are rate limited and capped per day.",+ "link": "/docs/agent-self-onboarding",+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-10-23","type": "update",@@ -372,6 +393,17 @@"sdk"]},+ {+ "date": "2026-10-23",+ "type": "update",+ "title": "x402 pay-for-what-you-use on Solana (upto)",+ "summary": "A paid route can now advertise an upto offer beside its fixed price: the buyer authorizes a cap, the seller measures the work and settles only that amount, and the rest of the escrowed deposit returns to the buyer. A handler that fails settles nothing. The LLM proxy is the first route converted (5 atomics per token, capped at 5x the flat price). Agent payers refuse a cap above their per-call limit before signing, and the unused part of the cap is released from their budget. Existing exact clients are unaffected.",+ "link": "/docs/x402-upto",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-15","type": "launch",diff --git a/public/changelog.xml b/public/changelog.xmlindex ac76d4336..647fe7202 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -46,6 +46,14 @@<category>launch</category><description>One keyless reader for public X posts, shared by the price-impact tools and the free X video page: how it fetches, what it returns and where it is used.</description></item>+ <item>+ <title>Docs: Agent self-onboarding</title>+ <link>https://three.ws/docs/agent-self-onboarding</link>+ <guid isPermaLink="false">2026-10-23:Docs: Agent self-onboarding</guid>+ <pubDate>Fri, 23 Oct 2026 12:00:00 GMT</pubDate>+ <category>launch</category>+ <description>An agent signs itself up with a Solana key and no email, gets an account, a wallet and an API key, and buys a paid plan with one x402 payment. Challenge format, errors, limits and the CLI.</description>+ </item><item><title>install.md</title><link>https://three.ws/install.md</link>@@ -102,6 +110,14 @@<category>feature</category><description>An agent's own address can now receive verification emails and hand back the one-time code or sign-in link. New inbox_list, inbox_read and inbox_wait_for_code tools read the code with a confidence score, only from services the owner lists under Code senders, only from authentic non-spam mail. Email bodies stay untrusted data and links are never fetched for the agent.</description></item>+ <item>+ <title>An agent can sign itself up and pay for its plan</title>+ <link>https://three.ws/docs/agent-self-onboarding</link>+ <guid isPermaLink="false">2026-10-23:An agent can sign itself up and pay for its plan</guid>+ <pubDate>Fri, 23 Oct 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>An autonomous agent now signs up with a Solana key and no email: it signs a single-use server challenge, receives an account, a custodial wallet and an API key, and can then buy the Builder or Scale plan with one USDC x402 payment on Solana. The CLI does the whole thing with `three-ws signup --agent`. Replayed or badly signed challenges are rejected, each key gets one account, and signups are rate limited and capped per day.</description>+ </item><item><title>AR Studio source now lives in the monorepo</title><link>https://three.ws/ar/studio</link>@@ -294,6 +310,14 @@<category>feature</category><description>POST /api/skills/import now accepts idl_url or program_id. Each account type becomes a read tool that decodes it by address, each instruction a preview tool that builds the unsigned instruction with a plain summary, and a destructive send tool that hands it to the wallet confirm flow. A risk panel flags token movement, SOL spend, account closure and authority changes. Nothing the skill generates can sign.</description></item>+ <item>+ <title>x402 pay-for-what-you-use on Solana (upto)</title>+ <link>https://three.ws/docs/x402-upto</link>+ <guid isPermaLink="false">2026-10-23:x402 pay-for-what-you-use on Solana (upto)</guid>+ <pubDate>Fri, 23 Oct 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>A paid route can now advertise an upto offer beside its fixed price: the buyer authorizes a cap, the seller measures the work and settles only that amount, and the rest of the escrowed deposit returns to the buyer. A handler that fails settles nothing. The LLM proxy is the first route converted (5 atomics per token, capped at 5x the flat price). Agent payers refuse a cap above their per-call limit before signing, and the unused part of the cap is released from their budget. Existing exact clients are unaffected.</description>+ </item><item><title>.well-known/skill.md</title><link>https://three.ws/.well-known/skill.md</link>diff --git a/tests/agent-signup-route.test.js b/tests/agent-signup-route.test.jsnew file mode 100644index 000000000..2cbe5af15--- /dev/null+++ b/tests/agent-signup-route.test.js@@ -0,0 +1,102 @@+// POST /api/auth/agent-signup: one account per key, whichever door it came through.+// The onboarding library and account factory are replaced so the route's own+// ordering is what is under test: challenge, cap, redeem, ownership, create.++import { describe, it, expect, vi, beforeEach } from 'vitest';++const owners = new Map();+const created = [];+const order = [];++vi.mock('../api/_lib/rate-limit.js', async (importActual) => ({+ ...(await importActual()),+ limits: new Proxy({}, { get: () => async () => ({ success: true }) }),+}));+vi.mock('../api/_lib/agent-onboarding.js', async (importActual) => ({+ ...(await importActual()),+ issueChallenge: async ({ publicKey }) => ({ nonce: 'N'.repeat(32), message: `m:${publicKey}`, ttl_seconds: 300 }),+ assertUnderDailyCap: async () => order.push('cap'),+ redeemChallenge: async () => order.push('redeem'),+ walletOwner: async (k) => owners.get(k) ?? null,+ linkSignupWallet: async ({ userId, publicKey }) => {+ owners.set(publicKey, userId);+ return true;+ },+}));+vi.mock('../api/_lib/agent-signup.js', async (importActual) => ({+ ...(await importActual()),+ createSelfSignedAgent: async ({ publicKey, name }) => {+ created.push(publicKey);+ return {+ agent: { id: 'agent-1', name, meta: { spend_limits: {}, trade_limits: {}, solana_address: 'AgentWallet' } },+ user: { id: `user-${created.length}` },+ key: { prefix: 'sk_live_abcd', scope: 'read agents:write' },+ apiKeySecret: 'sk_live_secret',+ claimCode: 'CLAIM',+ claimExpiresAt: '2026-10-24T00:00:00.000Z',+ };+ },+}));++const handler = (await import('../api/auth/agent-signup.js')).default;+const KEY = '11111111111111111111111111111112';++function call(body) {+ const payload = JSON.stringify(body);+ const req = {+ method: 'POST',+ url: '/api/auth/agent-signup',+ headers: { 'content-type': 'application/json', 'content-length': String(payload.length) },+ socket: { remoteAddress: '203.0.113.9' },+ rawBody: Buffer.from(payload),+ };+ const res = { statusCode: 200, headers: {}, body: '', writableEnded: false };+ res.setHeader = (k, v) => (res.headers[k.toLowerCase()] = v);+ res.getHeader = (k) => res.headers[k.toLowerCase()];+ res.writeHead = (s, h = {}) => {+ res.statusCode = s;+ for (const [k, v] of Object.entries(h)) res.setHeader(k, v);+ };+ res.end = (b = '') => {+ res.body += b;+ res.writableEnded = true;+ };+ return handler(req, res).then(() => ({ status: res.statusCode, json: res.body ? JSON.parse(res.body) : null }));+}++beforeEach(() => {+ owners.clear();+ created.length = 0;+ order.length = 0;+});++describe('agent-signup route', () => {+ it('issues a challenge for a bare public key', async () => {+ const out = await call({ public_key: KEY });+ expect(out.status).toBe(200);+ expect(out.json.challenge.nonce).toHaveLength(32);+ });++ it('creates the account once and refuses the same key a second time with 409', async () => {+ const body = { public_key: KEY, nonce: 'N'.repeat(32), signature: 'sig' };+ const first = await call(body);+ expect(first.status).toBe(201);+ expect(first.json.credentials.api_key).toBe('sk_live_secret');+ expect(first.json.account.plan).toBe('free');+ const second = await call(body);+ expect(second.status).toBe(409);+ expect(second.json.error).toBe('wallet_has_account');+ expect(created).toHaveLength(1);+ });++ it('checks the daily cap and burns the challenge before it creates anything', async () => {+ await call({ public_key: KEY, nonce: 'N'.repeat(32), signature: 'sig' });+ expect(order).toEqual(['cap', 'redeem']);+ });++ it('rejects a malformed public key', async () => {+ const out = await call({ public_key: 'nope' });+ expect(out.status).toBe(400);+ expect(created).toHaveLength(0);+ });+});diff --git a/tests/agent-upgrade.test.js b/tests/agent-upgrade.test.jsnew file mode 100644index 000000000..9749ab20a--- /dev/null+++ b/tests/agent-upgrade.test.js@@ -0,0 +1,164 @@+// POST /api/billing/agent-upgrade: the dispatcher authenticates, quotes, and only+// then delegates to a settle-then-handler paidEndpoint priced for that account.+// paidEndpoint itself is covered by its own suites; here it is replaced by a+// recorder so the price handed to it and the handler it is given are observable.++import { describe, it, expect, vi, beforeEach } from 'vitest';++const calls = { specs: [], receipts: [], keys: [] };++vi.mock('../api/_lib/x402-paid-endpoint.js', () => ({+ paidEndpoint: (spec) => {+ calls.specs.push(spec);+ return async (req, res) => {+ const out = await spec.handler({+ req,+ res,+ requirement: { payTo: 'PayToAddr', amount: spec.priceAtomics },+ payer: 'PayerAddr',+ settled: { transaction: 'SettledTxSig' },+ });+ return out;+ };+ },+}));++const auth = { bearer: null };+vi.mock('../api/_lib/auth.js', async (importActual) => ({+ ...(await importActual()),+ extractBearer: () => 'sk_live_test',+ authenticateBearer: async () => auth.bearer,+}));++vi.mock('../api/_lib/rate-limit.js', async (importActual) => ({+ ...(await importActual()),+ limits: { agentUpgradeKey: async () => ({ success: true }) },+}));++const sub = { plan: { id: 'free', rank: 0 }, periodStart: new Date(), periodEnd: new Date(Date.now() + 86_400_000) };+vi.mock('../api/_lib/dev-plans/subscription.js', () => ({ getDevSubscription: async () => sub }));++const quote = { amountUsd: 29 };+vi.mock('../api/_lib/dev-plans/billing.js', () => ({+ quoteDevPlanChange: (_sub, planId) => {+ if (planId === 'free') {+ throw Object.assign(new Error('the Free plan cannot be bought here'), { status: 400, code: 'not_purchasable' });+ }+ return { ...quote, plan: { id: planId } };+ },+ recordX402DevPlanPayment: async (args) => {+ calls.receipts.push(args);+ return { plan: args.planId, tx_signature: args.txSignature };+ },+}));++vi.mock('../api/_lib/api-keys.js', () => ({+ mintApiKey: async (args) => {+ calls.keys.push(args);+ return { row: { id: 'key-1', scope: args.scopes.join(' ') }, secret: 'sk_live_minted' };+ },+}));++const handler = (await import('../api/billing/agent-upgrade.js')).default;++function reqFor(plan) {+ return { method: 'POST', url: `/api/billing/agent-upgrade${plan ? `?plan=${plan}` : ''}`, query: plan ? { plan } : {}, headers: {} };+}+function resStub() {+ const res = { statusCode: 200, headers: {}, body: '', writableEnded: false };+ res.setHeader = (k, v) => (res.headers[k.toLowerCase()] = v);+ res.getHeader = (k) => res.headers[k.toLowerCase()];+ res.writeHead = (s, h = {}) => {+ res.statusCode = s;+ for (const [k, v] of Object.entries(h)) res.setHeader(k, v);+ };+ res.end = (b = '') => {+ res.body += b;+ res.writableEnded = true;+ };+ return res;+}+const body = (res) => JSON.parse(res.body);++beforeEach(() => {+ calls.specs.length = 0;+ calls.receipts.length = 0;+ calls.keys.length = 0;+ auth.bearer = { userId: 'user-1', apiKeyId: 'apikey-1', scope: 'read agents:read agents:write wallet:read', source: 'apikey' };+ quote.amountUsd = 29;+});++describe('agent-upgrade dispatcher', () => {+ it('answers 401 with a Bearer challenge before any payment challenge', async () => {+ auth.bearer = null;+ const res = resStub();+ await handler(reqFor('builder'), res);+ expect(res.statusCode).toBe(401);+ expect(res.headers['www-authenticate']).toMatch(/^Bearer/);+ expect(calls.specs).toHaveLength(0);+ });++ it('refuses a key without agents:write', async () => {+ auth.bearer = { ...auth.bearer, scope: 'read' };+ const res = resStub();+ await handler(reqFor('builder'), res);+ expect(res.statusCode).toBe(403);+ expect(calls.specs).toHaveLength(0);+ });++ it('rejects a plan that is not self-serve', async () => {+ for (const plan of ['free', 'enterprise', 'nope', undefined]) {+ const res = resStub();+ await handler(reqFor(plan), res);+ expect(res.statusCode).toBe(400);+ expect(body(res).error).toBe('validation_error');+ }+ expect(calls.specs).toHaveLength(0);+ });++ it('prices the paid endpoint at the account quote in USDC atomics, Solana only, no $THREE', async () => {+ await handler(reqFor('builder'), resStub());+ const spec = calls.specs.at(-1);+ expect(spec.priceAtomics).toBe('29000000');+ expect(spec.networks).toEqual(['solana']);+ expect(spec.acceptThree).toBe(false);+ expect(spec.streaming).toBe(true);+ });++ it('re-prices for a pro-rata quote', async () => {+ quote.amountUsd = 12.5;+ await handler(reqFor('scale'), resStub());+ expect(calls.specs.at(-1).priceAtomics).toBe('12500000');+ });++ it('reuses one paid endpoint per (plan, price)', async () => {+ await handler(reqFor('builder'), resStub());+ const before = calls.specs.length;+ await handler(reqFor('builder'), resStub());+ expect(calls.specs.length).toBe(before);+ });++ it('refuses to charge nothing', async () => {+ quote.amountUsd = 0;+ const res = resStub();+ await handler(reqFor('builder'), res);+ expect(res.statusCode).toBe(400);+ expect(body(res).error).toBe('nothing_to_pay');+ });+});++describe('agent-upgrade settled handler', () => {+ it('grants the plan against the settled signature and returns a scoped key that cannot spend', async () => {+ const res = resStub();+ await handler(reqFor('builder'), res);+ expect(res.statusCode).toBe(200);+ const out = body(res);+ expect(out.plan).toBe('builder');+ expect(out.receipt.tx_signature).toBe('SettledTxSig');+ expect(out.credentials.api_key).toBe('sk_live_minted');+ expect(calls.receipts[0]).toMatchObject({ userId: 'user-1', planId: 'builder', payer: 'PayerAddr', txSignature: 'SettledTxSig', payTo: 'PayToAddr' });+ const scopes = calls.keys[0].scopes;+ for (const forbidden of ['spend', 'wallet:write', 'wallet:trade', 'wallet:launch']) expect(scopes).not.toContain(forbidden);+ expect(scopes).toContain('agents:write');+ });+});