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.

fix(okx): stop the 402 naming an x402 v1 header on a v2-only rail

nirholas7e1b931ea0a6
diff --git a/api/_lib/x402-xlayer-okx.js b/api/_lib/x402-xlayer-okx.js
index c7b2b965f..871bd8859 100644
--- a/api/_lib/x402-xlayer-okx.js
+++ b/api/_lib/x402-xlayer-okx.js
@@ -209,6 +209,13 @@ export function okxXLayerAccept(resourceUrl, amount) {
};
}
+// What an unpaid caller on this rail must send back. x402 v2 (which OKX
+// implements, and whose SDK reads only `payment-signature`) renamed v1's
+// `X-PAYMENT` to `PAYMENT-SIGNATURE`. Our handlers accept either header, so the
+// message names both with the v2 name first; the platform-wide default in
+// x402-spec.js still names v1 for the v1 rails that earned it.
+export const X402_HEADER_ERROR = 'PAYMENT-SIGNATURE header is required (X-PAYMENT is also accepted)';
+
// Send the OKX-dialect 402: the minimal {x402Version, resource:{url,mimeType},
// accepts[, error]} envelope as BOTH body and base64 PAYMENT-REQUIRED header.
// Deliberately not build402Body(): the OKX validator's reference sellers emit
diff --git a/api/_okx3d/discovery.js b/api/_okx3d/discovery.js
index 009b9953f..5eb75761b 100644
--- a/api/_okx3d/discovery.js
+++ b/api/_okx3d/discovery.js
@@ -11,6 +11,7 @@
import { buildBazaarSchema } from '../_lib/x402-spec.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
+import { X402_HEADER_ERROR } from '../_lib/x402-xlayer-okx.js';
import { catalogEntry } from '../_lib/okx-catalog.js';
const ENTRY = catalogEntry('identity-studio');
@@ -128,6 +129,9 @@ function identityBazaarExtension() {
// found on OKX.AI.
export const IDENTITY_CHALLENGE = {
description: RESOURCE_DESCRIPTION,
+ // Name the x402 v2 header an OKX buyer actually sends, not the v1 default.
+ // See the same override on every forge row in api/_okx3d/forge.js.
+ error: X402_HEADER_ERROR,
bazaar: identityBazaarExtension(),
...withService({
serviceName: 'three.ws Agent Identity Studio',
diff --git a/api/_okx3d/forge.js b/api/_okx3d/forge.js
index fb73ecfd4..986f2a794 100644
--- a/api/_okx3d/forge.js
+++ b/api/_okx3d/forge.js
@@ -37,6 +37,7 @@ 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 { X402_HEADER_ERROR } from '../_lib/x402-xlayer-okx.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, tierOf } from '../_mcp-studio/studio-shape.js';
@@ -472,6 +473,14 @@ function buildSurface(id) {
const challenge = {
description,
+ // The 402 body's `error` names the header the buyer must send back. The
+ // platform-wide default names `X-PAYMENT`, which is x402 **v1**; OKX
+ // buyers speak v2 and send `PAYMENT-SIGNATURE` (their SDK reads only
+ // that name). Leaving the v1 default here told a reviewer of an
+ // x402-v2 listing, in the one string they are guaranteed to read, that
+ // we implement the version we do not. Both names are accepted on the
+ // wire, so the message names both, v2 first.
+ error: X402_HEADER_ERROR,
bazaar: forgeBazaarExtension(entry, paidTool),
...withService({
serviceName: `three.ws Forge, ${entry.name}`,
diff --git a/tests/api/okx-402-dialect.test.js b/tests/api/okx-402-dialect.test.js
new file mode 100644
index 000000000..bc86d6ec0
--- /dev/null
+++ b/tests/api/okx-402-dialect.test.js
@@ -0,0 +1,50 @@
+/**
+ * The 402 dialect our OKX.AI services speak.
+ *
+ * OKX implements x402 **v2**, whose buyer header is `PAYMENT-SIGNATURE`; the
+ * platform's shared default error string names v1's `X-PAYMENT`, because the
+ * Solana/Base rails that predate this one really do read that header. Shipping
+ * the v1 default on the OKX surface told a reviewer of an x402-v2 listing, in
+ * the one string every unpaid caller reads, that we implement the version we do
+ * not, on the exact surface whose 2026-07-04 rejection was "not integrated with
+ * the OKX Agent Payments Protocol standard".
+ *
+ * This pins the override on every OKX challenge (the listed forge rows and the
+ * back-burner Identity Studio) and pins that it survives build402Body, which is
+ * what actually renders the body and the PAYMENT-REQUIRED header.
+ */
+import { describe, it, expect } from 'vitest';
+
+process.env.PUBLIC_APP_ORIGIN ||= 'https://three.ws';
+
+const { X402_HEADER_ERROR } = await import('../../api/_lib/x402-xlayer-okx.js');
+const { forgeSurface, FORGE_SERVICE_IDS } = await import('../../api/_okx3d/forge.js');
+const { IDENTITY_CHALLENGE } = await import('../../api/_okx3d/discovery.js');
+const { build402Body } = await import('../../api/_lib/x402-spec.js');
+
+describe('OKX 402 dialect', () => {
+ it('names the x402 v2 buyer header, and still accepts the v1 name', () => {
+ expect(X402_HEADER_ERROR).toMatch(/^PAYMENT-SIGNATURE header is required/);
+ expect(X402_HEADER_ERROR).toContain('X-PAYMENT');
+ });
+
+ it('every listed forge row advertises it', () => {
+ for (const id of FORGE_SERVICE_IDS) {
+ expect(forgeSurface(id).challenge.error, id).toBe(X402_HEADER_ERROR);
+ }
+ });
+
+ it('the Identity Studio advertises it too', () => {
+ expect(IDENTITY_CHALLENGE.error).toBe(X402_HEADER_ERROR);
+ });
+
+ it('survives into the rendered 402 body', async () => {
+ const body = await build402Body({
+ resourceUrl: 'https://three.ws/api/okx/3d/forge-draft',
+ accepts: [],
+ ...forgeSurface('forge-draft').challenge,
+ });
+ expect(body.x402Version).toBe(2);
+ expect(body.error).toBe(X402_HEADER_ERROR);
+ });
+});