v0.6.0

What's Changed

Minor Changes

• Add defineVerifiability() typed builder for verifiability blocks (#272) — three tier-narrowed factory methods (selfAttested, hardwareAttested, verifiable) produce correct verifiability objects for defineManifest(). Invalid tier/field combos are rejected at the TypeScript type level rather than only at validation time.
• Adopt ERC-8257 assignment (#264) — replace ERC-Draft placeholder references with the officially assigned ERC-8257 number across CLI help text, documentation, and test vectors. Manifest schema type URL switched to the canonical ERCs site (https://ercs.ethereum.org/ERCS/erc-8257#tool-manifest-v1); test vectors and pinned hashes regenerated against the new canonical bytes.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.5.0...tool-sdk-v0.6.0

v0.5.0

What's Changed

Minor Changes

• Add toManifestAccess() to ERC721OwnerPredicateClient and ERC1155OwnerPredicateClient for programmatic manifest access generation with deterministic OpenSea collection links. Export shared requirement-kind constants (ERC721_KIND, ERC1155_KIND, SUBSCRIPTION_KIND).
• Suggest manifest access block when registering with --nft-gate. The register CLI command now detects when a manifest is missing the access field and the user is registering with --nft-gate. It generates the correct access object using ERC721OwnerPredicateClient.toManifestAccess() and prints it as a suggestion. The preview appears in both --dry-run and normal mode. In normal mode the user is prompted to view copy-paste instructions for updating their manifest.
• Enforce bidirectional tier consistency checks in manifest validator. The verifiability schema now rejects all 4 invalid tier/field combinations:
  • hardware-attested requires tee or e2ee execution
  • hardware-attested requires an attestation field
  • self-attested cannot use tee or e2ee execution
  • self-attested cannot include an attestation field

Patch Changes

• access.links values now require valid HTTPS URLs; non-HTTPS values (onchain addresses, http://, ipfs://) are rejected by schema validation.
• Enforce ERC-spec parser caps on access.requirements: max 256 entries, max 4,096 decoded bytes per access[].data field.
• Enforce access label limit as 256 bytes (UTF-8) instead of 256 characters, aligning with the updated ERC spec.
• Enforce lowercase-only hex in manifest schema fields (access[].kind, access[].data, attestation.enclaveHash, reproducibleBuild.buildHash, creatorAddress) to match the tightened ERC spec. Normalize wallet and onchain addresses to lowercase before comparison in register and update-metadata commands.

Full Changelog: v0.4.2...v0.5.0

v0.4.2

What's Changed

Patch release. Picks up @opensea/wallet-adapters@0.3.0 (provider-aware wallet hardening across Privy, Turnkey, Fireblocks, and Bankr) via the workspace dep.

No tool-sdk source changes.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.4.1...tool-sdk-v0.4.2

v0.4.1

What's Changed

• Replace ERC-XXXX placeholder references with ERC-Draft throughout CLI help text, schema defaults, and documentation.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.4.0...tool-sdk-v0.4.1

v0.4.0

What's Changed

DX improvements from canary builder feedback (#249)

• createWellKnownHandler now accepts ManifestDefinition (with EnvResolver lambdas) and resolves internally on first request — eliminates the silent-failure footgun where lambda fields would serialize as undefined. Accepts an optional env parameter for non-Node runtimes (Cloudflare Workers, Bun).
• Well-known handler no longer 404s on pathname mismatch — relies on framework router. If you mounted createWellKnownHandler as a fall-through, scope it to the well-known path explicitly.
• defineToolPaywall recipient accepts EnvResolver<Address> so the payout address can be read from env vars at request time instead of module-load time.
• defineToolPaywall returns onSettle callback for post-payment telemetry/logging.
• Template package.json files inject the current SDK version at init time instead of pinning stale ^0.1.0.
• Vercel adapter uses x-forwarded-proto header (consistent with Express adapter).
• describeToolAccess helper reads a tool's predicate name and requirements from the registry; decodeRequirement decodes known kinds (ERC-721, ERC-1155, Subscription) into typed objects.
• onSettle payer is now sourced from the facilitator's /verify response (reliable for pure-x402 tools) with fallback to ctx.callerAddress.
• registerTool and updateToolMetadata validate URI length client-side before sending the transaction.
• Templates include EnvResolver lambda examples in comments.
• init command prints workspace warning for pnpm users.

Testing utilities (#250)

• New @opensea/tool-sdk/testing subpath export with test utilities for tool builders: createMockManifest, createMockToolContext, mockFetch, and createTestHandler.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.3.1...tool-sdk-v0.4.0

v0.3.1

What's Changed

Re-export BankrAdapter and BankrConfig from @opensea/wallet-adapters (#245). createWalletFromEnv() already auto-detected Bankr when BANKR_API_KEY is set; this makes the named adapter directly importable from @opensea/tool-sdk for callers that need to construct it explicitly.

Bumps @opensea/wallet-adapters to ^0.2.1 (which adds the BankrAdapter).

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.3.0...tool-sdk-v0.3.1

v0.3.0

What's Changed

Breaking

• auth and smoke CLI commands migrated from TOOL_SDK_PRIVATE_KEY / privateKeyToAccount to createWalletFromEnv() from @opensea/wallet-adapters. Use PRIVATE_KEY + RPC_URL env vars or --wallet-provider for explicit provider selection. The --key (auth), --as (smoke), and TOOL_SDK_PRIVATE_KEY env var have been removed.

Features

• Delegated agent auth via delegate.xyz — operator wallet can act for an EOA owner without holding the predicate token directly.
• Runtime env resolution in defineManifest for Cloudflare Workers — manifest can reference env vars resolved at request time rather than build time.
• Predicate clients: ERC721OwnerPredicateClient and ERC1155OwnerPredicateClient for managing predicate collections.
• Manifest JSON Schema validation for inputs/outputs.
• registryAddress override in PredicateGateConfig and ToolRegistryClient for local development against forked Anvil or custom registry deploys.
• Init template improvements: agent-friendly discovery page + /llms.txt for direct LLM consumption; uses createWalletFromEnv / walletAdapterToClient from @opensea/wallet-adapters.

Fixes

• deploy wizard skips prompts for env vars already set in Vercel.
• deploy skips blank-valued env vars in .env.local.example to avoid prompting for empty placeholders.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.2.0...tool-sdk-v0.3.0

v0.2.0

What's Changed

• Endpoint probe (#228) — verify, inspect, and smoke commands now probe the tool endpoint to catch routing defects (404, 405) before signing payments or declaring success.

• paidAuthenticatedFetch (#227) — composite-gate client helper for tools that require both a SIWE auth header (predicate gate) and an x402 payment. Adds a --paid flag to smoke and surfaces a warning in inspect when a tool is composite-gated.

• Predicate v0.2 addresses on Base (#229) — ERC721_OWNER_PREDICATE and ERC1155_OWNER_PREDICATE now point at the redeployed v0.2 predicates that implement F18 access-requirement introspection (getRequirements()):

  • ERC721OwnerPredicate v0.2 → 0xd1F703D0B90BB7106fAebBfbcAdD2B07BDc4c769
  • ERC1155OwnerPredicate v0.2 → 0xc179b9d4D9B7ffe0CdA608134729f72003380A7e

  The ToolRegistry is unchanged at 0x7291BbFbC368C2D478eCe1eA30de31F612a34856. Tools registered against the v0.1 registry remain valid; tools that delegated access to the v0.1 predicates need setAccessPredicate to repoint at the new v0.2 addresses.

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.1.2...tool-sdk-v0.2.0

v0.1.2

First version of @opensea/tool-sdk actually on npm.

What's Changed

• Add repository field to package.json so npm provenance can validate the bundle against the public mirror at https://github.com/ProjectOpenSea/tool-sdk.

Why 0.1.2 instead of 0.1.1?

The tool-sdk-v0.1.1 tag and public release exist but never reached npm — the publish workflow failed because repository.url was empty in package.json and npm provenance requires it to match the source GitHub repo. 0.1.2 adds the missing field and is the first version published to npm. The 0.1.1 tag and public release stay as historical artifacts.

For the full feature set of this initial release, see the v0.1.1 release notes — they cover the entire @opensea/tool-sdk package (core SDK, onchain integration, gates, wallet adapters, CLI commands, docs).

Full Changelog: ProjectOpenSea/opensea-devtools@tool-sdk-v0.1.1...tool-sdk-v0.1.2

v0.1.1

First release of @opensea/tool-sdk — SDK and CLI for building ERC-XXXX compliant AI agent tools. The 0.1.0 baked into the source was a manual placeholder that never shipped; 0.1.1 is the first tagged, GitHub-released, npm-published version.

Core SDK

• createToolHandler for building tools with manifest validation, JCS keccak256 hashing, well-known endpoint middleware, and a GateMiddleware chain.
• Framework adapters for Vercel, Cloudflare, and Express.
• ToolHandlerError for typed HTTP status codes; unhandled errors are logged automatically.
• ToolManifestSchema with optional verifiability block (tier, execution, dataRetention, sourceVisibility, attestation, reproducibleBuild).

Onchain integration

• ToolRegistryClient with registerTool, setAccessPredicate, tryHasAccess, listToolsByCreator, name(), and version().
• Canonical CREATE2 deployments on Base mainnet: TOOL_REGISTRY (v0.1), ERC721_OWNER_PREDICATE, ERC1155_OWNER_PREDICATE. Each is a Deployment object ({ address, chains, overrides? }); resolve per-chain with deploymentAddress(deployment, chainId).
• register CLI enforces creatorAddress matches the signing wallet per ERC-XXXX spec.
• IAccessPredicate (interface ID 0xbdf9dc18) and IToolRegistry ABIs exported with full event coverage (ToolMetadataUpdated, AccessPredicateUpdated). Predicates expose machine-readable access requirements via getRequirements(toolId) returning AccessRequirement[] with RequirementLogic (AND/OR). Marker interfaces IERC721Holding, IERC1155Holding, ISubscription shipped via IRequirementTypes.sol.
• SubscriptionPredicateABI and CompositePredicateABI for tier-based and composite access control.

Access gates

• predicateGate({ toolId }) delegates the access decision to the onchain ToolRegistry. One middleware works for every predicate type — single-collection, multi-collection, ERC-1155, subscriptions, composites, future predicates — without per-predicate SDK changes. On-chain setAccessPredicate updates are picked up automatically. Returns 403 with the predicate address on (true, false), 502 on predicate misbehavior.
• checkToolAccess is the client-side preview of predicateGate (no SIWE) for frontends and CLIs that want to gate UI before invocation.
• nftGate is @deprecated in favor of predicateGate for any registered tool. It remains exported for local development against unregistered tools.
• SIWE auth helpers: createSiweMessage, authenticatedFetch. Accepts external signers (Bankr, MPC, HSM) for agent wallets.

x402 paywall gates

• payaiX402Gate — uses the PayAI community facilitator (https://facilitator.payai.network, no auth, free); recommended for prototyping.
• cdpX402Gate — uses Coinbase Developer Platform (https://api.cdp.coinbase.com/platform/v2/x402); accepts a createAuthHeaders callback for the CDP JWT auth.
• All hosted gates settle on chain after the handler succeeds — they invoke /settle once the response validates against the schema, moving USDC from payer to recipient and recording the settled tx hash on ctx.gates.x402.settlementTxHash. Settlement is synchronous (up to 10s timeout); failures log [tool-sdk] gate.settle failed: but the response still returns 200.
• defineToolPaywall helper prevents pricing/gate config drift between the manifest and the gate.
• Recipient address validation rejects zero and burn addresses.
• Client helpers: signX402Payment (signs an EIP-3009 TransferWithAuthorization for USDC, returns base64-encoded X-Payment header value) and paidFetch (drop-in fetch wrapper that handles the 402 challenge automatically).
• GateMiddleware gains an optional settle?(ctx) hook called by createToolHandler after a successful run.
• x402Gate (lower-level, for self-hosted facilitators) is unchanged.

Wallet adapters

• Wallet provider auto-detection across Privy, Turnkey, Fireblocks, and PrivateKey via the shared @opensea/wallet-adapters package. CLI accepts --wallet-provider to override.
• walletAdapterToClient delegates to @opensea/wallet-adapters/viem.
• Replaces the old TOOL_SDK_PRIVATE_KEY env var with the WalletAdapter abstraction.

CLI commands

• init — project scaffolding (Vercel/Express/Cloudflare templates) with TS-manifest support.
• validate, hash, export — also accept TypeScript manifest files.
• verify, register, update-metadata — manifest lifecycle.
• inspect — shows predicate type, ERC-721/1155 collections, SubscriptionPredicate config (collection, minTier), CompositePredicate terms (op, leaf predicates, negation), and accepts --check-access for any predicate via getRequirements.
• pay — pay a paywalled tool from the CLI.
• auth — SIWE-authenticated calls to predicate-gated tools.
• dry-run-gate, dry-run-predicate-gate — test gate setup locally before deploy.
• deploy --host vercel — one-command deploy: login check, project link (auto-configured with inferred project and scope), env var setup from .env.local.example (with sensitive-input masking), first deploy, TOOL_ENDPOINT configuration, force redeploy, and manifest verification. Recovers from non-zero vercel exit when a URL was issued.
• smoke — production endpoint verification.

Documentation

• README with full CLI reference (export, update-metadata, inspect, deploy, pay, auth, dry-run-gate, dry-run-predicate-gate).
• Predicate gating + SIWE authentication guides.
• Hosting comparison, migration guide, and FAQ.
• MIT LICENSE.