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(payments): document the holder tier block the credits balance now returns

nirholasf0beee74fb5a
diff --git a/data/changelog.json b/data/changelog.json
index bd7f4fabd..8b0f2d43f 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$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. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-25",
+ "title": "Crew HQ keeps its 3D room standing, and crew links now open where they point",
+ "summary": "Crew HQ refreshes who is in the world every 20 seconds, and it used to rebuild the whole room to do it: every member's 3D figure was destroyed and recreated four times a minute, which burns through the handful of live 3D canvases a browser will give a page and could catch a figure mid-load. The room now writes the new state into the figures already standing and only rebuilds when the roster itself changes, and opening a shared crew link no longer flashes the loading skeleton over a room that is already there. A member whose model cannot be loaded now shows their portrait on the plinth instead of an empty space. Signed-out visitors get a clean page: the sign-in-only crew request is no longer fired at all, the crew directory loads beside the room rather than behind it, and it stops listing the crew you are already looking at. A tag nobody flies offers the founding form only to someone who can actually take it, and a dropped connection now says what happened and how to retry instead of showing the browser's \"Failed to fetch\".",
+ "tags": [
+ "fix",
+ "improvement"
+ ],
+ "link": "/crews"
+ },
{
"date": "2026-08-25",
"title": "Compare reads correctly on a phone and stops mislabelling gains and losses",
diff --git a/docs/payment-sessions.md b/docs/payment-sessions.md
index f4da110f9..f0d03298e 100644
--- a/docs/payment-sessions.md
+++ b/docs/payment-sessions.md
@@ -82,12 +82,28 @@ curl -s https://three.ws/api/credits \
"three_symbol": "THREE",
"three_decimals": 6
},
+ "holder": {
+ "tier": { "level": 2, "id": "silver", "label": "Silver", "discount_bps": 1000 },
+ "usd_held": 140.0,
+ "discount_bps": 1000,
+ "next_tier": { "id": "gold", "label": "Gold", "min_usd": 500 },
+ "usd_to_next": 360.0
+ },
"buys": [ { "id": "...", "label": "...", "category": "...", "policy": "...", "usd": 0.05 } ],
"ledger": [ { "id": "...", "kind": "deposit", "amount_usd": 20, "...": "..." } ],
"next_cursor": null
}
```
+`holder` is the $THREE tier every debit on this account is already priced at:
+the same shape [`GET /api/pricing`](api-reference.md) returns. `discount_bps`
+is the discount applied to each spend (1000 = 10% off), `usd_held` is the USD
+value of the $THREE held by the linked wallet, and `next_tier` / `usd_to_next`
+say how much more $THREE reaches the next rung (`next_tier` is `null` at the
+top tier). Resolving it reads a Solana balance, so it degrades to `null` rather
+than failing the balance read; treat `null` as "tier unknown", not "no
+discount".
+
`ledger` is newest-first (25 entries here); each item carries `id`, `kind`
(`deposit`, `refund`, `grant`, `adjust`, or a spend), `amount_usd`,
`balance_after`, `action`, `ref_type`, `ref_id`, `tx_signature`, `asset`,