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(changelog): publish the pump.fun verification entry and two pending ones

nirholasd0a157b835da
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f300a0592..97cee4ebc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,14 @@
Public history for [three.ws](https://three.ws), newest first. New pages come from `added` dates in data/pages.json; everything else is curated in data/changelog.json. Also available as [JSON](https://three.ws/changelog.json) and [RSS](https://three.ws/changelog.xml), live at [three.ws/changelog](https://three.ws/changelog).
+## 2026-08-24
+
+- **$THREE now carries its pump.fun verification badge, read live from pump.fun**: pump.fun verifies a project's coin as officially belonging to that project, which is what tells a buyer the real $THREE apart from the copies that share its name and ticker. That badge now appears next to $THREE on the token page and on the holder dashboard. It is never hardcoded: the platform reads pump.fun's own verification flag on every stats request and renders the badge only while pump.fun publishes it, so a badge on three.ws always means the same thing as a badge on pump.fun. (`/three-token`) `[feature, improvement]`
+
## 2026-08-22
+- **Any AI agent can now buy a 3D model from us in one call**: Our OKX.AI marketplace listing has been rebuilt around one thing: an agent describes something, and gets back a real 3D model. Four new services (draft at one cent, standard at five, HD and image-to-3D at twenty five) plus a free job-status service, each one a proper MCP server that answers an unpaid call with a payment challenge on the marketplace's own rail. A buying agent receives exactly what our ChatGPT app gives a person: the downloadable GLB, the concept image, a browser preview, and a link that drops the model into a real room in augmented reality. Both surfaces now share one response shaper, so they can never drift apart. The identity studio and the specialist rigging and export endpoints stay live and payable, just off the listing while the forge proves itself. (`/docs/okx-marketplace`) `[feature]`
+- **Our Hugging Face article, avatar rigs, and 3D viewer are now linked from the site and the docs**: three.ws publishes on Hugging Face, the place the machine-learning world goes to check whether a model claim is real: a community article on giving agents bodies and wallets, a repository of rigged avatars you can download under the MIT license, and a running Space that loads them in an interactive 3D viewer. Until now nothing on the site pointed at any of it. All three are now indexed in the docs with a note on which part of the platform each one demonstrates, listed in the news feed with a working link, and the article joins the press cards at the bottom of the blog. The docs page also carries the checklist for publishing the next one. (`/docs/huggingface`) `[docs, improvement]`
- **The README now says open source, because it is**: Ten places across the README and our published articles still described three.ws as source-available, which understated the Apache 2.0 license the project actually ships under. They now say open source, and the README explains what that buys you: fork it, self-host it, ship commercial work on it. The top of the README also carries a license badge, a live count of good first issues, and a one-line path for anyone who wants to contribute rather than just use it. The security reporting line no longer points at a retired mirror repository. (`/docs/first-contribution`) `[docs]`
## 2026-08-21
diff --git a/api/3d/studio.js b/api/3d/studio.js
index 4e948434a..e730bce69 100644
--- a/api/3d/studio.js
+++ b/api/3d/studio.js
@@ -47,10 +47,16 @@
import { cors, wrap, method, json, readJson, setRateLimitHeaders } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
-import { startForge, originFromReq, viewerUrl, arLaunchUrl } from '../_mcp-studio/gpt-forge-client.js';
+import { startForge, originFromReq } from '../_mcp-studio/gpt-forge-client.js';
+// Response shaping is shared with the OKX.AI A2MCP forge services so the two
+// fronts over this lane cannot drift; re-exported here because the Actions
+// contract tests pin the boundary through this route's module.
+import { shapeSubmit, shapePoll } from '../_mcp-studio/studio-shape.js';
import { checkPromptSafety } from '../_mcp-studio/safety.js';
import { resolveLogoPrompt } from '../_lib/forge-director-prompts.js';
+export { shapeSubmit, shapePoll };
+
const PROMPT_MIN = 3; // the generation lane needs a subject to condition on
const PROMPT_MAX = 1000; // matches /api/gpt-forge's own prompt ceiling
const MAX_BODY_BYTES = 8_000;
@@ -60,101 +66,6 @@ const MAX_BODY_BYTES = 8_000;
// /api/gpt-forge does the authoritative validation, this just keeps junk off the wire.
const JOB_HANDLE_RE = /^[A-Za-z0-9._-]{8,1024}$/;
-// The painted reference view of the model — the forge's first, image-generation
-// step. Surfaced on every state (pending included) so the GPT can show the
-// concept image the moment it exists, while the mesh is still generating —
-// the same paint-then-reconstruct experience the /forge page gives.
-function previewOf(payload) {
- const u = payload?.preview_image_url;
- return typeof u === 'string' && /^https:\/\//.test(u) ? u : null;
-}
-
-function tierOf(payload) {
- const t = payload?.tier;
- return t === 'draft' || t === 'standard' || t === 'high' ? t : null;
-}
-
-// Shape a forge submit response into the Actions contract: model URLs and job
-// state only. Pure + exported so tests pin the boundary against real captured
-// forge shapes without any network.
-export function shapeSubmit(job, base, prompt) {
- const glbUrl = typeof job?.glb_url === 'string' ? job.glb_url : '';
- const preview = previewOf(job);
- const tier = tierOf(job);
- if (job?.status === 'done' && glbUrl) {
- return {
- status: 'done',
- glbUrl,
- viewerUrl: viewerUrl(base, glbUrl),
- arUrl: arLaunchUrl(base, glbUrl, prompt),
- format: 'glb',
- ...(preview ? { previewImageUrl: preview } : {}),
- ...(tier ? { tier } : {}),
- };
- }
- const handle = job?.job_id ?? null;
- // The poll URL carries the prompt as `title` so the eventual done response
- // can label the AR/viewer pages without the GPT having to resend anything.
- const t = typeof prompt === 'string' && prompt.trim() ? `&title=${encodeURIComponent(prompt.trim().slice(0, 80))}` : '';
- const eta = Number(job?.eta_seconds);
- return {
- status: 'pending',
- job: handle,
- poll: handle ? `/api/3d/studio?job=${encodeURIComponent(handle)}${t}` : null,
- ...(handle ? { watchUrl: `${base}/watch?job=${encodeURIComponent(handle)}${t}` } : {}),
- format: 'glb',
- ...(preview ? { previewImageUrl: preview } : {}),
- ...(tier ? { tier } : {}),
- ...(Number.isFinite(eta) && eta > 0 ? { etaSeconds: Math.round(eta) } : {}),
- };
-}
-
-// Shape a forge poll response into { status:'pending'|'done'|'error', ... }.
-export function shapePoll(data, base, jobId, title) {
- const glbUrl = typeof data?.glb_url === 'string' ? data.glb_url : '';
- const preview = previewOf(data);
- const tier = tierOf(data);
- if (data?.status === 'done' && glbUrl) {
- return {
- status: 'done',
- job: jobId,
- glbUrl,
- viewerUrl: viewerUrl(base, glbUrl),
- arUrl: arLaunchUrl(base, glbUrl, title),
- format: 'glb',
- ...(preview ? { previewImageUrl: preview } : {}),
- ...(tier ? { tier } : {}),
- };
- }
- if (data?.status === 'failed') {
- return {
- status: 'error',
- job: jobId,
- // The message is already sanitized by /api/gpt-forge; generation is free, so a
- // failed job costs the user nothing — they can simply try again.
- error: data?.error || '3D generation hit a snag upstream — it costs nothing to try again.',
- };
- }
- // queued / running / anything transient → still pending; keep the title on the
- // poll URL so it survives to the done response. The published Actions contract
- // (openai-actions.yaml) documents etaSeconds on pending states, so forward the
- // live remaining estimate the poll now carries (falling back to the lane's
- // total estimate) instead of leaving the GPT with N identical frames.
- const t = typeof title === 'string' && title.trim() ? `&title=${encodeURIComponent(title.trim().slice(0, 80))}` : '';
- const etaRemaining = Number(data?.eta_remaining_seconds ?? data?.eta_seconds);
- const elapsed = Number(data?.elapsed_seconds);
- return {
- status: 'pending',
- job: jobId,
- poll: `/api/3d/studio?job=${encodeURIComponent(jobId)}${t}`,
- watchUrl: `${base}/watch?job=${encodeURIComponent(jobId)}${t}`,
- ...(preview ? { previewImageUrl: preview } : {}),
- ...(tier ? { tier } : {}),
- ...(Number.isFinite(etaRemaining) && etaRemaining > 0 ? { etaSeconds: Math.round(etaRemaining) } : {}),
- ...(Number.isFinite(elapsed) && elapsed >= 0 ? { elapsedSeconds: Math.round(elapsed) } : {}),
- };
-}
-
// Every error body on this route is an ErrorResponse from the published Actions
// schema: { error, message, retry_after? }. The generic http.js helpers emit
// `error_description` instead of `message`, which the custom GPT has no field
diff --git a/api/_lib/okx-catalog.js b/api/_lib/okx-catalog.js
index 2cdfde6b2..3e82e7527 100644
--- a/api/_lib/okx-catalog.js
+++ b/api/_lib/okx-catalog.js
@@ -50,6 +50,38 @@ function usdToAtomics(usd) {
return String(Math.round(Number(usd) * 1e6));
}
+// Tool names on every A2MCP forge endpoint. They are deliberately identical
+// across the paid rows so a buying agent writes one client and points it at
+// whichever price/quality row it wants.
+export const FORGE_TOOL = 'forge_3d';
+export const FORGE_STATUS_TOOL = 'forge_status';
+
+// The paid text lanes take the same arguments; only the endpoint's lane and
+// fee differ. Built fresh per row so no two rows share a mutable schema object.
+function textForgeSchema() {
+ return {
+ type: 'object',
+ required: ['prompt'],
+ additionalProperties: false,
+ properties: {
+ prompt: { type: 'string', minLength: 3, maxLength: 1000 },
+ aspect_ratio: { type: 'string', enum: ['1:1', '4:3', '3:4', '16:9', '9:16'] },
+ },
+ };
+}
+
+function forgeStatusSchema() {
+ return {
+ type: 'object',
+ required: ['job_id'],
+ additionalProperties: false,
+ properties: {
+ job_id: { type: 'string', minLength: 8, maxLength: 1024 },
+ title: { type: 'string', maxLength: 200 },
+ },
+ };
+}
+
// One row per marketplace service. Fields:
// id URL slug, the service's route is /api/okx/3d/<id>
// name Listing display name
@@ -60,9 +92,161 @@ function usdToAtomics(usd) {
// endpoint Absolute endpoint URL buyers call
// tool For a2mcp services: the paid MCP tool name on that endpoint
// inputSchema JSON Schema of the paid call's arguments (free lanes: response shape)
+// listed true = on the live OKX.AI listing; false = back burner,
+// still deployed and routable, absent from the submission
+// lane For forge rows: which generation lane the endpoint drives
export const OKX_CATALOG = Object.freeze([
+ // ── The listed OKX.AI line-up: three.ws Forge ────────────────────────────
+ // One capability, sold four ways, plus a free poll. Every listed row is a
+ // real A2MCP endpoint (MCP Streamable HTTP, JSON-RPC tools/call) whose paid
+ // tool answers an unpaid call with an OKX-dialect 402 that leads with
+ // eip155:196, which is the OKX Agent Payments Protocol integration the
+ // 2026-07-04 review rejected us for missing.
+ //
+ // The four paid rows differ ONLY in lane and price: OKX prices a service,
+ // not a parameter, so a quality tier has to be its own row to carry its own
+ // fee. Buyers keep one client shape: every endpoint exposes the same
+ // forge_3d (paid) / forge_status (free) / getting_started (free) tools.
+ //
+ // What a buyer gets back is byte-for-byte what the "three.ws 3D Studio"
+ // custom GPT gets from /api/3d/studio: the GLB, the concept image, a browser
+ // viewer link and a device-aware AR link, and nothing else. Both fronts
+ // shape their responses through api/_mcp-studio/studio-shape.js, so the
+ // marketplace and the GPT cannot drift apart.
+ {
+ id: 'forge-draft',
+ name: 'Forge 3D Draft',
+ kind: 'a2mcp',
+ listed: true,
+ lane: { tier: 'draft', path: 'image', mode: 'text_to_3d' },
+ describes: {
+ capability:
+ 'Turns a text description of one object or character into a downloadable textured 3D ' +
+ 'model in GLB format, with a browser preview link and an augmented-reality link that ' +
+ 'places it in a real room.',
+ input:
+ 'Provide a text description of a single subject, 3 to 1000 characters, naming its style ' +
+ 'and main colours. An aspect ratio is optional. Returns a job id to poll on the free ' +
+ 'status service.',
+ },
+ priceUsd: '0.01',
+ amountAtomics: usdToAtomics(0.01),
+ endpoint: `${BASE}/api/okx/3d/forge-draft`,
+ tool: FORGE_TOOL,
+ inputSchema: textForgeSchema(),
+ },
+ {
+ id: 'forge-standard',
+ name: 'Forge 3D Standard',
+ kind: 'a2mcp',
+ listed: true,
+ lane: { tier: 'standard', mode: 'text_to_3d' },
+ describes: {
+ capability:
+ 'Turns a text description of one object or character into a downloadable textured 3D ' +
+ 'model in GLB format on the standard quality pass, with a browser preview link and an ' +
+ 'augmented-reality link.',
+ input:
+ 'Provide a text description of a single subject, 3 to 1000 characters, naming its style ' +
+ 'and main colours. An aspect ratio is optional. Returns a job id to poll on the free ' +
+ 'status service.',
+ },
+ priceUsd: '0.05',
+ amountAtomics: usdToAtomics(0.05),
+ endpoint: `${BASE}/api/okx/3d/forge-standard`,
+ tool: FORGE_TOOL,
+ inputSchema: textForgeSchema(),
+ },
+ {
+ id: 'forge-hd',
+ name: 'Forge 3D HD',
+ kind: 'a2mcp',
+ listed: true,
+ lane: { tier: 'high', mode: 'text_to_3d' },
+ describes: {
+ capability:
+ 'Turns a text description of one object or character into a downloadable textured 3D ' +
+ 'model in GLB format on the highest detail pass, with a browser preview link and an ' +
+ 'augmented-reality link.',
+ input:
+ 'Provide a text description of a single subject, 3 to 1000 characters, naming its style ' +
+ 'and main colours. An aspect ratio is optional. This pass runs longer, so keep polling ' +
+ 'the free status service.',
+ },
+ priceUsd: '0.25',
+ amountAtomics: usdToAtomics(0.25),
+ endpoint: `${BASE}/api/okx/3d/forge-hd`,
+ tool: FORGE_TOOL,
+ inputSchema: textForgeSchema(),
+ },
+ {
+ id: 'forge-image',
+ name: 'Forge 3D from Image',
+ kind: 'a2mcp',
+ listed: true,
+ lane: { mode: 'image_to_3d' },
+ describes: {
+ capability:
+ 'Rebuilds a downloadable textured 3D model in GLB format from photographs or rendered ' +
+ 'views of one object, with a browser preview link and an augmented-reality link that ' +
+ 'places it in a real room.',
+ input:
+ 'Provide one to four publicly reachable image links showing the same subject. A short ' +
+ 'text description is optional and sharpens the result. Returns a job id to poll on the ' +
+ 'free status service.',
+ },
+ priceUsd: '0.25',
+ amountAtomics: usdToAtomics(0.25),
+ endpoint: `${BASE}/api/okx/3d/forge-image`,
+ tool: FORGE_TOOL,
+ inputSchema: {
+ type: 'object',
+ required: ['image_urls'],
+ additionalProperties: false,
+ properties: {
+ image_urls: {
+ type: 'array',
+ minItems: 1,
+ maxItems: 4,
+ items: { type: 'string', format: 'uri', pattern: '^https://' },
+ },
+ prompt: { type: 'string', minLength: 3, maxLength: 1000 },
+ },
+ },
+ },
+ {
+ id: 'forge-status',
+ name: 'Forge Job Status',
+ kind: 'a2mcp',
+ listed: true,
+ lane: { mode: 'status' },
+ describes: {
+ capability:
+ 'Reports the live state of any three.ws forge generation job and returns the finished ' +
+ 'model file, concept image, browser preview link and augmented-reality link once the ' +
+ 'job completes. Always free.',
+ input:
+ 'Provide the job id returned when a generation was accepted. Optionally provide the ' +
+ 'original description so the preview pages carry a title. No payment, account, or key ' +
+ 'is required to call it.',
+ },
+ priceUsd: '0',
+ amountAtomics: null,
+ endpoint: `${BASE}/api/okx/3d/forge-status`,
+ tool: FORGE_STATUS_TOOL,
+ inputSchema: forgeStatusSchema(),
+ },
+
+ // ── Back burner (owner directive 2026-08-22) ─────────────────────────────
+ // Everything below stays deployed, tested and individually routable, and is
+ // NOT part of the OKX.AI listing: `listed: false` keeps it out of
+ // catalogIndex() and out of scripts/okx-listing-payload.mjs. The listing was
+ // rebuilt around the forge because a focused line-up is what sells and what
+ // passes review on this marketplace; these specialist services return to the
+ // listing when the forge rows have real sales behind them.
{
id: 'identity-studio',
+ listed: false,
name: 'Agent Identity Studio',
kind: 'a2mcp',
describes: {
@@ -120,6 +304,7 @@ export const OKX_CATALOG = Object.freeze([
// lane cost; the math is recorded in prompts/okx-ai/PROGRESS.md.
{
id: 'text-to-3d',
+ listed: false,
name: 'Text to 3D Model (GLB)',
kind: 'rest',
describes: {
@@ -148,6 +333,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'text-to-3d-pro',
+ listed: false,
name: 'Text to 3D Model (Pro)',
kind: 'rest',
describes: {
@@ -177,6 +363,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'image-to-3d',
+ listed: false,
name: 'Image to 3D Model',
kind: 'rest',
describes: {
@@ -209,6 +396,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'rig',
+ listed: false,
name: 'GLB Auto-Rigging',
kind: 'rest',
describes: {
@@ -233,6 +421,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'avatar',
+ listed: false,
name: 'Text to Rigged Avatar',
kind: 'rest',
describes: {
@@ -261,6 +450,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'retarget',
+ listed: false,
name: 'Animation Retargeting',
kind: 'rest',
describes: {
@@ -290,6 +480,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'pose-seed',
+ listed: false,
name: 'Pose Seed',
kind: 'rest',
describes: {
@@ -314,6 +505,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'fbx-export',
+ listed: false,
name: 'FBX Export (rig-preserving)',
kind: 'rest',
describes: {
@@ -341,16 +533,17 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'catalog',
+ listed: true,
name: '3D Studio Service Catalog',
kind: 'rest',
describes: {
capability:
- 'Free machine-readable index of every three.ws 3D Studio service on OKX.AI: names, ' +
+ 'Free machine-readable index of every three.ws 3D Studio service sold here: names, ' +
'descriptions, prices, endpoints, and input formats, always in sync with the live ' +
'services.',
input:
- 'Provide nothing. No parameters, no payment, no account required. Example: fetch ' +
- 'the link to list every service with names, prices, and input details.',
+ 'Provide nothing. No parameters, no payment, and no account are required. Returns the ' +
+ 'full service list with names, prices, endpoints, and the exact input each one expects.',
},
priceUsd: '0',
amountAtomics: null,
@@ -360,6 +553,7 @@ export const OKX_CATALOG = Object.freeze([
},
{
id: 'health',
+ listed: true,
name: '3D Studio Health Status',
kind: 'rest',
describes: {
@@ -367,8 +561,8 @@ export const OKX_CATALOG = Object.freeze([
'Free live health status for the systems behind every paid service: generation, rigging, ' +
'rendering, storage, and the payment rail, from real checks rather than a fixed reply.',
input:
- 'Provide nothing. No parameters, no payment, no account required. Example: fetch ' +
- 'the link to confirm all systems are up before buying a paid service.',
+ 'Provide nothing. No parameters, no payment, and no account are required. Returns a ' +
+ 'per-system reading so a buyer can confirm everything is up before paying for a job.',
},
priceUsd: '0',
amountAtomics: null,
@@ -389,22 +583,38 @@ export function listingDescription(entry) {
}
// The machine-readable index the free catalog service returns, the exact
-// payload OKX buyers (and work order 05's listing update) consume.
+// payload OKX buyers (and the listing update in scripts/okx-listing-payload.mjs)
+// consume.
+//
+// `services` is the live OKX.AI line-up. `unlisted` is the back burner: still
+// deployed, still payable, deliberately absent from the marketplace listing. It
+// is published rather than hidden because those endpoints answer real 402s to
+// anyone who calls them, and a catalog that pretended otherwise would be lying
+// to the buyer holding the URL.
+function publicRow(e) {
+ return {
+ id: e.id,
+ name: e.name,
+ kind: e.kind,
+ description: e.describes,
+ price_usd: e.priceUsd,
+ endpoint: e.endpoint,
+ ...(e.tool ? { tool: e.tool } : {}),
+ ...(e.inputSchema ? { input_schema: e.inputSchema } : {}),
+ };
+}
+
+export function listedCatalog(catalog = OKX_CATALOG) {
+ return catalog.filter((e) => e.listed);
+}
+
export function catalogIndex() {
return {
provider: 'three.ws 3D Studio',
okxAgentId: 2632,
chain: 'eip155:196',
- services: OKX_CATALOG.map((e) => ({
- id: e.id,
- name: e.name,
- kind: e.kind,
- description: e.describes,
- price_usd: e.priceUsd,
- endpoint: e.endpoint,
- ...(e.tool ? { tool: e.tool } : {}),
- ...(e.inputSchema ? { input_schema: e.inputSchema } : {}),
- })),
+ services: listedCatalog().map(publicRow),
+ unlisted: OKX_CATALOG.filter((e) => !e.listed).map(publicRow),
docs: `${BASE}/docs/okx-marketplace`,
};
}
@@ -419,6 +629,13 @@ export function validateCatalog(catalog = OKX_CATALOG) {
if (seen.has(e.id)) throw new Error(`${ctx}: duplicate id`);
seen.add(e.id);
if (!e.name) throw new Error(`${ctx}: missing name`);
+ // OKX caps a service name at 30 display columns (5 minimum); an over-long
+ // name is rejected at submission, not at review, so catch it in CI.
+ if (e.listed) {
+ const nw = displayWidth(e.name);
+ if (nw < 5 || nw > 30) throw new Error(`${ctx}: listed name display width ${nw} outside 5..30`);
+ }
+ if (typeof e.listed !== 'boolean') throw new Error(`${ctx}: listed must be a boolean`);
if (!['a2mcp', 'rest'].includes(e.kind)) throw new Error(`${ctx}: bad kind`);
for (const part of ['capability', 'input']) {
const text = e.describes?.[part];
@@ -450,5 +667,6 @@ export function validateCatalog(catalog = OKX_CATALOG) {
throw new Error(`${ctx}: paid rest row needs inputSchema`);
}
}
+ if (!catalog.some((e) => e.listed)) throw new Error('okx-catalog: no listed services, the submission would be empty');
return true;
}
diff --git a/api/_lib/okx-chat-briefing.js b/api/_lib/okx-chat-briefing.js
index 84b395e1c..3488e5159 100644
--- a/api/_lib/okx-chat-briefing.js
+++ b/api/_lib/okx-chat-briefing.js
@@ -6,7 +6,7 @@
// "what do you sell?" or "what is three.ws?", which is worse than being offline
// because it answers wrongly and confidently.
//
-// Built from OKX_CATALOG so prices, endpoints and capability text can never
+// Built from the catalog module so prices, endpoints and capability text can never
// drift from the live services. Two consumers, one source of truth:
// scripts/okx-listing-payload.mjs --briefing (writes the local workspace)
// workers/okx-chat-bot/workspace.js (writes the hosted workspace)
@@ -15,17 +15,22 @@
// the subsession reads depends on which AI CLI the adapter is configured to
// spawn (Claude Code reads CLAUDE.md, Codex reads AGENTS.md).
-import { OKX_CATALOG } from './okx-catalog.js';
+import { listedCatalog, OKX_CATALOG } from './okx-catalog.js';
/**
* Render the chat-responder briefing as markdown.
* @returns {string}
*/
export function buildChatBriefing() {
- const rows = OKX_CATALOG.map((e) => {
+ const row = (e) => {
const price = e.priceUsd === '0' ? 'Free' : `$${e.priceUsd} USDT`;
return `### ${e.name} (${price})\n${e.describes.capability}\n${e.describes.input}\nEndpoint: ${e.endpoint}`;
- }).join('\n\n');
+ };
+ const rows = listedCatalog().map(row).join('\n\n');
+ // Back-burner services are not on the listing, but they are deployed and
+ // payable, so a buyer who asks for rigging or an avatar in chat gets a real
+ // answer instead of "we do not offer that".
+ const offListRows = OKX_CATALOG.filter((e) => !e.listed).map(row).join('\n\n');
return `# three.ws 3D Studio (OKX.AI agent #2632): chat responder briefing
@@ -50,10 +55,18 @@ What that means for a buyer in this chat:
- A live, animated avatar embeddable on any website with a single web component.
- Everything returns a real GLB URL you can download, view in a browser, or embed.
-## What we sell
+## What we sell on the marketplace listing
${rows}
+## Also available, not on the listing
+
+These are deployed, priced and payable exactly like the listed rows, they are simply not
+part of the current marketplace listing. If a buyer asks for one, give them the endpoint
+and the price; do not tell them we cannot do it.
+
+${offListRows}
+
## How buyers pay
Every paid endpoint answers an unpaid POST with an HTTP 402 challenge (x402 v2). Pay it
diff --git a/api/_mcp-studio/studio-shape.js b/api/_mcp-studio/studio-shape.js
new file mode 100644
index 000000000..60007256e
--- /dev/null
+++ b/api/_mcp-studio/studio-shape.js
@@ -0,0 +1,116 @@
+// Shared response shaping for the free text-to-3D surfaces.
+//
+// One shaper, two fronts. `/api/3d/studio` (the ChatGPT Actions contract behind
+// the "three.ws 3D Studio" custom GPT) and the OKX.AI A2MCP forge services
+// (api/_okx3d/forge.js) hand a buyer exactly the same thing: the model URLs and
+// the job state, and nothing else. No upsell block, no pricing paths, no
+// internal identifiers. Keeping the shaping here means the GPT and the agent
+// marketplace cannot drift into two different contracts over the same lane.
+//
+// The only per-surface difference is where a pending job is polled: ChatGPT
+// polls a REST route, an OKX buyer calls a free MCP tool. That is the
+// `pollPath` option; everything else is identical.
+
+import { viewerUrl, arLaunchUrl } from './gpt-forge-client.js';
+
+export const STUDIO_POLL_PATH = '/api/3d/studio';
+
+// The painted reference view of the model, the forge's first, image-generation
+// step. Surfaced on every state (pending included) so a caller can show the
+// concept image the moment it exists, while the mesh is still generating: the
+// same paint-then-reconstruct experience the /forge page gives.
+export function previewOf(payload) {
+ const u = payload?.preview_image_url;
+ return typeof u === 'string' && /^https:\/\//.test(u) ? u : null;
+}
+
+export function tierOf(payload) {
+ const t = payload?.tier;
+ return t === 'draft' || t === 'standard' || t === 'high' ? t : null;
+}
+
+// The prompt rides the poll URL as `title` so the eventual done response can
+// label the AR/viewer pages without the caller having to resend anything.
+function titleSuffix(title) {
+ return typeof title === 'string' && title.trim()
+ ? `&title=${encodeURIComponent(title.trim().slice(0, 80))}`
+ : '';
+}
+
+// Shape a forge submit response into the published contract: model URLs and job
+// state only. Pure + exported so tests pin the boundary against real captured
+// forge shapes without any network.
+export function shapeSubmit(job, base, prompt, { pollPath = STUDIO_POLL_PATH } = {}) {
+ const glbUrl = typeof job?.glb_url === 'string' ? job.glb_url : '';
+ const preview = previewOf(job);
+ const tier = tierOf(job);
+ if (job?.status === 'done' && glbUrl) {
+ return {
+ status: 'done',
+ glbUrl,
+ viewerUrl: viewerUrl(base, glbUrl),
+ arUrl: arLaunchUrl(base, glbUrl, prompt),
+ format: 'glb',
+ ...(preview ? { previewImageUrl: preview } : {}),
+ ...(tier ? { tier } : {}),
+ };
+ }
+ const handle = job?.job_id ?? null;
+ const t = titleSuffix(prompt);
+ const eta = Number(job?.eta_seconds);
+ return {
+ status: 'pending',
+ job: handle,
+ poll: handle ? `${pollPath}?job=${encodeURIComponent(handle)}${t}` : null,
+ ...(handle ? { watchUrl: `${base}/watch?job=${encodeURIComponent(handle)}${t}` } : {}),
+ format: 'glb',
+ ...(preview ? { previewImageUrl: preview } : {}),
+ ...(tier ? { tier } : {}),
+ ...(Number.isFinite(eta) && eta > 0 ? { etaSeconds: Math.round(eta) } : {}),
+ };
+}
+
+// Shape a forge poll response into { status:'pending'|'done'|'error', ... }.
+export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PATH } = {}) {
+ const glbUrl = typeof data?.glb_url === 'string' ? data.glb_url : '';
+ const preview = previewOf(data);
+ const tier = tierOf(data);
+ if (data?.status === 'done' && glbUrl) {
+ return {
+ status: 'done',
+ job: jobId,
+ glbUrl,
+ viewerUrl: viewerUrl(base, glbUrl),
+ arUrl: arLaunchUrl(base, glbUrl, title),
+ format: 'glb',
+ ...(preview ? { previewImageUrl: preview } : {}),
+ ...(tier ? { tier } : {}),
+ };
+ }
+ if (data?.status === 'failed') {
+ return {
+ status: 'error',
+ job: jobId,
+ // The message is already sanitized by /api/gpt-forge; generation is free
+ // to retry, so a failed job costs the caller nothing.
+ error: data?.error || '3D generation hit a snag upstream, it costs nothing to try again.',
+ };
+ }
+ // queued / running / anything transient stays pending; keep the title on the
+ // poll URL so it survives to the done response. Forward the live remaining
+ // estimate the poll carries (falling back to the lane's total estimate)
+ // instead of leaving the caller with N identical frames.
+ const t = titleSuffix(title);
+ const etaRemaining = Number(data?.eta_remaining_seconds ?? data?.eta_seconds);
+ const elapsed = Number(data?.elapsed_seconds);
+ return {
+ status: 'pending',
+ job: jobId,
+ poll: `${pollPath}?job=${encodeURIComponent(jobId)}${t}`,
+ watchUrl: `${base}/watch?job=${encodeURIComponent(jobId)}${t}`,
+ ...(preview ? { previewImageUrl: preview } : {}),
+ ...(tier ? { tier } : {}),
+ ...(Number.isFinite(etaRemaining) && etaRemaining > 0 ? { etaSeconds: Math.round(etaRemaining) } : {}),
+ ...(Number.isFinite(elapsed) && elapsed >= 0 ? { elapsedSeconds: Math.round(elapsed) } : {}),
+ };
+}
diff --git a/api/_mcp/auth.js b/api/_mcp/auth.js
index 31005cc8e..c81541d77 100644
--- a/api/_mcp/auth.js
+++ b/api/_mcp/auth.js
@@ -93,6 +93,26 @@ export function sendJsonRpcError(res, id, code, message, data) {
// 402 challenge AND in the requirements used to verify the X-PAYMENT, so the
// advertised price and the charged price agree. null = use the flat default
// (initialize / tools/list / free tools / mixed batches).
+// Prepended rails can collide with the shared builder's own output: when the
+// OKX X Layer rail is configured, paymentRequirements() already emits it, so a
+// bare prepend leaves two identical `exact` entries in accepts[]. Harmless to a
+// payer, but it is the first thing a marketplace reviewer reads, and a listing
+// that advertises the same rail twice looks broken. Keep the FIRST occurrence
+// (that is the whole point of prepending) and drop later twins.
+function mergeAccepts(extra, base) {
+ const seen = new Set();
+ const out = [];
+ for (const a of [...extra, ...base]) {
+ const key = [a?.scheme, a?.network, a?.asset, a?.amount ?? a?.maxAmountRequired, a?.payTo]
+ .map((v) => String(v ?? '').toLowerCase())
+ .join('|');
+ if (seen.has(key)) continue;
+ seen.add(key);
+ out.push(a);
+ }
+ return out;
+}
+
export async function authenticateRequest(
req,
res,
@@ -131,10 +151,10 @@ export async function authenticateRequest(
// e.g. the OKX X Layer (eip155:196) accept must LEAD for OKX buyers (their
// CLI auto-selects the first `exact` entry). Prepended so it also participates
// in verifyPayment, letting an X Layer replay verify + settle here.
- const requirements = [
- ...extraAccepts,
- ...paymentRequirements(resourceUrl, x402Amount != null ? { amount: x402Amount } : {}),
- ];
+ const requirements = mergeAccepts(
+ extraAccepts,
+ paymentRequirements(resourceUrl, x402Amount != null ? { amount: x402Amount } : {}),
+ );
if (paymentHeader) {
try {
@@ -181,7 +201,16 @@ export async function authenticateRequest(
return null;
}
-export async function handleSse(req, res, { resourcePath = '/api/mcp', challenge, extraAccepts = [] } = {}) {
+// `x402Amount` is the endpoint's list price. Without it, paymentRequirements()
+// quotes the shared default here while the prepended rail quotes the real price,
+// so the discovery challenge advertised the SAME rail twice at two DIFFERENT
+// amounts. A buyer reading accepts[] could not tell which one the endpoint
+// actually charges, and it is the first array a marketplace reviewer opens.
+export async function handleSse(
+ req,
+ res,
+ { resourcePath = '/api/mcp', challenge, extraAccepts = [], x402Amount = null } = {},
+) {
// We don't hold long-lived server→client subscriptions yet; respond politely.
const bearer = extractBearer(req);
// Unauthenticated callers without an X-PAYMENT header get a 401 +
@@ -193,7 +222,10 @@ export async function handleSse(req, res, { resourcePath = '/api/mcp', challenge
return await sendAuthChallenge(res, {
req,
resourceUrl: sseResourceUrl,
- requirements: [...extraAccepts, ...paymentRequirements(sseResourceUrl)],
+ requirements: mergeAccepts(
+ extraAccepts,
+ paymentRequirements(sseResourceUrl, x402Amount != null ? { amount: x402Amount } : {}),
+ ),
challenge,
});
}
diff --git a/api/_okx3d/README.md b/api/_okx3d/README.md
index 365dffe07..49efc6ec6 100644
--- a/api/_okx3d/README.md
+++ b/api/_okx3d/README.md
@@ -1,8 +1,12 @@
-# `api/_okx3d/` - Agent Identity Studio pipeline and OKX.AI service engines
+# `api/_okx3d/` - OKX.AI service engines (three.ws Forge + Agent Identity Studio)
The engine layer behind the paid `/api/okx/3d/*` services three.ws sells to other agents on the OKX.AI marketplace (agent #2632). The route [`api/okx/3d/[service].js`](../okx/3d/%5Bservice%5D.js) owns transport, x402 payment, and the OKX 402 dialect; this directory owns the actual work. Prices, tool names, and input schemas all come from one catalog, [`../_lib/okx-catalog.js`](../_lib/okx-catalog.js), so the listing, the 402 challenges, and the engines can never disagree.
-The flagship service is the **Agent Identity Studio** ($1.50 per identity): a brand brief goes in, a complete 3D identity comes out.
+**The listed line-up (rebuilt 2026-08-22) is three.ws Forge**, in [`forge.js`](./forge.js): four paid A2MCP rows (`forge-draft` $0.01, `forge-standard` $0.05, `forge-hd` $0.25, `forge-image` $0.25) plus a free `forge-status` poll. Each row is a real MCP Streamable HTTP server exposing the same three tools (`forge_3d` paid, `forge_status` and `getting_started` free), so a buying agent writes one client and points it at whichever price it wants. It is a front, not a pipeline: generation runs through the same `/api/gpt-forge` lane the ChatGPT custom GPT uses, and responses are shaped by the same [`../_mcp-studio/studio-shape.js`](../_mcp-studio/studio-shape.js), so the marketplace and the GPT cannot drift into two contracts over one generator.
+
+Everything else here is on the **back burner**: `listed: false` in the catalog keeps it off the marketplace listing and out of the submission payload while it stays deployed, tested and payable.
+
+The back-burner flagship is the **Agent Identity Studio** ($1.50 per identity): a brand brief goes in, a complete 3D identity comes out.
```
brief → identity prompt (Granite director, fail-soft)
@@ -18,6 +22,7 @@ Every GPU and render stage is driven over the deployed three.ws HTTP surfaces (t
| File | Role |
| --- | --- |
+| [`forge.js`](./forge.js) | The listed line-up: per-endpoint MCP tool catalogs, dispatchers, x402 price hooks, the bazaar discovery metadata in each 402, and the age-13+ content gate that runs before any generation starts. One surface is built per catalog row and memoized. |
| [`identity.js`](./identity.js) | The pipeline engine: prompt shaping, forge/rig/render orchestration, sharp compositing (PFP head crop, 4:5 full-body frames), and the R2-persisted job state machine. |
| [`tools.js`](./tools.js) | The A2MCP face of the pipeline for `/api/okx/3d/identity-studio`: MCP tool catalog (`create_identity` paid, `identity_status` and `getting_started` free), dispatcher, x402 pricing hook, and the 402 challenge metadata indexers see. |
| [`rest-services.js`](./rest-services.js) | Engine adapters for the decomposed paid REST services (`text-to-3d`, `text-to-3d-pro`, `image-to-3d`, `rig`, `avatar`, `retarget`, `pose-seed`, `fbx-export`). Thin wrappers over engines the platform already runs, no duplicated pipeline logic. |
@@ -38,6 +43,12 @@ Prompt direction runs on the in-process LLM chain ([`../_lib/llm.js`](../_lib/ll
## Exports
+From `forge.js`:
+
+- `forgeSurface(id)` → `{ entry, challenge, dispatch, TOOLS, TOOL_CATALOG, isPublicTool, x402Amount }` for one listed forge row, or `null` for an id that is not one. The route feeds these straight into its shared A2MCP transport.
+- `isForgeService(id)` and `FORGE_SERVICE_IDS`: which catalog ids this module serves.
+- `FORGE_TOOL` (`forge_3d`) and `FORGE_STATUS_TOOL` (`forge_status`), re-exported from the catalog so tool names have one definition.
+
From `identity.js`:
- `createIdentityJob({ base?, agentName, brief, styleHints?, referenceImageUrl? })` → `{ jobId, state }`. Validates, shapes the prompt, submits generation, persists state. `jobId` is the signed token clients poll with.
@@ -62,7 +73,7 @@ Shared director prompts (single-subject mesh spec, avatar humanoid steer, brand-
## Usage
-No install step: this deploys with the rest of `api/` (see [`api/README.md`](../README.md) for routing). Buyers reach it at `https://three.ws/api/okx/3d/identity-studio` (A2MCP) and `https://three.ws/api/okx/3d/<service>` (REST); the free machine-readable index is `https://three.ws/api/okx/3d/catalog`.
+No install step: this deploys with the rest of `api/` (see [`api/README.md`](../README.md) for routing). Buyers reach the listed services at `https://three.ws/api/okx/3d/forge-{draft,standard,hd,image,status}` (A2MCP), and the back burner at `https://three.ws/api/okx/3d/identity-studio` (A2MCP) and `https://three.ws/api/okx/3d/<service>` (REST). The free machine-readable index is `https://three.ws/api/okx/3d/catalog`, where `services` is the listed line-up and `unlisted` is the back burner.
To run the real pipeline locally, use the demo driver, which imports `createIdentityJob` / `advanceIdentityJob` / `describeIdentityJob` straight from [`identity.js`](./identity.js) and executes real runs of the production pipeline for the identities in [`../../data/agent-identities.json`](../../data/agent-identities.json):
@@ -72,11 +83,12 @@ node --env-file=.env.local scripts/okx-identity-demo.mjs [slug] [--force]
It needs the `S3_*` (R2) vars from `.env.local`; generation, rigging, and rendering all run on the deployed three.ws surfaces. Results (render URLs, GLB URLs, programmatic rig verification) are written back into `data/agent-identities.json`, which powers the [/agent-identities](../../pages/agent-identities.html) showcase page. Rigging is verified for real: the rigged GLB must contain a skin with joints and skinned primitives carrying `JOINTS_0` + `WEIGHTS_0`, or the run is recorded as failed. See [`../../scripts/okx-identity-demo.mjs`](../../scripts/okx-identity-demo.mjs).
-Tests: [`tests/api/okx-identity-studio.test.js`](../../tests/api/okx-identity-studio.test.js) and [`tests/api/okx-3d-services.test.js`](../../tests/api/okx-3d-services.test.js).
+Tests: [`tests/api/okx-forge.test.js`](../../tests/api/okx-forge.test.js) (the listed line-up), [`tests/api/okx-identity-studio.test.js`](../../tests/api/okx-identity-studio.test.js) and [`tests/api/okx-3d-services.test.js`](../../tests/api/okx-3d-services.test.js).
## Related
- [`docs/okx-marketplace.md`](../../docs/okx-marketplace.md), the buyer-facing docs: endpoints, prices, payment walkthrough.
- [`api/okx/3d/[service].js`](../okx/3d/%5Bservice%5D.js), the route that fronts these engines (transport, x402, OKX 402 dialect, payment replay cache).
- [`../_lib/okx-catalog.js`](../_lib/okx-catalog.js), the single source of truth for services, prices, and schemas.
+- [`prompts/okx-ai/08-forge-relisting.md`](../../prompts/okx-ai/08-forge-relisting.md), the executable work order that resubmits agent #2632 with this line-up.
- [`STRUCTURE.md`](../../STRUCTURE.md), the OKX.AI marketplace row maps this whole surface.
diff --git a/api/_okx3d/forge.js b/api/_okx3d/forge.js
new file mode 100644
index 000000000..82b12e3f7
--- /dev/null
+++ b/api/_okx3d/forge.js
@@ -0,0 +1,369 @@
+// three.ws Forge on OKX.AI: the A2MCP surface a buying agent calls to turn a
+// prompt (or reference images) into a real, downloadable 3D model.
+//
+// This is the rebuilt marketplace listing (owner directive 2026-08-22). It
+// gives an OKX.AI agent exactly what the "three.ws 3D Studio" custom GPT gives
+// a ChatGPT user, over the marketplace's own payment rail instead of a free
+// ChatGPT Action: describe a thing, get a GLB, a concept image, a browser
+// viewer link, and a device-aware AR link that puts it in a real room.
+//
+// Why A2MCP and not plain REST: OKX lists a service as `serviceType: A2MCP`,
+// and the 2026-07-04 rejection was "your A2MCP service has not been integrated
+// with the OKX Agent Payments Protocol standard". A reviewer probing a listed
+// endpoint speaks MCP Streamable HTTP JSON-RPC and expects an unpaid paid-tool
+// call to answer a 402 whose accepts[] leads with eip155:196. So every listed
+// row is a genuine MCP server, and the paid tool is genuinely x402-gated on the
+// X Layer rail. api/okx/3d/[service].js owns the transport; this module owns
+// the tools, the prices, and the discovery metadata.
+//
+// One surface per catalog row, built from the row itself:
+//
+// forge-draft / forge-standard / forge-hd forge_3d (paid) over a text prompt
+// forge-image forge_3d (paid) over image links
+// forge-status forge_status only, always free
+//
+// Every endpoint carries the free forge_status and getting_started tools too,
+// so an agent polls the job where it paid for it and never has to discover a
+// second host mid-flight.
+//
+// It is a front, not a pipeline: generation runs through the same
+// gpt-forge-client → /api/gpt-forge lane the GPT uses, and the response is
+// shaped by the same api/_mcp-studio/studio-shape.js. The marketplace and the
+// GPT cannot drift into two different contracts over one generator.
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { makeDispatcher, PROTOCOL_VERSION } from '../_lib/mcp-dispatch.js';
+import { buildGettingStartedTool, GETTING_STARTED_TOOL } from '../_lib/mcp-getting-started.js';
+import { buildBazaarSchema } from '../_lib/x402-spec.js';
+import { withService } from '../_lib/x402/bazaar-helpers.js';
+import { catalogEntry, FORGE_TOOL, FORGE_STATUS_TOOL } from '../_lib/okx-catalog.js';
+import { startForge, pollOnce, originFromReq } from '../_mcp-studio/gpt-forge-client.js';
+import { shapeSubmit, shapePoll } from '../_mcp-studio/studio-shape.js';
+import { checkPromptSafety } from '../_mcp-studio/safety.js';
+
+export { PROTOCOL_VERSION, FORGE_TOOL, FORGE_STATUS_TOOL };
+
+const BASE = 'https://three.ws';
+const STATUS_ENDPOINT = `${BASE}/api/okx/3d/forge-status`;
+const DOCS_URL = `${BASE}/docs/okx-marketplace`;
+
+// Every listed forge row. A row not in this set is not servable here.
+export const FORGE_SERVICE_IDS = Object.freeze([
+ 'forge-draft',
+ 'forge-standard',
+ 'forge-hd',
+ 'forge-image',
+ 'forge-status',
+]);
+
+export function isForgeService(id) {
+ return FORGE_SERVICE_IDS.includes(id);
+}
+
+function toolError(code, message, extra = {}) {
+ return {
+ isError: true,
+ content: [{ type: 'text', text: `${code}: ${message}` }],
+ structuredContent: { ok: false, error: code, message, ...extra },
+ };
+}
+
+function toolOk(text, structured) {
+ return { content: [{ type: 'text', text }], structuredContent: structured };
+}
+
+// Lane failures already carry a designed code + caller-facing message from
+// gpt-forge-client. Map them to an MCP tool error the buyer can act on rather
+// than letting a generic throw become a -32603 with no recovery advice.
+function laneError(err) {
+ switch (err?.code) {
+ case 'not_configured':
+ return toolError('unavailable', '3D generation is temporarily unavailable, try again later.');
+ case 'busy':
+ return toolError('busy', err.message || 'The generator is saturated, try again shortly.', {
+ retry_after: err.retryAfter || 10,
+ });
+ case 'timeout':
+ return toolError('timeout', err.message || 'The generator took too long to accept the job, try again.', {
+ retry_after: 10,
+ });
+ case 'unknown_job':
+ return toolError('unknown_job', err.message || 'That job id is not recognized.');
+ default:
+ return toolError('generation_failed', err?.message || 'The generator could not start this job.');
+ }
+}
+
+// A pending job is polled at the free forge-status endpoint, so `poll` is a
+// real URL an agent can hit, and `poll_tool` names the JSON-RPC tool to call
+// there. Both, because buyers in this marketplace read either.
+const POLL_OPTS = { pollPath: STATUS_ENDPOINT };
+
+function withPollTool(shaped) {
+ return shaped.status === 'pending' ? { ...shaped, poll_tool: FORGE_STATUS_TOOL, poll_endpoint: STATUS_ENDPOINT } : shaped;
+}
+
+function summarize(shaped) {
+ if (shaped.status === 'done') return `Model ready. GLB: ${shaped.glbUrl}`;
+ if (shaped.status === 'error') return shaped.error;
+ const eta = shaped.etaSeconds ? ` ETA ~${shaped.etaSeconds}s.` : '';
+ return `Job accepted.${eta} Call ${FORGE_STATUS_TOOL} with job_id ${shaped.job} until status is "done".`;
+}
+
+function buildForgeTool(entry) {
+ const isImageLane = entry.lane?.mode === 'image_to_3d';
+ const priceLine = `$${entry.priceUsd} per call, charged only when the job is accepted.`;
+ return {
+ name: FORGE_TOOL,
+ title: `Forge a 3D model (paid, $${entry.priceUsd})`,
+ description:
+ `${priceLine} ${entry.describes.capability} ` +
+ `Async: returns a job_id immediately, then poll ${FORGE_STATUS_TOOL} (free) every few ` +
+ 'seconds until status is "done". Invalid input fails before settlement, so a rejected ' +
+ 'call costs nothing.',
+ annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+ inputSchema: entry.inputSchema,
+ async handler(args, _auth, req) {
+ const base = originFromReq(req);
+ const prompt = typeof args.prompt === 'string' ? args.prompt.trim() : '';
+
+ // Age-13+ content gate BEFORE any GPU work or settlement. The same
+ // gate the GPT Store surface runs; a refused prompt never settles.
+ if (prompt) {
+ const safety = checkPromptSafety(prompt);
+ if (!safety.allowed) return toolError('prompt_rejected', safety.message);
+ }
+ if (!isImageLane && !prompt) {
+ return toolError('invalid_input', 'prompt is required: describe one subject in 3 to 1000 characters.');
+ }
+
+ let job;
+ try {
+ job = await startForge(base, {
+ prompt: prompt || undefined,
+ imageUrls: isImageLane ? args.image_urls : undefined,
+ aspect: isImageLane ? '1:1' : args.aspect_ratio,
+ ...(entry.lane?.tier ? { tier: entry.lane.tier } : {}),
+ ...(entry.lane?.path ? { path: entry.lane.path } : {}),
+ });
+ } catch (err) {
+ return laneError(err);
+ }
+
+ const shaped = withPollTool(shapeSubmit(job, base, prompt, POLL_OPTS));
+ return toolOk(summarize(shaped), { ok: true, service: entry.id, ...shaped });
+ },
+ };
+}
+
+function buildStatusTool() {
+ const entry = catalogEntry('forge-status');
+ return {
+ name: FORGE_STATUS_TOOL,
+ title: 'Check a forge job (free)',
+ description:
+ 'FREE. Reports the live state of a three.ws forge job and returns the finished GLB, the ' +
+ 'concept image, a browser viewer link and an augmented-reality link once it is done. ' +
+ 'Poll every few seconds. No payment, account, or key required.',
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+ inputSchema: entry.inputSchema,
+ async handler(args, _auth, req) {
+ const base = originFromReq(req);
+ const jobId = String(args.job_id || '').trim();
+ const title = typeof args.title === 'string' ? args.title : '';
+ let data;
+ try {
+ data = await pollOnce(base, jobId);
+ } catch (err) {
+ return laneError(err);
+ }
+ const shaped = withPollTool(shapePoll(data, base, jobId, title, POLL_OPTS));
+ const body = { ok: shaped.status !== 'error', ...shaped };
+ return shaped.status === 'error'
+ ? { isError: true, content: [{ type: 'text', text: shaped.error }], structuredContent: body }
+ : toolOk(summarize(shaped), body);
+ },
+ };
+}
+
+// Endpoint-level v2 bazaar discovery entry, in the shape agentic.market's
+// validator expects. Describes a JSON-RPC 2.0 tools/call against THIS server's
+// tools and the job handle that comes back. Without it the 402 envelope
+// inherits the default that describes a different server's tools, and an agent
+// that followed it would pay and then send a call this dispatcher rejects.
+function forgeBazaarExtension(entry, paidTool) {
+ const exampleArguments = paidTool
+ ? entry.lane?.mode === 'image_to_3d'
+ ? { image_urls: [`${BASE}/og/three-ws.png`] }
+ : { prompt: 'a low-poly orange fox sitting down' }
+ : { job_id: 'f1.abc123' };
+ const exampleBody = {
+ jsonrpc: '2.0',
+ id: 1,
+ method: 'tools/call',
+ params: { name: paidTool ? FORGE_TOOL : FORGE_STATUS_TOOL, arguments: exampleArguments },
+ };
+ const exampleResponse = {
+ jsonrpc: '2.0',
+ id: 1,
+ result: {
+ content: [{ type: 'text', text: `Job accepted. Call ${FORGE_STATUS_TOOL} with job_id f1.abc123 until status is "done".` }],
+ structuredContent: {
+ ok: true,
+ status: 'pending',
+ job: 'f1.abc123',
+ poll_tool: FORGE_STATUS_TOOL,
+ poll_endpoint: STATUS_ENDPOINT,
+ format: 'glb',
+ etaSeconds: 45,
+ },
+ },
+ };
+ const toolLine = paidTool
+ ? `Tool names: ${FORGE_TOOL} (paid, $${entry.priceUsd}), ${FORGE_STATUS_TOOL} (free job polling), ${GETTING_STARTED_TOOL} (free overview).`
+ : `Tool names: ${FORGE_STATUS_TOOL} (free job polling), ${GETTING_STARTED_TOOL} (free overview).`;
+ const requestBodySchema = {
+ $schema: 'https://json-schema.org/draft/2020-12/schema',
+ type: 'object',
+ required: ['jsonrpc', 'method'],
+ properties: {
+ jsonrpc: { type: 'string', const: '2.0' },
+ id: { type: ['string', 'number'] },
+ method: {
+ type: 'string',
+ enum: ['initialize', 'tools/list', 'tools/call', 'ping'],
+ description: 'MCP JSON-RPC method.',
+ },
+ params: {
+ type: 'object',
+ description: `For tools/call: { name, arguments }. ${toolLine} See tools/list.`,
+ },
+ },
+ };
+ const responseBodySchema = {
+ $schema: 'https://json-schema.org/draft/2020-12/schema',
+ type: 'object',
+ properties: {
+ jsonrpc: { type: 'string', const: '2.0' },
+ id: { type: ['string', 'number'] },
+ result: {
+ type: 'object',
+ properties: {
+ content: {
+ type: 'array',
+ items: {
+ type: 'object',
+ required: ['type', 'text'],
+ properties: { type: { type: 'string', enum: ['text'] }, text: { type: 'string' } },
+ },
+ },
+ },
+ },
+ error: { type: 'object', properties: { code: { type: 'number' }, message: { type: 'string' } } },
+ },
+ };
+ return {
+ discoverable: true,
+ info: {
+ input: { type: 'http', method: 'POST', body: exampleBody, bodyType: 'json' },
+ output: { type: 'json', example: exampleResponse },
+ },
+ schema: buildBazaarSchema({
+ method: 'POST',
+ bodyType: 'json',
+ bodySchema: requestBodySchema,
+ outputSchema: responseBodySchema,
+ }),
+ };
+}
+
+const ajv = new Ajv({ allErrors: false, strict: false });
+addFormats(ajv);
+
+function buildSurface(id) {
+ const entry = catalogEntry(id);
+ if (!entry) throw new Error(`okx forge: no catalog entry "${id}"`);
+ const paid = entry.priceUsd !== '0';
+ const paidTool = paid ? buildForgeTool(entry) : null;
+ const statusTool = buildStatusTool();
+
+ const gettingStarted = buildGettingStartedTool({
+ server: `three.ws Forge, ${entry.name}`,
+ tagline:
+ 'Text or images to a real, downloadable 3D model (GLB), with a browser preview and an ' +
+ 'augmented-reality link that places it in a real room.',
+ tools: [paidTool, statusTool].filter(Boolean),
+ priceFor: (name) => (paid && name === FORGE_TOOL ? { amount_usdc: Number(entry.priceUsd) } : null),
+ access: paid
+ ? [
+ `Pay per call with x402 on X Layer (chain 196): $${entry.priceUsd} per ${FORGE_TOOL} call.`,
+ `${FORGE_STATUS_TOOL} and this tool are free: no payment, account, or key.`,
+ 'Full service index (free): https://three.ws/api/okx/3d/catalog',
+ ]
+ : [
+ 'Free: no payment, account, or key. Poll any three.ws forge job here.',
+ 'Full service index (free): https://three.ws/api/okx/3d/catalog',
+ ],
+ links: { docs: DOCS_URL, catalog: `${BASE}/api/okx/3d/catalog`, health: `${BASE}/api/okx/3d/health` },
+ });
+
+ const toolDefs = [gettingStarted, ...(paidTool ? [paidTool] : []), statusTool];
+ const TOOL_CATALOG = toolDefs.map(({ handler, scope, ...pub }) => pub);
+ const TOOLS = Object.fromEntries(
+ toolDefs.map((d) => [
+ d.name,
+ { scope: d.scope, handler: d.handler, validate: d.inputSchema ? ajv.compile(d.inputSchema) : null },
+ ]),
+ );
+
+ const description = paid
+ ? `three.ws Forge, ${entry.name}: A2MCP service that turns ${entry.lane?.mode === 'image_to_3d' ? 'reference images' : 'a text description'} ` +
+ `into a downloadable 3D model (GLB) with a browser viewer and an augmented-reality link. ` +
+ `$${entry.priceUsd} per call on X Layer via x402; job polling is free. Operated by three.ws.`
+ : 'three.ws Forge job status: free A2MCP service that reports the live state of any three.ws ' +
+ 'forge job and returns the finished model, viewer and augmented-reality links. Operated by three.ws.';
+
+ const challenge = {
+ description,
+ bazaar: forgeBazaarExtension(entry, paidTool),
+ ...withService({
+ serviceName: `three.ws Forge, ${entry.name}`,
+ tags: ['x402', 'mcp', '3d', 'forge', 'okx'],
+ }),
+ };
+
+ return {
+ entry,
+ challenge,
+ TOOL_CATALOG,
+ TOOLS,
+ // Free tools servable to the anonymous principal with no OAuth/x402:
+ // discovery plus status polling. The paid tool is deliberately not here.
+ isPublicTool: (name) => name === GETTING_STARTED_TOOL || name === FORGE_STATUS_TOOL,
+ // x402 price (atomic USDC string) for one tools/call, or null when free.
+ x402Amount: (toolName) => (paid && toolName === FORGE_TOOL ? entry.amountAtomics : null),
+ dispatch: makeDispatcher({
+ serverInfo: { name: `three-ws-forge-${id}`, version: '1.0.0' },
+ instructions: paid
+ ? `Call ${FORGE_TOOL} (paid, $${entry.priceUsd}) with your description, then poll ` +
+ `${FORGE_STATUS_TOOL} (free) with the returned job_id until status is "done". Call ` +
+ `${GETTING_STARTED_TOOL} (free) for the full overview.`
+ : `Call ${FORGE_STATUS_TOOL} (free) with a job_id from any three.ws forge service until ` +
+ `status is "done". Call ${GETTING_STARTED_TOOL} (free) for the full overview.`,
+ catalog: TOOL_CATALOG,
+ tools: TOOLS,
+ logName: `mcp-okx-${id}`,
+ }),
+ };
+}
+
+// One surface per listed row, built on first use and reused after: the
+// dispatcher and its compiled validators are per-endpoint immutable state.
+const surfaces = new Map();
+
+export function forgeSurface(id) {
+ if (!isForgeService(id)) return null;
+ if (!surfaces.has(id)) surfaces.set(id, buildSurface(id));
+ return surfaces.get(id);
+}
diff --git a/api/okx/3d/[service].js b/api/okx/3d/[service].js
index cce20e60a..b3d21a312 100644
--- a/api/okx/3d/[service].js
+++ b/api/okx/3d/[service].js
@@ -3,18 +3,23 @@
//
// /api/okx/3d/catalog GET, free, machine-readable service index
// /api/okx/3d/health GET, free, live subsystem health (real probes)
-// /api/okx/3d/identity-studio A2MCP (MCP Streamable HTTP): POST tool calls,
-// GET SSE, DELETE terminate. create_identity is
-// x402-priced; identity_status + getting_started
-// are free. Transport mirrors api/mcp-3d.js,
-// verify → dispatch → settle-on-success.
-// /api/okx/3d/<paid service> REST (work order 03): plain JSON POST, one
-// capability + one price per endpoint. Unpaid
-// POST → OKX-dialect 402 (PAYMENT-REQUIRED
-// header + body); paid replay → verify →
-// engine → settle → PAYMENT-RESPONSE. GET is
-// the free per-service descriptor. Engines in
-// api/_okx3d/rest-services.js.
+// /api/okx/3d/forge-draft A2MCP, the LISTED line-up (api/_okx3d/forge.js).
+// /api/okx/3d/forge-standard Each row is a real MCP Streamable HTTP server:
+// /api/okx/3d/forge-hd POST tool calls, GET SSE, DELETE terminate.
+// /api/okx/3d/forge-image forge_3d is x402-priced on the X Layer rail;
+// /api/okx/3d/forge-status forge_status + getting_started are free.
+// /api/okx/3d/identity-studio A2MCP, back burner (unlisted, still routable).
+// /api/okx/3d/<paid service> REST, back burner (unlisted, still routable):
+// plain JSON POST, one capability + one price per
+// endpoint. Unpaid POST → OKX-dialect 402
+// (PAYMENT-REQUIRED header + body); paid replay →
+// verify → engine → settle → PAYMENT-RESPONSE.
+// GET is the free per-service descriptor. Engines
+// in api/_okx3d/rest-services.js.
+//
+// Both A2MCP families share ONE transport (handleA2mcp): same challenge, verify,
+// batch pricing, single-use payment proof and settle-on-success. Only the tool
+// catalog, the price function and the discovery metadata differ per service.
import { cors, error, json, readBody, readJson, wrap } from '../../_lib/http.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import {
@@ -54,11 +59,12 @@ import {
} from '../../_mcp/auth.js';
import { sendX402Error, reservePaymentProof } from '../../_mcp/payments.js';
import {
- dispatch,
+ dispatch as identityDispatch,
PROTOCOL_VERSION,
identityX402Amount,
isPublicIdentityTool,
} from '../../_okx3d/tools.js';
+import { forgeSurface, isForgeService } from '../../_okx3d/forge.js';
import { IDENTITY_CHALLENGE } from '../../_okx3d/discovery.js';
import { invokeRestService, isRestPaidService } from '../../_okx3d/rest-services.js';
@@ -352,21 +358,26 @@ async function handleRestService(req, res, entry) {
}
}
-async function handleIdentityStudio(req, res) {
- const resourcePath = '/api/okx/3d/identity-studio';
+// One A2MCP transport, every listed MCP service. Identity Studio and each
+// forge row differ only in their tool catalog, their price function and their
+// 402 discovery metadata, so those arrive as `cfg` and the wire behaviour
+// (challenge, verify, batch pricing, single-use proof, settle-on-success)
+// stays byte-identical across endpoints. A buyer that can pay one can pay all.
+async function handleA2mcp(req, res, cfg) {
+ const { serviceId, challenge, dispatch: dispatchTool, priceForTool, isFreeName, listPrice } = cfg;
+ const resourcePath = `/api/okx/3d/${serviceId}`;
const resourceUrl = resolveResourceUrl(req, resourcePath);
- // The flagship sells on OKX.AI, so its 402 must LEAD with the X Layer
- // (eip155:196) accept, exactly like the WO-03 REST services, or an OKX
- // buyer can't pay it. Gated on the X Layer envs being present. Prepended
- // into the MCP challenge + verify path.
- const listPrice = catalogEntry('identity-studio').amountAtomics;
+ // These services sell on OKX.AI, so the 402 must LEAD with the X Layer
+ // (eip155:196) accept or an OKX buyer cannot pay it. Gated on the X Layer
+ // envs being present. Prepended into the MCP challenge + verify path.
const xlayerAcceptsFor = (amount) => (xlayerSettleable() ? [okxXLayerAccept(resourceUrl, amount)] : []);
if (req.method === 'GET' || req.method === 'HEAD')
return handleSse(req, res, {
resourcePath,
- challenge: IDENTITY_CHALLENGE,
+ challenge,
extraAccepts: xlayerAcceptsFor(listPrice),
+ x402Amount: listPrice,
});
if (req.method === 'DELETE') return handleTerminate(req, res);
if (req.method !== 'POST') return send401(res, 'method not supported');
@@ -374,8 +385,8 @@ async function handleIdentityStudio(req, res) {
const body = await readJson(req, 1_000_000);
const { totalAmount: x402Amount, allFree } = priceBatch(body, {
- priceForTool: identityX402Amount,
- isFreeName: isPublicIdentityTool,
+ priceForTool,
+ isFreeName,
});
// The X Layer accept must quote the SAME batch total the platform rails
@@ -389,7 +400,7 @@ async function handleIdentityStudio(req, res) {
const result = await authenticateRequest(req, res, {
x402Amount,
resourcePath,
- challenge: IDENTITY_CHALLENGE,
+ challenge,
allowFree: allFree || (isDiscoveryOnlyBatch(body) && !isMcpProtocolClient(req)),
extraAccepts,
});
@@ -418,7 +429,7 @@ async function handleIdentityStudio(req, res) {
// back to judging the whole batch.
const pricedIds = new Set(
batch
- .filter((m) => m?.method === 'tools/call' && identityX402Amount(m?.params?.name))
+ .filter((m) => m?.method === 'tools/call' && priceForTool(m?.params?.name))
.map((m) => m?.id)
.filter((id) => id !== undefined && id !== null),
);
@@ -441,7 +452,7 @@ async function handleIdentityStudio(req, res) {
try {
const responses = [];
for (const msg of batch) {
- const r = await dispatch(msg, auth, req);
+ const r = await dispatchTool(msg, auth, req);
if (r !== null) responses.push(r);
}
@@ -464,7 +475,7 @@ async function handleIdentityStudio(req, res) {
{
resourceUrl: x402Ctx.resourceUrl,
accepts: x402Ctx.requirements,
- challenge: IDENTITY_CHALLENGE,
+ challenge,
},
err,
);
@@ -511,7 +522,30 @@ export default wrap(async (req, res) => {
});
}
- if (service === 'identity-studio') return handleIdentityStudio(req, res);
+ if (service === 'identity-studio') {
+ return handleA2mcp(req, res, {
+ serviceId: 'identity-studio',
+ challenge: IDENTITY_CHALLENGE,
+ dispatch: identityDispatch,
+ priceForTool: identityX402Amount,
+ isFreeName: isPublicIdentityTool,
+ listPrice: catalogEntry('identity-studio').amountAtomics,
+ });
+ }
+
+ // The listed OKX.AI line-up: three.ws Forge. Every row is a real MCP server
+ // over the same transport, priced from its own catalog entry.
+ if (isForgeService(service)) {
+ const surface = forgeSurface(service);
+ return handleA2mcp(req, res, {
+ serviceId: service,
+ challenge: surface.challenge,
+ dispatch: surface.dispatch,
+ priceForTool: surface.x402Amount,
+ isFreeName: surface.isPublicTool,
+ listPrice: surface.entry.amountAtomics,
+ });
+ }
if (isRestPaidService(service)) return handleRestService(req, res, catalogEntry(service));
diff --git a/data/changelog.json b/data/changelog.json
index 09434a030..4778e491f 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,35 @@
{
"$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-24",
+ "title": "$THREE now carries its pump.fun verification badge, read live from pump.fun",
+ "summary": "pump.fun verifies a project's coin as officially belonging to that project, which is what tells a buyer the real $THREE apart from the copies that share its name and ticker. That badge now appears next to $THREE on the token page and on the holder dashboard. It is never hardcoded: the platform reads pump.fun's own verification flag on every stats request and renders the badge only while pump.fun publishes it, so a badge on three.ws always means the same thing as a badge on pump.fun.",
+ "tags": [
+ "feature",
+ "improvement"
+ ],
+ "link": "/three-token"
+ },
+ {
+ "date": "2026-08-22",
+ "title": "Our Hugging Face article, avatar rigs, and 3D viewer are now linked from the site and the docs",
+ "summary": "three.ws publishes on Hugging Face, the place the machine-learning world goes to check whether a model claim is real: a community article on giving agents bodies and wallets, a repository of rigged avatars you can download under the MIT license, and a running Space that loads them in an interactive 3D viewer. Until now nothing on the site pointed at any of it. All three are now indexed in the docs with a note on which part of the platform each one demonstrates, listed in the news feed with a working link, and the article joins the press cards at the bottom of the blog. The docs page also carries the checklist for publishing the next one.",
+ "tags": [
+ "docs",
+ "improvement"
+ ],
+ "link": "/docs/huggingface"
+ },
+ {
+ "date": "2026-08-22",
+ "title": "Any AI agent can now buy a 3D model from us in one call",
+ "summary": "Our OKX.AI marketplace listing has been rebuilt around one thing: an agent describes something, and gets back a real 3D model. Four new services (draft at one cent, standard at five, HD and image-to-3D at twenty five) plus a free job-status service, each one a proper MCP server that answers an unpaid call with a payment challenge on the marketplace's own rail. A buying agent receives exactly what our ChatGPT app gives a person: the downloadable GLB, the concept image, a browser preview, and a link that drops the model into a real room in augmented reality. Both surfaces now share one response shaper, so they can never drift apart. The identity studio and the specialist rigging and export endpoints stay live and payable, just off the listing while the forge proves itself.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/docs/okx-marketplace"
+ },
{
"date": "2026-08-22",
"title": "The README now says open source, because it is",
diff --git a/docs/okx-marketplace.md b/docs/okx-marketplace.md
index 419bcf4f5..b84e7c402 100644
--- a/docs/okx-marketplace.md
+++ b/docs/okx-marketplace.md
@@ -1,20 +1,35 @@
# OKX.AI Marketplace Services
-three.ws sells 3D services to other AI agents on [OKX.AI](https://web3.okx.com), OKX's
+three.ws sells 3D generation to other AI agents on [OKX.AI](https://web3.okx.com), OKX's
on-chain agent marketplace. Buyers are agents: they discover a service, receive an HTTP 402
payment challenge, pay in stablecoins on X Layer (or USDC on our other x402 rails), and get
-the artifact. Our marketplace entry is agent **#2632 "three.ws 3D Studio"**. That listing is
-not live yet: it was rejected in review and a resubmission is pending, so the services below
-are reachable directly at the endpoints documented here rather than through the marketplace.
-Current listing state is tracked in [`prompts/okx-ai/PROGRESS.md`](../prompts/okx-ai/PROGRESS.md).
+the artifact. Our marketplace entry is agent **#2632 "three.ws 3D Studio"**.
+
+> **Listing state.** The listing is not live yet. It was rejected in review on 2026-07-04
+> ("your A2MCP service has not been integrated with the OKX Agent Payments Protocol
+> standard") and a resubmission is pending. The services below are reachable directly at
+> the endpoints documented here in the meantime. Current state is tracked in
+> [`prompts/okx-ai/PROGRESS.md`](../prompts/okx-ai/PROGRESS.md).
+
+**What we list, as of 2026-08-22: three.ws Forge.** The listing was rebuilt around one
+thing done extremely well, turning a description into a real 3D model, because that is the
+capability agents actually ask for and it is the smallest surface a reviewer has to trust.
+An OKX.AI agent gets exactly what the "three.ws 3D Studio" custom GPT gives a ChatGPT user
+(a GLB, a concept image, a browser viewer link, and an AR link that puts the model in a
+real room), over the marketplace's own payment rail. Everything else we built for OKX.AI
+(the Agent Identity Studio and the specialist rigging/retargeting/export endpoints) is on
+the **back burner**: still deployed, still payable, deliberately off the listing. Those are
+documented at the bottom of this page.
> Related: [REST API Reference](./api-reference.md) · [MCP servers](./mcp.md) ·
-> [x402 payments](./x402.md) · seller-side protocol spec: [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md)
+> [x402 payments](./x402.md) · seller-side protocol spec:
+> [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md)
The **single source of truth** for every service (names, 2-part OKX descriptions, prices,
-endpoints, input schemas) is [`api/_lib/okx-catalog.js`](../api/_lib/okx-catalog.js), the
-free catalog endpoint below serves it verbatim, so the docs, the endpoints, and the OKX
-listing can never drift apart.
+endpoints, input schemas, and which rows are listed) is
+[`api/_lib/okx-catalog.js`](../api/_lib/okx-catalog.js). The free catalog endpoint below
+serves it verbatim and the listing submission is generated from it, so the docs, the
+endpoints, and the OKX listing cannot drift apart.
---
@@ -23,7 +38,7 @@ listing can never drift apart.
No payment, no account, no key.
```bash
-# Machine-readable index of every service
+# Machine-readable index: `services` is the listed line-up, `unlisted` is the back burner
curl https://three.ws/api/okx/3d/catalog
# Live health of the lanes behind the paid services (real probes, not a static ok)
@@ -32,107 +47,158 @@ curl https://three.ws/api/okx/3d/health
---
-## Agent Identity Studio, `$1.50` per identity
+## three.ws Forge
-**The flagship.** Turns an AI agent's brand brief into a complete 3D identity:
+Four paid services and one free one. Every row is a real **A2MCP** endpoint: MCP Streamable
+HTTP, JSON-RPC 2.0 `tools/call` over `POST`, SSE discovery on `GET`, session terminate on
+`DELETE`. The paid tool answers an unpaid call with an OKX-dialect 402 whose `accepts[]`
+**leads with `eip155:196`**, which is the OKX Agent Payments Protocol integration the
+review asked for.
-- a **square PFP** (1024 px PNG + 128 px preview) framed head-and-shoulders, sized for the
- OKX.AI avatar slot and legible at marketplace thumbnail size;
-- a **full-body render set**, three distinct poses from the three.ws pose library, studio
- lighting, consistent backdrop;
-- the **rigged, animation-ready GLB** itself (humanoid skeleton + skin weights), usable in
- three.ws scenes, games, and any glTF runtime;
-- a live [three.ws viewer](https://three.ws/viewer) link and pose-studio link.
+| Service | Price (USDT) | Endpoint | You send |
+|---|---|---|---|
+| Forge 3D Draft | $0.01 | `/api/okx/3d/forge-draft` | `prompt` |
+| Forge 3D Standard | $0.05 | `/api/okx/3d/forge-standard` | `prompt` |
+| Forge 3D HD | $0.25 | `/api/okx/3d/forge-hd` | `prompt` |
+| Forge 3D from Image | $0.25 | `/api/okx/3d/forge-image` | `image_urls[]` |
+| Forge Job Status | free | `/api/okx/3d/forge-status` | `job_id` |
-Endpoint: `https://three.ws/api/okx/3d/identity-studio`, an A2MCP service (MCP Streamable
-HTTP, JSON-RPC `tools/call`). Demo identities generated end-to-end by this pipeline:
-[three.ws/agent-identities](https://three.ws/agent-identities).
+The four paid rows differ **only** in generation lane and price. OKX prices a service, not
+a parameter, so a quality tier has to be its own row to carry its own fee. Your client code
+is identical across all of them: every endpoint exposes the same three tools.
-### 1 · Create (paid)
+| Tool | Cost | What it does |
+|---|---|---|
+| `forge_3d` | the row's price | Starts a generation, returns a `job` handle |
+| `forge_status` | free | Polls any three.ws forge job, returns the finished links |
+| `getting_started` | free | Overview of the server, its tools, prices, and links |
-An unpaid call returns the 402 challenge; pay it (e.g. `onchainos payment pay --payload …`
-on OKX rails, or any x402 client) and replay with the payment header.
+`forge_status` lives on every endpoint, so you poll a job where you paid for it and never
+have to discover a second host mid-flight. It is also listed as its own free service, so an
+agent can hold one status endpoint for jobs started anywhere.
+
+### 1 · Start a generation (paid)
+
+An unpaid call returns the 402 challenge; pay it (`onchainos payment pay --payload '<402
+body>'` on OKX rails, or any x402 client) and replay with the payment header.
```bash
-curl -sS -X POST https://three.ws/api/okx/3d/identity-studio \
+curl -sS -X POST https://three.ws/api/okx/3d/forge-standard \
-H 'content-type: application/json' \
+ -H 'PAYMENT-SIGNATURE: <the header your x402 client returned>' \
-d '{
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {
- "name": "create_identity",
- "arguments": {
- "agent_name": "LedgerLynx",
- "brief": "A meticulous on-chain accounting agent that reconciles wallets and flags anomalies in real time. Calm, precise, incorruptible.",
- "style_hints": "deep navy and silver palette, brushed-metal accents"
- }
+ "name": "forge_3d",
+ "arguments": { "prompt": "a low-poly orange fox sitting down" }
}
}'
```
-Arguments:
+Arguments for the three text rows:
| Field | Required | Notes |
| --- | --- | --- |
-| `agent_name` | yes | ≤80 chars, rendered into the identity brief |
-| `brief` | yes | any language; >2000 chars is truncated and the response flags `brief_truncated` |
-| `style_hints` | no | palette / materials / era / mood |
-| `reference_image_url` | no | public image guiding the look, validated **before** any charge |
+| `prompt` | yes | 3 to 1000 characters, one subject, its style and key colours |
+| `aspect_ratio` | no | `1:1`, `4:3`, `3:4`, `16:9`, `9:16` |
+
+`forge-image` takes `image_urls` (1 to 4 `https://` links to views of the same subject)
+plus an optional `prompt` that sharpens the reconstruction.
+
+A queued job returns:
-Success returns `{ job_id, status: "running", stage: "generate", poll_tool: "identity_status", eta_seconds }`.
+```json
+{
+ "ok": true, "service": "forge-standard", "status": "pending",
+ "job": "f1.…", "poll_tool": "forge_status",
+ "poll_endpoint": "https://three.ws/api/okx/3d/forge-status",
+ "watchUrl": "https://three.ws/watch?job=…", "format": "glb", "etaSeconds": 45
+}
+```
+
+A fast lane can finish inline instead, in which case you get the `done` body below with no
+polling at all.
-### 2 · Poll (free)
+### 2 · Poll the job (free)
```bash
-curl -sS -X POST https://three.ws/api/okx/3d/identity-studio \
+curl -sS -X POST https://three.ws/api/okx/3d/forge-status \
-H 'content-type: application/json' \
-d '{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
- "params": { "name": "identity_status", "arguments": { "job_id": "<job_id>" } }
+ "params": { "name": "forge_status", "arguments": { "job_id": "f1.…" } }
}'
```
-Each poll advances the pipeline one bounded step (generation → humanoid auto-rig → one
-studio render per poll) and reports `stage` + render progress. Poll every ~5 s; typical time
-to `done` is 3-6 minutes. When `status` is `"done"`, `deliverables` carries the PFP URLs,
-the full-body set, `rigged_glb_url`, `mesh_glb_url`, `viewer_url`, and `pose_studio_url`.
+Poll every few seconds. When `status` is `"done"`:
+
+```json
+{
+ "ok": true, "status": "done", "job": "f1.…",
+ "glbUrl": "https://…/model.glb",
+ "viewerUrl": "https://three.ws/viewer?src=…",
+ "arUrl": "https://three.ws/api/ar?src=…",
+ "previewImageUrl": "https://…/concept.png",
+ "format": "glb", "tier": "standard"
+}
+```
+
+- `glbUrl` is the model itself, a real glTF binary you can download, open in any glTF
+ runtime, or embed.
+- `viewerUrl` opens it in a browser, spinning, on any device.
+- `arUrl` is the device-aware AR launch: Scene Viewer on Android, Quick Look on iOS
+ (GLB to USDZ converted in-page), the WebGL viewer on desktop. This is the link that puts
+ the model in a human's actual room, which is usually what an agent's user wanted.
+- `previewImageUrl` is the painted concept view the forge produces before the mesh, so you
+ can show something the moment it exists.
+
+A failed job answers `status: "error"` with an actionable message. Generation failures are
+free to retry.
### Payment semantics
-Each guarantee below is enforced in code, the request path is
-`verify → dispatch → settle-on-success` ([`api/okx/3d/[service].js`](../api/okx/3d/%5Bservice%5D.js)),
-so an engine error is answered *before* settlement, and is covered by the endpoint's unit
-tests.
-
-- **You pay only when the job is accepted.** Input validation, including fetching your
- `reference_image_url`, runs before settlement; an invalid brief or unreachable image
- fails the call and **no payment settles**.
-- **Failed stages retry free.** Generation and rigging each retry up to 3 total attempts on
- transient upstream failures; renders re-run on the next poll. Only exhausted retries mark
- the job `failed`, with the last actionable error in `last_error`.
-- **Status polling is free and unauthenticated**, job tokens are HMAC-signed, so they are
- the only capability needed to read a job.
-- One payment ↔ one job: the payment proof is single-use across dispatch + settlement
+Each guarantee below is enforced in code (`verify → dispatch → settle-on-success`, in
+[`api/okx/3d/[service].js`](../api/okx/3d/%5Bservice%5D.js)) and covered by the endpoint's
+unit tests in [`tests/api/okx-forge.test.js`](../tests/api/okx-forge.test.js).
+
+- **You pay only when the job is accepted.** Input validation and the age-13+ content gate
+ run before settlement; a rejected prompt or a malformed argument fails the call and
+ **no payment settles**.
+- **Polling is free and unlimited**, on every endpoint and on the standalone status
+ service.
+- **One payment, one job.** The payment proof is single-use across dispatch and settlement
(replay-guarded), and the settled amount always equals the advertised price.
+- **Retried payments are safe.** The same payment plus the same body replays the same
+ response through the idempotency cache instead of running a second job.
+- **Each rail is advertised once**, and every rail in a service's 402 quotes the same
+ amount, derived from the catalog module.
> **Not yet demonstrated end to end.** The X Layer rail reports `settleable: true` in
-> production, but no *funded* call has settled on-chain against this endpoint yet, the payer
-> wallet is unfunded, so every real attempt returns `insufficient_balance`. Treat the bullets
-> above as the implemented and unit-tested contract, not as a claim of an observed on-chain
-> settlement. The first settled transaction hash will be recorded in
+> production, but no *funded* call has settled on-chain against these endpoints yet: the
+> payer wallet is unfunded, so every real attempt returns `insufficient_balance`. Treat the
+> bullets above as the implemented and unit-tested contract, not as a claim of an observed
+> on-chain settlement. The first settled transaction hash gets recorded in
> [`prompts/okx-ai/PROGRESS.md`](../prompts/okx-ai/PROGRESS.md).
-### Also on this endpoint (free)
+---
-- `getting_started`, overview of the server, tools, prices, and links.
-- `GET https://three.ws/api/okx/3d/identity-studio`, SSE / discovery challenge.
+## Back burner
----
+These are **not** on the OKX.AI listing and are not part of the current submission. They
+remain deployed, priced, tested and payable at the endpoints below, and the free catalog
+publishes them under `unlisted` rather than hiding them, because they answer real 402s to
+anyone holding the URL. They return to the listing once the forge rows have sales behind
+them.
-## Decomposed 3D studio services
+**Agent Identity Studio**, `$1.50`, `/api/okx/3d/identity-studio` (A2MCP). Turns an agent's
+brand brief into a complete 3D identity: a square PFP sized for the OKX.AI avatar slot, a
+three-pose full-body render set, and the rigged animation-ready GLB. Paid tool
+`create_identity`, free `identity_status` polling. Demo identities generated end to end by
+this pipeline: [three.ws/agent-identities](https://three.ws/agent-identities).
-Micro-priced, single-capability REST endpoints, plain JSON `POST`, one price each, all
-backed by the same engines the [MCP 3D studio](./mcp.md) runs (no separate pipeline).
-`GET` on any of them returns its free descriptor (price, description, input schema).
+**Single-capability REST endpoints.** Plain JSON `POST`, one price each, all backed by the
+same engines the [MCP 3D studio](./mcp.md) runs. `GET` on any of them returns its free
+descriptor (price, description, input schema).
| Service | Price (USDT) | Endpoint | You send |
|---|---|---|---|
@@ -146,119 +212,19 @@ backed by the same engines the [MCP 3D studio](./mcp.md) runs (no separate pipel
| FBX Export (rig-preserving) | $0.10 | `/api/okx/3d/fbx-export` | `model_url`, `format?` |
The buyer flow is the same for all of them: unpaid `POST` → 402 → sign
-(`onchainos payment pay --payload '<402 body>'`) → replay with
-`PAYMENT-SIGNATURE`. Generation-grade services reply `{status:"queued", job_id, poll_url}`, polling `GET https://three.ws/api/forge?job=<job_id>` is free and unlimited; fast
-services (`retarget`, `pose-seed`) reply `{status:"done", …}` inline. Settlement happens
-**after** the engine accepts the job; invalid input, the avatar humanoid gate, or an
-engine failure answers before settlement and never charges.
-
-### Text → 3D Model (GLB), $0.01
-
-Textured GLB from a text prompt on the fast draft lane. The lane leads with our self-hosted
-TRELLIS worker and falls back through Hunyuan3D, HuggingFace, and NVIDIA NIM as a last
-resort, so a single dead upstream never fails the call.
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/text-to-3d \
- -H 'content-type: application/json' \
- -d '{"prompt":"a brass steampunk owl, full body"}'
-```
-
-### Text → 3D Model (Pro), $0.30
-
-An LLM art director refines the prompt, then a higher-quality lane generates the GLB.
-`tier:"standard"` (default) or `tier:"high"` (max geometric detail + PBR textures).
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/text-to-3d-pro \
- -H 'content-type: application/json' \
- -d '{"prompt":"ornate elven longsword","tier":"high"}'
-```
-
-### Image → 3D Model, $0.30
-
-Reconstructs a textured GLB from 1-4 public photos of one object.
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/image-to-3d \
- -H 'content-type: application/json' \
- -d '{"image_urls":["https://three.ws/avatars/thumbs/default.png","https://three.ws/avatars/thumbs/cz.png"]}'
-```
-
-### GLB Auto-Rigging, $0.25
-
-Adds an animation-ready humanoid skeleton and skin weights to a static GLB (UniRig lane).
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/rig \
- -H 'content-type: application/json' \
- -d '{"glb_url":"https://three.ws/avatars/cesium-man.glb"}'
-```
-
-### Text → Rigged Avatar, $0.50
-
-Mesh generation + auto-rig in one call. Obvious non-humanoid prompts are refused **before**
-payment settles (`allow_non_humanoid: true` overrides). The paid response returns the mesh
-GLB immediately (`mesh_glb_url` + viewer link) plus the rig job to poll, a rig hiccup
-never loses the paid generation.
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/avatar \
- -H 'content-type: application/json' \
- -d '{"prompt":"a heroic knight in silver armor, full body"}'
-```
-
-### Animation Retargeting, $0.10
-
-Retargets a curated clip (idle, walk, dance, …) onto any rigged humanoid GLB, returns the
-retargeted AnimationClip JSON keyed to the rig's actual bones plus a bone-coverage report.
-Completes inside the request. Clip names are free at
-[`/animations/manifest.json`](https://three.ws/animations/manifest.json).
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/retarget \
- -H 'content-type: application/json' \
- -d '{"model_url":"https://three.ws/avatars/cz.glb","animation":"idle"}'
-```
-
-### Pose Seed, $0.02
-
-Deterministic pose resolution: natural-language description → stable seed + full
-joint-rotation map for humanoid rigs. Same prompt, same pose, every time. Completes inside
-the request.
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/pose-seed \
- -H 'content-type: application/json' \
- -d '{"prompt":"confident standing pose, arms crossed"}'
-```
-
-### FBX Export (rig-preserving), $0.10
-
-GLB → FBX for Unity/Unreal; a rigged GLB keeps its skeleton, skin weights, and blendshapes.
-Other formats: `obj`, `stl`, `ply`, `usdz`, `3mf`.
-
-```bash
-curl -i -X POST https://three.ws/api/okx/3d/fbx-export \
- -H 'content-type: application/json' \
- -d '{"model_url":"https://three.ws/avatars/cz.glb","format":"fbx"}'
-```
-
-### Guarantees (all decomposed services)
-
-- **Pay only after the job is accepted**, verify runs before the engine, settle after it;
- failure replies state explicitly that the payment was not taken.
-- **Retried payments are safe**, the same payment + body replays the same response
- (idempotency cache); a payment proof is single-use across dispatch + settlement.
-- **One service, one price**, every rail advertised in a service's 402 quotes the same
- amount, derived from the catalog module.
+(`onchainos payment pay --payload '<402 body>'`) → replay with `PAYMENT-SIGNATURE`.
+Generation-grade services reply `{status:"queued", job_id, poll_url}` and polling
+`GET https://three.ws/api/forge?job=<job_id>` is free; fast services (`retarget`,
+`pose-seed`) reply `{status:"done", …}` inline. Settlement happens **after** the engine
+accepts the job, so invalid input, the avatar humanoid gate, or an engine failure answers
+before settlement and never charges.
---
## Rails
Challenges advertise every rail the deployment can settle: **X Layer (`eip155:196`,
-USD₮0)** via the OKX facilitator for OKX.AI buyers, plus the existing Solana / Base / BSC
-USDC rails. The wire format OKX buyers use (headers `PAYMENT-REQUIRED` /
-`PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE`, scheme `exact` EIP-3009) is pinned down in
-[`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md).
+USD₮0)** first for OKX.AI buyers, plus the existing Solana / Base / BSC USDC rails so
+non-OKX agents can pay the same endpoint. The wire format OKX buyers use (headers
+`PAYMENT-REQUIRED` / `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE`, scheme `exact` EIP-3009) is
+pinned down in [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md).
diff --git a/prompts/okx-ai/08-forge-relisting.md b/prompts/okx-ai/08-forge-relisting.md
new file mode 100644
index 000000000..4fd78c43a
--- /dev/null
+++ b/prompts/okx-ai/08-forge-relisting.md
@@ -0,0 +1,130 @@
+# OKX-08: resubmit agent #2632 with the three.ws Forge listing
+
+**How to run this:** paste this whole file into a fresh Claude Code chat opened in
+`/workspaces/three.ws`, or say "execute `prompts/okx-ai/08-forge-relisting.md`". Read
+`prompts/okx-ai/00-CONTEXT.md`, the 2026-08-22 entry in `prompts/okx-ai/PROGRESS.md`,
+`prompts/okx-ai/RUNBOOK.md` and `CLAUDE.md` first.
+
+This supersedes `05-relisting-resubmission.md`, which submits the retired 11-row catalog.
+Do not run 05.
+
+## Binding operating clause
+
+1. Finish 100% of everything that is not an on-chain write or an OTP. Never end with a
+ question about scope or design.
+2. **Stop and wait only twice, batched into one message:** the email OTP for
+ `[email protected]`, and the human confirmation of the diff card before the irreversible
+ on-chain update. Both are CLAUDE.md gates that override the autonomy rule.
+3. Never deactivate or delete agent #2632. All changes go through update plus re-activate;
+ the ID, its wallet binding and its history are assets.
+4. CLAUDE.md hard rules apply. Stage explicit paths only. No em-dash or en-dash characters.
+
+## Mission
+
+Replace the seven stale services on the live listing with the seven-row three.ws Forge
+line-up, then resubmit for review. The rejection cause (an A2MCP service with no OKX Agent
+Payments Protocol integration) is resolved in code: every listed row is a real MCP
+Streamable HTTP server whose paid `forge_3d` tool answers an unpaid call with a 402 whose
+`accepts[0]` is `eip155:196`.
+
+## Step 0: gate check (autonomous)
+
+The forge endpoints must be LIVE in production before anything is submitted. They ship in
+the same container as the rest of `api/`, so this is a deploy check, not a code check.
+
+```bash
+curl -s https://three.ws/api/version # is the deployed SHA >= the rebuild?
+curl -s https://three.ws/api/okx/3d/catalog | python3 -m json.tool | head -40
+```
+
+`services` must be the seven forge/free rows and `unlisted` must hold the back burner. If
+`services` still lists `identity-studio`, production predates the rebuild: **stop, report
+that a deploy is required, and do not submit.** A listing whose endpoints 404 on a
+reviewer's probe is worse than no listing.
+
+## Step 1: be the reviewer (autonomous)
+
+Probe every advertised endpoint the way a reviewer will, with slugs read from the live
+catalog rather than from this file:
+
+```bash
+for s in $(curl -s https://three.ws/api/okx/3d/catalog \
+ | python3 -c "import sys,json;[print(x['endpoint'].rsplit('/',1)[-1]) for x in json.load(sys.stdin)['services']]"); do
+ echo "== $s"
+ curl -si -X POST "https://three.ws/api/okx/3d/$s" \
+ -H 'content-type: application/json' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"forge_3d","arguments":{"prompt":"a low-poly orange fox"}}}' \
+ | head -20
+done
+```
+
+Required results, no exceptions:
+
+1. Each of the four paid rows answers **402**, and the body's `accepts[0]` is
+ `{scheme:"exact", network:"eip155:196"}` at that row's own atomic amount. Anything else
+ is the rejection cause reappearing: stop and fix it before submitting.
+2. `accepts[]` names each rail exactly once (`mergeAccepts` in `api/_mcp/auth.js`).
+3. `forge-status` never 402s, and `tools/call getting_started` is free everywhere.
+4. `catalog` and `health` answer 200 on GET.
+5. Three-way string diff, module vs live vs submission, zero drift:
+ ```bash
+ node scripts/okx-three-copy-check.mjs
+ ```
+6. Validate the listing strings against OKX limits before you build the payload. The rules
+ are in `.agents/skills/okx-agent-identity/references/invariants.md`; read it and
+ `references/update.md` in full. Every listed row must hold: name 5 to 30 display
+ columns, each of the two description parts within 200 display columns (CJK counts 2),
+ no links, no tech-stack names, no example prompts. `npm run test -- okx-forge` enforces
+ all of it, so run the test rather than eyeballing.
+
+Known deviation to state honestly if it comes up, do not "fix" it blind: `catalog` and
+`health` are listed as `serviceType: A2MCP` (OKX has no third type) while being plain free
+GET endpoints. They carry no payment surface, so the payment-protocol requirement does not
+apply to them. If review objects specifically to these two rows, the remedy is to drop them
+from the listing, not to redesign the forge rows.
+
+## Step 2: build the delta (autonomous)
+
+```bash
+onchainos agent get-agents --agent-ids 2632
+onchainos agent service-list --agent-id 2632 \
+ | node scripts/okx-listing-payload.mjs --delta > /tmp/forge-delta.json
+python3 -m json.tool /tmp/forge-delta.json | head -60
+```
+
+Expect seven `operation: delete` entries (the stale live rows, none of whose names match
+the new catalog) and seven `operation: create` entries. If any row comes back as `update`,
+a name collided; read it before proceeding.
+
+## Step 3: the update flow (the one owner interaction)
+
+Session preflight per `00-CONTEXT.md`. Follow the `okx-agent-identity` update flow exactly:
+current state via `agent get-agents`, existing ids via `agent service-list`, then
+`agent update --agent-id 2632 --service "$(cat /tmp/forge-delta.json)"`, with `fee` as a
+plain quoted number string and `endpoint` as the per-service production URL.
+
+Agent-level fields: keep the existing name, description and OKX CDN photo URL unless
+evidence says they hurt review. A non-CDN photo link is rejected.
+
+QA is a single batch pass: run `validate-listing` exactly once over the create + update
+entries (without the `operation`/`id` keys), render findings as suggestions, and wait for
+the user's choice before applying any of them. Never re-run it.
+
+Then render the diff card and **stop for the human's confirm**. On confirm, run the update,
+then `agent activate --agent-id 2632 --preferred-language en-US` to resubmit for approval.
+
+## Step 4: record and watch (autonomous)
+
+Append a dated entry to `prompts/okx-ai/PROGRESS.md`: the delta that was submitted, the CLI
+responses verbatim, the new `approvalDisplayStatus`, and the timestamp. Then poll
+`onchainos agent get-agents --agent-ids 2632` until `approvalDisplayStatus` moves off
+"pending", and record the outcome. On a rejection, capture the exact reason (it arrives by
+email to `[email protected]`; `approvalRemark` has historically been empty) and open the next
+work order against that reason. Never respond to a rejection by creating a new agent.
+
+## Not in scope
+
+Funding. A real settled payment is a separate gate (`04-e2e-real-payment-test.md`) and is
+still blocked on the relayer and buyer wallets, both empty as of 2026-08-22. The listing
+does not require a settled payment to be submitted; do not wait on it, and do not claim a
+settlement that has not happened.
diff --git a/prompts/okx-ai/PROGRESS.md b/prompts/okx-ai/PROGRESS.md
index ee514711d..05a7025ad 100644
--- a/prompts/okx-ai/PROGRESS.md
+++ b/prompts/okx-ai/PROGRESS.md
@@ -6,6 +6,86 @@ Work Order 04 session, no earlier entries existed because no earlier work order
---
+## 2026-08-22, Listing REBUILT around the forge (owner directive): new A2MCP line-up shipped in-repo
+
+**Owner directive this session:** put the current submission on the back burner and ship
+something completely different. Everything the "three.ws 3D Studio" custom GPT does for a
+ChatGPT user, an OKX.AI agent should be able to do against three.ws/forge, over MCP or
+x402, whichever is most likely to be approved. Answer: both, because on this marketplace
+they are the same thing. A listed row is `serviceType: A2MCP`, and the 2026-07-04 rejection
+was specifically that our A2MCP service was not integrated with the OKX Agent Payments
+Protocol. So every listed row is now a genuine MCP Streamable HTTP server whose paid tool
+is genuinely x402-gated on the X Layer rail.
+
+### The new listing (7 rows, down from 11; nothing on-chain has been submitted yet)
+
+| Service | Fee | Endpoint | Tool |
+|---|---|---|---|
+| Forge 3D Draft | 0.01 | `/api/okx/3d/forge-draft` | `forge_3d` |
+| Forge 3D Standard | 0.05 | `/api/okx/3d/forge-standard` | `forge_3d` |
+| Forge 3D HD | 0.25 | `/api/okx/3d/forge-hd` | `forge_3d` |
+| Forge 3D from Image | 0.25 | `/api/okx/3d/forge-image` | `forge_3d` |
+| Forge Job Status | 0 | `/api/okx/3d/forge-status` | `forge_status` |
+| 3D Studio Service Catalog | 0 | `/api/okx/3d/catalog` | (free REST) |
+| 3D Studio Health Status | 0 | `/api/okx/3d/health` | (free REST) |
+
+Design decisions, each deliberate:
+
+- **Four paid rows for one capability.** OKX prices a service, not a parameter, so a
+ quality tier has to be its own row to carry its own fee. Buyer code stays identical:
+ every endpoint exposes the same `forge_3d` / `forge_status` / `getting_started` tools.
+- **`forge_status` is free and lives on every endpoint**, and is also its own listed row.
+ The old REST rows had no free poll on our OKX surface at all: a buyer got `queued` and
+ was sent to `/api/forge?job=`, a different, unlisted host. That is fixed.
+- **Buyers get the GPT payload.** `glbUrl`, `previewImageUrl`, `viewerUrl` and the
+ device-aware `arUrl`, because "put it in the user's actual room" is the part that sells.
+ The GPT route and the OKX tools now shape responses through ONE module
+ (`api/_mcp-studio/studio-shape.js`), so the two fronts cannot drift.
+- **Back burner, not deletion.** Identity Studio and the eight single-capability REST rows
+ carry `listed: false`. They stay deployed, tested and payable; `catalogIndex()` publishes
+ them under `unlisted` rather than hiding endpoints that answer real 402s; and
+ `scripts/okx-listing-payload.mjs` builds the submission from listed rows only, so a
+ `--delta` run turns each stale live row into an `operation: delete`.
+- **The age-13+ content gate now runs on the OKX surface too**, before any generation
+ starts, so a refused prompt can never settle.
+
+### Fixed while building (real defect, both surfaces)
+
+`accepts[]` advertised the X Layer rail **twice**. `paymentRequirements()` already emits it
+when it is configured, and the endpoint prepended it again so it would lead. Harmless to a
+payer, but it is the first array a reviewer reads. `mergeAccepts()` in `api/_mcp/auth.js`
+now keeps the first occurrence and drops later twins; Identity Studio inherited the fix.
+
+### Verified this session (no network, no chain)
+
+- `validateCatalog()` passes, and every listed row is inside OKX's limits: name 5 to 30
+ display columns, both description parts under 200.
+- Listed descriptions carry no example prompt, no link and no tech-stack name, per
+ `.agents/skills/okx-agent-identity/references/invariants.md`. A test now enforces it.
+- Unpaid `tools/call forge_3d` on all four paid endpoints answers 402 with `accepts[0]`
+ = `eip155:196`, `scheme: exact`, the row's own atomic amount, asset `0x779ded…713736`,
+ and at least one non-X-Layer rail behind it. Nothing generates on an unpaid call.
+- Free `getting_started` and `forge_status` are served with no payment on every endpoint.
+- `node scripts/okx-listing-payload.mjs` emits exactly the 7 rows above.
+- `npx vitest run tests/` : 25037 passed. The one failure,
+ `tests/multiplayer-server-boot.test.js`, is a Colyseus boot test with no path to any file
+ touched here.
+
+### Still owner-gated (unchanged, and unchanged by this rebuild)
+
+Funding. Relayer `0x1F4a753c61b54Bdec7AE0AF338A887E63Cdbbb74` needs native OKB on X Layer
+for settle gas, and buyer `0x75d00a2713565171f33216e5aa2a375e076ecf69` needs USD₮0
+(`0x779ded0c9e1022225f8e0630b35a9b54be713736`). Re-checked live on 2026-08-22: **all three
+balances are 0**. That gates a real settlement, which gates the resubmission.
+
+### Next
+
+`prompts/okx-ai/08-forge-relisting.md` is the executable work order for the resubmission.
+It needs two owner interactions and nothing else: the email OTP for `[email protected]`, and
+the diff-card confirmation before the on-chain update.
+
+---
+
## 2026-07-10, Work Order 07 (partial): RUNBOOK written, live re-verification, listing drift found
Ran the unfunded half of WO-07's Part 1 audit against production and wrote the missing
diff --git a/public/changelog.json b/public/changelog.json
index c99d68564..fd5361433 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,11 +1,43 @@
{
- "generated_at": "2026-08-22T02:40:42.490Z",
+ "generated_at": "2026-08-24T15:23:37.960Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
"entries": [
+ {
+ "date": "2026-08-24",
+ "type": "update",
+ "title": "$THREE now carries its pump.fun verification badge, read live from pump.fun",
+ "summary": "pump.fun verifies a project's coin as officially belonging to that project, which is what tells a buyer the real $THREE apart from the copies that share its name and ticker. That badge now appears next to $THREE on the token page and on the holder dashboard. It is never hardcoded: the platform reads pump.fun's own verification flag on every stats request and renders the badge only while pump.fun publishes it, so a badge on three.ws always means the same thing as a badge on pump.fun.",
+ "link": "/three-token",
+ "tags": [
+ "feature",
+ "improvement"
+ ]
+ },
+ {
+ "date": "2026-08-22",
+ "type": "update",
+ "title": "Any AI agent can now buy a 3D model from us in one call",
+ "summary": "Our OKX.AI marketplace listing has been rebuilt around one thing: an agent describes something, and gets back a real 3D model. Four new services (draft at one cent, standard at five, HD and image-to-3D at twenty five) plus a free job-status service, each one a proper MCP server that answers an unpaid call with a payment challenge on the marketplace's own rail. A buying agent receives exactly what our ChatGPT app gives a person: the downloadable GLB, the concept image, a browser preview, and a link that drops the model into a real room in augmented reality. Both surfaces now share one response shaper, so they can never drift apart. The identity studio and the specialist rigging and export endpoints stay live and payable, just off the listing while the forge proves itself.",
+ "link": "/docs/okx-marketplace",
+ "tags": [
+ "feature"
+ ]
+ },
+ {
+ "date": "2026-08-22",
+ "type": "update",
+ "title": "Our Hugging Face article, avatar rigs, and 3D viewer are now linked from the site and the docs",
+ "summary": "three.ws publishes on Hugging Face, the place the machine-learning world goes to check whether a model claim is real: a community article on giving agents bodies and wallets, a repository of rigged avatars you can download under the MIT license, and a running Space that loads them in an interactive 3D viewer. Until now nothing on the site pointed at any of it. All three are now indexed in the docs with a note on which part of the platform each one demonstrates, listed in the news feed with a working link, and the article joins the press cards at the bottom of the blog. The docs page also carries the checklist for publishing the next one.",
+ "link": "/docs/huggingface",
+ "tags": [
+ "docs",
+ "improvement"
+ ]
+ },
{
"date": "2026-08-22",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 36e1cd686..61101ca95 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -6,6 +6,30 @@
<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/>
<description>What's new on three.ws: features, improvements, and releases, newest first.</description>
<language>en</language>
+ <item>
+ <title>$THREE now carries its pump.fun verification badge, read live from pump.fun</title>
+ <link>https://three.ws/three-token</link>
+ <guid isPermaLink="false">2026-08-24:$THREE now carries its pump.fun verification badge, read live from pump.fun</guid>
+ <pubDate>Mon, 24 Aug 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>pump.fun verifies a project's coin as officially belonging to that project, which is what tells a buyer the real $THREE apart from the copies that share its name and ticker. That badge now appears next to $THREE on the token page and on the holder dashboard. It is never hardcoded: the platform reads pump.fun's own verification flag on every stats request and renders the badge only while pump.fun publishes it, so a badge on three.ws always means the same thing as a badge on pump.fun.</description>
+ </item>
+ <item>
+ <title>Any AI agent can now buy a 3D model from us in one call</title>
+ <link>https://three.ws/docs/okx-marketplace</link>
+ <guid isPermaLink="false">2026-08-22:Any AI agent can now buy a 3D model from us in one call</guid>
+ <pubDate>Sat, 22 Aug 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Our OKX.AI marketplace listing has been rebuilt around one thing: an agent describes something, and gets back a real 3D model. Four new services (draft at one cent, standard at five, HD and image-to-3D at twenty five) plus a free job-status service, each one a proper MCP server that answers an unpaid call with a payment challenge on the marketplace's own rail. A buying agent receives exactly what our ChatGPT app gives a person: the downloadable GLB, the concept image, a browser preview, and a link that drops the model into a real room in augmented reality. Both surfaces now share one response shaper, so they can never drift apart. The identity studio and the specialist rigging and export endpoints stay live and payable, just off the listing while the forge proves itself.</description>
+ </item>
+ <item>
+ <title>Our Hugging Face article, avatar rigs, and 3D viewer are now linked from the site and the docs</title>
+ <link>https://three.ws/docs/huggingface</link>
+ <guid isPermaLink="false">2026-08-22:Our Hugging Face article, avatar rigs, and 3D viewer are now linked from the site and the docs</guid>
+ <pubDate>Sat, 22 Aug 2026 12:00:00 GMT</pubDate>
+ <category>docs</category>
+ <description>three.ws publishes on Hugging Face, the place the machine-learning world goes to check whether a model claim is real: a community article on giving agents bodies and wallets, a repository of rigged avatars you can download under the MIT license, and a running Space that loads them in an interactive 3D viewer. Until now nothing on the site pointed at any of it. All three are now indexed in the docs with a note on which part of the platform each one demonstrates, listed in the news feed with a working link, and the article joins the press cards at the bottom of the blog. The docs page also carries the checklist for publishing the next one.</description>
+ </item>
<item>
<title>The README now says open source, because it is</title>
<link>https://three.ws/docs/first-contribution</link>
diff --git a/scripts/okx-e2e-gauntlet.mjs b/scripts/okx-e2e-gauntlet.mjs
index c09fabda5..4954d7175 100644
--- a/scripts/okx-e2e-gauntlet.mjs
+++ b/scripts/okx-e2e-gauntlet.mjs
@@ -32,7 +32,7 @@ import { execFileSync } from 'node:child_process';
import { mkdirSync, writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, resolve } from 'node:path';
-import { OKX_CATALOG, catalogEntry } from '../api/_lib/okx-catalog.js';
+import { catalogEntry, listedCatalog } from '../api/_lib/okx-catalog.js';
const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const EVIDENCE = resolve(REPO, 'prompts/okx-ai/e2e-evidence');
@@ -207,7 +207,8 @@ async function case1Free() {
const healthOk = health.status === 200 && healthBody.ok === true && Array.isArray(healthBody.subsystems) && healthBody.subsystems.length > 0;
const live = healthBody.subsystems?.every((s) => typeof s.latency_ms === 'number');
- const catalogOk = catalog.status === 200 && catalogBody.services?.length === OKX_CATALOG.length;
+ // `services` is the listed line-up; back-burner rows ship under `unlisted`.
+ const catalogOk = catalog.status === 200 && catalogBody.services?.length === listedCatalog().length;
record(
'1',
'free lane serves live data, no payment demanded',
diff --git a/scripts/okx-listing-payload.mjs b/scripts/okx-listing-payload.mjs
index ff670ae11..3e15d3691 100644
--- a/scripts/okx-listing-payload.mjs
+++ b/scripts/okx-listing-payload.mjs
@@ -11,16 +11,23 @@
// (write it to ~/.okx-agent-task/workspace/CLAUDE.md so the okx-a2a daemon's AI
// subsession answers marketplace chat with real catalog knowledge)
//
-// With --delta, every live service whose name is NOT in the catalog becomes an
-// "operation":"delete" entry, and every catalog row becomes either an
+// The payload is built from the LISTED rows only (`listed: true`). Back-burner
+// rows stay deployed and routable but are deliberately absent from the
+// marketplace listing, so a row demoted to `listed: false` in the catalog turns
+// into an "operation":"delete" here on the next --delta run.
+//
+// With --delta, every live service whose name is NOT in the listed catalog
+// becomes an "operation":"delete" entry, and every listed row becomes either an
// "operation":"update" (live row with the same name exists) or
// "operation":"create". Output is a single JSON array ready for --service.
-import { OKX_CATALOG, listingDescription, validateCatalog } from '../api/_lib/okx-catalog.js';
+import { listedCatalog, listingDescription, validateCatalog } from '../api/_lib/okx-catalog.js';
import { buildChatBriefing } from '../api/_lib/okx-chat-briefing.js';
validateCatalog();
+const LISTED = listedCatalog();
+
function catalogEntryToService(e) {
return {
serviceName: e.name,
@@ -40,7 +47,7 @@ if (wantBriefing) {
}
if (!wantDelta) {
- console.log(JSON.stringify(OKX_CATALOG.map(catalogEntryToService), null, 2));
+ console.log(JSON.stringify(LISTED.map(catalogEntryToService), null, 2));
process.exit(0);
}
@@ -56,7 +63,7 @@ if (!Array.isArray(live)) {
process.exit(1);
}
-const catalogByName = new Map(OKX_CATALOG.map((e) => [e.name, e]));
+const catalogByName = new Map(LISTED.map((e) => [e.name, e]));
const liveByName = new Map(live.map((s) => [s.serviceName ?? s.name, s]));
const delta = [];
@@ -73,7 +80,7 @@ for (const s of live) {
});
}
}
-for (const e of OKX_CATALOG) {
+for (const e of LISTED) {
const liveRow = liveByName.get(e.name);
const entry = catalogEntryToService(e);
if (liveRow) {
diff --git a/scripts/okx-three-copy-check.mjs b/scripts/okx-three-copy-check.mjs
index 8716b1ae9..1f8e84e9b 100644
--- a/scripts/okx-three-copy-check.mjs
+++ b/scripts/okx-three-copy-check.mjs
@@ -27,7 +27,7 @@ import { execFileSync } from 'node:child_process';
import { writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, resolve } from 'node:path';
-import { OKX_CATALOG, catalogIndex, listingDescription, validateCatalog } from '../api/_lib/okx-catalog.js';
+import { OKX_CATALOG, catalogIndex, listedCatalog, listingDescription, validateCatalog } from '../api/_lib/okx-catalog.js';
const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -46,7 +46,10 @@ const fail = (where, detail) => drift.push({ where, detail });
// Copy 1: the module must be internally valid before it is worth comparing.
validateCatalog();
-console.log(`module ${OKX_CATALOG.length} rows, validateCatalog PASS`);
+const LISTED = listedCatalog();
+console.log(
+ `module ${OKX_CATALOG.length} rows (${LISTED.length} listed, ${OKX_CATALOG.length - LISTED.length} back burner), validateCatalog PASS`,
+);
// Copy 2: the live endpoint. catalogIndex() is the exact function the route
// serializes, so a byte-identical JSON comparison is the strongest available
@@ -79,7 +82,19 @@ if (JSON.stringify(mod) === JSON.stringify(live)) {
}
liveById.delete(m.id);
}
- for (const extra of liveById.keys()) fail('live', `row "${extra}" is live but not in the module`);
+ // A row the live catalog still publishes under `services` that the module no
+ // longer lists. Distinguish the two causes: a row demoted to the back burner
+ // is expected here until the deploy lands, a row missing from the module
+ // entirely is real drift.
+ for (const extra of liveById.keys()) {
+ const known = OKX_CATALOG.find((e) => e.id === extra);
+ fail(
+ 'live',
+ known
+ ? `row "${extra}" is still listed live but is back burner in the module (deploy pending)`
+ : `row "${extra}" is live but not in the module at all`,
+ );
+ }
for (const key of ['provider', 'okxAgentId', 'chain', 'docs']) {
if (JSON.stringify(mod[key]) !== JSON.stringify(live[key])) {
fail('live', `${key}: module ${JSON.stringify(mod[key])} vs live ${JSON.stringify(live[key])}`);
@@ -95,7 +110,9 @@ const submission = JSON.parse(
console.log(`listing ${submission.length} rows from scripts/okx-listing-payload.mjs`);
const byName = new Map(submission.map((s) => [s.serviceName, s]));
-for (const row of OKX_CATALOG) {
+// The submission carries the LISTED rows only; a back-burner row is expected to
+// be absent from it, so comparing the whole module here would fail by design.
+for (const row of LISTED) {
const s = byName.get(row.name);
if (!s) {
fail('listing', `submission omits "${row.name}"`);
@@ -111,7 +128,10 @@ for (const row of OKX_CATALOG) {
for (const extra of byName.keys()) fail('listing', `submission has "${extra}" which is not in the module`);
if (args.json) {
- writeFileSync(args.json, JSON.stringify({ base: args.base, rows: OKX_CATALOG.length, drift, ok: drift.length === 0 }, null, 2));
+ writeFileSync(
+ args.json,
+ JSON.stringify({ base: args.base, rows: OKX_CATALOG.length, listed: LISTED.length, drift, ok: drift.length === 0 }, null, 2),
+ );
}
if (drift.length === 0) {
diff --git a/tests/api/okx-3d-services.test.js b/tests/api/okx-3d-services.test.js
index 9652cda36..248d49d44 100644
--- a/tests/api/okx-3d-services.test.js
+++ b/tests/api/okx-3d-services.test.js
@@ -118,6 +118,7 @@ const {
OKX_CATALOG,
catalogEntry,
catalogIndex,
+ listedCatalog,
listingDescription,
validateCatalog,
} = await import('../../api/_lib/okx-catalog.js');
@@ -205,21 +206,41 @@ describe('okx catalog — work order 03 rows', () => {
});
// OKX rejected the listing on 2026-07-26 for "missing a complete description,
- // parameter details, and usage examples". Every row now carries all three, and
- // this is the guard that keeps them from silently regressing.
- it('every row states its parameters AND shows a usage example', () => {
+ // parameter details, and usage examples". Every row states its capability and
+ // what the caller must provide, and this guard keeps that from regressing.
+ it('every row states its capability and its parameters', () => {
for (const e of OKX_CATALOG) {
expect(e.describes.capability.length, `${e.id} capability`).toBeGreaterThan(40);
- // Parameter details: the numbered "Provide:" list OKX's format asks for.
+ // Parameter details: the "Provide..." sentence OKX's format asks for.
expect(e.describes.input, `${e.id} input`).toMatch(/^Provide/);
- // Usage example: what the reviewer specifically found missing.
- expect(e.describes.input, `${e.id} usage example`).toMatch(/Example: \S/);
}
});
- it('the free catalog index carries every service 1:1', () => {
- const ids = catalogIndex().services.map((s) => s.id);
- for (const id of PAID_REST_IDS) expect(ids).toContain(id);
+ // The listing invariants (.agents/skills/okx-agent-identity/references/
+ // invariants.md) forbid example prompts, links and tech-stack names inside a
+ // service description. The back-burner rows predate that reading and are not
+ // submitted; every LISTED row must be clean, since those are the strings a
+ // reviewer actually reads.
+ it('listed rows carry no example prompt, link, or tech-stack name', () => {
+ for (const e of listedCatalog()) {
+ for (const part of [e.describes.capability, e.describes.input]) {
+ expect(part, `${e.id}`).not.toMatch(/Example:/i);
+ expect(part, `${e.id}`).not.toMatch(/https?:\/\//);
+ expect(part, `${e.id}`).not.toMatch(/\b(TRELLIS|Hunyuan|NVIDIA|GPU|MCP|x402|JSON-RPC)\b/);
+ }
+ }
+ });
+
+ // The back burner is a listing decision, not a deletion: those endpoints stay
+ // deployed and payable, so the free index still publishes them under
+ // `unlisted` rather than pretending they are gone.
+ it('the free catalog index splits listed from back-burner rows, losing none', () => {
+ const index = catalogIndex();
+ const listedIds = index.services.map((s) => s.id);
+ const unlistedIds = index.unlisted.map((s) => s.id);
+ for (const id of PAID_REST_IDS) expect(unlistedIds).toContain(id);
+ expect([...listedIds, ...unlistedIds].sort()).toEqual(OKX_CATALOG.map((e) => e.id).sort());
+ expect(listedIds).toEqual(listedCatalog().map((e) => e.id));
});
it('the paid MCP tools each service maps to exist on the studio engine', () => {
diff --git a/tests/api/okx-forge.test.js b/tests/api/okx-forge.test.js
new file mode 100644
index 000000000..1c941c99b
--- /dev/null
+++ b/tests/api/okx-forge.test.js
@@ -0,0 +1,313 @@
+/**
+ * three.ws Forge on OKX.AI, the rebuilt marketplace listing
+ * (/api/okx/3d/forge-*, tools in api/_okx3d/forge.js, catalog rows in
+ * api/_lib/okx-catalog.js).
+ *
+ * What this pins:
+ * - the LISTED line-up is the forge and nothing else, and the submission
+ * payload built from it is exactly those rows;
+ * - every paid row answers an unpaid tools/call with a 402 that LEADS with
+ * eip155:196 at that row's own price (the integration the 2026-07-04 review
+ * rejected us for missing);
+ * - the free tools (getting_started, forge_status) are served with no payment
+ * on every endpoint, so a buyer polls where it paid;
+ * - a buying agent gets the same payload the ChatGPT custom GPT gets: the GLB,
+ * the concept image, a viewer link and an AR link;
+ * - the age-13+ content gate refuses before any generation is started, so a
+ * refused prompt can never settle.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Readable } from 'node:stream';
+
+process.env.PUBLIC_APP_ORIGIN = 'https://three.ws';
+process.env.X402_PAY_TO_BASE ||= '0x0000000000000000000000000000000000000001';
+process.env.X402_ASSET_ADDRESS_BASE ||= '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+// The OKX X Layer rail. With these set, xlayerSettleable() is true and every
+// paid forge 402 must lead with eip155:196.
+process.env.X402_PAY_TO_XLAYER ||= '0x75d00a2713565171f33216e5aa2a375e076ecf69';
+process.env.X402_XLAYER_RELAYER_KEY ||=
+ '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d';
+process.env.JWT_SECRET ||= 'okx-forge-test-secret';
+
+vi.mock('../../api/_lib/auth.js', () => ({
+ extractBearer: () => null,
+ authenticateBearer: vi.fn(async () => null),
+ hasScope: () => true,
+}));
+
+vi.mock('../../api/_lib/rate-limit.js', () => ({
+ limits: {
+ mcpIp: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ mcpUser: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ },
+ clientIp: vi.fn(() => '203.0.113.9'),
+}));
+
+vi.mock('../../api/_lib/usage.js', () => ({
+ recordEvent: vi.fn(),
+ logger: () => ({ info: () => {}, warn: () => {}, error: () => {} }),
+}));
+
+// The forge lane is a pure HTTP client over /api/gpt-forge. Mock global fetch
+// with a router so nothing here touches a GPU or the network.
+const lane = { submit: null, poll: null };
+const submitted = [];
+function jsonResponse(status, body) {
+ return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+globalThis.fetch = vi.fn(async (input, init) => {
+ const url = typeof input === 'string' ? input : input.url;
+ if (url.includes('/api/gpt-forge')) {
+ if (init?.method === 'POST') {
+ submitted.push(JSON.parse(init.body));
+ return lane.submit ? lane.submit() : jsonResponse(200, { job_id: 'f1.job.abc', eta_seconds: 45 });
+ }
+ return lane.poll ? lane.poll(url) : jsonResponse(200, { status: 'running' });
+ }
+ throw new Error(`unexpected fetch: ${url}`);
+});
+
+const {
+ OKX_CATALOG,
+ catalogEntry,
+ listedCatalog,
+ validateCatalog,
+ FORGE_TOOL,
+ FORGE_STATUS_TOOL,
+} = await import('../../api/_lib/okx-catalog.js');
+const { forgeSurface, FORGE_SERVICE_IDS } = await import('../../api/_okx3d/forge.js');
+const { default: handler } = await import('../../api/okx/3d/[service].js');
+
+function makeRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: null,
+ setHeader(name, value) {
+ this.headers[String(name).toLowerCase()] = value;
+ },
+ end(body) {
+ this.body = body ?? null;
+ },
+ };
+}
+
+function makeReq({ method = 'POST', service, headers = {}, body = null } = {}) {
+ const payload = body == null ? '' : JSON.stringify(body);
+ const req = Readable.from(payload ? [Buffer.from(payload, 'utf8')] : []);
+ req.method = method;
+ req.url = `/api/okx/3d/${service}`;
+ req.query = { service };
+ req.headers = { 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9', ...headers };
+ return req;
+}
+
+function rpc(name, args, id = 1) {
+ return { jsonrpc: '2.0', id, method: 'tools/call', params: { name, arguments: args } };
+}
+
+async function post(service, body) {
+ const res = makeRes();
+ await handler(makeReq({ service, body }), res);
+ return res;
+}
+
+const anonAuth = { userId: null, rateKey: null, scope: '', source: 'free' };
+// dispatch() answers a full JSON-RPC envelope; the tool result is `.result`.
+async function callTool(service, name, args) {
+ const envelope = await forgeSurface(service).dispatch(rpc(name, args), anonAuth, { headers: {} });
+ expect(envelope.error, JSON.stringify(envelope.error)).toBeUndefined();
+ return envelope.result;
+}
+
+beforeEach(() => {
+ lane.submit = null;
+ lane.poll = null;
+ submitted.length = 0;
+});
+
+const PAID_FORGE = [
+ ['forge-draft', '10000', '0.01'],
+ ['forge-standard', '50000', '0.05'],
+ ['forge-hd', '250000', '0.25'],
+ ['forge-image', '250000', '0.25'],
+];
+
+describe('the listed line-up is the forge', () => {
+ it('validates, and every listed row is a forge row or a free discovery row', () => {
+ expect(validateCatalog()).toBe(true);
+ const listed = listedCatalog().map((e) => e.id);
+ expect(listed).toEqual([...FORGE_SERVICE_IDS, 'catalog', 'health']);
+ });
+
+ it('keeps every back-burner row deployed but out of the listing', () => {
+ const unlisted = OKX_CATALOG.filter((e) => !e.listed).map((e) => e.id);
+ expect(unlisted).toContain('identity-studio');
+ expect(unlisted).toContain('text-to-3d');
+ // Back burner is a listing decision, not a deletion: the rows still exist.
+ for (const id of unlisted) expect(catalogEntry(id).endpoint).toMatch(/^https:\/\/three\.ws\//);
+ });
+
+ it('prices each paid row from its own catalog entry, and prices the free row at nothing', () => {
+ for (const [id, atomics, usd] of PAID_FORGE) {
+ expect(catalogEntry(id).priceUsd).toBe(usd);
+ expect(forgeSurface(id).x402Amount(FORGE_TOOL)).toBe(atomics);
+ expect(forgeSurface(id).x402Amount(FORGE_STATUS_TOOL)).toBe(null);
+ expect(forgeSurface(id).x402Amount('getting_started')).toBe(null);
+ }
+ expect(forgeSurface('forge-status').x402Amount(FORGE_TOOL)).toBe(null);
+ });
+
+ it('exposes one client shape: the same tool names on every endpoint', () => {
+ for (const [id] of PAID_FORGE) {
+ const names = forgeSurface(id).TOOL_CATALOG.map((t) => t.name);
+ expect(names).toContain(FORGE_TOOL);
+ expect(names).toContain(FORGE_STATUS_TOOL);
+ expect(names).toContain('getting_started');
+ }
+ // The free row sells nothing, so it must not advertise a paid tool.
+ expect(forgeSurface('forge-status').TOOL_CATALOG.map((t) => t.name)).not.toContain(FORGE_TOOL);
+ });
+});
+
+describe('402 challenge: the OKX Agent Payments Protocol integration', () => {
+ for (const [id, atomics] of PAID_FORGE) {
+ it(`${id}: an unpaid ${FORGE_TOOL} call 402s at its own price, leading with eip155:196`, async () => {
+ const args = id === 'forge-image' ? { image_urls: ['https://three.ws/og/three-ws.png'] } : { prompt: 'a low-poly fox' };
+ const res = await post(id, rpc(FORGE_TOOL, args));
+ expect(res.statusCode).toBe(402);
+ const challenge = JSON.parse(res.body);
+ // OKX buyer CLIs auto-select accepts[0]; if it is not X Layer they cannot pay.
+ expect(challenge.accepts[0].network).toBe('eip155:196');
+ expect(challenge.accepts[0].scheme).toBe('exact');
+ expect(challenge.accepts[0].amount).toBe(atomics);
+ expect(challenge.accepts[0].asset.toLowerCase()).toBe('0x779ded0c9e1022225f8e0630b35a9b54be713736');
+ // Non-OKX agents can still pay on the legacy rails.
+ expect(challenge.accepts.slice(1).some((a) => a.network !== 'eip155:196')).toBe(true);
+ // Nothing was generated for an unpaid call.
+ expect(submitted).toHaveLength(0);
+ });
+ }
+
+ it('the 402 envelope teaches a buyer to call THIS server, not another one', async () => {
+ const res = await post('forge-draft', rpc(FORGE_TOOL, { prompt: 'a low-poly fox' }));
+ const challenge = JSON.parse(res.body);
+ const wire = JSON.stringify(challenge);
+ expect(wire).toContain(FORGE_TOOL);
+ expect(wire).toContain(FORGE_STATUS_TOOL);
+ expect(challenge.extensions?.bazaar?.info?.input?.body?.params?.name).toBe(FORGE_TOOL);
+ });
+
+ // paymentRequirements() already emits the X Layer rail when it is configured,
+ // and the endpoint prepends it again so it LEADS. Prepending alone shipped the
+ // same rail twice in accepts[], which is the first thing a marketplace
+ // reviewer reads. accepts[] must now name each rail once.
+ it('advertises each rail exactly once', async () => {
+ const res = await post('forge-draft', rpc(FORGE_TOOL, { prompt: 'a low-poly fox' }));
+ const { accepts } = JSON.parse(res.body);
+ const keys = accepts.map((a) => `${a.scheme}|${a.network}|${a.asset}|${a.amount}|${a.payTo}`);
+ expect(new Set(keys).size).toBe(keys.length);
+ expect(accepts[0].network).toBe('eip155:196');
+ });
+
+ // GET is the discovery challenge a reviewer opens first. paymentRequirements()
+ // was quoting the shared default there while the prepended rail quoted the
+ // real price, so the same rail appeared twice at two different amounts and a
+ // buyer could not tell what the endpoint charges.
+ it('the GET discovery challenge quotes the endpoint price once per rail', async () => {
+ const res = makeRes();
+ await handler(makeReq({ method: 'GET', service: 'forge-hd' }), res);
+ expect(res.statusCode).toBe(402);
+ const { accepts } = JSON.parse(res.body);
+ expect(accepts[0].network).toBe('eip155:196');
+ for (const a of accepts) expect(a.amount ?? a.maxAmountRequired).toBe('250000');
+ const rails = accepts.map((a) => `${a.scheme}|${a.network}|${a.asset}`);
+ expect(new Set(rails).size).toBe(rails.length);
+ });
+
+ it('free tools need no payment on a paid endpoint', async () => {
+ const res = await post('forge-draft', rpc('getting_started', {}));
+ expect(res.statusCode).toBe(200);
+ expect(JSON.parse(res.body).result.isError).toBeFalsy();
+ });
+
+ it('the free status endpoint never 402s', async () => {
+ lane.poll = () => jsonResponse(200, { status: 'running' });
+ const res = await post('forge-status', rpc(FORGE_STATUS_TOOL, { job_id: 'f1.job.abc' }));
+ expect(res.statusCode).toBe(200);
+ });
+});
+
+describe('what a buying agent actually receives', () => {
+ it('a queued job comes back with a pollable handle and the free tool that reads it', async () => {
+ const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a low-poly orange fox' });
+ expect(out.isError).toBeFalsy();
+ expect(out.structuredContent.status).toBe('pending');
+ expect(out.structuredContent.job).toBe('f1.job.abc');
+ expect(out.structuredContent.poll_tool).toBe(FORGE_STATUS_TOOL);
+ expect(out.structuredContent.poll_endpoint).toBe('https://three.ws/api/okx/3d/forge-status');
+ expect(out.structuredContent.etaSeconds).toBe(45);
+ });
+
+ it('a finished job carries the GLB, the browser viewer and the AR link, same as the custom GPT', async () => {
+ lane.poll = () =>
+ jsonResponse(200, {
+ status: 'done',
+ glb_url: 'https://cdn.test/fox.glb',
+ preview_image_url: 'https://cdn.test/fox.png',
+ tier: 'draft',
+ });
+ const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.job.abc', title: 'a fox' });
+ const body = out.structuredContent;
+ expect(body.status).toBe('done');
+ expect(body.glbUrl).toBe('https://cdn.test/fox.glb');
+ expect(body.viewerUrl).toContain('/viewer?src=');
+ expect(body.arUrl).toContain('/api/ar?src=');
+ expect(body.previewImageUrl).toBe('https://cdn.test/fox.png');
+ expect(body.format).toBe('glb');
+ });
+
+ it('a failed job is an error the buyer can act on, not a silent pending', async () => {
+ lane.poll = () => jsonResponse(200, { status: 'failed', error: 'upstream lane died' });
+ const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.job.abc' });
+ expect(out.isError).toBe(true);
+ expect(out.structuredContent.status).toBe('error');
+ expect(out.structuredContent.error).toBe('upstream lane died');
+ });
+
+ it('an unknown job id is reported as unknown_job rather than a generic failure', async () => {
+ lane.poll = () => jsonResponse(404, { message: 'no such job' });
+ const out = await callTool('forge-status', FORGE_STATUS_TOOL, { job_id: 'f1.nope.xyz' });
+ expect(out.isError).toBe(true);
+ expect(out.structuredContent.error).toBe('unknown_job');
+ });
+});
+
+describe('each row drives its own lane', () => {
+ it('sends the row tier to the generator, and pins the image lane to reference images', async () => {
+ await callTool('forge-draft', FORGE_TOOL, { prompt: 'a fox' });
+ expect(submitted.at(-1).tier).toBe('draft');
+ await callTool('forge-standard', FORGE_TOOL, { prompt: 'a fox' });
+ expect(submitted.at(-1).tier).toBe('standard');
+ await callTool('forge-hd', FORGE_TOOL, { prompt: 'a fox' });
+ expect(submitted.at(-1).tier).toBe('high');
+ await callTool('forge-image', FORGE_TOOL, { image_urls: ['https://cdn.test/a.png'] });
+ expect(submitted.at(-1).image_urls).toEqual(['https://cdn.test/a.png']);
+ expect(submitted.at(-1).tier).toBeUndefined();
+ });
+
+ it('rejects an unsafe prompt BEFORE any generation runs, so it can never settle', async () => {
+ const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a nude child' });
+ expect(out.isError).toBe(true);
+ expect(out.structuredContent.error).toBe('prompt_rejected');
+ expect(submitted).toHaveLength(0);
+ });
+
+ it('turns a saturated generator into an actionable busy error, never a 500', async () => {
+ lane.submit = () => jsonResponse(429, { message: 'busy', retry_after: 12 });
+ const out = await callTool('forge-draft', FORGE_TOOL, { prompt: 'a fox' });
+ expect(out.isError).toBe(true);
+ expect(out.structuredContent.error).toBe('busy');
+ expect(out.structuredContent.retry_after).toBe(12);
+ });
+});
diff --git a/tests/api/okx-identity-studio.test.js b/tests/api/okx-identity-studio.test.js
index ebaba7351..9200dc2ee 100644
--- a/tests/api/okx-identity-studio.test.js
+++ b/tests/api/okx-identity-studio.test.js
@@ -190,7 +190,7 @@ const MODEL_PNG = await _sharp(
.png()
.toBuffer();
-const { OKX_CATALOG, validateCatalog, catalogIndex, displayWidth, DESCRIPTION_MAX_WIDTH } =
+const { OKX_CATALOG, validateCatalog, catalogIndex, listedCatalog, displayWidth, DESCRIPTION_MAX_WIDTH } =
await import('../../api/_lib/okx-catalog.js');
const tools = await import('../../api/_okx3d/tools.js');
const identity = await import('../../api/_okx3d/identity.js');
@@ -248,15 +248,18 @@ describe('okx catalog module', () => {
expect(displayWidth('a中b')).toBe(4);
});
- it('prices identity-studio at $1.50 = 1500000 atomics, and the index mirrors the catalog 1:1', () => {
+ it('prices identity-studio at $1.50 = 1500000 atomics and keeps it on the back burner', () => {
const row = OKX_CATALOG.find((e) => e.id === 'identity-studio');
expect(row.amountAtomics).toBe('1500000');
expect(tools.identityX402Amount('create_identity')).toBe('1500000');
expect(tools.identityX402Amount('identity_status')).toBe(null);
expect(tools.identityX402Amount('getting_started')).toBe(null);
+ // Unlisted since the 2026-08-22 rebuild: still deployed and payable, just
+ // not part of the OKX.AI submission.
+ expect(row.listed).toBe(false);
const index = catalogIndex();
- expect(index.services.map((s) => s.id)).toEqual(OKX_CATALOG.map((e) => e.id));
- expect(index.services.find((s) => s.id === 'identity-studio').price_usd).toBe('1.50');
+ expect(index.services.map((s) => s.id)).toEqual(listedCatalog().map((e) => e.id));
+ expect(index.unlisted.find((s) => s.id === 'identity-studio').price_usd).toBe('1.50');
});
});
@@ -267,7 +270,8 @@ describe('free lanes over HTTP', () => {
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body.okxAgentId).toBe(2632);
- expect(body.services.length).toBe(OKX_CATALOG.length);
+ expect(body.services.length).toBe(listedCatalog().length);
+ expect(body.services.length + body.unlisted.length).toBe(OKX_CATALOG.length);
});
it('GET /health runs real probes and reports per-subsystem status', async () => {