Build, register, and gate AI-callable tool endpoints using the OpenSea Tool Registry (ERC-8257) on Base.
When to use this skill (scope_in)
Use opensea-tool-sdk when you need to:
- Scaffold an AI-callable tool endpoint (HTTPS, JSON Schema,
.well-knownmanifest) for Vercel, Cloudflare, or Express - Register a tool onchain on the Base ToolRegistry so other agents can discover it
- Gate access via x402 pay-per-call (USDC) or predicates (ERC-721/ERC-1155 ownership, subscriptions, trait gating, ERC-20 balance, composites)
- Call a gated or paid tool: 402 payments (
paidFetch), predicate-gated auth (eip3009AuthenticatedFetch), or both (paidAuthenticatedFetch) - Search and discover registered tools via the OpenSea REST API
When NOT to use this skill (scope_out, handoff)
| Need | Use instead |
|---|---|
| Query NFT/token data, search, collection stats | opensea-api |
| Buy/sell NFTs | opensea-marketplace |
| Swap ERC20 tokens | opensea-swaps |
| Set up wallet signing providers | opensea-wallet |
This SDK is for tool providers and consumers. To query OpenSea marketplace data (floor prices, listings, trades), use the opensea-api skill instead.
Concepts
| Term | Meaning |
|---|---|
| Tool | A single REST API endpoint with a JSON Schema interface, discoverable via /.well-known/ai-tool/<slug>.json. Each tool should perform one focused operation. |
| Manifest | JCS-canonicalized JSON describing the tool's name, endpoint, inputs, outputs, pricing, and access policy |
| ToolRegistry | Onchain contract (Base) where tools are registered with a manifest hash and optional access predicate |
| Access Predicate | An IAccessPredicate contract that gates who can invoke a tool (NFT ownership, subscriptions, trait gating, ERC-20 balance, composites) |
| x402 | HTTP 402-based pay-per-call protocol (caller signs a USDC TransferWithAuthorization; server settles after execution) |
| EIP-3009 auth | Zero-value USDC TransferWithAuthorization signature used to authenticate callers for predicate-gated tools |
| Facilitator | Third-party service that verifies and settles x402 payments (PayAI or Coinbase CDP) |
Important Constraints
One tool = one endpoint. Each tool registration represents a single REST API endpoint with a singular focus and intention. The endpoint URL in your manifest should point to a specific API route that performs one well-defined operation (e.g., POST /api/price-check or POST /api/translate), not a generic HTML page, documentation site, or multi-purpose URL. Think of each registered tool the same way you think of an individual REST API endpoint. It should accept a specific input, perform a specific action, and return a specific output.
Origin binding: manifest and endpoint must share the exact same origin. Your .well-known/ai-tool/<slug>.json manifest and your tool's invocation endpoint must be served from the exact same origin (identical scheme, host, and port per RFC 6454). Subdomains do not count as the same origin. example.com and api.example.com are different origins. This is enforced at registration time. If the manifest origin and endpoint origin don't match exactly, the tool will be rejected and marked as deregistered.
- Valid: manifest at
https://my-tool.example.com/.well-known/ai-tool/my-tool.json, endpoint athttps://my-tool.example.com/api/my-tool - Invalid: manifest at
https://example.com/.well-known/ai-tool/my-tool.json, endpoint athttps://api.example.com/api/my-tool
If you need your API on a subdomain, serve the manifest from that same subdomain (e.g., both on api.example.com).
Deployed Contracts (Ethereum mainnet, Base, Shape, Abstract, Monad, Robinhood Chain)
Canonical v0.2 deployments — identical CREATE2 address on every supported chain.
| Contract | Address |
|---|---|
| ToolRegistry (v0.2) | 0x265BB2DBFC0A8165C9A1941Eb1372F349baD2cf1 |
| ERC721OwnerPredicate (v0.2) | 0xc8721c9A776958FfFfEb602DA1b708bf1D318379 |
| ERC1155OwnerPredicate (v0.2) | 0x77373Dc3c1AE9A1e937eF3e5E08F4807D47c7c11 |
| SubscriptionPredicate (v0.2) | 0xCBe0cd9B1d99d95Baa9c58f2767246C52e461f25 |
| TraitGatedPredicate (v0.2) | 0x10abF07CfA34Bf22372C57f27e8bd9C2DCF93fA1 |
| ERC20BalancePredicate (v0.2) | 0x1a834FC48B5f6e119c62C12a98b32137bCFA77cD |
Tool Discovery [Beta]
Find registered tools through the OpenSea REST API with an OPENSEA_API_KEY. If you have none, the opensea-api skill's opensea-resolve-key.sh fetches a free instant key and caches it in ~/.opensea/api_key; reuse that key instead of fetching a new one per request.
With the OpenSea CLI: opensea tools search --query <text>, opensea tools list, opensea tools get <chain_id> <registry> <tool_id>, opensea tools activity <chain_id> <registry> <tool_id>.
| Endpoint | Parameters |
|---|---|
GET /api/v2/tools (docs) |
sort_by (newest default, oldest), type (open, nft_gated, token_gated, subscription, gated), source (onchain, x402_bazaar, x402_bankr; all when omitted), limit (1-200), cursor |
GET /api/v2/tools/search (docs) |
query, registry_chain, tags, access_type (open, nft_gated, subscription), creator, source, collection, include_details (default true), sort_by (relevance default, newest, most_used), limit (1-200), cursor |
GET /api/v2/tools/{registry_chain}/{registry_addr}/{tool_id} (docs) |
Path only. registry_chain is the chain ID (1, 8453) |
GET /api/v2/tools/{registry_chain}/{registry_addr}/{tool_id}/activity |
include_creator_payments (default false), limit (default 25), offset |
curl -s "https://api.opensea.io/api/v2/tools/search?query=nft&access_type=open&limit=10" \
-H "x-api-key: $OPENSEA_API_KEY" | jq
curl -s "https://api.opensea.io/api/v2/tools/8453/0x265BB2DBFC0A8165C9A1941Eb1372F349baD2cf1/1" \
-H "x-api-key: $OPENSEA_API_KEY" | jq
1. Create a Tool
1a. Scaffold a project
npx @opensea/tool-sdk init --runtime vercel # or: cloudflare, express
This generates:
src/manifest.ts— tool manifest definitionsrc/handler.ts— request handler with input/output schemasapi/index.ts— framework adapter entry pointpublic/llms.txt— agent-readable discovery pageapi/well-known/[slug].ts— serves the manifest at/.well-known/ai-tool/<slug>.json
1b. Define the manifest
import { defineManifest } from "@opensea/tool-sdk"
export const manifest = defineManifest({
name: "My Tool",
description: "What this tool does",
endpoint: "https://my-tool.example.com/api",
creatorAddress: "0xYOUR_WALLET_ADDRESS",
inputs: {
type: "object",
properties: {
query: { type: "string", description: "Search query" },
},
required: ["query"],
},
outputs: {
type: "object",
properties: {
result: { type: "string" },
},
},
// Optional: add pricing for x402 paywall (see references/x402.md)
// pricing: paywall.pricing,
// Optional: add access requirements (see references/predicate-gating.md)
// access: { logic: "OR", requirements: [...] },
})
1c. Write the handler
import { createToolHandler } from "@opensea/tool-sdk"
import { z } from "zod/v4"
import { manifest } from "./manifest.js"
const InputSchema = z.object({ query: z.string() })
const OutputSchema = z.object({ result: z.string() })
export const toolHandler = createToolHandler({
manifest,
inputSchema: InputSchema,
outputSchema: OutputSchema,
// gates: [], // Add gates here (see references/x402.md and references/predicate-gating.md)
handler: async (input) => {
return { result: `Processed: ${input.query}` }
},
})
1d. Wire up the adapter
Vercel:
import { toVercelHandler } from "@opensea/tool-sdk"
import { toolHandler } from "../src/handler.js"
export default toVercelHandler(toolHandler)
Express:
import { toExpressHandler } from "@opensea/tool-sdk"
import { toolHandler } from "./handler.js"
app.post("/api", toExpressHandler(toolHandler))
Cloudflare Workers:
import { toolHandler } from "./handler.js"
export default { fetch: toolHandler }
2. Register a Tool Onchain
2a. Via CLI
# Set up wallet
export PRIVATE_KEY=0x...
export RPC_URL=https://mainnet.base.org
# Register (open access — no predicate)
npx @opensea/tool-sdk register \
--metadata https://my-tool.example.com/.well-known/ai-tool/my-tool.json \
--network base
# Register with an access predicate
npx @opensea/tool-sdk register \
--metadata https://my-tool.example.com/.well-known/ai-tool/my-tool.json \
--network base \
--access-predicate 0xPREDICATE_ADDRESS
# Dry run (no transaction)
npx @opensea/tool-sdk register --metadata ... --network base --dry-run
The CLI:
- Fetches the manifest from
--metadataURL - Validates the manifest schema
- Verifies
manifest.creatorAddressmatches your wallet - Computes the JCS keccak256 manifest hash
- Calls
ToolRegistry.registerTool(metadataURI, manifestHash, accessPredicate) - Returns the
toolIdfrom theToolRegisteredevent
2b. Via SDK (programmatic)
import { ToolRegistryClient, computeManifestHash } from "@opensea/tool-sdk"
import { createWalletFromEnv, walletAdapterToClient } from "@opensea/tool-sdk"
import { base } from "viem/chains"
const adapter = createWalletFromEnv()
const walletClient = await walletAdapterToClient(adapter, base)
const registry = new ToolRegistryClient({
chain: base,
rpcUrl: "https://mainnet.base.org",
walletClient,
})
const { toolId, txHash } = await registry.registerTool({
metadataURI: "https://my-tool.example.com/.well-known/ai-tool/my-tool.json",
manifest, // your ToolManifest object
accessPredicate: "0x0000...0000", // address(0) = open access
})
console.log(`Registered tool ${toolId} in tx ${txHash}`)
3. Gating tool access
Tools can be gated three ways:
| Gate | Mechanism | Reference |
|---|---|---|
| x402 paywall | Pay-per-call (USDC, EIP-3009) | references/x402.md |
| Predicate gate | Onchain check (NFT, subscription, trait gating, ERC-20 balance, composite) | references/predicate-gating.md |
| Combined | EIP-3009 auth and payment (predicate first, then x402) | references/predicate-gating.md |
For deployed predicate addresses, requirement encodings, and SDK helpers like describeToolAccess / decodeRequirement, see references/known-predicates.md.
4. Wallet Setup
Signing uses @opensea/wallet-adapters, the same providers and env vars as the OpenSea CLI: Privy, Fireblocks, Turnkey, Bankr, or a local PRIVATE_KEY, auto-detected in that order or chosen with --wallet-provider. The full env var table, setup and signing-policy hardening are in the opensea-wallet skill.
RPC_URL (or --rpc-url) sets the RPC for onchain reads and writes. Without it, commands use the network's public RPC, which can be slow or rate-limited.
import { createWalletFromEnv, createBankrAccount } from "@opensea/tool-sdk"
const adapter = createWalletFromEnv() // auto-detected provider
const account = await createBankrAccount(process.env.BANKR_API_KEY!) // Bankr as a viem account for eip3009AuthenticatedFetch / paidAuthenticatedFetch
5. Response Codes
| Code | Meaning | Action |
|---|---|---|
| 200 | Success | Parse the JSON body per the manifest's outputs schema |
| 400 | Invalid input | Fix request body to match the manifest's inputs schema |
| 401 | Invalid or expired X-Payment signature | Re-sign a fresh zero-value EIP-3009 authorization and retry with the X-Payment header |
| 402 | Payment / identity required | The challenge is in body.accepts[0] (x402 v1) or the PAYMENT-REQUIRED response header (v2). For predicate gates (amount "0"), sign a zero-value authorization; for x402 paywalls, sign the requested amount. Send it back in X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2) — pay/paidFetch choose the right header automatically. |
| 403 | Access denied | Inspect body.predicate to discover what's needed; acquire the required token/subscription |
| 405 | Method not allowed | Use the verb the tool expects. pay auto-retries as GET when an unspecified-method POST probe returns 404/405; otherwise pass --method <verb>. |
| 500 | Internal tool error | Retry or contact the tool creator |
| 502 | Predicate/facilitator error | The upstream predicate or payment facilitator misbehaved; retry later |
6. Quick Reference: CLI Commands
| Command | Purpose |
|---|---|
init |
Scaffold a new tool project |
validate |
Validate a manifest file |
hash |
Compute the JCS keccak256 hash of a manifest |
export |
Export the manifest as JSON |
register |
Register a tool onchain. Supports --nft-gate, --erc20-gate + --erc20-min-balance, or --predicate-config to bundle predicate setup with registration |
update-metadata |
Update a tool's metadata URI and manifest hash onchain |
inspect |
Look up a tool's onchain config by ID |
verify |
Verify a manifest against its onchain hash |
deploy |
Deploy a tool to Vercel |
auth |
Call a predicate-gated tool (EIP-3009) |
pay |
Call an x402-paid or gated tool (probes for 402, signs, retries). Handles x402 v1/v2 and GET tools. Flags: --method <verb> (defaults POST; bodyless verbs put params in the query string; auto-falls back to GET on a 404/405 POST probe), --max-amount <baseUnits> spend cap (default 10 USDC, unlimited to disable), --body, --wallet-provider |
smoke |
Auto-detect gate type and call |
dry-run-gate |
Simulate an x402 gate check locally |
dry-run-predicate-gate |
Simulate a predicate gate check locally |
set-collections |
Set ERC-721 collection gate list for a tool |
get-collections |
Read ERC-721 collection gate list for a tool |
set-collection-tokens |
Set ERC-1155 collection + token ID gate for a tool |
configure-subscription |
Configure SubscriptionPredicate gate (collection + minTier) for a tool |
configure-trait-gating |
Configure TraitGatedPredicate gate (collection, traits contract, trait key, allowed values) for a tool |
get-trait-config |
Read trait gating configuration for a tool |
configure-erc20-gate |
Configure ERC20BalancePredicate gate (token, minBalance) for a tool |
get-erc20-config |
Read ERC-20 balance gating configuration for a tool |
All CLI commands accept --wallet-provider privy|turnkey|fireblocks|bankr|private-key or auto-detect from env vars.
The manifest is hashed as served (ERC-8257 §2). The registry hash is the JCS keccak256 of the full manifest document, including any namespaced extension fields. Nothing is stripped and no defaults are injected before hashing, so a hash computed by any RFC 8785 implementation agrees with the SDK and the backend. The schema is open: extension fields MUST be namespaced (reverse-DNS, e.g. io.opensea.paymentHint, or the legacy x- prefix); validate, hash, and register warn about bare un-namespaced extension fields, since those risk colliding with future normative fields.
7. Usage Tracking
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.
usageReporting (recommended)
Pass usageReporting to createToolHandler and it runs the reporter at the very end of the lifecycle, awaited before the response returns (bounded by timeoutMs, default 5s) so it completes even on serverless runtimes that freeze on response flush. Failures are logged, never fatal. No walletClient is needed server-side:
- 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.
import { createToolHandler } from "@opensea/tool-sdk"
export const toolHandler = createToolHandler({
manifest,
inputSchema: InputSchema,
outputSchema: OutputSchema,
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
For custom analytics, pass onInvocation: (event: InvocationEvent) => {...} to createToolHandler. It fires after the handler succeeds and settles, before the response returns, with callerAddress (verified), paid, toolName, latencyMs and timestamp.
8. End-to-End Examples
A free, open-access tool:
npx @opensea/tool-sdk init --runtime vercel # then edit src/manifest.ts and src/handler.ts
npx @opensea/tool-sdk deploy
npx @opensea/tool-sdk register --network base \
--metadata https://my-tool.vercel.app/.well-known/ai-tool/my-tool.json
curl -X POST https://my-tool.vercel.app/api -H "Content-Type: application/json" -d '{"query":"hello"}'
Gated variants change the server gate, the registration flags and the call command:
| Gate | Server | Register with | Call with |
|---|---|---|---|
| x402 pay-per-call | paywall gate (x402.md) | no predicate | npx @opensea/tool-sdk pay <url> --body '<json>' |
| ERC-721 holders | predicateGate (predicate-gating.md) |
--nft-gate <collection>, or set-collections <id> <collection> later |
npx @opensea/tool-sdk auth <url> --body '<json>' |
| Subscription | predicateGate |
--access-predicate 0xCBe0cd9B1d99d95Baa9c58f2767246C52e461f25 --predicate-config '{"collection":"0x...","minTier":0}', or configure-subscription later |
auth |
| ERC-20 balance | predicateGate |
--erc20-gate <token> --erc20-min-balance <base units>, or configure-erc20-gate later |
auth |
| NFT plus payment | paidPredicateGate |
a predicate as above | pay (one 402 round trip carries identity and payment) |
pay and auth need a wallet (section 4). Predicate checks read the chain through RPC_URL when it is set, otherwise the network's public RPC. pay --max-amount <base units> caps spend (default 10 USDC).
References
references/x402.md: pay-per-call protocol, server-side paywall,paidFetchreferences/predicate-gating.md: 402-based predicate access control (zero-valueX-Payment), combined gatesreferences/known-predicates.md: deployed predicate contracts and SDK helpers- Tool SDK GitHub