SDK des outils OpenSea

Construisez, enregistrez et contrôlez l'accès aux endpoints d'outils appelables par l'IA en utilisant le registre des outils OpenSea (ERC proposé) sur Base.

Quand utiliser cette compétence (scope_in)

Utilisez opensea-tool-sdk quand vous devez :

• Scaffolder un endpoint d'outil appelable par l'IA (HTTPS, JSON Schema, manifeste .well-known) pour Vercel, Cloudflare ou Express
• Enregistrer un outil onchain sur le ToolRegistry de Base pour que d'autres agents puissent le découvrir
• Contrôler l'accès via x402 pay-per-call (USDC) ou prédicats (propriété ERC-721/ERC-1155, abonnements, composites)
• Appeler un outil contrôlé : authentification SIWE (authenticatedFetch), paiements 402 (paidFetch), ou les deux (paidAuthenticatedFetch)

Quand NE PAS utiliser cette compétence (scope_out, handoff)

Ce SDK s'adresse aux fournisseurs et consommateurs d'outils. Pour interroger les données de la marketplace OpenSea (prix plancher, annonces, échanges), utilisez plutôt la compétence opensea-api.

Concepts

Contrats déployés (mainnet Base)

1. Créer un outil

1a. Scaffolder un projet

npx @opensea/tool-sdk init --runtime vercel   # ou: cloudflare, express

Ceci génère :

• src/manifest.ts : définition du manifeste de l'outil
• src/handler.ts : gestionnaire de requête avec schémas d'entrée/sortie
• api/index.ts : point d'entrée adaptateur de framework
• public/llms.txt : page de découverte lisible par agent
• api/well-known/[slug].ts : sert le manifeste à /.well-known/ai-tool/<slug>.json

1b. Définir le manifeste

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: ajouter la tarification pour le mur de paiement x402 (voir references/x402.md)
  // pricing: paywall.pricing,
  // Optional: ajouter les exigences d'accès (voir references/predicate-gating.md)
  // access: { logic: "OR", requirements: [...] },
})

1c. Écrire le gestionnaire

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: [],  // Ajouter les contrôles ici (voir references/x402.md et references/predicate-gating.md)
  handler: async (input) => {
    return { result: `Processed: ${input.query}` }
  },
})

1d. Brancher l'adaptateur

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. Enregistrer un outil onchain

2a. Via CLI

# Configurer le portefeuille
export PRIVATE_KEY=0x...
export RPC_URL=https://mainnet.base.org

# Enregistrer (accès ouvert, pas de prédicat)
npx @opensea/tool-sdk register \
  --metadata https://my-tool.example.com/.well-known/ai-tool/my-tool.json \
  --network base

# Enregistrer avec contrôle NFT (collection ERC-721)
npx @opensea/tool-sdk register \
  --metadata https://my-tool.example.com/.well-known/ai-tool/my-tool.json \
  --network base \
  --nft-gate 0xCOLLECTION_ADDRESS

# Enregistrer avec un prédicat d'accès personnalisé
npx @opensea/tool-sdk register \
  --metadata https://my-tool.example.com/.well-known/ai-tool/my-tool.json \
  --network base \
  --access-predicate 0xPREDICATE_ADDRESS

# Simulation (pas de transaction)
npx @opensea/tool-sdk register --metadata ... --network base --dry-run

La CLI :

1. Récupère le manifeste depuis l'URL --metadata
2. Valide le schéma du manifeste
3. Vérifie que manifest.creatorAddress correspond à votre portefeuille
4. Calcule le hash keccak256 JCS du manifeste
5. Appelle ToolRegistry.registerTool(metadataURI, manifestHash, accessPredicate)
6. Retourne le toolId depuis l'événement ToolRegistered

2b. Via SDK (programmation)

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,                                      // votre objet ToolManifest
  accessPredicate: "0x0000...0000",              // address(0) pour accès ouvert
})

console.log(`Registered tool ${toolId} in tx ${txHash}`)

3. Contrôler l'accès aux outils

Les outils peuvent être contrôlés de trois façons :

Pour les adresses de prédicat déployées, les encodages de conditions requises et les helpers SDK comme describeToolAccess / decodeRequirement, voir references/known-predicates.md.

4. Configuration du portefeuille

Le SDK supporte plusieurs fournisseurs de portefeuille via @opensea/wallet-adapters. Définissez les variables d'environnement et le SDK détecte automatiquement le fournisseur. Consultez la compétence opensea-wallet pour la table complète des fournisseurs, les variables d'environnement, les procédures de configuration et la configuration de la politique de signature.

import { createWalletFromEnv } from "@opensea/tool-sdk"

const adapter = createWalletFromEnv()
const address = await adapter.getAddress()

Pour Bankr (signataire externe) :

import { createBankrAccount } from "@opensea/tool-sdk"

const account = await createBankrAccount("your-bankr-api-key")
// Utiliser avec authenticatedFetch ou paidAuthenticatedFetch

5. Codes de réponse

6. Référence rapide : commandes CLI

Toutes les commandes CLI acceptent --wallet-provider privy|turnkey|fireblocks|bankr|private-key ou détection automatique depuis les variables d'environnement.

7. Exemples de bout en bout

Exemple A : outil libre à accès ouvert

# 1. Scaffolder
npx @opensea/tool-sdk init --runtime vercel
# 2. Éditer src/manifest.ts et src/handler.ts avec votre logique
# 3. Déployer
npx @opensea/tool-sdk deploy
# 4. Enregistrer (accès ouvert)
PRIVATE_KEY=0x... npx @opensea/tool-sdk register \
  --metadata https://my-tool.vercel.app/.well-known/ai-tool/my-tool.json \
  --network base
# 5. Appeler
curl -X POST https://my-tool.vercel.app/api \
  -H "Content-Type: application/json" \
  -d '{"query": "hello"}'

Exemple B : outil payant x402 (pay-per-call uniquement, pas de vérification d'identité)

# Serveur : ajouter un contrôle de mur de paiement (voir references/x402.md)
# Appeler via CLI :
PRIVATE_KEY=0x... npx @opensea/tool-sdk pay \
  https://my-tool.vercel.app/api \
  --body '{"query": "hello"}'

Exemple C : outil contrôlé par NFT (vérification d'identité, pas de paiement)

# Enregistrer avec contrôle NFT
PRIVATE_KEY=0x... npx @opensea/tool-sdk register \
  --metadata https://my-tool.vercel.app/.well-known/ai-tool/my-tool.json \
  --network base \
  --nft-gate 0xCOLLECTION

# Serveur : ajouter predicateGate (voir references/predicate-gating.md)

# Appeler via CLI :
PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org \
  npx @opensea/tool-sdk auth \
  https://my-tool.vercel.app/api \
  --body '{"query": "hello"}'

Exemple D : outil contrôlé par NFT et payant (les deux contrôles)

# Serveur : ajouter predicateGate et paywall.gate (voir references/predicate-gating.md)
# Appeler via CLI :
PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org \
  npx @opensea/tool-sdk smoke \
  --endpoint https://my-tool.vercel.app/api \
  --expect 200

Références

• references/x402.md : protocole pay-per-call, mur de paiement côté serveur, paidFetch
• references/predicate-gating.md : contrôle d'accès basé sur SIWE, contrôles combinés
• references/known-predicates.md : contrats de prédicat déployés et helpers SDK
• SDK des outils GitHub