Release v0.15.0

Origin-SHA: 63bd02560fb7f2e118f392b9cabe45c25e5f8a00

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,22 @@
 # @opensea/tool-sdk
 
+## 0.15.0
+
+### Minor Changes
+
+- Unified 402 flow for free and paid predicate-gated tools.
+
+  `predicateGate` now speaks the x402-style 402 challenge for both free and paid tools. When no auth is provided and `operatorAddress` is configured, it returns a 402 with `PaymentRequirements` (`payTo`=operator, `maxAmountRequired`=0) instead of a 401. The gate accepts an `X-Payment` header as the auth source (taking precedence over `Authorization`), recovers the signer from the EIP-712 `TransferWithAuthorization` payload, and extracts caller identity from the `from` field. `PaymentRequirements` are chain-aware: the network name and USDC asset address are derived from the configured chain. `x402Version` and the `exact` scheme are validated.
+
+  **Breaking changes:**
+
+  - `eip3009AuthenticatedFetch` and `paidAuthenticatedFetch` no longer take `chainId` or `to` params. On a 402 they sign `X-Payment` with the advertised `payTo` and retry; the redundant `Authorization: EIP-3009` header has been removed.
+  - `EIP3009_CHAIN_MAP` and `ZERO_ADDRESS` exports were removed.
+
+  **New features:**
+
+  - `eip3009AuthenticatedFetch` gains an `allowedRecipients` guard that prevents signing `X-Payment` for arbitrary `payTo` addresses returned by a malicious 402 response, mirroring `paidAuthenticatedFetch`'s `validatePaymentSafety`.
+
 ## 0.14.2
 
 ### Patch Changes

examples/nft-appraisal-tool/api/holder.ts

@@ -8,6 +8,7 @@ import { buildToolHandler } from "../src/handler.js"
 import { buildHolderManifest } from "../src/manifest.js"
 import { setOpenseaApiKey } from "../src/opensea.js"
 import { buildHolderGates, buildHolderPaywall } from "../src/paywall.js"
+import { buildUsageReporting } from "../src/usage.js"
 
 const creator = process.env.CREATOR_ADDRESS as `0x${string}` | undefined
 const recipient = process.env.RECIPIENT_ADDRESS as `0x${string}` | undefined
@@ -40,7 +41,17 @@ const manifest = buildHolderManifest({
   endpoint: `${baseEndpoint}/api/holder`,
   pricing: paywall.pricing,
 })
-const vercelHandler = toVercelHandler(buildToolHandler({ manifest, gates }))
+const vercelHandler = toVercelHandler(
+  buildToolHandler({
+    manifest,
+    gates,
+    // Holder tier is tool id 2 on the Base ToolRegistry (HOLDER_TOOL_ID).
+    usageReporting: buildUsageReporting({
+      apiKey: openseaKey,
+      toolOnchainId: Number(holderToolId),
+    }),
+  }),
+)
 
 export default function (req: VercelRequest, res: VercelResponse) {
   return vercelHandler(req, res)

examples/nft-appraisal-tool/api/index.ts

@@ -8,6 +8,7 @@ import { buildToolHandler } from "../src/handler.js"
 import { buildPublicManifest } from "../src/manifest.js"
 import { setOpenseaApiKey } from "../src/opensea.js"
 import { buildPublicPaywall } from "../src/paywall.js"
+import { buildUsageReporting } from "../src/usage.js"
 
 // Vercel populates process.env before this module loads, so initialization
 // happens once at module load. The factory architecture (buildPublicPaywall
@@ -37,7 +38,15 @@ const manifest = buildPublicManifest({
   pricing: paywall.pricing,
 })
 const vercelHandler = toVercelHandler(
-  buildToolHandler({ manifest, gates: [paywall.gate] }),
+  buildToolHandler({
+    manifest,
+    gates: [paywall.gate],
+    // Public tier is tool id 1 on the Base ToolRegistry (see README).
+    usageReporting: buildUsageReporting({
+      apiKey: openseaKey,
+      toolOnchainId: 1,
+    }),
+  }),
 )
 
 export default function (req: VercelRequest, res: VercelResponse) {

examples/nft-appraisal-tool/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^1.2.0",
-    "@opensea/tool-sdk": "^0.13.0",
+    "@opensea/tool-sdk": "^0.14.2",
     "ai": "^4.3.0",
     "zod": "4.3.6"
   },

examples/nft-appraisal-tool/pnpm-lock.yaml

@@ -1,5 +1,6 @@
 import {
   createToolHandler,
+  type Eip3009UsageReporterConfig,
   type GateMiddleware,
   type ManifestDefinition,
   ToolHandlerError,
@@ -27,6 +28,13 @@ export interface BuildToolHandlerOptions {
    * doesn't need to.
    */
   gates: GateMiddleware[]
+  /**
+   * Optional usage-reporting config. When set, the SDK reports each
+   * successful invocation to OpenSea at the very end of the lifecycle
+   * (fire-and-forget). For these paid tiers it reports the x402 payer plus
+   * the settlement tx hash. Omitted in local/dev where no API key is set.
+   */
+  usageReporting?: Eip3009UsageReporterConfig
 }
 
 /**
@@ -40,6 +48,7 @@ export function buildToolHandler(opts: BuildToolHandlerOptions) {
     inputSchema: InputSchema,
     outputSchema: AppraisalSchema,
     gates: opts.gates,
+    usageReporting: opts.usageReporting,
     handler: async input => {
       try {
         return await runAppraisal({

examples/nft-appraisal-tool/src/handler.ts

@@ -8,6 +8,7 @@ import {
   buildHolderPaywall,
   buildPublicPaywall,
 } from "./paywall.js"
+import { buildUsageReporting } from "./usage.js"
 
 export interface Env {
   OPENSEA_API_KEY: string
@@ -64,6 +65,11 @@ function initHandlers(env: Env) {
   const publicHandler = buildToolHandler({
     manifest: publicManifest,
     gates: [publicPaywall.gate],
+    // Public tier is tool id 1 on the Base ToolRegistry (see README).
+    usageReporting: buildUsageReporting({
+      apiKey: env.OPENSEA_API_KEY,
+      toolOnchainId: 1,
+    }),
   })
   const holderHandler = env.HOLDER_TOOL_ID
     ? buildToolHandler({
@@ -72,6 +78,10 @@ function initHandlers(env: Env) {
           toolId: BigInt(env.HOLDER_TOOL_ID),
           rpcUrl: env.BASE_RPC_URL,
         }),
+        usageReporting: buildUsageReporting({
+          apiKey: env.OPENSEA_API_KEY,
+          toolOnchainId: Number(env.HOLDER_TOOL_ID),
+        }),
       })
     : undefined
 

examples/nft-appraisal-tool/src/index.ts

@@ -0,0 +1,30 @@
+import {
+  type Eip3009UsageReporterConfig,
+  TOOL_REGISTRY,
+} from "@opensea/tool-sdk"
+
+/**
+ * Base mainnet — where this tool is registered on `ToolRegistry` v0.2 and
+ * where x402 settlements occur.
+ */
+const TOOL_CHAIN_ID = 8453
+
+/**
+ * Build the `usageReporting` config for a tool tier (its ERC-8257 composite
+ * key is `TOOL_CHAIN_ID` + the canonical registry address + the tier's onchain
+ * id). The SDK reports the verified caller automatically — for these paid
+ * tiers, the x402 payer and settlement tx hash. No wallet or signing is
+ * involved; the OpenSea API key authenticates this service as the reporter.
+ */
+export function buildUsageReporting(opts: {
+  apiKey: string
+  toolOnchainId: number
+}): Eip3009UsageReporterConfig {
+  return {
+    chainId: TOOL_CHAIN_ID,
+    toolChainId: TOOL_CHAIN_ID,
+    toolRegistryAddress: TOOL_REGISTRY.address as `0x${string}`,
+    toolOnchainId: opts.toolOnchainId,
+    apiKey: opts.apiKey,
+  }
+}

examples/nft-appraisal-tool/src/usage.ts

@@ -0,0 +1,7 @@
+# Copy to .dev.vars for `wrangler dev`. Same format as .env files.
+
+OPENSEA_API_KEY=
+CREATOR_ADDRESS=
+HOLDER_TOOL_ID=
+TOOL_ENDPOINT=http://localhost:8787
+# ETH_RPC_URL=

examples/token-nft-overlap-tool/.dev.vars.example

@@ -0,0 +1,18 @@
+# Copy to .env.local and fill in. Loaded by scripts/ and by `vercel dev`.
+
+# OpenSea v2 REST API key (https://docs.opensea.io/reference/api-keys)
+OPENSEA_API_KEY=
+
+# Creator address recorded as the manifest's `creatorAddress`.
+# Must match the wallet that registers the tool on the ToolRegistry (ERC-8257).
+CREATOR_ADDRESS=
+
+# Onchain ToolRegistry tool ID (decimal string).
+# Obtain from the `ToolRegistered` event after registering with --nft-gate.
+HOLDER_TOOL_ID=
+
+# Optional override for the manifest's endpoint field.
+# TOOL_ENDPOINT=https://token-nft-overlap-tool.vercel.app
+
+# Optional Ethereum RPC override for predicate static-calls.
+# ETH_RPC_URL=