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(money): update the agent wallet API, money map and LLM lanes docs

nirholas677cd7639ccc
diff --git a/docs/agent-wallet-api.md b/docs/agent-wallet-api.md
index 5d17f1cb2..d325f88fa 100644
--- a/docs/agent-wallet-api.md
+++ b/docs/agent-wallet-api.md
@@ -17,7 +17,7 @@ All eight surfaces address the same custodial Solana keypair, obey the same owne
| Surface | Route root | What it controls |
|---|---|---|
| Capabilities | `/api/agents/:id/capabilities` | Scoped, time-boxed, revocable session keys for autonomous spend |
-| Orders | `/api/agents/:id/orders` | The programmable order engine (limit, stop, trailing, DCA, TWAP, conditional) |
+| Orders | `/api/agents/:id/orders` | The programmable order engine (limit, stop, trailing, ratcheting stop, DCA, TWAP, conditional) |
| Intents | `/api/agents/:id/intents` | Plain-language wallet rules compiled into structured, armed intents |
| Treasury Autopilot | `/api/agents/:id/autopilot` | The self-funding treasury policy and its runway view |
| Portfolio | `/api/agents/:id/portfolio` | FIFO cost basis, realized and unrealized P&L by source, live risk metrics |
@@ -306,6 +306,7 @@ Reads are owner-gated. `POST`, `PUT`, and `DELETE` are additionally CSRF-gated.
| `limit` | A buy at or below the target, a sell at or above it |
| `stop` | A buy once the level breaks upward, a sell once it breaks downward |
| `trailing` | A sell after `trail_pct` off the high-water mark, a buy after `trail_pct` off the low |
+| `trail_ratchet` | A sell-only two-phase stop: sells if the metric falls `ratchet.initial_stop_pct` below the entry, then lock tiers raise the floor as profit grows and it never moves down |
| `dca` | On a fixed interval, `slices` times |
| `twap` | One total order sliced over time to cut price impact |
| `conditional` | A validated signal condition becomes true |
@@ -314,7 +315,7 @@ Shared fields: `type`, `side` (`buy` or `sell`), `mint` (validated Solana addres
Sizing: a buy needs `size_sol`; a sell needs either `size_tokens` (raw base units) or `sell_pct` (over 0 through 100). A TWAP buy takes `total_sol` and derives the per-slice size; a TWAP sell takes `total_tokens` or `sell_pct` and divides it across the slices.
-Per-type fields: `limit_price` for `limit`, `stop_price` for `stop`, `trail_pct` (over 0, under 100) for `trailing`, `schedule: { interval_seconds, slices }` for `dca` (minimum 60 seconds, 1 slice) and `twap` (minimum 30 seconds, 2 slices, maximum 1000 slices), and `condition` for `conditional`.
+Per-type fields: `limit_price` for `limit`, `stop_price` for `stop`, `trail_pct` (over 0, under 100) for `trailing`, `ratchet: { initial_stop_pct, tiers }` for `trail_ratchet` (sell only; `initial_stop_pct` over 0 and under 100, 1 through 8 tiers of `{ profit_pct, lock_pct }`, both strictly ascending, each `lock_pct` below its `profit_pct` and at least `-initial_stop_pct`; optional `entry_price` in the trigger metric, otherwise the first live reading the sweep takes), `schedule: { interval_seconds, slices }` for `dca` (minimum 60 seconds, 1 slice) and `twap` (minimum 30 seconds, 2 slices, maximum 1000 slices), and `condition` for `conditional`.
A condition is one level deep, with no expressions and no code: `{ "all": [leaf, …] }` or `{ "any": [leaf, …] }`, at most 8 leaves. Each leaf is `{ signal, op, value }`. The closed signal set is `price_sol`, `mcap_sol`, `mcap_usd`, `price_change_pct`, `smart_money_score` (numeric, operators `gt`, `gte`, `lt`, `lte`, `eq`, `ne`), plus `dev_dump` and `graduated` (boolean, operators `is_true`, `is_false`). A signal the worker cannot read is treated as indeterminate: it never counts as satisfied and is reported in `missing`, so an order cannot fire on absent data.
@@ -338,6 +339,7 @@ A condition is one level deep, with no expressions and no code: `{ "all": [leaf,
"limit_price": 40000,
"stop_price": null,
"trail_pct": null,
+ "ratchet": null,
"peak_price": null,
"reference_price": null,
"schedule": null,
@@ -376,7 +378,7 @@ A condition is one level deep, with no expressions and no code: `{ "all": [leaf,
A live order trades from the agent wallet on its own when it fires, so this route requires a signed real-funds agreement: an unsigned account gets `403 risk_ack_required` and no order is created.
-Returns `201` with `{ "data": { "order": … } }`. Validation failures are `422` and carry the specific code from the normalizer: `invalid_order`, `invalid_type`, `invalid_side`, `invalid_mint`, `invalid_size`, `invalid_price`, `invalid_trail`, `invalid_schedule`, `invalid_expiry`, or `invalid_condition`, each with a human-readable `error_description`. A malformed body is `400 bad_request`, a wrong content type is `415`, and a database failure is `500 create_failed`.
+Returns `201` with `{ "data": { "order": … } }`. Validation failures are `422` and carry the specific code from the normalizer: `invalid_order`, `invalid_type`, `invalid_side`, `invalid_mint`, `invalid_size`, `invalid_price`, `invalid_trail`, `invalid_ratchet`, `invalid_schedule`, `invalid_expiry`, or `invalid_condition`, each with a human-readable `error_description`. A malformed body is `400 bad_request`, a wrong content type is `415`, and a database failure is `500 create_failed`.
DCA and TWAP orders are created with `next_fire_at` set to now, so the first slice fires on the next worker sweep.
@@ -437,7 +439,7 @@ A valid order returns the normalized spec, its readback, a live market snapshot,
}
```
-Three honest nulls to expect. `preview.current` is `null` when the quote lane misses, and the endpoint still succeeds. `would_fire_now` is always `false` for a trailing order, because a trail needs a tracked high or low-water mark that does not exist until the order is live. `firewall` is `null` for sells, for a wallet with no Solana address, and when the on-chain simulation cannot be run.
+Three honest nulls to expect. `preview.current` is `null` when the quote lane misses, and the endpoint still succeeds. `would_fire_now` is always `false` for a trailing order, because a trail needs a tracked high or low-water mark that does not exist until the order is live. A `trail_ratchet` preview is evaluated against its entry (`entry_price`, else the current reading), so it reports `false` unless the price is already through the initial stop. `firewall` is `null` for sells, for a wallet with no Solana address, and when the on-chain simulation cannot be run.
### POST /orders/cancel-all
@@ -449,7 +451,7 @@ No body. Cancels every order in `active`, `partial`, `firing`, or `paused` on th
### GET /orders/schema
-Returns `order_types`, `trigger_metrics`, `number_ops`, `bool_ops`, and `signals` (each signal as `{ kind, label }`). Build a client against this rather than hardcoding the vocabulary, since the endpoint and the worker import it from one module.
+Returns `order_types`, `reason_codes`, `trigger_metrics`, `number_ops`, `bool_ops`, and `signals` (each signal as `{ kind, label }`). `reason_codes` maps the stable codes to their meaning: `DAILY_LOSS` (a fill refused at the daily loss limit), `DRAWDOWN` (fell through the initial stop), `IMPACT` (price impact above the safety limit) and `TIER_LOCK` (fell back to a locked-in profit tier). They appear as `meta.reason_code` on order events, as a `[CODE]` prefix on skip details, in the agent's decision trail and as a chip in the wallet hub Orders tab. Codes are never renamed. Build a client against this rather than hardcoding the vocabulary, since the endpoint and the worker import it from one module.
### GET /orders/:orderId
diff --git a/docs/money-map.md b/docs/money-map.md
index d41dca222..913ba081e 100644
--- a/docs/money-map.md
+++ b/docs/money-map.md
@@ -14,7 +14,7 @@ signer/funder wallets and how to fund them).
## 1. The wallets
-Money-routing is deliberately **config-driven** — no receiver is hardcoded, so an
+Money-routing is deliberately **config-driven** - no receiver is hardcoded, so an
unset receiver fails closed rather than silently routing real USDC to a baked-in
address (the `X402_PAY_TO_*` getters in [env.js](../api/_lib/env.js)).
@@ -24,6 +24,8 @@ address (the `X402_PAY_TO_*` getters in [env.js](../api/_lib/env.js)).
| `X402_PAY_TO_SOLANA` | Primary x402 receiver (all generic paid calls) | `wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU` |
| `X402_PAY_TO_BASE` | x402 receiver on Base (EVM) | `0x4022…f402` |
| `X402_PAY_TO_BSC` | x402 receiver on BSC | (config) |
+| `X402_PAY_TO_XLAYER` | x402 receiver on X Layer (OKX Agent Payments rail); unset means that accept is not advertised | (config) |
+| `X402_PREPAID_DEPOSIT_WALLET` | where buyers send a prepaid x402 deposit; unset falls back to the prepaid settler's own address (`X402_PREPAID_SETTLER_SECRET_BASE58`) | (config) |
| `X402_ASSET_MINT_SOLANA` | USDC mint accepted | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` (default constant) |
### $THREE split receivers (inbound $THREE)
@@ -34,14 +36,15 @@ to these two wallets by the buyer's own transaction. Both are **required in
production and fail closed**: unset, `/api/token/quote` answers `503
treasury_unavailable` and no purchase can be priced at all.
-| Env var | Role | Production state (2026-09-30) |
+| Env var | Role | Production state (2026-10-25) |
| ------- | ---- | ----------------------------- |
| `THREE_TREASURY_WALLET` | Platform cut of every split; the pot the buyback lane buys into | **Unset, awaiting the owner's address.** Candidate: `wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU` (the x402 receiver) |
| `THREE_REWARDS_WALLET` | Holder reflections pool, planned pro-rata by the `rewards-distribute` cron | **Unset, awaiting the owner's address.** Candidate: `WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW` (the economy master), with the conflict below |
| `THREE_QUOTE_SECRET` | HMAC key that seals a quote's amount, split and destinations | **Set.** Secret Manager `three-quote-secret` (48 random bytes, base64url), `three-ws@` has `secretAccessor`, wired as a secret reference since revision `three-ws-api-00466-85g` |
Neither wallet has ever been set on any `three-ws-api` revision (all 465 through
-2026-09-30 were checked), so there is no prior value to restore. Both candidates
+2026-09-30 were checked, and the live service env was re-read on 2026-10-25 with
+the same result), so there is no prior value to restore. Both candidates
are ordinary system-owned mainnet accounts that can hold $THREE: the x402
receiver already holds a $THREE token account, the economy master has none yet
and the buyer's transaction creates it (`src/token-pay.js` adds an idempotent
@@ -78,7 +81,7 @@ by the `three_token_rail` subsystem in `/api/healthz`.
No platform split routes to the burn sink. Supply is never destroyed; the
treasury funds buybacks instead ([token/config.js](../api/_lib/token/config.js)).
-### Payout treasuries (outbound — pay third parties out-of-band)
+### Payout treasuries (outbound - pay third parties out-of-band)
| Env var (secret) | Pays | Network |
| ---------------- | ---- | ------- |
| `CLUB_SOLANA_TREASURY_SECRET_KEY_B64` | dancers (tip sweep) + vanity-bounty fallback | Solana |
@@ -95,14 +98,14 @@ treasury funds buybacks instead ([token/config.js](../api/_lib/token/config.js))
### Signer / funder wallets
Every engine signs from its **own** keypair; a single **funding root** tops those
-signers up with SOL when they run low, and does nothing else. Documented in full —
-encodings, minimum balances, guards, funding tool — in the
+signers up with SOL when they run low, and does nothing else. Documented in full -
+encodings, minimum balances, guards, funding tool - in the
[Solana signers runbook](../api/_lib/solana-signers.js) and the
[economy master](economy-master.md) subsystem doc.
| Wallet | Role |
| ------ | ---- |
-| `WwwuGbqHrwF5…T3WwW` (capital `W`) | **Economy master / funding root** (`ECONOMY_MASTER_SECRET_BASE58`) — funder-only; never trades, tips, or settles. The `treasury-topup` cron refills every engine signer from it every 30 min, allowlist-guarded (can only pay a registry pubkey). |
+| `WwwuGbqHrwF5…T3WwW` (capital `W`) | **Economy master / funding root** (`ECONOMY_MASTER_SECRET_BASE58`) - funder-only; never trades, tips, or settles. The `treasury-topup` cron refills every engine signer from it every 30 min, allowlist-guarded (can only pay a registry pubkey). |
| `wwwww…ccrU` | x402 **receiver** (`X402_PAY_TO_SOLANA`) + closed-loop spender |
| `wwwqv…HGUn` | a funded **engine signer** wallet |
| `PLATFORM_TREASURY_KEYPAIR`, `LAUNCHER_MASTER_*`, `CIRCULATION_TREASURY_*`, … | per-engine signers, each its own keypair, funded by the master |
@@ -121,17 +124,19 @@ encodings, minimum balances, guards, funding tool — in the
| `dance-tip` | platform receiver → dancer | 0% net | swept by `club-payouts` from `CLUB_SOLANA_TREASURY_*` |
| `club-cover` | platform receiver (kept) | 100% | funds the club float; issues a door pass |
| `cosmetic-purchase` | platform receiver → split | 50% | creator 50% (≤90%) from `COSMETIC_SPLIT_TREASURY_*` |
-| marketplace skill sale | agent owner `payout_address` | 0–10% fee | atomic split; fee → fee wallet |
-| labor skill (escrow) | worker + author | author 10% royalty | paid from escrow ([labor-settle.js:97](../api/_lib/labor-settle.js#L97)) |
+| marketplace skill sale | agent owner `payout_address` | 0-10% fee | atomic split; fee → fee wallet |
+| labor skill (escrow) | worker + author | author 10% royalty | paid from escrow ([labor-settle.js:104](../api/_lib/labor-settle.js#L104)) |
| pump trade | counterparty | **1%** | fee transfer appended to the trader's own tx (SOL, or USDC on a USDC-paired coin) |
| coin launch dev buy (`/launch`) | the bonding curve | **1%** of the dev buy | fee transfer inside the launch tx; no dev buy, no fee |
| `pump-launch` | `X402_PAY_TO_SOLANA/BASE` | 100% of $5 | pump.fun creator rewards accrue on-chain to nominated wallet |
| `ring-settle` (internal) | `X402_PAY_TO_SOLANA` | 100% | recirculates (dogfood volume) |
-| $THREE purchase (Forge High, spin, scarcity mint) | `THREE_TREASURY_WALLET` + `THREE_REWARDS_WALLET` | 70-80% treasury | remainder reflects to holders; no seller leg |
+| $THREE purchase (Forge High, spin, scarcity mint) | `THREE_TREASURY_WALLET` + `THREE_REWARDS_WALLET` | 50-80% treasury (consumption 70%, spin 50%, scarcity mint 80%) | remainder reflects to holders; no seller leg |
| $THREE marketplace sale | seller + the two receivers above | 5% treasury | seller keeps 90%, 5% reflects to holders |
+| copy-trading performance fee | leader + the two receivers above | 15% treasury | leader keeps 80% of the fee, 5% reflects to holders (`copy_performance_fee` policy) |
+| claimed pump.fun creator fee (launcher claimer) | agent wallet, then creator payout | 50% buyback earmark | 50% to the creator's payout wallet; not an on-chain payment split (`CREATOR_FEE_CLAIM_POLICY`) |
| vanity bounty | worker | escrow-based | from `VANITY_BOUNTY_PAYOUT_KEY` (→ club treasury fallback) |
-Two mechanisms above are easy to confuse — see the [split explainer](x402-endpoints.md#where-payments-land):
+Two mechanisms above are easy to confuse - see the [split explainer](x402-endpoints.md#where-payments-land):
a **`payTo` override** settles USDC straight to a third party (skill-call, service,
asset/animation download, pay-by-name); a **post-settlement split** lands the USDC
in the platform receiver first, then a separate treasury forwards a share
@@ -148,8 +153,8 @@ in the platform receiver first, then a separate treasury forwards a share
| Marketplace platform fee | platform cut | `MARKETPLACE_PLATFORM_FEE_BPS` | **0%** (cap 10%) |
| Pump trade fee | platform cut | `PUMP_PLATFORM_FEE_BPS` | **1%** (cap 5%) |
| Coin launch fee | platform cut on the dev buy | `PUMP_LAUNCH_FEE_BPS` | **1%** (cap 5%) |
-| Club tip | dancer share | — | **100%** to dancer (platform nets 0) |
-| Club cover | platform share | — | **100%** (club float) |
+| Club tip | dancer share | - | **100%** to dancer (platform nets 0) |
+| Club cover | platform share | - | **100%** (club float) |
The trade and launch fees are live at 1% (owner decision, 2026-09-16): every
customer trade three.ws builds or signs pays it in the same transaction, and
@@ -161,34 +166,34 @@ deployments tune them to real unit economics. Detail, surfaces and disclosure:
## 4. Services catalog (what three.ws sells)
-- **x402 HTTP endpoints**: 86 distinct paid routes in the
+- **x402 HTTP endpoints**: 88 paid routes in the
[ring catalog](../api/_lib/x402/ring-catalog.js), the single source of truth,
across intel/oracle, agent/reputation, generation/3D, launch/naming/utility,
club, avatar shop, and bazaars. Full list and prices:
[x402 endpoints](x402-endpoints.md).
-- **Paid MCP tools** —
+- **Paid MCP tools** -
- Main MCP ([api/mcp.js](../api/mcp.js), pricing `api/_lib/pump-pricing.js`):
`mint_3d_asset` $0.25, `retexture_model` $0.10, `optimize_model` $0.05,
`segment_model` $0.04, `retexture_region` $0.03, `apply_animation` $0.02,
`inspect_model`/`validate_model` $0.01, `render_avatar` $0.005,
`search_public_avatars`/`solana_agent_reputation` $0.001.
- 3D Studio MCP ([api/mcp-3d.js](../api/mcp-3d.js), pricing `api/_mcp3d/pricing.js`):
- 15 priced tools: `text_to_3d`/`image_to_3d` tiered (draft/standard/high),
- `auto_rig_model`/`capture_scene`/`retexture_model`/`retexture_region`/`anchor_provenance` $0.05,
+ 17 priced tools: `text_to_3d`/`image_to_3d` tiered (draft/standard/high),
+ `auto_rig_model`/`capture_scene`/`retexture_model`/`retexture_region`/`anchor_provenance`/`cad_generate` $0.05,
`stylize_model`/`remesh_model`/`segment_model` $0.02,
- `remove_background`/`pose_model`/`apply_animation`/`direct_prompt`/`generate_material` $0.01.
-- **OKX.AI ASP #2632 "three.ws 3D Studio"** — the same 3D pipeline listed on OKX.AI
+ `remove_background`/`pose_model`/`apply_animation`/`direct_prompt`/`generate_material`/`cad_rebuild` $0.01.
+- **OKX.AI ASP #2632 "three.ws 3D Studio"** - the same 3D pipeline listed on OKX.AI
(ERC-8004 / XLayer) as an Agent Service Provider, endpoint `https://three.ws/api/mcp-3d`,
- serviceType `A2MCP`. The 7 registered services (fees $0.01–$0.15 USDC): Text &
+ serviceType `A2MCP`. The 7 registered services (fees $0.01-$0.15 USDC): Text &
Image-to-3D, Video-to-3D Scene Capture, Auto-Rig, Universal Animation Retarget,
Masked Texture Repaint, Mesh Repair/Export, Mesh Segmentation. **This list lives
- in the on-chain ASP record, not in repo code** — update it here if the ASP
+ in the on-chain ASP record, not in repo code** - update it here if the ASP
registration changes.
-- **Marketplace skills** — agent skill marketplace over Solana Pay
+- **Marketplace skills** - agent skill marketplace over Solana Pay
([api/marketplace/](../api/marketplace/)); see [marketplace skills](ux-flows/06-marketplace-skills.md).
-- **Labor market** — bounty/escrow jobs with worker + author-royalty settlement; see
+- **Labor market** - bounty/escrow jobs with worker + author-royalty settlement; see
[labor market](labor-market.md).
-- **Other** — vanity bounties, forge REST ([api/x402/forge.js](../api/x402/forge.js)),
+- **Other** - vanity bounties, forge REST ([api/x402/forge.js](../api/x402/forge.js)),
subscriptions, credit deposits.
---
@@ -196,7 +201,7 @@ deployments tune them to real unit economics. Detail, surfaces and disclosure:
## 5. Autonomous money movement
Engines that move money on their own (cron/worker driven) draw from the signer
-wallets, not the receivers — and each signer is kept funded by the
+wallets, not the receivers - and each signer is kept funded by the
[economy master](economy-master.md) via the `treasury-topup` cron (every 30 min,
allowlist-guarded, reserve/per-engine/per-run caps). Which wallet funds which
engine and minimum balances are in the
@@ -222,26 +227,28 @@ watched for silence. One board rolls it all up.
| Layer | What it watches | Where |
|---|---|---|
-| **All-wallet leak scan** | Every mainnet `SOLANA_SIGNERS` wallet (masters, all treasuries, ring wallets) — any SOL/token debit to an address outside the controlled set, or an SPL Approve | `api/cron/wallets-leak-scan.js` (`*/15`), verdict source `wallets_onchain` |
-| **Ring leak scan** | The x402 ring role wallets specifically | `api/cron/x402-ring-leak-scan.js` (`*/10`), source `x402_ring_onchain` |
-| **Economy-master breach/tamper** | Unrecorded outbound + hash-chain integrity of the funding root | `api/cron/economy-reconcile.js` (`*/30`) |
-| **Zero-activity tripwire** | Enabled-but-silent money loops (the alarm the ring outage lacked) | `api/_lib/financial-tripwire.js`, wired for `x402_autonomous_loop` in the leak-scan cron |
+| **All-wallet leak scan** | Every mainnet `SOLANA_SIGNERS` wallet (masters, all treasuries, ring wallets) - any SOL/token debit to an address outside the controlled set, or an SPL Approve; its alarm links the [leaked-wallet rescue runbook](ops/wallet-rescue.md) | `api/cron/wallets-leak-scan.js` (`*/15`), verdict source `wallets_onchain` |
+| **Ring leak scan** | The x402 ring role wallets first, then registry wallets with recent ledger activity, then the rest oldest-checked first. One lease per cadence and a 200 s run budget, so overlapping callers skip instead of stacking scans | `api/cron/x402-ring-leak-scan.js` (`*/10`), source `x402_ring_onchain` |
+| **Economy-master breach/tamper** | Unrecorded outbound + hash-chain integrity of the funding root. Lease-gated to one run per 30-minute window | `api/cron/economy-reconcile.js` (`*/30`) |
+| **Zero-activity tripwire** | Enabled-but-silent money loops (the alarm the ring outage lacked) | `api/_lib/financial-tripwire.js`, wired for `x402_autonomous_loop` in `wallets-leak-scan.js` |
| **Reconciliation** | Ring settlements/sweeps + revenue vs chain | `ring-reconciliation.js`, `revenue-reconciliation.js` |
| **Unified board** | Per-subsystem open critical/warn verdicts + last activity, one call | `GET /api/ops/money-health` (admin session, or `x-ops-secret: $OPS_SECRET`) |
Guardrails on outflow: the economy master is funder-only with reserve/per-transfer/
per-run caps and a registry allowlist; the ring can only settle to allowlisted
wallets (anti-drain gate); the sniper auto-funder moves money only for strategies
-that set `auto_fund_enabled = true` (default off). See
+that set `auto_fund_enabled = true` (default off); agent spend above a payment
+session's approval threshold parks for owner approval instead of settling (see
+[a2a payments](a2a-payments.md)). See
[financial-controls.md](financial-controls.md) for the full register.
## Related
-- [Financial controls & audit register](financial-controls.md) — every ledger's integrity, reconciliation, retention, monitoring, and the ranked gap list.
-- [x402 endpoints](x402-endpoints.md) — the paid endpoint catalog and price overrides.
-- [x402 ring economy](x402-ring-economy.md) — the internal recirculation loop.
-- [Pump platform fee](pump-platform-fee.md) — the pump trade fee detail.
-- [Coin-launch wallets](ux-flows/08-coin-launch-wallets.md) — launch-time wallet flow.
-- [Creator revenue splits](../api/_lib/cosmetics-economy.js) — `recordSaleAndSplit`: the cosmetic split math and its real USDC payout.
-- [Agent wallet custody](agent-wallets.md) — how custodial keys are held.
-- [Solana signers runbook](../api/_lib/solana-signers.js) — signer/funder wallets + funding.
+- [Financial controls & audit register](financial-controls.md) - every ledger's integrity, reconciliation, retention, monitoring, and the ranked gap list.
+- [x402 endpoints](x402-endpoints.md) - the paid endpoint catalog and price overrides.
+- [x402 ring economy](x402-ring-economy.md) - the internal recirculation loop.
+- [Pump platform fee](pump-platform-fee.md) - the pump trade fee detail.
+- [Coin-launch wallets](ux-flows/08-coin-launch-wallets.md) - launch-time wallet flow.
+- [Creator revenue splits](../api/_lib/cosmetics-economy.js) - `recordSaleAndSplit`: the cosmetic split math and its real USDC payout.
+- [Agent wallet custody](agent-wallets.md) - how custodial keys are held.
+- [Solana signers runbook](../api/_lib/solana-signers.js) - signer/funder wallets + funding.
diff --git a/docs/ops/llm-lanes.md b/docs/ops/llm-lanes.md
index 731238942..cb660e5cd 100644
--- a/docs/ops/llm-lanes.md
+++ b/docs/ops/llm-lanes.md
@@ -158,6 +158,9 @@ Guardrails, all enforced in code:
(`isPaidModel()`), or the rung is refused with a warning. That registration is
what makes it metered rather than priced as free openrouter traffic, and what
keeps it away from anonymous callers.
+- Anonymous callers of `api/chat.js` may only name a catalogued non-paid model or
+ an OpenRouter `:free` id (`anonModelAllowed()` in `api/_lib/chat-models.js`), so
+ an arbitrary paid id cannot be routed onto the funded platform key.
- It sits in the **paid tail**, after every free rung, never leading.
- It is skipped entirely when a caller BYOK key, a server `ANTHROPIC_API_KEY`, or
Vertex Claude is available. It is a gap-filler, not a competitor.
diff --git a/docs/ops/search-indexing.md b/docs/ops/search-indexing.md
index 1ad1e9fd4..95b1fe814 100644
--- a/docs/ops/search-indexing.md
+++ b/docs/ops/search-indexing.md
@@ -16,11 +16,16 @@ Every public URL falls into one of these, and the failure modes are different:
title, description, canonical, OG/Twitter tags and JSON-LD from
`data/pages.json`, so the meta a crawler reads matches the catalog. Run it
with `--write` after adding a page; it never overwrites a tag a page already
- has.
-
-2. **A server-rendered page** (`api/*-og.js`, `api/markets/*`). The handler
- composes the document per request from the database. `/markets/news/...` and
- the crawler pages below are here.
+ has. The `/` entry resolves to `pages/desktop.html` (the web desktop home;
+ the previous homepage lives at `/classic`). `npm run audit:pages` fails on a
+ path listed twice in `data/pages.json` even when the rows carry different
+ copy, because each row would submit the same URL to the sitemap again, and a
+ page whose own meta says `noindex` does not belong in the manifest at all.
+
+2. **A server-rendered page** (`api/*-og.js`, `api/news/story-page.js`). The
+ handler composes the document per request from the database.
+ `/markets/news/<month>/<id>-<slug>` stories and the crawler pages below are
+ here.
3. **A single-page-app shell.** One HTML file backs an unbounded URL space:
`/coin/:id` renders `pages/coin.html`, `/m/:id` renders `pages/model.html`,
diff --git a/docs/oracle.md b/docs/oracle.md
index 876fd90cb..c7d49c530 100644
--- a/docs/oracle.md
+++ b/docs/oracle.md
@@ -160,7 +160,7 @@ The worker is configured entirely by environment. Selected knobs, with defaults:
This is the part built for owners of 3D agents, and it is an explicit, owner-only opt-in.
-Arm your agent at three.ws/oracle/arm. The config is the full risk envelope, not a toggle: minimum score and tier, which narrative categories are in scope, per-trade SOL size, a max daily SOL budget, a max number of open positions, whether at least one proven smart wallet must already be in the coin, size scaling, and an optional Telegram chat for alerts.
+Arm your agent at three.ws/oracle/arm. The config is the full risk envelope, not a toggle: minimum score and tier, which narrative categories are in scope, per-trade SOL size, a max daily SOL budget, a max number of open positions, whether at least one proven smart wallet must already be in the coin, size scaling, and an optional Telegram chat for alerts (the chat you linked to your account, shown read-only; see "Alerts and the social layer").
For every armed agent, on every freshly-scored coin, a pure decision function runs a sequence of gates. If any gate blocks, the agent passes; if all clear, it sizes and buys. The gates:
@@ -224,7 +224,7 @@ This is where the engine earns its keep. One score, many consumers.
**The Agent Exchange.** The /agent-exchange demo, where two 3D avatars trade intel in a virtual world while the on-chain transaction shows live, runs on the same paid crypto intel feed the sniper buys from.
-**Alerts and the social layer.** Armed agents alert their owners on Telegram on entries and on conviction drops for held coins. And any user can follow any agent at `/api/oracle/follow`, the watch tier of social copy-trading: pick an agent, set your own minimum score, and get pinged when it acts. The test-alert endpoint lets you verify your wiring before anything real fires.
+**Alerts and the social layer.** Armed agents alert their owners on Telegram on entries and on conviction drops for held coins. And any signed-in user can follow any agent at `/api/oracle/follow`, the watch tier of social copy-trading: pick an agent, set your own minimum score, and get pinged when it acts. Alerts only ever go to a chat you have proven you control: the follow and arm panels show the Telegram account you linked under Settings, Sign-in methods (read-only, with sign-in and link states when you have not), and `/api/oracle/follow` and `/api/oracle/test-alert` refuse any other `chat_id` with a 403. `GET /api/oracle/telegram-chat` returns that verified chat id. The test-alert endpoint lets you verify your wiring before anything real fires.
**The Telegram channel feed.** The whole Oracle also runs as a public Telegram channel, so you can hold the feed in your pocket without keeping a tab open. Three kinds of posts flow into it. Live signals: the scoring cron sweeps every two minutes and posts each coin the first time it crosses the feed floor, either by tier (`ORACLE_ALERT_MIN_TIER`, prime and strong by default) or by raw score (`ORACLE_FEED_MIN_SCORE`, default 56, the Lean boundary tracking the top slice of the live distribution). Agent activity: live entries and profitable exits post as they happen, with the agent's track-record link. A daily digest at 08:00 UTC anchors the channel with the day's scored count, top conviction, and platform-wide agent results. Every post carries the coin's mint, score, tier, and pillar breakdown, plus links back to the pump.fun page and the Oracle coin page. The channel is set by `TELEGRAM_ORACLE_CHAT_ID`; when it is a public @handle, `/api/oracle/stats` exposes the join URL and the /oracle hero renders a "Join the live Telegram feed" button. Each coin posts exactly once, deduplicated in-process and durably via `oracle_conviction.alerted_at`.
@@ -316,7 +316,7 @@ GET https://three.ws/api/oracle/trades?mint=<mint>
- Realized calibration per conviction band at `/api/oracle/calibration`: the fleet's actual win rate from real fills, next to what the band predicted, plus the bounded correction factor the scorer applies.
- A dynamic 1200x630 OpenGraph conviction card (SVG) for sharing a coin at `/api/oracle/og`. Its live market cap reads pump.fun first (with one retry, honouring `Retry-After`) and falls through to the shared multi-source market reader (Birdeye, DexScreener, GeckoTerminal) when pump.fun does not answer.
-The write endpoints. Two are auth-scoped to the agent's owner: `GET·POST /api/oracle/watch` reads or arms an agent's watch config with server-side validation clamping every limit, and `POST /api/oracle/test-alert` sends a test alert. The clamps only ever move a number toward safety: a size above the ceiling is lowered, but arming `mode: "live"` with a `per_trade_sol` under the 0.001 SOL floor, or a `max_daily_sol` smaller than one trade, is a 400 rather than a silent round-up into real spending. Moving a mainnet watch into live-armed also requires the account's signed real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement); without them the arm is refused with a 403 that links to `/legal/agreements` (see [Risk acknowledgment](risk-acknowledgment.md)). Re-saving an already live-armed watch, simulate mode, devnet, and disarming are not gated. Simulate runs keep the forgiving clamps. Two are public and IP rate-limited instead: `POST·DELETE /api/oracle/follow` subscribes a Telegram chat to an agent's signals (the chat id the caller supplies is the identity, so there is no session to scope to), and `POST /api/oracle/social` ingests tweets to additively boost virality (never downgrades an LLM read). The `oracle-social-ingest` cron (every 10 minutes) feeds it: it reads the timelines of tracked KOL handles through the keyless guest reader ([api/_lib/x-guest/](../api/_lib/x-guest/README.md)), keeps tweets with a cashtag from the last 24h, and POSTs them. Separately, each scored coin's own linked X account contributes `social.xAccount` (handle, age in days, followers) to the intel; this is a context feature and is not an input to the fitted model until a refit includes it.
+The write endpoints. Three need a signed-in caller: `GET·POST /api/oracle/watch` reads or arms an agent's watch config with server-side validation clamping every limit, and `POST /api/oracle/test-alert` sends a test alert. The clamps only ever move a number toward safety: a size above the ceiling is lowered, but arming `mode: "live"` with a `per_trade_sol` under the 0.001 SOL floor, or a `max_daily_sol` smaller than one trade, is a 400 rather than a silent round-up into real spending. Moving a mainnet watch into live-armed also requires the account's signed real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement); without them the arm is refused with a 403 that links to `/legal/agreements` (see [Risk acknowledgment](risk-acknowledgment.md)). Re-saving an already live-armed watch, simulate mode, devnet, and disarming are not gated. Simulate runs keep the forgiving clamps. `POST·DELETE /api/oracle/follow` (and the `GET` that reports whether a chat follows an agent) subscribes a Telegram chat to an agent's signals; it needs a session or bearer token, and `chat_id` must equal the chat of the caller's linked Telegram identity (401 when signed out, 403 otherwise), since a caller-supplied chat id alone proves nothing. `GET /api/oracle/telegram-chat` reads that verified chat. One is public and IP rate-limited instead: `POST /api/oracle/social` ingests tweets to additively boost virality (never downgrades an LLM read). The `oracle-social-ingest` cron (every 10 minutes) feeds it: it reads the timelines of tracked KOL handles through the keyless guest reader ([api/_lib/x-guest/](../api/_lib/x-guest/README.md)), keeps tweets with a cashtag from the last 24h, and POSTs them. Separately, each scored coin's own linked X account contributes `social.xAccount` (handle, age in days, followers) to the intel; this is a context feature and is not an input to the fitted model until a refit includes it.
### Through MCP
@@ -326,7 +326,7 @@ The read API is plain HTTP, so any MCP-capable assistant can call it with a gene
**Read the market in sixty seconds.** Open three.ws/oracle. The board is live, newest first. Click any coin: the drawer shows the score, the four pillars, the plain-language reasons ordered by what mattered most, the conviction sparkline, who is in, and the full live market picture. Prime and strong are the only tiers that mean act.
-**Arm your agent, risk free.** Create or pick an agent, open three.ws/oracle/arm, set minimum tier to strong, pick your categories, set a per-trade size and a daily budget, require smart money if you want the strictest gate, and leave mode on simulate. Add your Telegram chat and send the test alert. Watch your agent's simulated entries appear on three.ws/activity and its graded results accumulate. Flip to live only when the simulated ledger has earned it; the first live arm asks you to sign the real-funds agreements.
+**Arm your agent, risk free.** Create or pick an agent, open three.ws/oracle/arm, set minimum tier to strong, pick your categories, set a per-trade size and a daily budget, require smart money if you want the strictest gate, and leave mode on simulate. Link Telegram under Settings, Sign-in methods, then send the test alert to that chat. Watch your agent's simulated entries appear on three.ws/activity and its graded results accumulate. Flip to live only when the simulated ledger has earned it; the first live arm asks you to sign the real-funds agreements.
**Buy intel like an agent.** Walk into any coin town in /play, find the kiosk by the plaza, press E, and pay one cent USDC. Or skip the world and do it from code: point `@three-ws/x402-mcp` at the crypto intel endpoint and ask your assistant for the pump.fun trending board. Either way you just did what the sniper does on every pass: paid the machine economy for a real market read.
diff --git a/docs/site-performance.md b/docs/site-performance.md
index b7bbe8a4e..579fec04b 100644
--- a/docs/site-performance.md
+++ b/docs/site-performance.md
@@ -468,7 +468,7 @@ Each of these is the largest remaining number on the page it belongs to, and eac
**`/chat` is one 4,277 KiB JavaScript chunk. Closed on 2026-09-04:** the page now transfers **747 KiB**, blocks for 2ms and scores 99 desktop. The measurement that follows is kept as the record of what it cost. The page made 23 requests and `chat/assets/index-*.js` was 4,277 KiB of them; nothing renders until it has parsed, which is the entire story of its FCP (3,901ms desktop, 23,105ms mobile) and of an LCP that lands 140ms later. Blocking time is *one millisecond*, so no amount of deferring helps: the work is a single parse of a single chunk. [chat/vite.config.js](../chat/vite.config.js) sets no `manualChunks` and no `inlineDynamicImports`; the app simply imports everything statically from its entry, so Vite has nothing to split on. The fix is dynamic imports at the route and feature boundaries inside `chat/src`, which is a refactor of the sub-app rather than a build-config change.
-**`/forge` showcase thumbnails are full-size renders.** Twelve images from `pub-*.r2.dev` account for **6,273 KiB of the page's 8,339 KiB**, averaging 520 KB each. They are the 768x768 PNGs that [api/\_lib/forge-thumbs.js](../api/_lib/forge-thumbs.js) generates (`THUMB_SIZE = 768`), painted into a 200px-tall box. `loading="lazy"` and `decoding="async"` are already set per rule 5, so this is not a scheduling problem, it is a format and size problem: the same renders as WebP at a display-appropriate size are roughly a tenth of the bytes. The fix has to change the generator, re-run the backfill cron over existing rows, and handle the `forge/thumb/<id>.png` key extension that `forgeThumbKeyFor()` and the stored `preview_image_url` values both encode. One outlier in the same trace is a data-freshness artifact rather than a bug: a 2,358 KiB `forge/<clientKey>/<id>.png` is the untouched original for a row the backfill has not reached yet.
+**`/forge` showcase thumbnails are full-size renders.** Twelve images (served from `pub-*.r2.dev` when measured, from the same-origin `/cdn/` proxy since 2026-10-24) account for **6,273 KiB of the page's 8,339 KiB**, averaging 520 KB each. They are the 768x768 PNGs that [api/\_lib/forge-thumbs.js](../api/_lib/forge-thumbs.js) generates (`THUMB_SIZE = 768`), painted into a 200px-tall box. `loading="lazy"` and `decoding="async"` are already set per rule 5, so this is not a scheduling problem, it is a format and size problem: the same renders as WebP at a display-appropriate size are roughly a tenth of the bytes. The fix has to change the generator, re-run the backfill cron over existing rows, and handle the `forge/thumb/<id>.png` key extension that `forgeThumbKeyFor()` and the stored `preview_image_url` values both encode. One outlier in the same trace is a data-freshness artifact rather than a bug: a 2,358 KiB `forge/<clientKey>/<id>.png` is the untouched original for a row the backfill has not reached yet.
**The brand mark is an 85 KB SVG rendered at 22 pixels.** `public/three.svg` and the byte-identical `public/favicon.svg` are 85,257-byte SVGs wrapping two 800x436 PNGs behind `feColorMatrix` filters. They are referenced from 545 files as of 2026-09-17 (446 of them HTML: `grep -rl '/three\.svg\|/favicon\.svg' pages/ public/ src/ | wc -l`, up from 171 when this item was first measured), cost 62 KiB over the wire per page, and no call site in the repo renders the mark above 64 CSS px. Re-encoding the embedded rasters at exactly half resolution (800 to 400, lanczos3, no palette quantization) takes the file to 36,913 bytes and is visually indistinguishable at every size the site uses, with a maximum channel delta of 4 at 22px and 10 at 64px. It is not free above that: at 192px, which some platforms use for an SVG favicon, the delta reaches 105. Fractional downscales are much worse than the exact half (320px wide measured a delta of 78 at 22px), so this is a brand-asset decision with a measured cost attached, not a mechanical resize, and it needs the owner rather than a sweep.
@@ -486,20 +486,15 @@ only half a fix: it caps the tall case and lets the short case collapse.
**`/marketplace` was not touched by the 2026-09-04 sweep and is the worst page on the list.** It measured **38 desktop at a `benchmarkIndex` of 1,183**, with 22,560ms of blocking time, an LCP of 3,272ms and **11,790 KiB transferred**, which is more than the other seven pages put together. Its viewers already obey rule 4's `data-src` contract and its podium already obeys rule 5, and the page still mounts a hero carousel, a six-item themed strip and a card grid, all of them above the fold at 1350x940, so the contract has nothing left to defer. A single hero GLB was 3,341 KiB in that trace, which is rule 7's problem in a second place: `renderHero()` in [src/marketplace.js](../src/marketplace.js) takes whatever `state.featured` returns without asking how heavy it is. Applying rule 7's budget there is the obvious next move and it needs its own measurement, because unlike the homepage this page shows three avatars at once and the budget has to be shared.
-## Open: directory thumbnails are served with no cache headers at all
+## Half-closed on 2026-10-13: directory thumbnails had no cache headers
-This one is measured, understood, and deliberately not fixed yet, because the safe fix is larger than it looks.
+The caching half is fixed; the sizing half is still open.
-`/discover` downloads **28 images totalling 9,360 KiB**, of which 27 are avatar thumbnails at roughly 280 KB each. Every one of them comes from the Cloudflare `pub-*.r2.dev` public endpoint, which answers with **no `Cache-Control` header at all**: Lighthouse's `cache-insight` reports a cache lifetime of 0 for 29 resources, so a returning visitor re-downloads all of it.
+The measurement, kept as the record: `/discover` downloaded **28 images totalling 9,360 KiB**, of which 27 were avatar thumbnails at roughly 280 KB each. Every one came from the Cloudflare `pub-*.r2.dev` public endpoint, which answers with **no `Cache-Control` header at all**: Lighthouse's `cache-insight` reported a cache lifetime of 0 for 29 resources, so a returning visitor re-downloaded all of it. `/cdn/<key>` ([api/cdn-object.js](../api/cdn-object.js)) proxies the same bucket and answers `public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800` for `thumb/` keys (other keys get `max-age=86400, s-maxage=2592000`).
-The repository already has the fix. `/cdn/<key>` ([api/cdn-object.js](../api/cdn-object.js)) proxies the same bucket and answers `public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800` for `thumb/` keys. Verified against a live key from the feed, both routes return the identical 289,539-byte PNG and only the first-party one carries the header.
+What shipped: `thumbnailUrl()` in [api/\_lib/r2.js](../api/_lib/r2.js) now resolves a stored key (or a legacy raw-bucket URL, via `keyFromPublicUrl()`) to an absolute `<APP_ORIGIN>/cdn/<key>` URL through `cdnUrlOrNull()`, so every first-party feed and the documented `GET /api/explore` `image` field carry the cached, same-origin URL. It is absolute rather than relative because `/api/explore` has third-party consumers and `draft-mint.js` bakes the URL into on-chain metadata. Stored `forge_creations` URL columns written before the change are rewritten on read by `normalizeStoredUrl()`, and the forge thumbnail writer ([api/\_lib/forge-thumbs.js](../api/_lib/forge-thumbs.js)) now writes the `/cdn/` form. Serving through `/cdn/` also removes the cross-origin `r2.dev` reads that Chrome's Opaque Response Blocking was rejecting. [tests/thumbnail-url-guard.test.js](../tests/thumbnail-url-guard.test.js) and `tests/r2-normalize-stored-url.test.js` hold the split.
-What makes it non-trivial is that `thumbnailUrl()` in [api/\_lib/r2.js](../api/_lib/r2.js) is deliberately the single resolver for a stored thumbnail key, and its output goes to more places than a page:
-
-- `GET /api/explore` is a **documented public endpoint** (see [the API reference](./api-reference.md)), so its `image` field has third-party consumers and cannot become a site-relative path.
-- The same helper feeds the image baked into on-chain token metadata via `api/_lib/draft-mint.js`, which is written once and cannot be corrected afterwards.
-
-The shape of the fix is therefore a second helper, absolute rather than relative, applied only to first-party page feeds and never to the metadata writer, plus an addition to [tests/thumbnail-url-guard.test.js](../tests/thumbnail-url-guard.test.js) so the split stays honest. Sizing the thumbnails is worth doing in the same pass: they are stored at 768x768 and painted into a 293px box.
+Still open: the thumbnails are stored at 768x768 and painted into a 293px box, so the byte cost per card is unchanged on a first visit.
## Half-closed on 2026-09-08: `/forge`'s composer growth