Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
fix(okx): tell a charged buyer that a failed generation already settled instead of promising a free retry
nirholas5fa2cc4254b7
diff --git a/api/_mcp-studio/studio-shape.js b/api/_mcp-studio/studio-shape.jsindex 60007256e..e3e3b37e5 100644--- a/api/_mcp-studio/studio-shape.js+++ b/api/_mcp-studio/studio-shape.js@@ -71,7 +71,12 @@ export function shapeSubmit(job, base, prompt, { pollPath = STUDIO_POLL_PATH } =}// Shape a forge poll response into { status:'pending'|'done'|'error', ... }.-export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PATH } = {}) {+// `paid` says whether the surface asking is a metered one. It only changes what+// a FAILED job is told, and it has to: the free lanes really are free to retry,+// while a metered row settles the moment the lane accepts a job, so the free+// wording would tell a charged buyer something false about their money. See the+// failed branch below.+export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PATH, paid = false } = {}) {const glbUrl = typeof data?.glb_url === 'string' ? data.glb_url : '';const preview = previewOf(data);const tier = tierOf(data);@@ -88,12 +93,26 @@ export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PAT};}if (data?.status === 'failed') {+ // The message is already sanitized by /api/gpt-forge, and the lane only+ // reports a failure once its own backend failover chain is exhausted, so+ // this is terminal for THIS job. What a retry costs depends on the+ // surface, and the difference is not cosmetic: on a metered row payment+ // settles when the lane accepts the job, so the free lanes' "it costs+ // nothing to try again" would tell a buyer who was already charged+ // something false. Neither note claims anything about one particular job+ // (a status row polls any job id it is handed); each states its own+ // surface's payment model, which is what the caller has to act on. The+ // exact per-call answer is the PAYMENT-RESPONSE receipt from the submit.+ const upstream = String(data?.error || '3D generation hit a snag upstream').trim().replace(/[.!]+$/, '');+ const lanes = Array.isArray(data?.retry_backends) ? data.retry_backends.filter((b) => typeof b === 'string') : [];+ const note = paid+ ? 'Jobs here settle when the lane accepts them, so a retry is a new paid call.'+ : 'It costs nothing to try again.';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.',+ error: `${upstream}. ${note}`,+ ...(lanes.length ? { retryBackends: lanes } : {}),};}// queued / running / anything transient stays pending; keep the title on thediff --git a/api/_okx3d/forge.js b/api/_okx3d/forge.jsindex 86bd21173..53a6cb4ef 100644--- a/api/_okx3d/forge.js+++ b/api/_okx3d/forge.js@@ -106,7 +106,10 @@ function laneError(err) {// 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 };+// `paid: true` is what makes a failed-job message honest on this surface: these+// rows settle when the lane accepts the job, so the free lanes' "it costs+// nothing to try again" would be a lie told to a buyer who was already charged.+const POLL_OPTS = { pollPath: STATUS_ENDPOINT, paid: true };// Every finished creation has a public page at /m/<creation id>: the model// spinning in a viewer, AR and fullscreen, download, embed and share, commentsdiff --git a/docs/okx-marketplace.md b/docs/okx-marketplace.mdindex b722f4ef7..3e51d69b8 100644--- a/docs/okx-marketplace.md+++ b/docs/okx-marketplace.md@@ -26,12 +26,36 @@ documented at the bottom of this page.> [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,+The **single source of truth** for every service (names, OKX listing copy, prices,endpoints, input schemas, and which rows are listed) is[`api/_lib/okx-catalog.js`](../api/_lib/okx-catalog.js). The free catalog endpoint belowserves it verbatim and the listing submission is generated from it, so the docs, theendpoints, and the OKX listing cannot drift apart.+### The A2MCP listing description format++OKX listing QA requires **four** newline-separated parts on an A2MCP service and rejects a+listing missing any of them (the contract is stated in `onchainos agent update --help`).+Submitting two parts is what earned the standing review remark on agent #2632: "The service+you submitted is missing a complete description, parameter details, and usage examples."++| Part | Content | Where it comes from |+| --- | --- | --- |+| 1 | What the service does | `describes.capability` |+| 2 | Every parameter on ONE line, `;`-separated, each `<name> (<type>, required/optional): <meaning>` | generated from `inputSchema` + `describes.params` |+| 3 | Request method (`POST`/`GET`, plus the MCP tool name where there is one) | generated from `kind` + `tool` |+| 4 | A working `curl` against the real endpoint | generated from `endpoint` + `describes.example` |++Parts 2 and 4 are **derived, never hand-written**: `parameterSpec()` reads the row's own+JSON Schema, so a renamed argument renames itself in the listing, and `requestExample()`+builds the call from example arguments that the test suite validates against that same+schema. A published example the endpoint would reject cannot ship. `validateCatalog()`+fails any listed row whose schema and documented parameters disagree, whose description is+not four non-empty parts, or which exceeds OKX's 2000 half-width cap.++Back-burner rows (`listed: false`) are held to the catalog rules only; they pick up the+four-part rules when they return to the listing.+---## Free discovery lane@@ -166,8 +190,13 @@ the viewer, the AR launch and the page.- `previewImageUrl` is the painted concept view the forge produces before the mesh, so youcan show something the moment it exists.-A failed job answers `status: "error"` with an actionable message. Generation failures are-free to retry.+A failed job answers `status: "error"` with an actionable message and, when the generator can+name them, `retryBackends`: the alternate engines that can still serve this request. The lane+exhausts its own backend failover chain before it ever reports a failure, so an `error` frame+is terminal for that job. **A retry is a new paid call**: these rows settle when the lane+accepts a job (see Payment semantics below), so a job that fails during generation has been+charged. Over the 30 days to 2026-09-02, 255 of 10,278 forge jobs (2.5%) ended `failed` after+acceptance.### Payment semantics@@ -177,7 +206,9 @@ 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 gaterun before settlement; a rejected prompt or a malformed argument fails the call and- **no payment settles**.+ **no payment settles**. Acceptance is the line: once the lane takes the job the payment+ settles, so a failure that happens later, during generation, has been charged and a retry+ is a new paid call. Nothing here refunds after settlement.- **HD means HD.** If the high-detail lane will not take a job, `forge-hd` answers`tier_unavailable` (with `charged: false` and a `retry_after`) instead of quietly servinga standard mesh at the HD price. That refusal is also before settlement.diff --git a/tests/okx-chat-bot.test.js b/tests/okx-chat-bot.test.jsindex ef3a3bca4..3ddf9f23a 100644--- a/tests/okx-chat-bot.test.js+++ b/tests/okx-chat-bot.test.js@@ -9,7 +9,7 @@// Pure logic only: no daemon, no wallet, no network, no DB.import http from 'node:http';-import { existsSync } from 'node:fs';+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { join } from 'node:path';@@ -97,14 +97,18 @@ describe('okx-chat-bot session classifier', () => {});describe('okx-chat-bot provider selection', () => {+ // A host with no interactive CLI login, so these assertions read the env and+ // nothing else. mkdtemp gives a home that provably holds no credential file.+ const bare = mkdtempSync(join(tmpdir(), 'okx-bot-nohome-'));+it('prefers Claude when an Anthropic credential is present', () => {- const r = resolveProvider({ ANTHROPIC_API_KEY: 'sk-ant-x', OPENAI_API_KEY: 'sk-y' });+ const r = resolveProvider({ ANTHROPIC_API_KEY: 'sk-ant-x', OPENAI_API_KEY: 'sk-y' }, bare);expect(r.provider).toBe('claude');expect(r.credentialed).toBe(true);});it('falls back to the codex CLI when only an OpenAI key exists', () => {- const r = resolveProvider({ OPENAI_API_KEY: 'sk-y' });+ const r = resolveProvider({ OPENAI_API_KEY: 'sk-y' }, bare);expect(r.provider).toBe('codex');expect(r.credentialed).toBe(true);});@@ -112,17 +116,30 @@ describe('okx-chat-bot provider selection', () => {// A provider CLI with no key spawns, fails to authenticate, and the buyer// just sees silence. That must surface as uncredentialed, never as ready.it('reports uncredentialed rather than pretending a keyless CLI will answer', () => {- const r = resolveProvider({});+ const r = resolveProvider({}, bare);expect(r.credentialed).toBe(false);expect(classify({ ...ONLINE, providerCredentialed: r.credentialed }).ready).toBe(false);});+ // The stopgap host has no key at all: its claude CLI was logged in by a human+ // and the adapter authors replies from that grant. Calling it uncredentialed+ // is a false red on a host that demonstrably answers buyers.+ it('counts an interactive claude CLI login as a credential', () => {+ const home = mkdtempSync(join(tmpdir(), 'okx-bot-home-'));+ mkdirSync(join(home, '.claude'), { recursive: true });+ writeFileSync(join(home, '.claude', '.credentials.json'), '{}');+ const r = resolveProvider({}, home);+ expect(r).toMatchObject({ provider: 'claude', credentialed: true });+ expect(r.reason).toMatch(/interactive login/);+ rmSync(home, { recursive: true, force: true });+ });+it('honours an explicit pin and still tells the truth about its credential', () => {- expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'codex', OPENAI_API_KEY: 'k' })).toMatchObject({+ expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'codex', OPENAI_API_KEY: 'k' }, bare)).toMatchObject({provider: 'codex',credentialed: true,});- expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'claude', OPENAI_API_KEY: 'k' })).toMatchObject({+ expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'claude', OPENAI_API_KEY: 'k' }, bare)).toMatchObject({provider: 'claude',credentialed: false,});