v0.24.0

What's Changed

• Add support for the upto x402 payment scheme, which allows variable pricing (charge up to amountPerCall, with the actual charge potentially less). createX402Client now registers both ExactEip3009Scheme and UptoEip3009Scheme internally, letting @x402/core route to the correct scheme based on the challenge's scheme field. The pay CLI, paidFetch, and paidAuthenticatedFetch route to the appropriate scheme automatically, so callers no longer need to know which scheme to instantiate. (#459)

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.23.1...tool-sdk-v0.24.0

v0.23.1

What's Changed

• --tool-ref and the usage reporters now support non-address registries such as x402:bazaar and x402:bankr for tools that are not registered onchain (#455). toolRegistryAddress is widened to string, and toolOnchainId is kept as a string to preserve precision for IDs exceeding Number.MAX_SAFE_INTEGER.
• --tool-ref now uses a comma delimiter (chainId,registryAddress,onchainId) instead of a colon, so a registry identifier that itself contains a colon stays unambiguous (#457). Example: 8453,x402:bazaar,8679018179619845322.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.23.0...tool-sdk-v0.23.1

v0.23.0

What's Changed

• 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, 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 when reporting usage for a tool whose endpoint maps to more than one registry entry. (#453)

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.22.0...tool-sdk-v0.23.0

v0.22.0

What's Changed

• Migrate paidFetch, paidAuthenticatedFetch, and the pay CLI to the @x402/core client infrastructure (x402Client, x402HTTPClient, SchemeNetworkClient) for payment payload creation and header encoding. Adds an ExactEip3009Scheme adapter wrapping tool-sdk's existing EIP-3009 signing into the standard x402 scheme interface. No public API changes. (#447)

This also resolves a payment-blocking bug in the previous home-rolled encoder: btoa(JSON.stringify(...)) threw InvalidCharacterError whenever a server's 402 challenge echoed a non-Latin1 character (e.g. an em-dash in resource.description). The @x402/core encoder is UTF-8-safe, and the v2 payload no longer embeds resource/accepted.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.21.0...tool-sdk-v0.22.0

v0.21.0

What's Changed

• Usage report fires via platform waitUntil (createToolHandler): the fire-and-forget usage report now runs as keep-alive-after-response work instead of being awaited inline. This removes reporting latency from every successful call and closes a billing edge — x402 settlement runs before the report, so awaiting it meant a function freeze in that window could charge a paid caller without returning a result. Auto-detected on Vercel (no @vercel/functions dependency), wired on Cloudflare via toCloudflareHandler (its fetch gains an optional ctx arg), overridable via a new waitUntil option on ToolHandlerConfig, and awaited as before when no waitUntil is available. (#449)
• init Vercel template defaults maxDuration = 60 on the tool entrypoint, so LLM-backed tools don't 502 on Vercel's 10s Hobby default. (#448)

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.20.1...tool-sdk-v0.21.0

v0.20.1

What's Changed

• Caller usage reporting, default-on: pay now sends a caller-side usage report by default (--no-report-usage to opt out). --api-key falls back to OPENSEA_API_KEY before auto-provisioning an instant key. A duplicate-report rejection (the tool's own server-side reporter already recorded the settlement) is treated as success. reportCallerX402Usage / reportCallerEip3009Usage now return a CallerUsageReportResult (reported | already-reported | skipped | failed) so callers can surface the real outcome. (#445)
• Reject x402 payment on 5xx: paidFetch and paidAuthenticatedFetch now throw X402PaymentError when the server responds 5xx after a payment is sent, instead of silently returning the error response. The error exposes response and settled so callers can detect a possibly-settled payment and avoid double charges. (#441)

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.20.0...tool-sdk-v0.20.1

v0.20.0

What's Changed

• Caller-side usage reporting: new reportCallerX402Usage, reportCallerEip3009Usage, and extractSettlementTxHash exports. Tool callers can report usage by endpoint URL with auto-provisioned API keys, integrated into paidFetch, paidAuthenticatedFetch (via the reportCallerUsage option), and the pay CLI (--report-usage).
• Settlement-response header from createToolHandler: after a paid call settles, the handler now echoes the onchain settlement tx hash to the caller via PAYMENT-RESPONSE (v2) / X-PAYMENT-RESPONSE (v1). This lets caller-side reporting (and any x402 client) read the tx hash via extractSettlementTxHash. Adds the buildSettlementResponseHeader helper.
• Security hardening: caller reporters reject non-https aggregator URLs (allowing http://localhost for dev), and reportCallerEip3009Usage documents/​warns about transmitting a replayable authorization.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.19.0...tool-sdk-v0.20.0

v0.19.0

What's Changed

Support x402 v2 and GET endpoints in pay (#437). Bazaar-discovered x402 tools are frequently GET endpoints that speak x402 v2, where the SDK previously could not transact at all: pay only issued POST, only read the v1 body accepts challenge, and signed the v1 X-PAYMENT envelope.

• New x402-challenge.ts: resolveNetwork() accepts base, eip155:8453, and 8453; parseX402Challenge() reads the PAYMENT-REQUIRED header or the body and normalizes the v2 amount field to maxAmountRequired.
• signX402Payment emits the version-correct envelope (v1 {scheme,network,payload} vs v2 {payload,resource,accepted}) and echoes the challenge's x402Version. New x402PaymentHeaderName() (X-PAYMENT for v1, PAYMENT-SIGNATURE for v2) and X402_SETTLEMENT_HEADERS exports.
• paidFetch routes through the shared parser and the version-correct header.
• pay command: --method flag (defaults to POST) with auto-fallback to GET on 404/405, query-string encoding for bodyless verbs, version-correct payment header, on-chain settlement readout, RPC_URL defaulting to a public Base endpoint, and clearer wallet-config errors.
• smoke and paid-authenticated-fetch resolve networks so CAIP-2 networks still get USDC validation.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.18.0...tool-sdk-v0.19.0

v0.18.0

What's Changed

• Hash the manifest as served, per ERC-8257 §2: the full JCS document including any namespaced extension fields, with no schema stripping and no injected defaults. The result agrees with any RFC 8785 implementation and with the OpenSea backend.
• computeManifestHash now accepts the raw served or authored object and hashes it as-is.
• The manifest schema is open: namespaced extension fields (reverse-DNS, e.g. io.opensea.paymentHint, or the legacy x- prefix) are preserved. The type field is no longer defaulted.
• validate, hash, and register warn about bare un-namespaced extension fields. New findBareExtensionKeys(data) export.

Compatibility: tools whose served manifest contains extra fields or omits type will now produce a different (correct) hash than prior versions, and should re-register or update so their onchain hash matches the served document.

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

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