Release v0.28.5

Origin-SHA: 15e3931443079d979fec234c42b1a1cf8102ad74

Co-authored-by: Cody <132297275+CodySearsOS@users.noreply.github.com>
Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/tool-sdk
 
+## 0.28.5
+
+### Patch Changes
+
+- f324c6d: Normalize x402 registry references to the public usage-reporting source tokens.
+
 ## 0.28.4
 
 ### Patch Changes

README.md

@@ -172,9 +172,9 @@ npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
 | `--max-amount <baseUnits>` | Reject challenges charging more than this (token base units). Pass `unlimited` to disable |
 | `--no-report-usage` | Disable the caller-side usage report sent to OpenSea after a successful payment |
 | `--api-key <key>` | API key for usage reporting (falls back to `OPENSEA_API_KEY`, then an auto-provisioned instant key) |
-| `--tool-ref <ref>` | Tool coordinates as `chainId,registryAddress,onchainId` (e.g. `8453,0x265b...2cf1,65`, or `8453,x402:bazaar,123` for x402 registries). Disambiguates usage reporting when multiple tools share one endpoint |
+| `--tool-ref <ref>` | Tool coordinates as `chainId,registryAddress,onchainId` (e.g. `8453,0x265b...2cf1,65`, or `8453,x402_bazaar,123` for x402 registries). The legacy `x402:bazaar` / `x402:bankr` forms are also accepted and normalized. Disambiguates usage reporting when multiple tools share one endpoint |
 
-When an endpoint URL maps to more than one registered tool, an endpoint-only usage report is rejected with `400 Multiple tools registered for endpoint`. Pass `--tool-ref` so the report identifies the exact tool by its composite key. The fields are comma-separated so a registry identifier that contains a colon (such as the `x402:bazaar` / `x402:bankr` registries used for tools that are not registered onchain) stays unambiguous:
+When an endpoint URL maps to more than one registered tool, an endpoint-only usage report is rejected with `400 Multiple tools registered for endpoint`. Pass `--tool-ref` so the report identifies the exact tool by its composite key. The canonical public source tokens are `x402_bazaar` and `x402_bankr`; the legacy colon forms are accepted and normalized. The fields are comma-separated so the registry identifier stays unambiguous:
 
 ```bash
 # Onchain (ERC-8257) registry:
@@ -185,7 +185,7 @@ npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
 # x402 registry (not registered onchain):
 npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
   --body '{"query":"hello"}' \
-  --tool-ref 8453,x402:bazaar,8679018179619845322
+  --tool-ref 8453,x402_bazaar,8679018179619845322
 ```
 
 ### `auth <url>`

biome.json

@@ -12,6 +12,7 @@
       "**/*.json",
       "!**/.claude",
       "!**/typechain",
+      "!lib",
       "!**/dist",
       "!**/coverage",
       "!**/.vercel",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.28.4",
+  "version": "0.28.5",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {
@@ -55,7 +55,7 @@
     "tsup": "8.5.1",
     "typescript": "6.0.2",
     "vitest": "3.2.4",
-    "@biomejs/biome": "^2.5.2"
+    "@biomejs/biome": "2.5.2"
   },
   "engines": {
     "node": ">=18.0.0"

src/__tests__/caller-reporter.test.ts

@@ -125,7 +125,7 @@ describe("reportCallerX402Usage", () => {
     })
   })
 
-  it("sends x402:bazaar registry and string onchainId in the composite key", async () => {
+  it("normalizes x402:bazaar registry in the composite key", async () => {
     const result = await reportCallerX402Usage(
       makeX402Event({
         toolChainId: 8453,
@@ -138,7 +138,7 @@ describe("reportCallerX402Usage", () => {
 
     const body = JSON.parse(fetchSpy.mock.calls[0]![1].body)
     expect(body.tool_chain_id).toBe(8453)
-    expect(body.tool_registry_address).toBe("x402:bazaar")
+    expect(body.tool_registry_address).toBe("x402_bazaar")
     expect(body.tool_onchain_id).toBe("8679018179619845322")
     expect(body.tool_endpoint).toBeUndefined()
   })

src/__tests__/pay.test.ts

@@ -32,28 +32,38 @@ describe("parseToolRef", () => {
     })
   })
 
-  it("parses an x402:bazaar registry whose name contains a colon", async () => {
+  it("normalizes an x402:bazaar registry to the public source token", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
     expect(parseToolRef("8453,x402:bazaar,8679018179619845322")).toEqual({
       toolChainId: 8453,
-      toolRegistryAddress: "x402:bazaar",
+      toolRegistryAddress: "x402_bazaar",
       toolOnchainId: "8679018179619845322",
     })
   })
 
-  it("parses an x402:bankr registry", async () => {
+  it("normalizes x402 registry names case-insensitively", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
-    expect(parseToolRef("8453,x402:bankr,5311379622895099236")).toEqual({
+    expect(parseToolRef("8453,X402:BANKR,5311379622895099236")).toEqual({
       toolChainId: 8453,
-      toolRegistryAddress: "x402:bankr",
+      toolRegistryAddress: "x402_bankr",
       toolOnchainId: "5311379622895099236",
     })
   })
 
+  it("preserves canonical x402 source tokens", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(parseToolRef("8453,x402_bazaar,123").toolRegistryAddress).toBe(
+      "x402_bazaar",
+    )
+    expect(parseToolRef("8453,x402_bankr,123").toolRegistryAddress).toBe(
+      "x402_bankr",
+    )
+  })
+
   it("preserves an onchain id beyond Number.MAX_SAFE_INTEGER as a string", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
     const big = "9007199254740993" // 2^53 + 1, not representable as a JS number
-    expect(parseToolRef(`8453,x402:bazaar,${big}`).toolOnchainId).toBe(big)
+    expect(parseToolRef(`8453,x402_bazaar,${big}`).toolOnchainId).toBe(big)
   })
 
   it("accepts onchain id 0", async () => {

src/cli/commands/pay.ts

@@ -11,6 +11,7 @@ import {
 } from "../../lib/client/x402-payment.js"
 import { toX402PaymentRequired } from "../../lib/client/x402-scheme.js"
 import { reportCallerX402Usage } from "../../lib/usage/caller-reporter.js"
+import { normalizeToolRegistryAddress } from "../../lib/usage/tool-registry.js"
 import {
   createWalletForProvider,
   createWalletFromEnv,
@@ -42,13 +43,14 @@ export interface ToolRef {
  * Parse a `--tool-ref` value of the form `chainId,registryAddress,onchainId`
  * (comma-separated, exactly three fields).
  *
- * A comma delimiter keeps the registry identifier unambiguous even when it
- * contains a colon, as the x402 registries do (`x402:bazaar`, `x402:bankr`).
+ * A comma delimiter keeps the registry identifier unambiguous, including for
+ * the legacy colon forms of the x402 registries (`x402:bazaar`,
+ * `x402:bankr`), which are accepted and normalized.
  *
  * Examples:
  *   `8453,0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1,65`  → onchain ERC-8257
- *   `8453,x402:bazaar,8679018179619845322`                → x402 bazaar tool
- *   `8453,x402:bankr,5311379622895099236`                 → x402 bankr tool
+ *   `8453,x402_bazaar,8679018179619845322`                → x402 bazaar tool
+ *   `8453,x402_bankr,5311379622895099236`                 → x402 bankr tool
  *
  * The onchainId is kept as a string to preserve precision for IDs that
  * exceed `Number.MAX_SAFE_INTEGER`.
@@ -78,7 +80,7 @@ export function parseToolRef(ref: string): ToolRef {
   }
   return {
     toolChainId,
-    toolRegistryAddress: registry,
+    toolRegistryAddress: normalizeToolRegistryAddress(registry),
     toolOnchainId: onchainStr,
   }
 }
@@ -116,7 +118,7 @@ export const payCommand = new Command("pay")
   )
   .option(
     "--tool-ref <ref>",
-    "Tool coordinates as chainId,registryAddress,onchainId (e.g. 8453,0x265b...2cf1,65 or 8453,x402:bazaar,123). Disambiguates usage reporting when multiple tools share one endpoint.",
+    "Tool coordinates as chainId,registryAddress,onchainId (e.g. 8453,0x265b...2cf1,65 or 8453,x402_bazaar,123). x402:bazaar and x402:bankr are also accepted and normalized. Disambiguates usage reporting when multiple tools share one endpoint.",
   )
   .action(async (url: string, options: PayOptions) => {
     // The x402 X-Payment signature is a gasless EIP-3009 authorization — it is

src/lib/usage/caller-reporter.ts

@@ -1,4 +1,5 @@
 import { isAddress } from "viem"
+import { normalizeToolRegistryAddress } from "./tool-registry.js"
 
 const NUMERIC_STRING_RE = /^\d+$/
 
@@ -151,7 +152,9 @@ function buildToolIdentity(
   return {
     fields: {
       tool_chain_id: event.toolChainId,
-      tool_registry_address: event.toolRegistryAddress,
+      tool_registry_address: normalizeToolRegistryAddress(
+        event.toolRegistryAddress,
+      ),
       tool_onchain_id: event.toolOnchainId,
     },
   }

src/lib/usage/tool-registry.ts

@@ -0,0 +1,10 @@
+export function normalizeToolRegistryAddress(registry: string): string {
+  switch (registry.toLowerCase()) {
+    case "x402:bazaar":
+      return "x402_bazaar"
+    case "x402:bankr":
+      return "x402_bankr"
+    default:
+      return registry
+  }
+}