Release v0.14.1

Origin-SHA: 2abe34e59adcdb442de80e2e6a6ee1c6b98b1851

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,15 @@
 # @opensea/tool-sdk
 
+## 0.14.1
+
+### Patch Changes
+
+- 776788d: Fix usage reporting to attribute the real caller, and make reporting a service-side-only responsibility.
+
+  - x402 usage reports now use the on-chain payer as `caller_address` (after any gate-verified caller), instead of a placeholder address.
+  - EIP-3009 usage reports now forward the caller's original signed authorization, stashed by `predicateGate` on `ctx.callerAuthorization` and surfaced via `InvocationEvent.callerAuthorization`. The server no longer re-signs as itself.
+  - Removed `walletClient`, `operatorAddress`, and `tokenAddress` from `Eip3009UsageReporterConfig`. Reporting is authenticated by `apiKey`, and there is no caller self-reporting or signing path. `signZeroValueAuthorization` remains exported for building `Authorization: EIP-3009` request headers.
+
 ## 0.14.0
 
 ### Minor Changes

README.md

@@ -841,7 +841,7 @@ See [docs/predicate-gating-guide.md](docs/predicate-gating-guide.md) for the ful
 
 ## Usage Reporting
 
-Report tool invocations to OpenSea's analytics endpoint (`POST /api/v2/tools/usage`) using EIP-3009 zero-value authorizations for caller verification.
+Report tool invocations to OpenSea's analytics endpoint (`POST /api/v2/tools/usage`). For each call the SDK reports the **verified caller**: the on-chain **payer** for paid x402 calls, or the caller's **own EIP-3009 authorization** for calls authenticated by `predicateGate`. A tool server never signs on the caller's behalf.
 
 ### Setup
 
@@ -851,7 +851,7 @@ Report tool invocations to OpenSea's analytics endpoint (`POST /api/v2/tools/usa
 export OPENSEA_API_KEY="your-api-key"
 ```
 
-2. **Add `usageReporting` to your handler config** — both free (EIP-3009) and paid (x402) invocations are reported automatically:
+2. **Add `usageReporting` to your handler config** — both free (EIP-3009 auth) and paid (x402) invocations are reported automatically:
 
 ```typescript
 import { createToolHandler } from "@opensea/tool-sdk"
@@ -860,62 +860,66 @@ const handler = createToolHandler({
   manifest,
   inputSchema,
   outputSchema,
+  gates: [/* x402 paywall and/or predicateGate */],
   handler: async (input, ctx) => {
     // your tool logic
   },
   usageReporting: {
-    walletClient,             // caller's viem WalletClient (must have account attached)
-    chainId: 8453,            // chain for EIP-712 USDC domain (Base in this example)
-    operatorAddress: "0x...", // tool operator / pricing recipient
-    toolChainId: 8453,        // ERC-8257: chain where tool is registered
+    chainId: 8453,                // chain for the EIP-712 USDC domain / x402 fallback
+    toolChainId: 8453,            // ERC-8257: chain where the tool is registered
     toolRegistryAddress: "0x...", // ERC-8257: registry contract
-    toolOnchainId: 42,        // ERC-8257: tool ID in registry
+    toolOnchainId: 42,            // ERC-8257: tool ID in the registry
     apiKey: process.env.OPENSEA_API_KEY!,
   },
 })
 ```
 
-That's it — the handler fires the reporter as a fire-and-forget async call at the very end of the lifecycle, after the response is built. It never blocks or fails the tool call. Free calls send a signed EIP-3009 authorization; paid x402 calls send the settlement tx hash.
+> **Reporting is the service's job, never the caller's.** The `apiKey` authenticates *you* (the operator) as the reporter. The caller is identified by data they already supplied (the x402 payer, or the EIP-3009 authorization `predicateGate` verified), so no caller wallet, signing, or `walletClient` is involved.
+
+That's it: the handler fires the reporter as a fire-and-forget async call at the very end of the lifecycle, after the response is built. It never blocks or fails the tool call.
 
 ### How it works
 
-The caller's wallet signs a zero-value EIP-3009 `TransferWithAuthorization` message (USDC domain, `value = 0`) proving address ownership. The SDK sends this signature plus the ERC-8257 composite key to the endpoint. No tokens are transferred — this is purely for identity verification and analytics.
+- **Paid (x402) calls** report `verification_type: "x402_settlement"` with the on-chain payer address and the settlement transaction hash. The backend verifies the settlement directly, so no signature is needed.
+- **EIP-3009-authenticated calls** (e.g. behind `predicateGate`) report `verification_type: "eip3009_authorization"` by **forwarding the caller's original zero-value `TransferWithAuthorization`** (USDC domain, `value = 0`). The caller already signed it to authenticate; the SDK passes that exact signature through, so the reported identity is the real caller, not the server. No tokens are transferred.
 
 ### Configuration reference
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `walletClient` | Yes | Caller's viem `WalletClient` with attached account |
-| `chainId` | Yes | Chain ID for the EIP-712 USDC domain (1, 8453, 137, 42161, 10, 43114) |
-| `operatorAddress` | Yes | Tool operator address (used as `to` in the authorization) |
+| `chainId` | Yes | Chain ID for the EIP-712 USDC domain / x402 `chain_id` fallback (1, 8453, 137, 42161, 10, 43114) |
 | `toolChainId` | Yes | ERC-8257 composite key: chain of registration |
 | `toolRegistryAddress` | Yes | ERC-8257 composite key: registry contract |
 | `toolOnchainId` | Yes | ERC-8257 composite key: numeric tool ID |
-| `apiKey` | Yes | OpenSea API key ([get one here](https://docs.opensea.io/reference/api-keys)) |
+| `apiKey` | Yes | OpenSea API key ([get one here](https://docs.opensea.io/reference/api-keys)). Authenticates the tool service as the reporter |
 | `aggregatorUrl` | No | Override endpoint URL (default: `https://api.opensea.io/api/v2/tools/usage`) |
-| `tokenAddress` | No | Override USDC address (default: canonical address for `chainId`) |
 | `timeoutMs` | No | Request timeout in ms (default: 5000) |
 
 ### Standalone Reporters
 
-If you need to report usage outside the handler flow (e.g. from a client or a custom pipeline), use the standalone reporter functions directly:
+If you report usage outside the handler flow (a custom pipeline or a separate reporting service), use the standalone reporter functions directly.
 
 #### EIP-3009 Reporter
 
+Forwards a caller's already-collected EIP-3009 authorization. Pass an `InvocationEvent` whose `callerAuthorization` holds the authorization your auth layer verified:
+
 ```typescript
 import { createEip3009UsageReporter } from "@opensea/tool-sdk"
 
 const reportUsage = createEip3009UsageReporter({
-  walletClient,
   chainId: 8453,
-  operatorAddress: "0x...",
   toolChainId: 8453,
   toolRegistryAddress: "0x...",
   toolOnchainId: 42,
   apiKey: process.env.OPENSEA_API_KEY!,
 })
 
-await reportUsage({ latencyMs: 123 })
+await reportUsage({
+  paid: false,
+  latencyMs: 123,
+  timestamp: Date.now(),
+  callerAuthorization, // the caller's verified zero-value authorization
+})
 ```
 
 #### x402 Settlement Reporter

package.json

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

skill/SKILL.md

@@ -377,45 +377,42 @@ All CLI commands accept `--wallet-provider privy|turnkey|fireblocks|private-key`
 
 ## 7. Usage Tracking
 
-Tool-sdk supports usage tracking via the `onInvocation` callback on `createToolHandler`. This fires after every successful invocation (post-settle, pre-response) with an `InvocationEvent` containing caller identity, payment status, and timing.
+Tool-sdk reports usage to OpenSea's analytics endpoint (`POST /api/v2/tools/usage`) for each successful call. It reports the **verified caller**: the on-chain payer for paid x402 calls, or the caller's own EIP-3009 authorization for `predicateGate`-authenticated calls. A tool server never signs on the caller's behalf.
 
-### createEip3009UsageReporter (recommended)
+### usageReporting (recommended)
 
-`createEip3009UsageReporter` is the recommended `onInvocation` implementation. It reports tool usage via EIP-3009 zero-value `TransferWithAuthorization` signatures:
+Pass `usageReporting` to `createToolHandler` and it fires the reporter as a fire-and-forget call at the very end of the lifecycle (after the response is built). No `walletClient` is needed server-side:
 
-- **Free / gated calls**: signs a zero-value authorization proving the operator controls the wallet, and POSTs with `verification_type: "eip3009_authorization"`.
-- **Paid x402 calls**: POSTs with `verification_type: "x402_settlement"` and the settlement tx hash — no additional signature needed.
+- **Paid x402 calls** → `verification_type: "x402_settlement"` with the payer address and settlement tx hash. The backend verifies the tx directly.
+- **EIP-3009-authenticated calls** (behind `predicateGate`) → `verification_type: "eip3009_authorization"`, **forwarding the caller's original signed authorization**. The caller already signed it to authenticate, so the reported identity is the real caller.
 
 ```typescript
-import { createToolHandler, createEip3009UsageReporter } from "@opensea/tool-sdk"
-import { createWalletClient, http } from "viem"
-import { privateKeyToAccount } from "viem/accounts"
-import { base } from "viem/chains"
-
-const walletClient = createWalletClient({
-  account: privateKeyToAccount("0x..."),
-  chain: base,
-  transport: http(),
-})
+import { createToolHandler } from "@opensea/tool-sdk"
 
 export const toolHandler = createToolHandler({
   manifest,
   inputSchema: InputSchema,
   outputSchema: OutputSchema,
-  onInvocation: createEip3009UsageReporter({
-    walletClient,
-    chainId: 8453,
-    // optional: aggregatorUrl, tokenAddress, toolSlug, timeoutMs
-  }),
+  gates: [/* x402 paywall and/or predicateGate */],
+  usageReporting: {
+    chainId: 8453,                // EIP-712 USDC domain / x402 chain_id fallback
+    toolChainId: 8453,            // ERC-8257: chain where the tool is registered
+    toolRegistryAddress: "0x...", // ERC-8257: registry contract
+    toolOnchainId: 42,            // ERC-8257: tool ID in the registry
+    apiKey: process.env.OPENSEA_API_KEY!,
+    // optional: aggregatorUrl, tokenAddress, timeoutMs
+  },
   handler: async (input) => {
     return { result: `Processed: ${input.query}` }
   },
 })
 ```
 
+Reporting is always the service's responsibility (authenticated by `apiKey`), never the caller's; there is no caller self-reporting path. To report from a custom pipeline instead of the handler, use the standalone `createEip3009UsageReporter` / `createX402UsageReporter` (see the tool-sdk README "Usage Reporting" section).
+
 ### onInvocation callback
 
-You can also provide a custom `onInvocation` callback for bespoke analytics:
+You can also provide a custom `onInvocation` callback for bespoke analytics. It fires after the handler succeeds and settles, before the response is returned, with an `InvocationEvent` containing caller identity, payment status, and timing:
 
 ```typescript
 import { createToolHandler } from "@opensea/tool-sdk"