Release v0.25.0

CodySearsOS · ryanio · CodySearsOS · commit 6a76e1d6a554 · 2026-06-27T14:49:12.000Z
Origin-SHA: 979e4028929ccbcd7847c1b91219e74a69a60b77

Co-authored-by: Ryan Ghods &lt;ryan@ryanio.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -19,7 +19,8 @@ pnpm run type-check  # TypeScript type checking
 | Path | Role |
 |------|------|
 | `src/index.ts` | Library entry point — public `tool-sdk` exports |
-| `src/cli.ts` | CLI entry point (Commander program wiring) |
+| `src/cli.ts` | CLI bin entry — imports `program` and calls `program.parse()` |
+| `src/cli/index.ts` | Commander program wiring — builds `program` and registers all commands |
 | `src/types.ts` | Shared public types |
 | `src/cli/commands/` | CLI commands: `auth`, `configure-erc20-gate`, `configure-subscription`, `configure-trait-gating`, `deploy`, `dry-run-gate`, `dry-run-predicate-gate`, `export`, `get-collections`, `get-erc20-config`, `get-trait-config`, `hash`, `init`, `inspect`, `pay`, `register`, `set-collection-tokens`, `set-collections`, `smoke`, `update-metadata`, `validate`, `verify` |
 | `src/lib/onchain/abis.ts` | TypeScript ABI definitions mirroring Solidity interfaces |
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @opensea/tool-sdk
 
+## 0.25.0
+
+### Minor Changes
+
+- 5deb6c1: The `register` command now validates that the manifest URL and declared endpoint share the same origin before sending the onchain transaction. Previously only `verify` and `deploy` checked this, so a developer could burn gas registering a tool the indexer would immediately reject. All three commands (`register`, `verify`, `deploy`) now show a consistent, actionable error message that explicitly calls out subdomains as different origins and explains how to fix it.
+
 ## 0.24.0
 
 ### Minor Changes
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {
diff --git a/skill/SKILL.md b/skill/SKILL.md
@@ -48,14 +48,25 @@ This SDK is for tool *providers and consumers*. To query OpenSea marketplace dat
 
 | Term | Meaning |
 |------|---------|
-| **Tool** | An HTTPS endpoint with a JSON Schema interface, discoverable via `/.well-known/ai-tool/<slug>.json` |
+| **Tool** | A single REST API endpoint with a JSON Schema interface, discoverable via `/.well-known/ai-tool/<slug>.json`. Each tool should perform one focused operation. |
 | **Manifest** | JCS-canonicalized JSON describing the tool's name, endpoint, inputs, outputs, pricing, and access policy |
 | **ToolRegistry** | Onchain contract (Base) where tools are registered with a manifest hash and optional access predicate |
 | **Access Predicate** | An `IAccessPredicate` contract that gates who can invoke a tool (NFT ownership, subscriptions, trait gating, ERC-20 balance, composites) |
 | **x402** | HTTP 402-based pay-per-call protocol (caller signs a USDC `TransferWithAuthorization`; server settles after execution) |
 | **EIP-3009 auth** | Zero-value USDC `TransferWithAuthorization` signature used to authenticate callers for predicate-gated tools |
 | **Facilitator** | Third-party service that verifies and settles x402 payments (PayAI or Coinbase CDP) |
 
+## Important Constraints
+
+**One tool = one endpoint.** Each tool registration represents a single REST API endpoint with a singular focus and intention. The endpoint URL in your manifest should point to a specific API route that performs one well-defined operation (e.g., `POST /api/price-check` or `POST /api/translate`), not a generic HTML page, documentation site, or multi-purpose URL. Think of each registered tool the same way you think of an individual REST API endpoint. It should accept a specific input, perform a specific action, and return a specific output.
+
+**Origin binding: manifest and endpoint must share the exact same origin.** Your `.well-known/ai-tool/<slug>.json` manifest and your tool's invocation endpoint must be served from the exact same origin (identical scheme, host, and port per [RFC 6454](https://datatracker.ietf.org/doc/html/rfc6454)). **Subdomains do not count as the same origin.** `example.com` and `api.example.com` are different origins. This is enforced at registration time. If the manifest origin and endpoint origin don't match exactly, the tool will be rejected and marked as deregistered.
+
+- Valid: manifest at `https://my-tool.example.com/.well-known/ai-tool/my-tool.json`, endpoint at `https://my-tool.example.com/api/my-tool`
+- Invalid: manifest at `https://example.com/.well-known/ai-tool/my-tool.json`, endpoint at `https://api.example.com/api/my-tool`
+
+If you need your API on a subdomain, serve the manifest from that same subdomain (e.g., both on `api.example.com`).
+
 ## Deployed Contracts (Ethereum mainnet, Base, Shape, Abstract)
 
 Canonical v0.2 deployments — identical CREATE2 address on every supported chain.
diff --git a/src/cli/commands/deploy.ts b/src/cli/commands/deploy.ts
@@ -500,9 +500,29 @@ async function deployToVercel(options: DeployOptions): Promise<void> {
     const manifestOrigin = new URL(manifestUrl).origin
     const endpointOrigin = new URL(manifest.endpoint).origin
     if (manifestOrigin !== endpointOrigin) {
-      console.error(pc.red("Error: Origin mismatch (anti-impersonation check)"))
-      console.error(pc.dim(`  Manifest served from: ${manifestOrigin}`))
-      console.error(pc.dim(`  Endpoint origin: ${endpointOrigin}`))
+      console.error(
+        pc.red(
+          "Error: Origin mismatch between manifest URL and declared endpoint",
+        ),
+      )
+      console.error(pc.dim(`  Manifest origin:  ${manifestOrigin}`))
+      console.error(pc.dim(`  Endpoint origin:  ${endpointOrigin}`))
+      console.error()
+      console.error(
+        pc.yellow(
+          "  The manifest and endpoint must be served from the exact same origin (scheme + host + port).",
+        ),
+      )
+      console.error(
+        pc.yellow(
+          "  Subdomains count as different origins (e.g. example.com ≠ api.example.com).",
+        ),
+      )
+      console.error(
+        pc.yellow(
+          "  Move your manifest or endpoint so both share the same host, then retry.",
+        ),
+      )
       process.exit(1)
     }
 
diff --git a/src/cli/commands/register.ts b/src/cli/commands/register.ts
@@ -209,6 +209,36 @@ export const registerCommand = new Command("register")
     warnBareExtensionKeys(data)
 
     const manifest = result.data
+
+    const manifestOrigin = new URL(options.metadata).origin
+    const endpointOrigin = new URL(manifest.endpoint).origin
+    if (manifestOrigin !== endpointOrigin) {
+      console.error(
+        pc.red(
+          "Error: Origin mismatch between manifest URL and declared endpoint",
+        ),
+      )
+      console.error(pc.dim(`  Manifest origin:  ${manifestOrigin}`))
+      console.error(pc.dim(`  Endpoint origin:  ${endpointOrigin}`))
+      console.error()
+      console.error(
+        pc.yellow(
+          "  The manifest and endpoint must be served from the exact same origin (scheme + host + port).",
+        ),
+      )
+      console.error(
+        pc.yellow(
+          "  Subdomains count as different origins (e.g. example.com ≠ api.example.com).",
+        ),
+      )
+      console.error(
+        pc.yellow(
+          "  Move your manifest or endpoint so both share the same host, then retry.",
+        ),
+      )
+      process.exit(1)
+    }
+
     // Hash the manifest as served (ERC-8257 §2): the full fetched document,
     // not the schema-stripped copy.
     const hash = computeManifestHash(data as object)
diff --git a/src/cli/commands/verify.ts b/src/cli/commands/verify.ts
@@ -58,9 +58,29 @@ export const verifyCommand = new Command("verify")
     const manifestOrigin = new URL(url).origin
     const endpointOrigin = new URL(manifest.endpoint).origin
     if (manifestOrigin !== endpointOrigin) {
-      console.error(pc.red("Error: Origin mismatch (anti-impersonation check)"))
-      console.error(pc.dim(`  Manifest served from: ${manifestOrigin}`))
-      console.error(pc.dim(`  Endpoint origin: ${endpointOrigin}`))
+      console.error(
+        pc.red(
+          "Error: Origin mismatch between manifest URL and declared endpoint",
+        ),
+      )
+      console.error(pc.dim(`  Manifest origin:  ${manifestOrigin}`))
+      console.error(pc.dim(`  Endpoint origin:  ${endpointOrigin}`))
+      console.error()
+      console.error(
+        pc.yellow(
+          "  The manifest and endpoint must be served from the exact same origin (scheme + host + port).",
+        ),
+      )
+      console.error(
+        pc.yellow(
+          "  Subdomains count as different origins (e.g. example.com ≠ api.example.com).",
+        ),
+      )
+      console.error(
+        pc.yellow(
+          "  Move your manifest or endpoint so both share the same host, then retry.",
+        ),
+      )
       process.exit(1)
     }
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@opensea/tool-sdk",`
`3`		`- "version": "0.24.0",`
	`3`	`+ "version": "0.25.0",`
`4`	`4`	`"type": "module",`
`5`	`5`	`"description": "SDK and CLI for building ERC-8257 compliant AI agent tools",`
`6`	`6`	`"repository": {`