v0.17.1

What's Changed

• Thread --rpc-url through to registry reads in CLI commands. Previously the flag only applied to writes; read paths (status, get, list) fell back to the default RPC endpoint. (#426)
• Add ERC-8257 image metadata to chonks and overlap example tool manifests. (#423)

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.17.0...tool-sdk-v0.17.1

v0.17.0

What's Changed

Minor Changes

• Sync the manifest schema with the canonical ERC-8257 spec: featuredImage is now an optional field in the manifest Zod schema, so manifests declaring it pass validation. (#419)

Patch Changes

• Remove the broken --auth eip3009 path from the pay CLI command (along with its --manifest and --chain options). The flag bypassed the unified x402 flow (probe → 402 → sign X-Payment → retry) and caused 500 errors. pay now always uses the probe-then-sign path. (#421)
• Update example READMEs to remove --auth eip3009 usage. (#422)

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.16.1...tool-sdk-v0.17.0

v0.16.1

What's Changed

• Security fix: validBefore is now required in predicate-gate authorizations. Previously a caller could sign a TransferWithAuthorization with validBefore=0 and omit the field from the X-Payment payload, so the expiry check was skipped and the gate accepted an unbounded, non-expiring proof. The field is now required in both the X-Payment and EIP-3009 auth paths, with the now-dead validBefore !== undefined guards and the ?? "0" recovery fallback removed.

Community Contributions

• Reported and fixed by @Nexory (#9, #10). Thanks for the detailed writeup and the matching PR.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.16.0...tool-sdk-v0.16.1

v0.16.0

What's Changed

• feat: paidPredicateGate (#409): a combined gate that resolves identity verification (predicate) and x402 payment in a single 402 round trip. Tools using it need only 2 requests (a 402 advertising the real payment amount, then a 200) instead of 3. The caller's X-Payment signature proves identity, via the recovered from address, and authorizes the transfer in one step. The onchain predicate is checked before the facilitator settles payment, so denied access returns a 403 and moves no funds. New exports: paidPredicateGate and PaidPredicateGateConfig.
• docs: predicate gate docs updated for the unified 402 + X-Payment flow (#408).
• fix: the token-nft-overlap-tool example passes operatorAddress in its Vercel entry (#407).

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.15.0...tool-sdk-v0.16.0

v0.15.0

What's Changed

Unified 402 flow for free and paid predicate-gated tools (#401).

• 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; 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.
• New free, predicate-gated example: token-nft-overlap-tool (#398).
• usageReporting wired into the nft-appraisal example (#397).

Full Changelog: v0.14.2...v0.15.0

v0.14.2

What's Changed

Await the usageReporting reporter before returning the tool response.

Previously the handler fired the reporter fire-and-forget after the response was built. On serverless runtimes (Vercel, AWS Lambda) the function is frozen the instant the response flushes, so the in-flight request was killed and the usage report silently never reached /api/v2/tools/usage. The handler now awaits the report (bounded by the reporter's timeoutMs, default 5s) so it reliably completes. Failures are still caught and logged and never fail the tool call.

Full Changelog: v0.14.1...v0.14.2

v0.14.1

What's Changed

Fixes caller attribution in usage reporting (the POST /api/v2/tools/usage integration) and corrects the trust model.

• x402 calls now attribute the on-chain payer as caller_address, instead of a placeholder address. The x402 gate records the payer; the reporter now uses it.
• EIP-3009-authenticated calls now forward the caller's original signed authorization. predicateGate stashes the verified authorization on ctx.callerAuthorization, the handler threads it onto InvocationEvent.callerAuthorization, and the reporter forwards it. The server no longer signs a fresh authorization as itself.
• Removed walletClient, operatorAddress, and tokenAddress from Eip3009UsageReporterConfig. Usage reporting is a service-side responsibility authenticated by apiKey; there is no caller self-reporting or server-side signing path. signZeroValueAuthorization remains exported for building Authorization: EIP-3009 request headers.

Docs (README + bundled tool-builder skill) updated to match.

Full Changelog: v0.14.0...v0.14.1

v0.14.0

What's Changed

Usage reporting reworked to match the os2-core POST /api/v2/tools/usage endpoint.

Breaking changes

• Eip3009UsageReporterConfig now requires apiKey, operatorAddress, and the ERC-8257 composite key (toolChainId, toolRegistryAddress, toolOnchainId). The old tool_slug field is removed.
• Default aggregator URL changed to https://api.opensea.io/api/v2/tools/usage.
• Base Sepolia (84532) removed from NETWORK_USDC.

New features

• ToolHandlerConfig.usageReporting: pass an Eip3009UsageReporterConfig and createToolHandler auto-fires the reporter on every successful invocation (both free EIP-3009 and paid x402 paths). Works alongside onInvocation.
• createX402UsageReporter: standalone reporter for paid x402 tools (no wallet signing, just the settlement tx hash).
• Per-event txHash hex-format validation in the x402 reporter.

Full Changelog: v0.13.0...v0.14.0

v0.13.0

What's Changed

• Add Shape and Abstract chain support to all CLI commands. The --network flag now accepts shape and abstract in addition to base and mainnet.
• Switch predicate gate and CLI auth from SIWE to EIP-3009. predicateGate now accepts Authorization: EIP-3009 <token> (preferred) and Authorization: SIWE <token> (deprecated); EIP-3009 verification uses pure ecrecover on EIP-712 typed data with no RPC call. New exports: createEip3009AuthHeader, eip3009AuthenticatedFetch, Eip3009AuthenticatedFetchOptions. SIWE exports (createSiweMessage, createSiweAuthHeader, authenticatedFetch) are deprecated.
• Add EIP-3009 zero-value authorization for usage tracking: signZeroValueAuthorization, createEip3009UsageReporter, and an onInvocation callback on createToolHandler.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.12.0...tool-sdk-v0.13.0

v0.12.0

What's Changed

• feat: add ERC20BalancePredicate support: new predicate client, ABI, configure-erc20-gate / get-erc20-config CLI commands, and requirement decoding for ERC-20 token-balance gating
• feat: deploy the canonical ERC20BalancePredicate (0x1a834FC48B5f6e119c62C12a98b32137bCFA77cD on Ethereum mainnet and Base) and default the gating CLIs to it
• feat: add --erc20-gate / --erc20-min-balance flags to register for one-shot ERC-20 balance-gated tool registration; ERC20BalancePredicateClient constructor now defaults to the canonical address
• feat: deploy ToolRegistry + all five canonical predicates to Shape (chain 360) and Abstract (chain 2741)
• docs: add configure-trait-gating / get-trait-config CLI reference to the README

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.11.0...tool-sdk-v0.12.0