Manifest

The ERC-XXXX tool manifest lives at:

GET /.well-known/ai-tool/{{TOOL_SLUG}}.json

Endpoint

POST to /api with a JSON body matching the manifest's inputs schema. See the manifest for the exact input format.

Authentication

This tool may use one or both of the following gates (check the manifest for details):

Predicate gate (SIWE) — requires a SIWE authorization header: Authorization: SIWE <base64url(message)>.<signature>. Build the SIWE message for the domain of {{TOOL_ENDPOINT}} and sign with a qualifying wallet.
x402 payment gate — requires an X-Payment header with a signed USDC transfer authorization. The endpoint returns 402 with payment requirements if this gate is active.

Agent quick start

Using @opensea/tool-sdk CLI:

# Predicate-gated tool (SIWE auth)
PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org npx @opensea/tool-sdk auth \
  {{TOOL_ENDPOINT}}/api --body '{"query": "hello"}'

# x402-paid tool (USDC payment, no SIWE)
PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org npx @opensea/tool-sdk pay \
  {{TOOL_ENDPOINT}}/api --body '{"query": "hello"}'

# Smoke-test (auto-detects gate type)
PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org npx @opensea/tool-sdk smoke \
  --endpoint {{TOOL_ENDPOINT}}/api --expect 200

Or programmatically with wallet adapters:

import { createWalletFromEnv, walletAdapterToClient } from "@opensea/tool-sdk"
import { base } from "viem/chains"

// createWalletFromEnv auto-detects provider from env vars:
//   Privy > Fireblocks > Turnkey > PrivateKey
const adapter = createWalletFromEnv()
const client = await walletAdapterToClient(adapter, base)

For predicate-gated tools (SIWE auth):

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

const res = await authenticatedFetch(
  "{{TOOL_ENDPOINT}}/api",
  { account: client.account, method: "POST", body: JSON.stringify({ query: "hello" }) },
)
const data = await res.json()

For x402-paid tools (USDC payment, no SIWE):

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

const res = await paidFetch(
  "{{TOOL_ENDPOINT}}/api",
  { signer: adapter, method: "POST", body: JSON.stringify({ query: "hello" }) },
)
const data = await res.json()

For tools with both gates (SIWE + x402):

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

const res = await paidAuthenticatedFetch(
  "{{TOOL_ENDPOINT}}/api",
  {
    account: client.account,
    signer: adapter,
    method: "POST",
    body: JSON.stringify({ query: "hello" }),
  },
)
const data = await res.json()

Wallet providers

The SDK supports multiple wallet providers via @opensea/wallet-adapters. Set the corresponding env vars and createWalletFromEnv() auto-detects the provider:

PRIVATE_KEY + RPC_URL — Local private key (simplest)
PRIVY_APP_ID          — Privy server wallet
TURNKEY_API_PUBLIC_KEY — Turnkey signing
FIREBLOCKS_API_KEY    — Fireblocks vault

CLI commands also accept --wallet-provider privy|turnkey|fireblocks|private-key.

Response

On success, returns 200 with a JSON body matching the manifest's outputs schema. On auth failure, returns 401 (missing/invalid SIWE) or 403 (access predicate denied). For x402-gated tools, 402 indicates payment is required.