Release v0.23.0

Origin-SHA: 04996aeec60ecd5517f71b01247f6001a12fd1bd

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/tool-sdk
 
+## 0.23.0
+
+### Minor Changes
+
+- a39766d: Caller-side usage reporting can now identify a tool by its ERC-8257 composite key instead of only its endpoint URL. `reportCallerX402Usage` accepts optional `toolChainId`, `toolRegistryAddress`, and `toolOnchainId` fields, and the `pay` CLI gains a `--tool-ref <chainId:registryAddress:onchainId>` flag (e.g. `--tool-ref 8453:0x265b...2cf1:65`). When supplied, these are sent in place of `tool_endpoint`, matching the server-side reporter's payload. This fixes the `400 Multiple tools registered for endpoint` error that occurred when reporting usage for a tool whose endpoint maps to more than one registry entry.
+
 ## 0.22.0
 
 ### Minor Changes

README.md

@@ -167,7 +167,20 @@ npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
 | Flag | Description |
 |------|-------------|
 | `--body <json>` | JSON body (inline string or `@path/to/file.json`) |
+| `--method <verb>` | HTTP method (defaults to POST; falls back to GET if a POST probe 404/405s) |
 | `--wallet-provider <provider>` | Wallet provider to use for signing |
+| `--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>` | ERC-8257 tool coordinates as `chainId:registryAddress:onchainId` (e.g. `8453:0x265b...2cf1:65`). 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 onchain composite key:
+
+```bash
+npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
+  --body '{"query":"hello"}' \
+  --tool-ref 8453:0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1:65
+```
 
 ### `auth <url>`
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {

src/__tests__/caller-reporter.test.ts

@@ -99,6 +99,57 @@ describe("reportCallerX402Usage", () => {
     expect(body.latency_ms).toBe(250)
   })
 
+  it("sends the ERC-8257 composite key in place of tool_endpoint when provided", async () => {
+    const result = await reportCallerX402Usage(
+      makeX402Event({
+        toolChainId: 8453,
+        toolRegistryAddress:
+          "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1" as `0x${string}`,
+        toolOnchainId: 65,
+      }),
+      makeConfig(),
+    )
+    expect(result.outcome).toBe("reported")
+
+    const body = JSON.parse(fetchSpy.mock.calls[0]![1].body)
+    expect(body.tool_chain_id).toBe(8453)
+    expect(body.tool_registry_address).toBe(
+      "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1",
+    )
+    expect(body.tool_onchain_id).toBe(65)
+    // The composite key is sent INSTEAD of the (ambiguous) endpoint.
+    expect(body.tool_endpoint).toBeUndefined()
+    expect(body.x402).toEqual({
+      caller_address: CALLER_ADDRESS,
+      tx_hash: VALID_TX_HASH,
+      chain_id: 8453,
+    })
+  })
+
+  it("skips the report when only partial composite coordinates are given", async () => {
+    const result = await reportCallerX402Usage(
+      // chainId without registry/onchainId — must be all-or-nothing.
+      makeX402Event({ toolChainId: 8453 }),
+      makeConfig(),
+    )
+    expect(result.outcome).toBe("skipped")
+    expect(result.detail).toMatch(/coordinates/i)
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
+  it("skips the report when the composite registry address is invalid", async () => {
+    const result = await reportCallerX402Usage(
+      makeX402Event({
+        toolChainId: 8453,
+        toolRegistryAddress: "not-an-address" as `0x${string}`,
+        toolOnchainId: 65,
+      }),
+      makeConfig(),
+    )
+    expect(result.outcome).toBe("skipped")
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
   it("uses custom aggregatorUrl when provided", async () => {
     await reportCallerX402Usage(
       makeX402Event(),

src/__tests__/pay.test.ts

@@ -20,6 +20,39 @@ afterEach(() => {
   delete process.env.RPC_URL
 })
 
+describe("parseToolRef", () => {
+  const REGISTRY = "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1"
+
+  it("parses chainId:registryAddress:onchainId", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(parseToolRef(`8453:${REGISTRY}:65`)).toEqual({
+      toolChainId: 8453,
+      toolRegistryAddress: REGISTRY,
+      toolOnchainId: 65,
+    })
+  })
+
+  it("accepts onchain id 0", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(parseToolRef(`8453:${REGISTRY}:0`).toolOnchainId).toBe(0)
+  })
+
+  it("throws when the ref does not have exactly three parts", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(() => parseToolRef(`8453:${REGISTRY}`)).toThrow(/tool-ref/)
+  })
+
+  it("throws on a non-numeric chain id", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(() => parseToolRef(`base:${REGISTRY}:65`)).toThrow(/chain/i)
+  })
+
+  it("throws on an invalid registry address", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(() => parseToolRef("8453:not-an-address:65")).toThrow(/registry/i)
+  })
+})
+
 describe("pay command", () => {
   it("probes for 402 then replays with X-Payment header", async () => {
     const calls: { url: string; headers: Record<string, string> }[] = []

src/cli/commands/pay.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander"
 import pc from "picocolors"
+import { isAddress } from "viem"
 import {
   parseX402Challenge,
   resolveNetwork,
@@ -30,6 +31,48 @@ interface PayOptions {
   walletProvider?: string
   reportUsage?: boolean
   apiKey?: string
+  toolRef?: string
+}
+
+/** ERC-8257 composite key identifying a tool onchain. */
+export interface ToolRef {
+  toolChainId: number
+  toolRegistryAddress: `0x${string}`
+  toolOnchainId: number
+}
+
+/**
+ * Parse a `--tool-ref` value of the form `chainId:registryAddress:onchainId`
+ * (e.g. `8453:0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1:65`) into an ERC-8257
+ * composite key. The registry address contains no colons and both IDs are
+ * numeric, so a 3-way split is unambiguous. Throws on a malformed ref.
+ */
+export function parseToolRef(ref: string): ToolRef {
+  const parts = ref.split(":")
+  if (parts.length !== 3) {
+    throw new Error(
+      `Invalid --tool-ref "${ref}": expected chainId:registryAddress:onchainId`,
+    )
+  }
+  const [chainStr, registry, onchainStr] = parts
+  const toolChainId = Number(chainStr)
+  if (!Number.isInteger(toolChainId) || toolChainId <= 0) {
+    throw new Error(
+      `Invalid --tool-ref chain id "${chainStr}": expected a positive integer`,
+    )
+  }
+  if (!isAddress(registry)) {
+    throw new Error(
+      `Invalid --tool-ref registry address "${registry}": expected a 0x address`,
+    )
+  }
+  const toolOnchainId = Number(onchainStr)
+  if (!Number.isInteger(toolOnchainId) || toolOnchainId < 0) {
+    throw new Error(
+      `Invalid --tool-ref onchain id "${onchainStr}": expected a non-negative integer`,
+    )
+  }
+  return { toolChainId, toolRegistryAddress: registry, toolOnchainId }
 }
 
 /** HTTP verbs that carry no request body — inputs go in the query string. */
@@ -66,6 +109,10 @@ export const payCommand = new Command("pay")
     "--api-key <key>",
     "API key for usage reporting. Falls back to OPENSEA_API_KEY, then to an auto-provisioned instant key.",
   )
+  .option(
+    "--tool-ref <ref>",
+    "ERC-8257 tool coordinates as chainId:registryAddress:onchainId (e.g. 8453:0x265b...2cf1:65). 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
     // never broadcast, so no RPC is actually needed to sign. The private-key
@@ -140,6 +187,18 @@ export const payCommand = new Command("pay")
         ? undefined
         : (options.maxAmount ?? DEFAULT_MAX_AMOUNT)
 
+    let toolRef: ToolRef | undefined
+    if (options.toolRef) {
+      try {
+        toolRef = parseToolRef(options.toolRef)
+      } catch (err) {
+        console.error(
+          pc.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
+        )
+        process.exit(1)
+      }
+    }
+
     await runPaymentOnly(
       url,
       params,
@@ -150,6 +209,7 @@ export const payCommand = new Command("pay")
       // Usage reporting is on by default; `--no-report-usage` opts out.
       options.reportUsage ?? true,
       options.apiKey ?? process.env.OPENSEA_API_KEY,
+      toolRef,
     )
   })
 
@@ -201,6 +261,7 @@ async function runPaymentOnly(
   maxAmount: string | undefined,
   reportUsage: boolean,
   apiKey: string | undefined,
+  toolRef?: ToolRef,
 ): Promise<void> {
   console.log(pc.cyan("Probing endpoint for payment requirements..."))
 
@@ -336,6 +397,7 @@ async function runPaymentOnly(
           callerAddress: callerAddress as `0x${string}`,
           txHash: settlementTx,
           chainId: resolved.chainId,
+          ...toolRef,
         },
         { apiKey },
       )

src/lib/usage/caller-reporter.ts

@@ -56,6 +56,16 @@ export interface CallerX402UsageEvent {
   chainId: number
   /** Tool invocation latency in milliseconds. */
   latencyMs?: number
+  /**
+   * ERC-8257 composite key identifying the tool onchain. Provide ALL THREE to
+   * disambiguate when several tools are registered to the same endpoint URL —
+   * the aggregator rejects an endpoint-only report with 400 in that case. When
+   * present, these are sent in place of `toolEndpoint`, matching the
+   * server-side reporter's payload.
+   */
+  toolChainId?: number
+  toolRegistryAddress?: `0x${string}`
+  toolOnchainId?: number
 }
 
 export interface CallerEip3009UsageEvent {
@@ -81,6 +91,64 @@ const DEFAULT_AGGREGATOR_URL = "https://api.opensea.io/api/v2/tools/usage"
 const DEFAULT_TIMEOUT_MS = 5_000
 const TX_HASH_REGEX = /^0x[0-9a-fA-F]{64}$/
 
+/**
+ * Resolve which tool-identity fields to send: the ERC-8257 composite key when
+ * its coordinates are supplied (all three required, and valid), otherwise the
+ * endpoint URL. Returns an `error`/`detail` pair instead of throwing so the
+ * caller can record a `skipped` outcome.
+ */
+function buildToolIdentity(
+  event: CallerX402UsageEvent,
+):
+  | { fields: Record<string, unknown> }
+  | { error: string; detail: string } {
+  const hasAny =
+    event.toolChainId !== undefined ||
+    event.toolRegistryAddress !== undefined ||
+    event.toolOnchainId !== undefined
+  if (!hasAny) {
+    return { fields: { tool_endpoint: event.toolEndpoint } }
+  }
+
+  if (
+    event.toolChainId === undefined ||
+    event.toolRegistryAddress === undefined ||
+    event.toolOnchainId === undefined
+  ) {
+    return {
+      error:
+        "tool coordinates must be provided together: toolChainId, toolRegistryAddress, and toolOnchainId",
+      detail: "partial tool coordinates",
+    }
+  }
+  if (!Number.isInteger(event.toolChainId) || event.toolChainId <= 0) {
+    return {
+      error: `toolChainId must be a positive integer, got: ${event.toolChainId}`,
+      detail: "invalid toolChainId",
+    }
+  }
+  if (!isAddress(event.toolRegistryAddress)) {
+    return {
+      error: `invalid toolRegistryAddress: ${event.toolRegistryAddress}`,
+      detail: "invalid toolRegistryAddress",
+    }
+  }
+  if (!Number.isInteger(event.toolOnchainId) || event.toolOnchainId < 0) {
+    return {
+      error: `toolOnchainId must be a non-negative integer, got: ${event.toolOnchainId}`,
+      detail: "invalid toolOnchainId",
+    }
+  }
+
+  return {
+    fields: {
+      tool_chain_id: event.toolChainId,
+      tool_registry_address: event.toolRegistryAddress,
+      tool_onchain_id: event.toolOnchainId,
+    },
+  }
+}
+
 // Bounded in practice: one entry per unique origin (typically 1–2).
 const apiKeyCache = new Map<string, string>()
 const pendingProvisions = new Map<string, Promise<string | undefined>>()
@@ -179,6 +247,14 @@ export async function reportCallerX402Usage(
     return { outcome: "skipped", detail: "invalid txHash" }
   }
 
+  // Identify the tool either by its ERC-8257 composite key (preferred when an
+  // endpoint maps to multiple registered tools) or by its endpoint URL.
+  const toolIdentity = buildToolIdentity(event)
+  if ("error" in toolIdentity) {
+    console.error(`[tool-sdk] ${toolIdentity.error}`)
+    return { outcome: "skipped", detail: toolIdentity.detail }
+  }
+
   const aggregatorUrl = config.aggregatorUrl ?? DEFAULT_AGGREGATOR_URL
   if (!isSecureAggregatorUrl(aggregatorUrl)) {
     console.error(
@@ -208,7 +284,7 @@ export async function reportCallerX402Usage(
       },
       body: JSON.stringify({
         verification_type: "x402_settlement",
-        tool_endpoint: event.toolEndpoint,
+        ...toolIdentity.fields,
         latency_ms: event.latencyMs,
         x402: {
           caller_address: event.callerAddress,