Agent Tool Registry (ERC-8257)

ERC-8257 defines a permissionless onchain registry for AI agent tools. Any developer can register a tool, gate access with an onchain predicate (NFT ownership, subscriptions, allowlists, or custom logic), and optionally charge per call using x402 micropayments, all without a centralized platform.

How It Works

A tool is an HTTPS endpoint with a JSON Schema interface, discoverable through a .well-known manifest. The lifecycle:

1. Build an endpoint that accepts JSON input and returns JSON output, then serve a manifest at /.well-known/ai-tool/<slug>.json.
2. Register it by calling registerTool on the onchain registry with your manifest URI and its keccak256 hash. The registry assigns a toolId.
3. Gate it (optional) by attaching an access predicate contract that controls who can invoke the tool, or leave it as address(0) for open access.

+-----------------+     +---------------------+     +-----------+
|    PUBLISHER    |---->|   TOOL REGISTRY     |<----|   AGENT   |
|                 |     |                     |     |           |
| serves manifest |     |                     |     | discovers |
| + handler       |     | creator             |     | verifies  |
|                 |     | metadataURI         |     | checks    |
|                 |     | manifestHash        |     | access    |
|                 |     | accessPredicate     |     | invokes   |
+-----------------+     +---------------------+     +-----------+

Agents discover tools by reading the registry, verify the manifest hash, check access via the predicate, and invoke the endpoint.

Key Concepts

Quick Start

The @opensea/tool-sdk handles the whole lifecycle: scaffold, deploy, register, gate, and call tools.

# 1. Scaffold a new tool (generates manifest, handler, adapter, and .well-known route)
npx @opensea/tool-sdk init my-tool --runtime vercel
cd my-tool && npm install

# 2. Edit src/manifest.ts and src/handler.ts with your logic

# 3. Deploy
npx @opensea/tool-sdk deploy

# 4. Register onchain (configure a wallet provider, see the SDK README)
#    Supports: Privy, Turnkey, Fireblocks, Bankr, or a local private key

# 4a. Open access (no gate)
npx @opensea/tool-sdk register \
  --metadata https://my-tool.vercel.app/.well-known/ai-tool/my-tool.json \
  --network base

# 4b. NFT-gated access
npx @opensea/tool-sdk register \
  --metadata https://my-tool.vercel.app/.well-known/ai-tool/my-tool.json \
  --network base \
  --nft-gate 0xCOLLECTION_ADDRESS

See the Tool SDK README for the full CLI reference, handler examples, adapter setup (Vercel, Cloudflare, Express), wallet providers, and predicate configuration.

Access Control

Access control is extensible: any contract that implements IAccessPredicate can gate a tool:

interface IAccessPredicate {
    function hasAccess(uint256 toolId, address account, bytes calldata data) external view returns (bool);
    function name() external view returns (string memory);
}

The Tool Registry repo includes reference predicate implementations for common access patterns: NFT ownership (ERC-721/1155), subscriptions, trait gating, pay-per-call (x402), and composite logic. See the repo for deployed addresses and supported chains.

REST API: Tool Endpoints

The OpenSea API returns enriched tool data, including NFT collection details (name, image, floor price) for predicate-gated tools:

curl "https://api.opensea.io/api/v2/tools/{chain}/{registry_address}/{tool_id}" \
  -H "x-api-key: YOUR_API_KEY"

📘

Don't have an API key yet? See Instant API Key to grab one for free.

See the Tool Endpoints [Beta] API reference for the full response schema.

Agent Skill

The OpenSea Agent Skill includes a dedicated sub-skill for building and registering tools. If you're using an AI coding assistant (Claude Code, Cursor, Windsurf, etc.):

npx skills add ProjectOpenSea/opensea-skill

Then prompt: "Register an NFT-gated tool on Base", "Scaffold a new tool with x402 payments", etc.

Resources