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.

23.4 KB
Raw Blame

OKX.AI Marketplace Services

three.ws sells 3D generation to other AI agents on OKX.AI, 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".

Listing state, read live 2026-09-09: rejected, awaiting resubmission. The line-up below was resubmitted on 2026-08-27 (on-chain update tx 0xb4b2f51d…415ba, X Layer) and the review rejected it on 2026-09-03 over the payment leg: an OKX agentic wallet is an EIP-7702 delegated EOA and our verifier refused its signature. That is fixed and live (2026-09-05 release), OKX's own agent x402-check reads valid: true on all four paid rows, and a TEE-signed authorization is accepted end to end. The resubmission itself is an on-chain write and is the only step left. The first rejection, on 2026-07-04 ("your A2MCP service has not been integrated with the OKX Agent Payments Protocol standard"), was closed by the X Layer rail every row now leads with. Approval is not a precondition for using any of this: every endpoint documented here is deployed and answers today. Current state is tracked in prompts/finish/_context/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 · MCP servers · x402 payments · seller-side protocol spec: specs/okx-agent-payments.md

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. The free catalog endpoint below serves it verbatim and the listing submission is generated from it, so the docs and the endpoints cannot drift apart. The rows OKX stores are the one copy that is not automatic: they only change when an agent update is submitted, so npm run okx:three-copy compares them against the module and fails on the difference rather than letting it go unnoticed.

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

No payment, no account, no key.

# 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),
# including the median and p90 of the last hour's real forge_3d submits
curl https://three.ws/api/okx/3d/health

health answers 200 when every subsystem is up and 503 when one is not, so a buyer can gate on the status code alone. The payment-rail subsystem is the one worth reading before paying. It carries:

Field What it tells a buyer
settleable Whether a payment made right now could actually be collected, not merely that a rail is configured
block The X Layer block height the probe read, so the reading has an age
token The fee token's symbol(), read from the contract rather than from our config
facilitator_configured Whether settlement routes through the OKX facilitator
relayer_funded When settlement routes through our own relayer instead, whether that relayer holds the gas to broadcast the redemption. null means the relayer is not the route in use
relayer_error Present only when the relayer's balance could not be read at all, which is a different fact from a balance of zero

The row goes ok: false (and the endpoint 503) when nothing can settle, because a rail that quotes a price it cannot collect would take a payment and fail afterwards. That is the one health reading that should stop you paying.


three.ws Forge

Four paid services and one free one. Every row is a real A2MCP endpoint: MCP Streamable HTTP, JSON-RPC 2.0 over POST, session terminate on DELETE (204). 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.

POST is the whole transport here: these servers hold no server-to-client stream, so a GET is not an SSE session. On a paid row it answers the same 402 challenge (verified 2026-09-02: GET /api/okx/3d/forge-draft is 402 with or without Accept: text/event-stream), and on a free row it answers 405 with Allow: POST, DELETE, which is what the approved sellers on this marketplace answer too. Discover a row by reading the free catalog, or by calling getting_started over POST.

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

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 four tools (the free forge-status row carries the three free ones).

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
look_at_model free Renders any public https GLB from up to six angles and returns the frames as MCP image blocks, plus its geometry (triangles, materials, textures) and a plain reading of it

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.

look_at_model exists because a buying agent that receives a .glb link cannot open it. Hand it the glbUrl you were delivered and it returns pictures of the model, so the agent can check it got what it paid for before relaying the link. Arguments: glb_url (required), views (up to six of front, three-quarter, side, back, top, bottom), size (128 to 1024 px, default 512):

curl -sS -X POST https://three.ws/api/okx/3d/forge-status \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": { "name": "look_at_model",
      "arguments": { "glb_url": "https://three.ws/avatars/fox.glb", "views": ["front", "side"], "size": 256 } }
  }'
``` 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/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": "forge_3d",
      "arguments": { "prompt": "a low-poly orange fox sitting down" }
    }
  }'

Arguments for the three text rows:

Field Required Notes
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:

{
  "ok": true, "service": "forge-standard", "status": "pending",
  "job": "f1.…", "poll_tool": "forge_status",
  "poll_endpoint": "https://three.ws/api/okx/3d/forge-status",
  "poll_arguments": { "job_id": "f1.…", "title": "a low-poly orange fox sitting down" },
  "watchUrl": "https://three.ws/watch?job=…", "format": "glb", "etaSeconds": 45
}

Copy poll_arguments verbatim into the next forge_status call. The title is optional; if you drop it, the status service recovers it from the job itself.

A fast lane can finish inline instead, in which case you get the done body below with no polling at all.

2 · Poll the job (free)

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": "forge_status", "arguments": { "job_id": "f1.…" } }
  }'

Poll every few seconds. When status is "done":

{
  "ok": true, "status": "done", "job": "f1.…",
  "glbUrl": "https://…/model.glb",
  "viewerUrl": "https://three.ws/viewer?src=…",
  "arUrl": "https://three.ws/api/ar?src=…",
  "pageUrl": "https://three.ws/m/0b6d2a9e-…",
  "previewImageUrl": "https://…/concept.png",
  "format": "glb", "tier": "standard"
}

The text content of the same response lists every one of those links on its own line, so an agent that relays tool text to a human without reading structuredContent still hands over the viewer, the AR launch and the page.

  • 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.
  • pageUrl is the model's public page: the model spinning in a viewer with AR and fullscreen, download, embed code, share, comments and likes. It is the one link to hand a human when they should get everything.
  • 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 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

Each guarantee below is enforced in code (verify → dispatch → settle-on-success, in api/okx/3d/[service].js) and covered by the endpoint's unit tests in 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. 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 serving a standard mesh at the HD price. That refusal is also before settlement.
  • Delivery has to be up before you are charged. A finished mesh reaches you only once it has been copied into the delivery bucket, so a paid row checks that the bucket is writable before it hands the job to the generator. If it is not, the call answers delivery_unavailable (with charged: false and a retry_after) rather than accepting, settling, and leaving you polling a job that can never reach done. The check is cached and fails open on a transient fault, so only a credential that is deterministically rejected or missing stops the row selling.
  • A real MCP client gets a 402. The shared three.ws MCP servers answer OAuth-capable clients (Accept: text/event-stream, mcp-protocol-version) with a 401 so they can discover OAuth. The OKX.AI endpoints never do: every unpaid paid-tool call is a 402 with the PAYMENT-REQUIRED header, whatever the client sends, because the OKX buyer flow keys strictly on 402.
  • 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. That holds for every unpaid POST, not just a well-formed tools/call: a body that names no priced tool (an empty body, a plain business payload, a mistyped tool name) is quoted at the row's list price rather than falling back to the platform default, so a buyer never reads two prices for one rail.
  • A bare POST is answered with the quotation, not a content-type error. The A2MCP guide's compliance self-check is curl -i -X POST <endpoint> with no body and no content-type, and its pass condition for a paid row is HTTP 402 carrying PAYMENT-REQUIRED. Every paid row answers it that way. Unparseable bytes from a caller that is already past the paywall get the JSON-RPC parse error (-32700), and nothing settles because nothing ran.
  • Both of those are checked against the live site on demand. node scripts/okx-compliance-probe.mjs walks all four paid rows through the reviewer's probe shapes (the bodyless self-check, an empty JSON body, a plain business payload, and a well-formed priced tools/call) and exits non-zero if any 402 goes missing, duplicates a rail, or quotes anything but the row's registered list price. Point it elsewhere with --base, and capture the run with --out prompts/okx-ai/e2e-evidence/<file>.json. Run it before every listing resubmission.

Not yet demonstrated end to end. The X Layer rail reports settleable: true 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/finish/_context/okx-ai-PROGRESS.md.


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.

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.

Single-capability REST endpoints. Plain JSON POST, one price each, all backed by the same engines the MCP 3D studio runs. GET on any of them returns its free descriptor (price, description, input schema).

Service Price (USDT) Endpoint You send
Text → 3D Model (GLB) $0.01 /api/okx/3d/text-to-3d prompt
Text → 3D Model (Pro) $0.30 /api/okx/3d/text-to-3d-pro prompt, tier?
Image → 3D Model $0.30 /api/okx/3d/image-to-3d image_urls[]
GLB Auto-Rigging $0.25 /api/okx/3d/rig glb_url
Text → Rigged Avatar $0.50 /api/okx/3d/avatar prompt or image_url
Animation Retargeting $0.10 /api/okx/3d/retarget model_url, animation
Pose Seed $0.02 /api/okx/3d/pose-seed prompt
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} 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 at acceptance answers before settlement and never charges. The same acceptance line applies here as on the listed rows: a job that fails later, during generation, has been charged (see Payment semantics).


Rails

Challenges advertise every rail the deployment can settle: X Layer (eip155:196, 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.


Verified behavior

Everything above states what the code is built to do. This section states only what has been measured against production, so a buyer can tell the two apart. It is written from the end-to-end gauntlet (npm run okx:gauntlet, source scripts/okx-e2e-gauntlet.mjs), and every claim below has a capture under prompts/okx-ai/e2e-evidence/. Last run 2026-09-09 against https://three.ws.

Every claim in this section is reproducible without spending anything:

npm run okx:gauntlet -- --no-spend

That mode runs every case that cannot move money, including the ones that sign a real authorization the server is meant to refuse, and holds back every case that could pay.

Replay protection: verified. Three independent ways of presenting a payment that should not buy anything were tried against the live paid rows, and all three were refused before any work ran:

What was sent What production answered
An authorization signed for forge-draft (10000 atomic) replayed against forge-hd (250000) 402 with a fresh challenge and signed payment amount 10000 is below required 250000. The nonce was still unredeemed on X Layer afterwards.
An authorization whose validity window had passed 402, a message naming the expiry, and a complete fresh challenge to sign instead. Nonce unredeemed.
Four malformed PAYMENT-SIGNATURE headers (not base64, valid base64 of the wrong shape, empty, truncated JSON) 402 in every case, each naming what was wrong. No tool ran.

Challenge shape: verified. All four listed paid rows answer an unpaid tools/call with 402 and a PAYMENT-REQUIRED header whose first accept is eip155:196, at an amount byte-identical to the catalog price, paying the same payTo. This holds whether or not the client sends the MCP headers an OAuth-capable client would send.

Free lanes: verified. catalog and health serve live data at 200 with no payment demanded, and MCP initialize plus tools/list are free on every paid row, so a buyer can read the tool schema before deciding to pay.

Legacy rails: advertised, not yet bought. The same 402 also offers the pre-OKX rails the platform already sells on (Solana USDC, Solana $THREE, and Base), each at the same price as the X Layer accept. That the advertisement is correct is measured. That one of them still pays is not: like the X Layer rail below, no funded purchase has been made, so this is a verified advertisement and an unverified purchase, and it is listed here as exactly that.

Refund semantics: no refunds, and none are needed for a refused call. There is no refund path. What there is instead is the acceptance line described under Payment semantics: a call refused at acceptance never settles, so there is nothing to refund. That a refused call leaves the authorization unredeemed is enforced in code and covered by unit tests in tests/api/okx-forge.test.js; the on-chain half of that assertion (reading the nonce back off X Layer after a funded refusal) has not been run yet, for the reason in the next paragraph.

Settlement timing: NOT yet verified on this rail, and we will not claim otherwise. No funded payment has ever settled against these endpoints. The rail reports settleable: true on /api/okx/3d/health and the settlement path is unit-tested, but the buyer wallet has never held a balance, so there is no transaction hash to point at. This paragraph gets replaced by real hashes, amounts and block numbers the day the first one lands, and not before.